AIDebug

AIDebug 是一款以证据为核心的恶意软件逆向工程 CLI 和终端界面工具。 它结合了确定性的离线分类、全文件十六进制检查、深度 PE 结构分析、Capstone 反汇编、Ghidra 重构、可选的 LLM 交叉验证、本地 ELF 调试、编译型学习练习以及 分析师审阅报告。

当前源码版本：AIDebug 3.1.0。请参阅 3.1.0 版本说明。

最新不可变已发布版本仍为 AIDebug v3.0.0， 可通过 1200km-aidebug 获取， 直至版本匹配的 3.1.0 标签和 GitHub 发布完成经过验证的 发布工作流。

亮点

• 无需 AI 服务即可进行确定性的 PE 和 ELF 静态分类。
• 全文件、感知出现次数的 ASCII、UTF-8、UTF-16LE 和 UTF-16BE 字符串 智能分析，包含智能分类、排序以及 DLL/API 解释。
• 针对完整分析文件的只读、分页十六进制查看器。
• 深度 PE32/PE32+ 结构浏览器，包含映射的 RVA、VA 和文件偏移。
• 基于 Ghidra 的类 C 重构，支持单个函数或完整的受限 函数集。
• 通过 Anthropic、OpenAI、Google Gemini 或本地 Ollama 兼容端点进行可选的基于证据的审阅。
• 基于 GDB 的本地 ELF 调试，支持断点、单步执行、寄存器、增量、 反汇编上下文以及函数输入/输出候选。
• 主 GUI 中包含一百个独立的 C 学习案例，附带真实编译器输出、 反汇编和 Ghidra 伪代码。
• 基于 SHA-256 索引的本地分析历史和兼容的发现恢复。
• 面向分析师审阅的 HTML、版本化 JSON、YARA 候选、ATT&CK 候选和 CFG 输出。

安装

从 PyPI 安装稳定包：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install 1200km-aidebug==3.0.0
aidebug --version

根据需要安装可选功能：

# 远程/本地 LLM 提供商和经过验证的 YARA 生成
python -m pip install "1200km-aidebug[ai]==3.0.0"

# Frida 动态插桩
python -m pip install "1200km-aidebug[dynamic]==3.0.0"

# 所有可选的 Python 集成
python -m pip install "1200km-aidebug[all]==3.0.0"

用于开发：

git clone https://github.com/anpa1200/AIDebug.git
cd AIDebug
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev,dynamic]"

Ghidra、GDB、Bubblewrap、C 编译器和 Frida 目标组件是外部 工具，仅由需要它们的工作流使用。

快速开始

在主终端界面中打开 PE 或 ELF 样本：

aidebug --binary /path/to/sample.exe --offline

运行确定性分析而不使用全屏界面并导出证据：

aidebug --binary /path/to/sample.exe \
  --offline --no-tui --report --json-export --yara \
  --out-dir reports/

使用 Ghidra 重构：

aidebug --binary /path/to/sample.exe --offline --no-tui --decompile
aidebug --binary /path/to/sample.exe --offline --no-tui \
  --decompile-all reports/sample-reconstruction.c

通过临时、不执行的 ELF 工件分析一个 C 翻译单元：

aidebug --source /path/to/example.c --offline --no-tui

独立于文件扩展名识别任意文件：

aidebug --identify /path/to/renamed-or-unknown-file --offline

--identify 报告结构化 JSON，包含声明类型、MIME 类型、常见 扩展名、置信度、方法、证据、SHA-256 和大小。确定性 覆盖范围包括常见的可执行文件和字节码格式、归档和磁盘 镜像、Office/OpenDocument/EPUB 容器、文档、图像、音频/视频、 数据包捕获、数据库、注册表/事件日志工件、脚本和文本。 基于 ZIP 的格式通过受限成员名称和小型元数据读取进行检查；文件 永远不会被执行或提取。

安装 python-magic 以及操作系统的 libmagic 数据库以获取 本地平台已知的额外签名：

python -m pip install python-magic

当没有确定性签名、结构或文本规则匹配时，已配置的 AI 提供商可以从受限元数据中推断候选：扩展名、大小、 SHA-256、最多 96 个头部字节、32 个尾部字节、样本熵和 NUL 比率。 文件主体、提取的字符串和文件系统路径不会被发送。仅 AI 结果标记为 ai-inference，置信度上限为 60%，并且需要 分析师验证。使用 --offline 完全禁用回退；未解析的 类型报告为 Unknown，退出状态为 2。

