AIDebug

审阅者起点

以证据为中心的反向工程 CLI。 Andrey Pautov 开发 Python 分析界面、离线分类、字符串情报、PE 检查和报告工作流。Capstone、Ghidra、GDB 以及可选的 AI 提供程序属于集成组件，并非本项目原创的工具。

角色相关性： 恶意软件分类、反向工程工具、安全的 AI 辅助分析、Python 交付。

运行安全的本地演示并查看验证范围 · 本地验证记录

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

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

最新的不可变已发布版本仍为 AIDebug v3.0.0， 以 1200km-aidebug 形式提供， 直到版本匹配的 3.1.0 标签和 GitHub 发行版完成已验证的 发布工作流。

亮点

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

安装

已发布的 3.0.0 包

从 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 provider clients and local validation of AI-generated YARA candidates
python -m pip install "1200km-aidebug[ai]==3.0.0"

# Frida dynamic instrumentation
python -m pip install "1200km-aidebug[dynamic]==3.0.0"

# All optional Python integrations
python -m pip install "1200km-aidebug[all]==3.0.0"

已审查的 3.1.0 源码

String Intelligence 在包发布之前需要 3.1 版源码。 3.1 审查 固定了下面的修订版本。其运行时代码也与已审计的 10 月 1 日 主修订版本 80b0b7172b592814504c405a16bf4cc0ce4161eb 一致。

git clone https://github.com/anpa1200/AIDebug.git
cd AIDebug
git checkout cd81ef242db0bcea3296970d45c241a4228d2d27
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .
aidebug --version

从该检出目录中，使用 python -m pip install -e ".[ai]"、".[dynamic]" 或 ".[all]" 添加额外组件。请将额外组件保持在同一条安装轨道上：在源码 3.1 之上安装 "1200km-aidebug[ai]==3.0.0" 可能会将其替换为已发布的 3.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 目标组件均为外部工具，仅在需要它们的工作流中使用。

REMnux 集成

AIDebug 于 2026 年 10 月 7 日通过 PR #355 被纳入 REMnux，首次包含于 salt-states v2026.41.4。 已接受的 state 会从 PyPI 安装未固定版本的 1200km-aidebug[ai] 到 /opt/aidebug，启用升级，并暴露 /usr/local/bin/aidebug。经 2026 年 10 月 8 日验证，PyPI 仍提供 3.0.0；这不会安装未发布的 3.1 源码或 dynamic extra。使用 --offline 可保持分析在本地进行。 参见 REMnux 安装与版本边界。

快速开始

在主终端界面中打开 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 分类会检查前 4,096 个名称，并最多读取 mimetype 条目的 128 字节。Python 在名称限制生效之前解析中央目录；这并不能限制初始目录解析的内存占用。整个输入上限为 128 MiB，并且文件永远不会被执行或提取。内置捕获签名覆盖两种字节序的纳秒 PCAP 以及 PCAP-NG。目前缺少传统的微秒 PCAP 签名；可选的 libmagic 可能识别它们。

安装 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 地址必须占据一个完整有效的 token，配置赋值必须匹配保守的整行语法。这可以防止短二进制片段仅仅因为包含点、冒号或等号就被提升。相关标签共享同一个置信度族，因此 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，并在被接受之前通过严格的本地 schema、枚举、引用和 IOC 接地校验。最终 reducer 看到的是经过校验的发现，而不是原始清单。提取限制、失败的批次以及已审查/已发送计数始终会被报告；覆盖不完整会强制给出 unknown 的整体评估。字符串可能包含密码、API 令牌、客户数据以及攻击者编写的提示注入，因此在启用此功能之前请审查远程 AI 边界。

对于 string CLI 报告，退出状态 0 表示已生成报告，即使 AI 审查是部分完成或失败的。请检查 ai_analysis.coverage.complete、failed_chunks、unattempted_chunks、reviewed_count 和 retained_count，以及 ai_analysis.overall_assessment 和 ai_analysis.limitations。缺少 ai_analysis 表示未包含 AI 审查。 参见工作流完成检查。

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

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

PE 结构工作区

加载一个 PE 文件并在主 GUI 中按 X（或 P）。AIDebug 会呈现它所哈希的确切字节，并将结构证据组织为有界、可导航的视图。