Karib0u/capa-x

# capa-x capa-x 是一个独立的原生 Rust 实现，对应 [Mandiant capa](https://github.com/mandiant/capa) 静态后端。它在分析时 无需 Python 即可运行未经修改的 capa 规则。它不隶属于 Google LLC 或 Mandiant, Inc.， 也未获得其认可。 - 支持 x86/x64 PE、ELF、.NET/CLR、原始 shellcode 和 capa freeze 文件， 外加 x86_64/AArch64 Mach-O（`-f macho`，一个 capa-x 扩展——见下文） 以及原生 AArch64 PE/ELF。 - 在任何 `--jobs` 值下都能产生确定性输出。 - 对于不支持的输入和未知的规则语法，会结合上下文信息报错。 - 在 200 个样本的评估语料库中，与锁定的 Python capa 9.4.0 达到了 98.55% 的规则级一致性。 Python capa 是行为参考标准。capa-x 是一个原生后端，并不能完全 替代所有的 capa 输入格式。已接受的后端差异 记录在 [KNOWN_DIVERGENCES.md](KNOWN_DIVERGENCES.md) 中。 ## 支持的输入 | 输入 | 状态 | 参考 | |---|---|---| | PE x86/x64 | 支持 | Python capa 9.4.0, Vivisect | | PE AArch64 (`IMAGE_FILE_MACHINE_ARM64`) | 支持 —— **capa-x 扩展** | 无 Python oracle；见下文 | | ELF x86/x64 | 支持 | Python capa 9.4.0, Vivisect | | ELF AArch64 | 支持 | 无原始 AArch64 的 Python oracle；基于 Ghidra BinExport2 验证 | | .NET / CLR 托管 PE | 支持 | Python capa 9.4.0, `dnfile` | | 原始 shellcode，32/64 位 | 支持 | Python capa 9.4.0, `sc32`/`sc64` | | capa freeze 文件 | 支持 | Python capa 9.4.0 | | Mach-O x86_64/arm64/arm64e（精简或胖二进制，`-f macho`） | 支持 —— **capa-x 扩展** | 无 Python oracle；见下文 | | IDA, Ghidra, Binary Ninja, BinExport | 非目标 | 原生输入才是重点 | 不支持的输入绝不会被静默接受或进行部分分析。 锁定的 capa 9.4.0 根本不接受 Mach-O 作为原始输入，因此 `-f macho` 是一个有文档记录的 capa-x 扩展，而不是一致性声明：它绝不会 被 `-f auto` 选中（该选项完全镜像了上游自有的 PE/ELF/freeze 检测 顺序），必须显式请求。capa 的特性语义 仍然支配着特性的含义；精简和胖（`--arch` 选择一个切片， `auto` 接受胖头顺序中第一个支持的切片）x86_64、`arm64` 和 `arm64e` Mach-O 均受支持。 原生 AArch64 解码、恢复和特征提取（基于 `disarm64`， 运行时无需 Ghidra/IDA/Binary Ninja/BinExport）涵盖了 ELF、Mach-O 和 PE —— 相同的解码器和恢复核心，与每种容器 格式的现有加载器相结合。锁定的 capa 9.4.0 完全没有原始 AArch64 输入 （它自身的 AArch64 支持仅限 BinExport2），因此 AArch64 PE 和 Mach-O 带有 与 x86_64 Mach-O 相同的“capa-x 扩展，无 Python oracle”的注意事项； AArch64 ELF 则基于锁定的 Ghidra BinExport2 固件语料库进行验证， 结果记录在兼容性证据中。 CLR PE 会被自动检测，并优先路由至 `.NET` 后端，而不是原生 x86 提取器（`-f pe` 会覆盖此行为并强制走 x86 路径，而 `-f dotnet` 会强制走 `.NET` 路径）。混合模式程序集（一个二进制文件中包含 托管 + 非托管代码）仅分析其托管方法 —— 不存在进入原生部分的跨 runtime 调用图，这符合 上游 capa 自身的 `dnfile` 提取器行为。该文件带有“混合模式” 特性特征，并且混合模式程序集在其他方面的检测和 分析与完全托管的程序集相同。 ## 兼容性矩阵 上表按格式列出了所有输入；而下表将相同的输入 按 *capa-x 对它们作出的声明类型* 进行分组 —— 忽略这种 区别正是移植项目过度声明的开端。 | 类别 | 成员 | Oracle | |---|---|---| | 上游一致性原始输入 | PE, ELF, shellcode (x86/x64), .NET/CLR | 直接与 Python capa 9.4.0 比较，记录在 `docs/BENCHMARKS.md` | | 跨后端一致性 | AArch64 ELF | 无原始 AArch64 的 Python oracle；基于锁定的 Ghidra BinExport2 进行特性和规则级比较，方法见 [docs/BENCHMARKS.md](docs/BENCHMARKS.md) | | capa-x 扩展 | Mach-O (x86_64, AArch64), AArch64 PE | 完全没有 Python oracle —— 锁定的 capa 9.4.0 没有原始 Mach-O 或 AArch64 输入；基于手动构建的结构/特性固件语料库进行验证（见 [docs/BENCHMARKS.md](docs/BENCHMARKS.md)），从不声称与上游一致 | | 已接受的差异 / 非目标 | Vivisect 绑定的恢复缺口，其他 ISA，实时动态提取器 | [`KNOWN_DIVERGENCES.md`](KNOWN_DIVERGENCES.md)（13 个已查明根本原因的类别） | ## 安装 从 [GitHub Releases](https://github.com/Karib0u/capa-x/releases) 下载归档文件，解压， 然后运行： ``` ./capa-x sample.exe ./capa-x -j sample.exe ``` 发布归档文件包含锁定的规则。在源码检出中，规则 位于 `./rules`。对于其他目录结构，请将 `rules/` 放在二进制文件旁，通过 `--rules` 传入，或设置环境变量 `CAPA_RULES_DIR`。 ## 快速开始 ``` # 人类可读的结果 capa-x sample.exe # Canonical JSON 结果文档 capa-x -j sample.exe # .NET / CLR 托管 PE（自动检测；-f dotnet 强制启用） capa-x sample.exe capa-x -f dotnet sample.exe # 原始 shellcode capa-x -f sc32 shellcode.bin capa-x -f sc64 shellcode.bin # 冻结输入 capa-x -f freeze sample.frz # 显式并行 capa-x --jobs 4 sample.exe ``` 运行 `capa-x --help` 以查看架构和操作系统覆盖、标签过滤、自定义 签名、详细程度以及输出选项。 分析过程不会执行任何网络访问。规则仅通过 显式命令下载： ``` capa-x fetch-rules ./rules ``` ## 从源码构建 需要 Rust 1.87 或更高版本。 ``` git clone https://github.com/Karib0u/capa-x.git cd capa-x git submodule update --init --depth 1 rules cargo build --release target/release/capa-x --version ``` 庞大的测试语料库和 Python 参考子模块仅在 差异开发时需要。`scripts/setup_dev.sh` 会安装该环境。 ## Python 绑定 [`capa-x-python/`](capa-x-python/) 是基于相同的 分析代码构建的进程内 Python 扩展 —— 无需子进程，分析时无需 Python， 也没有任何重新实现。使用 [maturin](https://www.maturin.rs/) 在本地构建它： ``` pip install maturin cd capa-x-python maturin develop --release ``` ``` import capa_x rules = capa_x.Rules.from_directory("rules") # parse + validate once result = capa_x.analyze("sample.exe", rules) # load once, scan many print(sorted(result["rules"].keys())) ``` `analyze()` 返回上游 capa 自身的 `ResultDocument` schema 作为纯 `dict` —— 与 `capa-x -j` 打印的形状相同，也与 `capa.render.result_document.ResultDocument.model_validate_json` 接受的 未修改形状一致（见 [`capa-x-python/README.md`](capa-x-python/README.md)）。预构建的 wheels（linux x86_64/aarch64，macOS x86_64/arm64，Windows x86_64）由 [`release.yml`](.github/workflows/release.yml) 在每次打标签时构建；每次推送 都会进行一次成本更低的仅限 linux 的构建以及相同的 schema 验证检查。 ## 准确性与局限性 针对发布树与 Python capa 9.4.0 及 锁定规则进行差异运行： | 指标 | 结果 | |---|---:| | 规则级一致性 | **98.55%** | | 匹配参考的规则 | 6,263 | | 差异规则 | 91：缺失 61 个，多出 30 个 | | 具有相同规则集的样本 | 161/200 (80.5%) | 规则级一致性处于领先地位，因为它衡量的是单个能力规则。 每一个测量到的差异都映射到了记录在案的根本原因。具体方法、 跨实现覆盖率、性能表以及复现命令 位于 [docs/BENCHMARKS.md](docs/BENCHMARKS.md)。 在受控的结果等价样本上，在五次测量运行中，capa-x 的中位数时间为 0.959 秒，Python capa 9.4.0 为 3.007 秒。在 10 个样本的并行语料库上，一个任务的总运行时间为 77.374 秒，使用默认 10 个任务时为 37.199 秒，每个样本的中位数加速比为 2.03 倍，最差的样本为 1.52 倍。这些是在配备 macOS 26.6 和 10 个逻辑 CPU 的 MacBook Pro M1 Max 上测量的结果，并非通用的 性能声明。 从 Python capa 迁移的用户偶尔会遇到 capa 匹配了某条规则，但 capa-x 却没有的情况；每一个已知案例都被编目在 [KNOWN_DIVERGENCES.md](KNOWN_DIVERGENCES.md) 中，且大多数受限于模拟器。 capa-x 尽最大努力跟踪上游 capa 版本；目前 锁定在 9.4.0，并且在锁定版本变更前，每一个受支持的上游版本都会使用 完整的差异测试套件进行重新验证。本项目由个人维护， 因此审查和安全响应时间均属尽力而为。 与之前的 Rust 移植不同，每一个结果都针对锁定的 Python capa 9.4.0 进行了差异测试：上述的规则级一致性涵盖了 200 个样本的语料库， 每一个差异规则都在 [KNOWN_DIVERGENCES.md](KNOWN_DIVERGENCES.md) 中单独查明根本原因。如果无法被测量，就 不作声明。 ## 复现证据 ``` scripts/setup_dev.sh cargo build --release cargo test --workspace cargo fmt --all -- --check cargo clippy --workspace --all-targets -- -D warnings python3 scripts/difftest.py --mode full \ --samples scripts/corpus-outer.txt --capa-cli target/release/capa-x \ --no-rust-cache python3 scripts/determinism.py \ --samples scripts/corpus-jobs.txt --capa-cli target/release/capa-x python3 scripts/bench.py \ --samples scripts/corpus-bench.txt --markdown ``` ## 文档与社区 - [架构](docs/ARCHITECTURE.md) - [设计决策](docs/decisions/) - [准确性与性能方法论](docs/BENCHMARKS.md) - [已知后端差异](KNOWN_DIVERGENCES.md) - [锁定的上游版本](PINNED.md) - [发布历史](CHANGELOG.md) - [贡献](CONTRIBUTING.md) - [安全政策](SECURITY.md) - [行为准则](CODE_OF_CONDUCT.md) 这是一个独立的实现，不隶属于 Google LLC 或 Mandiant, Inc.， 也未获得其认可。有关归属和 派生记录，请参阅 [NOTICE](NOTICE)。 基于 [Apache License 2.0](LICENSE) 授权。

标签：DAST, Rust, 云安全监控, 云计算, 云资产清单, 可视化界面, 威胁情报, 开发者工具, 恶意软件分析, 网络流量审计, 规则引擎, 逆向工具, 逆向工程, 通知系统, 静态分析