字符串智能工作区（3.1.0）

在主终端界面中按 S，或直接在工作区中启动：

aidebug --binary /path/to/sample.exe --offline --strings

该工作区保留文件偏移、可用时的映射地址、 编码、字节和字符长度、重复出现信息、 节上下文、置信度、分类分数以及每个分类的确定性原因。 过滤器涵盖最小长度、编码、类别和 自由文本搜索；列排序和分页使大型清单保持可用。 每个选定的编码都会扫描完整的受限大小工件。保留的 清单上限为 25,000 条记录，每个值最多显示 4,096 个字符； 精确的候选/遗漏计数和完整字节覆盖使任一上限可见。 每条记录最多保留 32 个 DLL/API 注释和 4,096 个描述 字符；对抗性溢出会在记录原因中报告。

检测是多标签的。单个值可以同时是 DLL、Windows 路径、URL、IP 地址、注册表项、命令、PowerShell 片段、命名管道、 哈希、凭据候选、用户代理或其他受支持的证据类型。 域候选经过 IDNA 规范化，并对照打包的离线 IANA 根区域快照进行检查；IP 地址必须占据完整的有效令牌，并且 配置赋值必须匹配保守的全行语法。这 防止短二进制片段仅仅因为包含点、冒号或等号就被提升。 相关标签共享一个置信度族，因此 ip_address 加上 ipv6 不会被视为两个独立的观察结果。 已知 DLL 和 API 会收到简短的中性能力描述；未知 名称会收到明确的未验证回退，而不是猜测的用途。 提取的名称是存在的证据，而不是代码调用了它或 样本是恶意的证明。

本地打印确定性清单、过滤显示的 CLI 视图，或 将规范的完整清单写为仅所有者可读的 JSON：

aidebug --binary /path/to/sample.exe --strings --no-tui
aidebug --binary /path/to/sample.exe --strings --no-tui \
  --string-encoding ascii --min-string-length 6 --string-category url
aidebug --binary /path/to/sample.exe --strings --no-tui \
  --strings-output reports/sample-strings.json

AI 字符串审阅是单独的选择加入操作。在工作区中按 A 并确认隐私/成本警告，或在 CLI 模式下显式请求：

aidebug --binary /path/to/sample.exe --strings --no-tui \
  --analyze-strings --accept-ai-cost \
  --strings-output reports/sample-strings-ai.json

每个保留的字符串都被分配一个稳定的证据 ID。在显式 确认后，AI 路径在确定性的、受限的块中规划每条保留记录； 提供商或验证失败会安全停止并保持可见。 响应必须说明每个提供的 ID，并且 在它们被接受之前通过严格的本地模式、枚举、引用和 IOC 接地验证。 最终归约器看到的是经过验证的发现，而不是 原始清单。提取限制、失败的批次 以及已审阅/已发送计数始终被报告；不完整的覆盖强制 unknown 总体评估。字符串可能包含密码、API 令牌、 客户数据和攻击者编写的提示注入，因此在启用此功能之前请审阅远程 AI 边界。

按文件或 SHA-256 检查先前的分析：

aidebug --history /path/to/sample.exe
aidebug --history 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

PE 结构工作区

加载 PE 文件并在主 GUI 中按 X（或 P）。AIDebug 呈现 它已哈希的确切字节，并将结构证据组织成受限的、 可导航的视图。

AIDebug 在构建这些视图时不会执行 PE。静态证书 验证不是 Windows 根信任或吊销验证，Rich 元数据 不是归因，强名称元数据不是发布者信任，静态 缓解标志不是有效运行时策略的证明。

已发布指南

这些文章提供了补充仓库文档的详细工作流和截图：

• AIDebug 3.1 完整发布审阅：从二进制输入到字符串智能 — 涵盖文件识别、PE 和 ELF 分类、函数、控制流、字符串、Ghidra、可选 AI 审阅、受控调试、历史和报告的完整证据优先工作流。
• 恶意软件分析的字符串分析：将二进制文本转化为可辩护的假设 — 感知出现次数的提取、保守分类、IOC 验证、交叉引用和 AIDebug 字符串智能。
• 恶意软件分析的 PE 文件结构：实用指南 — PE 布局、加载器行为、头部、节、导入、导出、资源、重定位、TLS、缓解、签名、覆盖层和 .NET 元数据（使用 AIDebug）。
• 恶意软件分析的汇编：实用 x86/x64 指南 — 寄存器、标志、调用约定、控制流、Windows API 和动手 AIDebug 学习案例。
• 解释它看到的每个函数的 AI 驱动的恶意软件调试器 — 本地保留的原始 AIDebug 项目演练。

