Query-farm/vgi-disasm
GitHub: Query-farm/vgi-disasm
一个 VGI 安全分析 worker，利用 Capstone 引擎将 PE/ELF/Mach-O 二进制文件和原始 shellcode 反汇编为 DuckDB 中的结构化 SQL 表，并提供带 MITRE ATT&CK 标签的轻量级恶意软件分诊能力。
Stars: 0 | Forks: 0
# vgi-disasm
一个 [VGI](https://query.farm) worker，它能**反汇编** PE / ELF / Mach-O 二进制文件以及原始 shellcode 数据块，将它们转换为**每条机器指令占一行**（地址、原始字节、助记符、操作数、指令组），由 [Capstone](https://www.capstone-engine.org/) 驱动，并通过 [goblin](https://github.com/m4b/goblin) 解析容器格式。在指令流的基础上，它会呈现节区/导入/字符串关系，以及用于恶意软件分诊的**轻量级、带有 MITRE ATT&CK 标签的能力指标**。
它是 `vgi-pe` 的反汇编同胞组件，并在 VGI **安全套件**中与 `vgi-yara` / `vgi-ioc` 搭配使用：*反汇编并为成千上万的样本打上能力标签，然后在一条 SQL 查询中将指令统计和 ATT&CK 标签与你的 YARA 匹配结果和 IOC 订阅源进行 JOIN 操作 —— 无需针对每个样本进行工具配置，且零数据流出。* 该 worker **完全基于静态解码处理 `BLOB` —— 它绝不执行输入内容**，没有网络请求，没有状态，这使其对于气隙隔离或受合规限制的恶意软件存储库是安全的。
## SQL 接口
```
INSTALL vgi FROM community;
LOAD vgi;
ATTACH 'vgi-disasm' AS disasm (TYPE vgi, LOCATION '/path/to/disasm-worker');
SET search_path = 'disasm.main';
```
| 功能 | 签名 | 类型 |
| --- | --- | --- |
| 反汇编 | `disassemble(blob [, arch, mode, base, section]) -> TABLE(address UBIGINT, size UTINYINT, bytes BLOB, mnemonic VARCHAR, op_str VARCHAR, groups VARCHAR[])` | table |
| 节区 | `sections(blob) -> TABLE(name, kind, vaddr UBIGINT, size UBIGINT, file_off UBIGINT, exec BOOL, entropy DOUBLE)` | table |
| 导入 | `imports(blob) -> TABLE(library, name, ordinal INTEGER, kind)` | table |
| 字符串 | `strings(blob [, min_len]) -> TABLE(offset UBIGINT, encoding, value)` | table |
| 能力 | `capabilities(blob) -> TABLE(rule, attack_id, attack_name, severity, evidence)` | table |
| 入口点 | `entrypoint(blob) -> STRUCT(arch, mode, vaddr UBIGINT, file_off UBIGINT, section)` | scalar |
| 格式探测 | `format(blob) -> STRUCT(container, arch, mode, bits UTINYINT, endian, entry UBIGINT)` | scalar |
| 版本 | `disasm_version() -> VARCHAR` | scalar |
**输入：字节 _或_ 路径。** 每个函数都接受二进制内容，无论是以内联 `BLOB` 字节的形式，还是以它自行打开并读取的 `VARCHAR` 文件系统路径的形式（这些字节会被静态解码，**绝不执行**）。表值函数的输入是单个 `ANY` 类型的参数，因此 `disassemble(from_hex('…'))` 和 `disassemble('sample.bin')` 均可成功绑定。
### 示例
```
-- 1. Disassemble x64 shellcode at an explicit base; enumerate its call sites.
SELECT address, mnemonic, op_str
FROM disassemble(from_hex('554889e5e800000000c3'), arch := 'x86', mode := 'x64', base := 4096)
WHERE list_contains(groups, 'call')
ORDER BY address;
-- 2. Disassemble a binary's executable sections (arch auto-detected from the
-- container; base = each section's virtual address). Pass a path or BLOB.
SELECT address, mnemonic, op_str, groups
FROM disassemble('sample.bin') -- or disassemble()
ORDER BY address;
-- 3. Sections, imports, and the entry point of a sample.
SELECT name, kind, exec, entropy FROM sections('sample.bin');
SELECT library, name, ordinal, kind FROM imports('sample.bin');
SELECT (entrypoint('sample.bin')).*;
SELECT (format('sample.bin')).*; -- fast "is this a binary I can disassemble?"
-- 4. Heuristic capabilities mapped to MITRE ATT&CK for one sample (the input is
-- a constant path or BLOB, per the note above), filtered to a technique family.
SELECT rule, attack_id, attack_name, severity, evidence
FROM capabilities('sample.bin')
WHERE attack_id LIKE 'T1055%'; -- process-injection family
```
## 反汇编模型
- **架构 / 模式解析**（优先级顺序）：显式的 `arch`/`mode` 参数 → 容器头（goblin：ELF `e_machine`，PE machine，Mach-O `cputype`） → 否则输出单条诊断行（`mnemonic='(error)'`，`op_str='arch required for raw blob'`）。支持：**x86 (16/32/64)、ARM、ARM64、MIPS、PPC、SystemZ、RISC-V**。
- **基址** 为 `address` 列提供初始值，并使相对分支操作数显示为**绝对**目标地址（如 `call 0x401050`）。默认值 = 节区的 VA（如果是原始数据块则为 0）；为 shellcode 传入 `base :=`，以便操作数与内存转储对齐。
- **节区选择**（`section` 参数）：`auto`（每个可执行节区，默认值），`all`（以原始字节形式处理从 `base` 开始的整个数据块），或节区名称（`.text`、`__text`）。
- **带有坏字节恢复的线性扫描。** v1 从每个选定节区的起始处向前解码；无法解码的字节会生成一个单字节的 `.byte` 行，随后扫描会从下一个字节继续恢复 —— 它绝不会卡死。（从入口点开始进行递归下降 / CFG 跟踪属于路线图规划内容。）
- **规范化指令组。** Capstone 的组详细信息被规范化为一个小型的、跨架构的通用词汇表 —— `call`、`jump`、`ret`、`int`、`privileged`、`branch_relative`、`fpu`、`sse`、`vm` —— 因此 `WHERE list_contains(groups, 'call')` 在 x86、ARM 或 MIPS 上均能同等生效。
## 能力（启发式，非 capa）
`capabilities(blob)` 从三个低成本信号生成带有 ATT&CK 标签的分诊指标：**导入名 → 技术**（例如 `VirtualAllocEx`/`WriteProcessMemory`/`CreateRemoteThread` → T1055 Process Injection），**可疑字符串 → 指标**（PowerShell `-enc`、`cmd.exe /c`、自启动注册表路径、虚拟机特征文件名、勒索软件提示信息），以及 **反分析指令模式**（`rdtsc`/`cpuid` 计时、`int3` / `int 0x2d`）。映射表以内置参考数据的形式发布；ATT&CK 技术 ID/名称来自 [attack.mitre.org](https://attack.mitre.org/)。这里**没有评分、没有规则组合、没有基本块特征** —— 这正是它区别于 [capa](https://github.com/mandiant/capa) 的界线（capa 是免费的、基于 Python 的工具，且在单样本深度分析上更胜一筹；将 `capa-rules` 作为数据源进行解析属于路线图规划内容）。
## 安全加固
输入内容*本身即*恶意软件，因此每次转换都经过了封装和边界限制：
- **行级异常捕获：** 格式错误或恶意的 blob 只会产生空结果或诊断输出，绝不会引发 panic 或导致扫描崩溃（一个 `proptest` 模糊测试门禁确保在所有架构下，任意字节输入均不会引发 panic）。
- **一切资源均设上限：** 对单个 blob 的指令数（`MAX_INSNS` ≈ 5M）、输入给 Capstone 的每节区字节数，以及字符串/导入/节区/能力的总计数都设有硬性上限，因此精心构造的“声明超大尺寸”的文件头无法导致 worker 发生 OOM。
- **绝不执行输入：** 反汇编是对字节的静态解码，而非模拟执行或实际运行。
## 构建与测试
```
cargo build --release # produces target/release/disasm-worker
cargo test # unit + golden vectors + proptest no-panic gate
cargo clippy --all-targets -- -D warnings
./run_tests.sh # haybarn SQLLogic E2E (needs haybarn-unittest + the vgi ext)
```
该 crate 分为 `disasm-core`（纯解码/解析/分诊引擎；不依赖 Arrow，不依赖 RPC）和 `disasm-worker`（VGI SDK Arrow 适配器）。CI 会运行 fmt/clippy/build/doc、Rust 测试套件、跨越 **subprocess + unix + HTTP** 传输矩阵的 SQLLogic E2E 测试，以及在 `--fail-on info` 级别运行的 `vgi-lint` 元数据门禁。
## 许可证与依赖
**MIT**（见 [`LICENSE`](LICENSE)）。所有依赖均为宽松许可，无 copyleft 限制：内置的 Capstone C 引擎采用 BSD-3-Clause 协议（内部嵌入了 BSD-3-Clause 协议的 LLVM MC 表）；`capstone`/`capstone-sys` 绑定库采用 MIT 协议；`goblin` 采用 MIT 协议；`object` 采用 MIT/Apache-2.0 协议。绝对不包含任何 GPL/AGPL。
Query.Farm DuckDB worker 的 VGI 生态系统的一部分。
版权所有 © 2026 Query Farm LLC。
标签：DAST, DNS 反向解析, DuckDB, Wayback Machine, 二进制分析, 云安全监控, 云安全运维, 云资产清单, 反汇编, 可视化界面, 恶意软件分析, 逆向工程, 通知系统, 静态分析