Query-farm/vgi-pe

一个用于 DuckDB 的 Query.Farm VGI worker。

# vgi-pe 以 DuckDB SQL 函数的形式对可执行二进制文件（**PE、ELF 和 Mach-O**）进行静态分析，由 [VGI](https://query.farm) worker 提供服务。这是一个防御性的 **恶意软件快速分诊 (malware-triage)** 工具：它解析不受信任的可执行映像，并报告静态信号（格式、架构、入口点、代码签名、构建时间戳、节 + 每节熵、导入、导出、可打印字符串），而绝对不会执行该二进制文件。 基于 [LIEF](https://lief.re) (Apache-2.0) 构建，这是一个适用于 PE / ELF / Mach-O 的宽松跨格式解析器。 ``` INSTALL vgi FROM community; LOAD vgi; ATTACH 'pe' (TYPE vgi, LOCATION 'uv run pe_worker.py'); SELECT pe.binary_format('sample.exe'); -- 'PE' | 'ELF' | 'MachO' | NULL SELECT pe.machine('sample.exe'); -- 'X86_64', 'ARM64', ... SELECT pe.is_signed('sample.exe'); -- Authenticode / Mach-O code signature SELECT pe.imphash('sample.exe'); -- PE import hash (clustering) SELECT pe.overall_entropy('sample.exe'); -- 0-8; high => packed/encrypted SELECT * FROM pe.sections('sample.exe') ORDER BY name; -- per-section entropy + flags SELECT * FROM pe.imports('sample.exe'); -- imported symbols SELECT * FROM pe.exports('sample.so'); -- exported symbols SELECT * FROM pe.strings('sample.exe', min_len := 8); -- printable strings ``` ## 函数接口 每个函数接受其二进制参数的方式为：**要么**是 worker 可以打开的 `VARCHAR` 文件系统路径，**要么**是原始字节的 `BLOB`。 ### 标量函数（输入一个二进制文件，输出一个值） | 函数 | 返回值 | 备注 | |---|---|---| | `binary_format(binary)` | `VARCHAR` | `'PE'` / `'ELF'` / `'MachO'`，否则为 NULL | | `is_signed(binary)` | `BOOLEAN` | 是否存在 PE Authenticode / Mach-O 代码签名 (ELF → `false`) | | `entry_point(binary)` | `UBIGINT` | 入口点虚拟地址 | | `machine(binary)` | `VARCHAR` | 架构，例如 `'X86_64'`，`'ARM64'` | | `compile_timestamp(binary)` | `TIMESTAMP` | PE `TimeDateStamp`；对于 ELF/Mach-O 为 NULL | | `section_count(binary)` | `INT` | 节 (section) 数量 | | `overall_entropy(binary)` | `DOUBLE` | 整个文件的香农熵，范围为 `[0, 8]` | | `imphash(binary)` | `VARCHAR` | 用于聚类的 PE 导入哈希；否则为 NULL | ### 表函数（输入一个二进制文件，输出多行） | 函数 | 列 | |---|---| | `sections(binary)` | `name, virtual_size, raw_size, entropy, characteristics` | | `imports(binary)` | `library, function` | | `exports(binary)` | `name, address` | | `strings(binary, min_len := 5)` | `seq, value` | `characteristics` 是一个逗号分隔的 PE 节标志字符串（例如 `CNT_CODE,MEM_EXECUTE,MEM_READ`），对于 ELF / Mach-O 为空。对于 ELF / Mach-O 的 `imports`，`library` 为空，而 `function` 是每个导入的符号名称；对于 PE，`library` 是 DLL，而 `function` 是符号 (symbol)（或 `ordinal#N`）。 ## 不受信任的输入 —— 这是核心所在 每个样本都被假定为不受信任的，可能是恶意的，甚至是恶意软件。 该 worker **只读取和描述** 字节；它 **从不执行** 二进制文件，也从不解析任何外部引用（不加载导入的库，不遵循除了传递给它的字节之外的任何内容）。 健壮性契约： - **畸形 / 截断 / 非二进制** 的输入会降级为 **NULL**（标量函数）或 **无数据行**（表函数）—— 绝对不会崩溃，绝对不会报错，也绝对不会挂起。恶意输入是预期内的情况，而不是异常情况。 - **NULL** 输入 → NULL / 无数据行。 - 工作量是 **有界的**：超过 `MAX_INPUT_BYTES` (512 MiB) 的输入将被拒绝，并且 `strings` 提取器会对字符串数量和每个字符串的长度进行限制。 ## 测试固件 该测试套件针对提交在 `test/sql/data/` 下的几个微小的 **真实** 可执行文件运行 —— `hello.exe` (PE32+, mingw)、`hello_elf` (ELF, `zig cc`)、`hello_macho` (Mach-O, 原生 `cc`) 和 `garbage.bin` (恶意情况)。它们由 `tests/fixtures.py` (`make fixtures`) 生成，该脚本为每个目标编译一个微型 C 程序，并将 PE 的 `TimeDateStamp` 修补为固定的 epoch + 使用 LIEF 重建，从而使提交的 PE 具有字节确定性。测试代码只 *读取* 提交的文件，因此运行该套件不需要编译器。 ## 开发 ``` uv sync --extra dev uv run pytest -q # unit: pure core + Client RPC scalars + in-proc tables make test-sql # E2E: haybarn-unittest over test/sql/* (authoritative) make test # both uv run ruff check . && uv run mypy vgi_pe/ ``` ## 许可协议 `vgi-pe` 自身的代码采用 **MIT** 协议。它依赖于 **LIEF**（即 `lief` PyPI wheel），该库采用 **Apache-2.0** 协议 —— 这是一个没有 copyleft 义务的宽松许可证，作为普通的、未经修改的、独立安装的依赖项使用。一切都是纯离线的（无网络），因此该套件运行起来既快又具备隔离性。 ## 作者与许可 由 [Query.Farm](https://query.farm) 编写。 版权所有 2026 Query Farm LLC - https://query.farm

标签：DAST, DuckDB, ELF文件, PE文件, 云安全监控, 恶意软件分析, 逆向分析, 逆向工具, 静态分析