学习模式

打开完整目录或从特定案例开始：

aidebug --learn
aidebug --learn mov-load
aidebug --learn lea-arithmetic
aidebug --learn switch-dispatch

每个捆绑案例都是 learning/cases/ 下的独立文件。 AIDebug 将所选案例编译为临时 x86-64 ELF，显示确切的 C 源码和编译器生成的指令，要求 Ghidra 进行独立 重构，记录构建来源，并移除临时工件。 生成的课程二进制文件永远不会被执行。

使用 --no-tui 进行文本输出，或加载经过审阅的外部集合：

aidebug --learn movsxd --no-tui
aidebug --learn --learning-collection /path/to/reviewed-cases

AI 提供商

AI 分析是可选的。确定性离线模式仍然可用，无需 凭据。

python -m pip install "1200km-aidebug[ai]==3.0.0"
cp .env.example .env
chmod 600 .env

配置恰好一个提供商，或在存在多个 凭据时显式设置 AIDEBUG_LLM_PROVIDER：

AIDEBUG_LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=replace_with_your_key

# 备选方案：
# OPENAI_API_KEY=replace_with_your_key
# GEMINI_API_KEY=replace_with_your_key
# OLLAMA_BASE_URL=http://127.0.0.1:11434/v1

使用 AIDEBUG_ENV_FILE=/absolute/path/to/private.env 将配置远离 不受信任的分析目录。远程批量分析需要显式的 --accept-ai-cost 确认。在向任何提供商发送样本证据之前，请审阅 远程 AI 数据边界。

活动 ELF 调试

基于 GDB 的活动模式执行选定的本地 ELF。仅在隔离的、 授权的实验室中使用它：

aidebug --binary ./sample.elf --mode debug --breakpoint main

可用命令包括 break、continue、step、next、finish、 registers、changes、io、disassemble 和 quit。Frida 动态模式 可单独用于受支持的本地或远程插桩工作流。

输出

工作原理

flowchart LR
  Input[PE, ELF, or C source] --> Parse[Bounded parsing and hashing]
  Parse --> Structure[Hex and PE structure evidence]
  Parse --> Strings[Deterministic string intelligence]
  Parse --> Disasm[Capstone disassembly]
  Disasm --> Patterns[Deterministic patterns]
  Disasm --> Ghidra[Ghidra reconstruction]
  Patterns --> Offline[Offline findings]
  Patterns --> AI[Optional LLM cross-check]
  Strings --> StringAI[Opt-in chunked string AI review]
  Ghidra --> AI
  Offline --> Reports[HTML, JSON, YARA, CFG]
  AI --> Reports
  StringAI --> StringJSON[Structured string JSON]
  Reports --> History[SHA-256-indexed history]

安全性和范围

仅在您被授权检查的软件和系统上使用 AIDebug，并且 在隔离的恶意软件分析虚拟机或实验室中。

• 静态分析不会执行被检查的 PE 或 ELF。
• C 输入和学习案例被编译为临时工件，其分析工作流 不会执行这些工件。
• GDB 活动模式启动本地 ELF；Frida 模式对运行中的目标进行插桩。
• 输出是受限的证据和假设，不是自动归因或 最终检测真相。
• 会话数据库和导出可能包含敏感证据，并且 AIDebug 不会对其加密。
• Ghidra 输出是重构的类 C 代码，不是恢复的原始源码。

在分析不受信任的样本之前，请阅读完整的 安全模型、安全策略 和 限制与验证计划。

文档

开发

运行快速的本地检查：

python -m ruff check .
python -m pytest -q

运行完整的隔离发布门禁：

./scripts/release-readiness.sh

有关贡献指南，请参阅 CONTRIBUTING.md。请勿将 实时恶意软件、凭据、私有案例数据或未脱敏的证据附加到问题 或拉取请求中。

项目

• 发布
• PyPI
• 问题
• 讨论
• 安全策略
• 引用元数据
• 1200km 安全研究生态系统

许可证

AIDebug 根据 MIT 许可证 发布。