fission-systems/fission-benchmark

## 概述 每个反编译器都在一个独立的 Docker 容器中运行，并对外提供统一的 HTTP API。 一个 Python 运行器并行发送反编译请求，将结果与原始 C 源代码进行对比评分，并生成比较报告。 **基准测试优先：** 此仓库的主要任务是保证测量的真实性，而不是发布 Fission 的功能。有关操作指南和标准集合契约，请参阅 [docs/BENCHMARK_OPERATING.md](docs/BENCHMARK_OPERATING.md)。 **仪表盘（拆分）：** | 路由 | 界面 | |-------|---------| | `/` | 概览 — 语义排名中心 + 导航 | | `/same-function` | 同函数矩阵（边界真实性） | | `/functions` | 按函数划分的代码网格 | | `/variants` | 编译器 × 优化级别透视 | | `/fission-vs-ghidra` | Fission ↔ Ghidra 分层一致性（共享 IR；不参与排名） | ``` Binary + Source (ground truth) ↓ ┌──────────────────────────────────────────────────────────────┐ │ runner.py (parallel httpx requests) │ │ Fission :8000 · Ghidra :8001 · Boomerang :8002 · Radare2 :8003 │ │ angr :8004 · Snowman :8005 · rev.ng :8006 · Reko :8008 · RetDec :8009 │ └──────────────────────────────┬───────────────────────────────┘ │ ↓ scoring.py (correctness score + consensus) ↓ render_report.py → results/latest.md + docs/index.html ↓ Vercel (official runs only) → fission-benchmark.vercel.app ``` ## 运行有效性 每个结果文件都通过两层判定进行评估： | 层级 | 含义 | CLI 退出状态 | |---|---|---| | `valid` | 测量质量合格 — 矩阵完整，Fission ≥ 90%，所有后端 ≥ 90% | — | | `publishable` | `valid`（有效）且使用 `--run-mode official` 且无来源问题 | Vercel 部署所必需 | **冒烟测试**（`--run-mode smoke`，在 push 时默认运行）会产生 `valid=True, publishable=False` — 工作流显示为绿色（通过），但不会发布任何内容。**官方运行**（`--run-mode official`，每周定时或手动触发）在部署前还必须通过可发布性检查。 ``` # 直接评估结果文件 python -m runner.run_validity results/dev_latest.json \ --github-env "$GITHUB_ENV" \ --github-summary "$GITHUB_STEP_SUMMARY" # 输出：MEASUREMENT_VALID=true/false, RUN_PUBLISHABLE=true/false ``` ## 防止过拟合（3层） | 层级 | 机制 | |---|---| | **训练集/留出集** | 80/20 的函数级别拆分（固定随机种子）。使用 `--corpus holdout` 进行留出集评估。 | | **跨编译器** | 相同源码分别使用 gcc -O0 和 gcc -O2 编译 — 独立评估 | | **多反编译器共识** | 如果所有反编译器得分都很低 → `⚪ 全局偏低 (harness)`。仅 Fission 得分低 → 质量差距。 | ## 快速开始 ### 环境要求 - Docker + Docker Compose - Python 3.11+ - GCC 兼容的 C 编译器 + `nm`（用于生成语料库二进制文件/地址），或使用下方 Docker 化的语料库构建器 - `pip install -e ".[dev]"` ### 运行 ``` # 构建 decompiler 容器 docker compose build # 构建 corpus 二进制文件并填充每个函数的地址 python scripts/build_corpus.py --split dev # 在 macOS/Apple Silicon 上，改为构建 Windows x86-64 PE corpus 二进制文件。 docker compose --profile tools run --rm corpus-builder # 启动容器 docker compose up -d # 等待健康检查 curl http://localhost:8001/health # Ghidra curl http://localhost:8003/health # Radare2 curl http://localhost:8010/health # MinGW/Wine semantic oracle # 运行 benchmark（smoke，仅限 candidate JSON —— 不会覆盖 latest.*） ORACLE_ENDPOINT=http://localhost:8010 python runner/runner.py --corpus dev # 官方可发布路径（需要容器 + 完整矩阵，无限制）： # ORACLE_ENDPOINT=http://localhost:8010 python runner/runner.py \ # --corpus dev --run-mode official --output results/dev_latest.json # ORACLE_ENDPOINT=http://localhost:8010 python runner/runner.py \ # --corpus holdout --run-mode official --output results/holdout_latest.json # python runner/holdout_report.py \ # --dev results/dev_latest.json --holdout results/holdout_latest.json \ # --json-output results/overfitting_report.json # python -m runner.publication_gate \ # --dev results/dev_latest.json \ # --holdout results/holdout_latest.json \ # --overfitting results/overfitting_report.json \ # --output results/publication-verdict.json ``` ### 选项 ``` # 单函数 smoke 测试 python runner/runner.py --corpus dev --limit 1 # 仅限特定 decompiler python runner/runner.py --corpus dev --decompilers fission,ghidra # 完整的 core decompiler 集合 python runner/runner.py --corpus dev \ --decompilers fission,ghidra,boomerang,radare2,angr,snowman,revng,reko,retdec # 通过环境变量跳过特定 decompiler FISSION_ENDPOINT=skip python runner/runner.py --corpus dev GHIDRA_ENDPOINT=skip python runner/runner.py --corpus dev # 将 decompiler 指向自定义 endpoint GHIDRA_ENDPOINT=http://localhost:9001 python runner/runner.py --corpus dev FISSION_ENDPOINT=http://localhost:9000 python runner/runner.py --corpus dev # 支持任何 {NAME}_ENDPOINT 变量： # BOOMERANG_ENDPOINT, RADARE2_ENDPOINT, ANGR_ENDPOINT, # SNOWMAN_ENDPOINT, REVNG_ENDPOINT, REKO_ENDPOINT # Holdout 评估（仅限发布 —— 开发期间绝不执行） python runner/runner.py --corpus holdout # 完整 corpus（dev + holdout 组合） python runner/runner.py --corpus full # 显式 run mode python runner/runner.py --corpus dev --run-mode official # marks as publishable candidate python runner/runner.py --corpus dev --run-mode smoke # default, no publish gate python runner/runner.py --corpus dev --run-mode local # local dev, non-official # 保存到自定义路径（绝不覆盖 latest.*） python runner/runner.py --corpus dev \ --output results/dev_latest.json # 最终 publication gate（需要独立有效的证据） python -m runner.publication_gate \ --dev results/dev_latest.json \ --holdout results/holdout_latest.json \ --overfitting results/overfitting_report.json \ --output results/publication-verdict.json # 仅在带有链接的最终裁决时才进行提升 python runner/render_report.py \ --input results/dev_latest.json \ --corpus dev \ --publication-verdict results/publication-verdict.json \ --update-latest # promotes to latest.json + latest.md + docs/index.html ``` ### 本地 Fission 构建（仅用于质量循环） CI 始终使用 **GitHub Release** 的 Fission 烘焙版本 (`FISSION_SOURCE=release`)。 对于日常的反编译器工作，您可以将**当前的 Linux 版 `fission_cli` + `utils/`** 挂载到同一个适配器中： ``` # 1) 构建 / 收集 Linux ELF CLI + utils（非 macOS Mach-O）。 scripts/prepare_local_fission.sh # 可选：FISSION_ROOT=/path/to/Fission # 可选：FISSION_LINUX_CLI=/path/to/linux/fission_cli # 可选：FISSION_FORCE_DOCKER_BUILD=1 # macOS 提示：brew install zig && cargo install cargo-zigbuild --locked # 2) 仅使用 local overlay 启动 Fission adapter set -a && source .env.local && set +a docker compose -f docker-compose.yml -f docker-compose.local.yml \ --profile local up -d --build fission # 3) 确认来源 curl -s "http://localhost:${FISSION_HOST_PORT:-8007}/health" # → "source": "local", "git_sha": "...", "release_version": "local-" # 4) 度量到非 latest 路径（不要覆盖官方 latest） python runner/runner.py --corpus dev --decompilers fission \ --output "results/local_${FISSION_GIT_SHA}.json" ``` **规则** | 路径 | Fission 二进制文件 | 结果 | |---|---|---| | CI 官方运行 → Vercel | 仅限 Release tag | 官方时间线 | | 本地质量循环 | 当前构建 (Linux ELF) | 仅限 `results/local_.json` | ## 仓库结构 ``` fission-benchmark/ ├── benchmark/ │ ├── KNOWN_ISSUES.md Infrastructure freeze policy and remaining trust gaps │ ├── decode_parity/ Instruction decoder parity runner │ ├── assembly_parity/ Instruction listing parity runner │ ├── pcode_parity/ Raw p-code parity runner │ ├── cfg_parity/ Basic block/edge parity runner │ ├── function_discovery/ Binary-level function discovery parity │ ├── ir_invariants/ Fission-internal IR invariant checks │ ├── golden_repros/ Fixed regression canary runner │ ├── telemetry/ JSONL result aggregation │ ├── readability/ Readability proxy metrics and human-study plan │ ├── decompiler_quality/ Current output-quality stage marker │ └── common/ Shared schemas, providers, JSONL helpers ├── docker/ │ ├── ghidra/ Ghidra 12.x headless + FastAPI │ ├── boomerang/ Boomerang + FastAPI │ ├── radare2/ Radare2 + r2ghidra + FastAPI │ ├── fission/ Fission CLI + FastAPI (release bake; local mount overlay) │ ├── angr/ angr decompiler + FastAPI │ ├── snowman/ Snowman/nocode + FastAPI │ ├── revng/ rev.ng + FastAPI │ ├── reko/ Reko + FastAPI │ └── retdec/ RetDec v5 + FastAPI ├── runner/ │ ├── runner.py Candidate-run orchestrator (--corpus, --run-mode) │ ├── corpus.py Corpus management + holdout split │ ├── scoring.py Correctness score + structural metrics │ ├── run_validity.py Shared validity engine (measurement_valid / publishable) │ ├── publication_gate.py Final dev + holdout + oracle evidence gate │ ├── render_report.py Non-destructive report renderer (--update-latest) │ ├── readability.py AST-based readability proxy metrics │ └── report.py Markdown + HTML report generation ├── scripts/ │ ├── build_corpus.py Compile corpus binaries + update function addresses │ ├── populate_holdout.py Deterministic 80/20 holdout lock from dev manifests │ └── migrate_legacy_results.py Wrap legacy flat-list JSON as envelope v2 ├── corpus/ │ ├── dev/ 80% — development corpus (source + manifests) │ └── holdout/ 20% — holdout corpus (release evaluation only) ├── docs/ Dashboard static files (committed by CI, served via Vercel) ├── results/ Benchmark results (auto-committed by official CI runs) ├── tests/ Unit and integration tests │ ├── test_run_validity.py Validity engine tests (28 cases) │ ├── test_render_report.py Legacy correctness migration tests │ └── test_report_integration.py Report generation integration tests ├── vercel.json Vercel static site config (serves docs/) └── .github/ └── workflows/ ├── benchmark.yml Smoke (push) + official (schedule/dispatch) runs └── build-check.yml Docker build validation ``` ## Fission 发布追踪 CI 默认设置 `FISSION_SOURCE=release` 并固定 `FISSION_VERSION=v0.1.6`。 这使得定时、push 和手动运行保持可复现性，直到仓库声明的基线被刻意更新。`/health` 探针必须报告 `"source": "release"`（如果是 `local-*` 则 CI 会失败）。 ### 首选操作路径 (GitHub CLI) 将发布版 CLI 烘焙到 GHCR 中，然后链接一次官方基准测试（Publish Images 在 fission 烘焙成功后会自动进行链接）： ``` # 1) 为 SemVer tag 构建 fission 镜像（同时链式执行 Benchmark & Deploy） gh workflow run "Publish Images" \ --repo fission-systems/fission-benchmark \ -f services=fission \ -f fission_version=v0.1.6 # 2) 官方排名 + Pages（快速路径：仅限 fission+ghidra） gh workflow run "Benchmark & Deploy" \ --repo fission-systems/fission-benchmark \ -f fission_version=v0.1.6 \ -f corpus=dev \ -f run_mode=official \ -f publish_results=true \ -f matrix_profile=core_c_pe \ -f decompilers=fission,ghidra \ -f parity_limit=40 # 3) 多 decomp UI 快照（慢速：9 个工具；按需 smoke 或 core） gh workflow run "Benchmark & Deploy" \ --repo fission-systems/fission-benchmark \ -f fission_version=v0.1.6 \ -f run_mode=official \ -f publish_results=false \ -f matrix_profile=smoke \ -f decompilers=fission,ghidra,boomerang,radare2,angr,snowman,revng,reko,retdec # 4) 语言 pivots（每周默认值：full_matrix，双工具并行 fan-out） gh workflow run "Benchmark & Deploy" \ --repo fission-systems/fission-benchmark \ -f fission_version=v0.1.6 \ -f run_mode=official \ -f publish_results=true \ -f matrix_profile=full_matrix \ -f decompilers=fission,ghidra ``` ### 性能分级 | 路径 | 配置 | 反编译器 | 典型实际耗时 | 是否发布排名？ | |------|---------|-------------|--------------------|--------------------| | push | smoke | 9-tool | ~15–40m | 否（仅多重信封） | | release / manual | core_c_pe | **fission+ghidra** | ~30–70m | 是 | | weekly schedule | full_matrix | fission+ghidra | ~1–3h（并行分片） | 是 + 语言透视 | | optional multi | smoke/core | 9-tool | 长 | 仅 Multi UI | 运行器已经按 `(decompiler, binary)` 对反编译任务进行了批处理。Ghidra 复用了**内容哈希项目缓存**来进行批量反编译（无需按请求进行冷导入）。 ### 从 Fission 跨仓库调度 `repository_dispatch` (`fission-release`) 仅启动 **Publish Images**（避免 在镜像存在之前与基准测试产生竞争）。烘焙完成后，CI 会使用相同的版本运行 `gh workflow run "Benchmark & Deploy"`。 ``` # 正确的 client_payload 结构（必须是 JSON 对象，而不是字符串）： gh api repos/fission-systems/fission-benchmark/dispatches --input - <<'EOF' { "event_type": "fission-release", "client_payload": { "fission_version": "v0.1.6" } } EOF ``` 手动运行工作流可以使用另一个特定的 tag 覆盖 `fission_version`， 或者使用 `latest` 来动态解析最新的 GitHub Release。 ## CI 工作流 | 触发器 | 运行模式 | 是否发布？ | |---|---|---| | `push` 到 `main` | `smoke` (9-tool) | 否 — 仅多重信封 | | 每周定时 (`cron`) | `official` full_matrix (2-tool) | 是 — 排名 + 语言透视 | | 手动排名 | `official` core_c_pe (2-tool) | 是 — 如果通过有效性检查 | | 手动多重测试 | 9-tool smoke/core | Multi UI（可选） | | `fission-release` 调度 | Publish Images → 链式排名 | 是 — 2-tool core_c_pe | 通过有效性检查的官方运行会提交 `results/` + `docs/`，并通过 Vercel CLI 部署到 **https://fission-benchmark.vercel.app**。 ## API 契约 所有反编译器容器对外提供： ``` POST /decompile Body: { "binary_b64": "", "addr": "0x1400010a0" } Response: { "decompiler": "ghidra", "name": "fibonacci", "code": "...", "time_ms": 120, "error": null } GET /health Response: { "status": "ok", "decompiler": "ghidra", "version": "12.0" } # Fission 也会报告来源： # { "status": "ok", "decompiler": "fission", "version": "...", # "release_version": "v0.1.6"|"local-", # "source": "release"|"local", "git_sha": "" } ``` ## 添加新的反编译器 1. 创建 `docker//Dockerfile` + `server.py`，实现上述 API 契约 2. 将服务添加到 `docker-compose.yml` 中的下一个可用端口 3. 添加到 `runner/runner.py` 中的 `DECOMPILERS` 字典 4. 添加到 `build-check.yml` 矩阵中 ## 核心开源后端 基准测试将每个配置的开源后端都视为核心比较集的一部分。在本地调试时，仍然可以使用 `*_ENDPOINT=skip` 或通过传递更窄的 `--decompilers` 列表来显式跳过单个服务。 | 后端 | 端口 | 备注 | |---|---:|---| | `ghidra` | 8001 | Ghidra 12.x headless，主要参考基准 | | `boomerang` | 8002 | Boomerang CLI，面向函数入口 | | `radare2` | 8003 | Radare2 + r2ghidra | | `angr` | 8004 | Python API，面向函数地址 | | `snowman` | 8005 | 使用 `nocode`；传统基准，仅限 amd64 | | `revng` | 8006 | 使用 `emit-c-as-single-file`（传统方式：`decompile-to-single-file`）；面向整个程序 | | `reko` | 8008 | Reko 反编译器 | | `retdec` | 8009 | RetDec v5（范围注释切片 + 地址锚点） | 托管的 CI 默认运行完整的核心集合，并在可用时优先拉取预构建的 GHCR 镜像，然后再回退到本地构建。 ## 分层质量门禁 反编译器相似度是基准测试的最后一层。在诊断 Fission 回归问题时，应首先运行较低级别的门禁： 1. `benchmark/assembly_parity` 比较来自两个汇编列表提供者的指令字节、助记符、操作数、长度和分支目标。 2. `benchmark/decode_parity` 比较解码字段，如指令长度、前缀、ModRM/SIB、位移和立即数。 3. `benchmark/pcode_parity` 比较来自两个提供者的原始 p-code 操作序列，通常是 Ghidra 原始 p-code 与 Fission SLEIGH 运行时输出之间的比较。 4. `benchmark/cfg_parity` 比较基本块和控制流边。 5. `benchmark/function_discovery` 是**函数查找**基准测试（清单一致性：地址集 + 双重召回率/精确率；Ghidra / PE / manifest 引用）。 6. `benchmark/ir_invariants` 在没有外部参考提供者的情况下检查 Fission 内部的 IR/NIR/HIR 不变量。 7. `benchmark/golden_repros` 运行固定的回归金丝雀测试。 8. `benchmark/telemetry` 按阶段、状态、不匹配类型、编译器和优化级别聚合 JSONL 行。 9. `runner/` 依然是反编译器输出质量的基准测试。 基准测试基础设施目前处于可靠性维护模式。在添加新维度、默认反编译器或综合排名之前，请查看 `benchmark/KNOWN_ISSUES.md`。 一致性阶段默认为**通过 Docker HTTP 进行 Ghidra 与 Fission 的对比**（参见 `benchmark/README.md`）。命令模板对于自定义工具仍然是可选的。 ``` # 前提条件：docker compose up -d ghidra fission export FISSION_HOST_PORT=8007 # if local overlay maps fission to 8007 # 单个阶段（HTTP 默认值） python -m benchmark.assembly_parity.run --limit 5 python -m benchmark.decode_parity.run --limit 5 python -m benchmark.pcode_parity.run --limit 5 python -m benchmark.cfg_parity.run --limit 5 python -m benchmark.function_discovery.run --limit 5 # 多工具 + 摘要： # python -m benchmark.function_discovery.run --candidates fission,radare2 --limit 5 # python -m runner.function_discovery_report results/function_discovery/latest.jsonl --print # 统一 runner → results/*_parity/latest.jsonl + telemetry python -m runner.run_parity --corpus dev --limit 5 --decompilers fission,ghidra python -m benchmark.telemetry.aggregate \ results/assembly_parity/latest.jsonl \ results/cfg_parity/latest.jsonl \ results/pcode_parity/latest.jsonl ``` ## 添加语料库用例 1. 在 `corpus/dev/source/` 下添加一个 C 源代码文件 2. 在 `corpus/dev/manifests/` 下添加一个清单，每个函数对应一个条目 3. 使用稳定的编译器变体，例如 `gcc -O0` 和 `gcc -O2` 4. 在进行基准测试之前运行 `python scripts/build_corpus.py --split dev` 构建脚本会在 `corpus/dev/binaries/` 下编译被忽略的本地二进制文件，并使用 `nm` 刷新每个变体的 `addr`。运行器会针对匹配的源函数进行评分，而不是整个源文件。 ## 标准指标集 公开报告遵循固定的架构 (`summary.schema = standard-set-v1`)： ### MVP（主要界面） | # | 指标 | 描述 | |---|---|---| | 0 | **同函数矩阵** | 请求契约 `(binary, addr)`；`same_function_rate = direct / (direct + boundary_*)`；核心 (fission+ghidra) 对比多重测试；**基础设施真实性**，不是语义排名的替代品 | | 1 | **语义通过率** | 在提供 PE+addr 时，`original_binary` 下的预言机测试通过率；唯一的排名维度 (`correctness_score`) | | 2 | **覆盖率** | 已尝试 / 适配器清理 / 无效边界 / 已测试语义 / 无 wrapper | | 3 | **失败分类** | 互斥的桶（`adapter_error`、`whole_program_output`、`compile_error` 等） | | 4 | **CFG 匹配** | 来自 `benchmark/cfg_parity` 的可选次要指标（不参与排名） | | 5 | **运行时** | 平均 `time_ms` | ### 扩展 | # | 指标 | 描述 | |---|---|---| | 6 | **留出集 + 过拟合** | 锁定的 80/20 拆分 + `holdout_report` / `publication_gate` | | 7 | **跨编译器 / 优化** | 按 `compiler_variant` 进行语义透视 | | 8 | **人类可读性** | 研究计划 + `benchmark/readability/study_pack/`（尚无最终得分） | | 9 | **真实世界剥离** | 预留的 `corpus/realworld/` 追踪通道 | ### 仅用于诊断（不参与排名） | 指标 | 描述 | |---|---| | **源码相似度** | 对规范化后的文本进行 `difflib.SequenceMatcher` 操作 —不是**语义准确度 | | **结构惩罚** | 相对于源码的 goto / 嵌套情况 | | **可读性代理指标** | 在进行人类研究之前未经验证 | 构建器：`runner/standard_summary.py`。仪表盘主表省略了相似度。 预言机服务在匹配的 Windows x86/x86-64 MinGW ABI + Wine 下支持两个测试对象： | `oracle_subject` | 参考端 | 使用时机 | |---|---|---| | `original_binary` | 在提供的语料库 PE 中调用位于 `function_addr` 的函数（手动处理 PE 内存映射 + 重定位/导入） | 运行器始终提供 `reference_binary_b64` + `function_addr` — **对于可发布的运行是必需的** | | `source_recompile` | 将提取的 C 源代码重新编译作为参考 | 在省略 PE 字节/地址时的回退方案（仅用于诊断） | 发布有效性 (`oracle_evidence_valid`) 仅接受带有 `oracle_subject: original_binary` 的聚合证据。官方运行还需要 `profile: realistic`， 完整的矩阵（不带 `--limit` / `--function`），非空的留出集，关联的过拟合 报告，以及 `publication_gate` 成功。 ## 结果信封格式 所有结果文件都使用带有版本控制的信封 (`schema_version: 2`)： ``` { "schema_version": 2, "run": { "started_at": "2026-07-11T00:00:00Z", "finished_at": "2026-07-11T00:05:00Z", "duration_ms": 300000, "runner_commit": "abc1234", "corpus": "dev", "official": true }, "matrix": { "expected_decompilers": ["fission", "ghidra"], "expected_cells": [ { "decompiler": "fission", "function_name": "foo", "compiler_variant": "gcc -O0" } ], "expected_rows": 2, "observed_rows": 2 }, "validity": { "valid": true, "publishable": true, "fission_coverage": 1.0, "reasons": [], "publish_reasons": [] }, "rows": [ ... ] } ``` 遗留的扁平列表文件支持渲染，但始终被标记为 `publishable: false`。 ## 许可证 AGPL-3.0-or-later ### 速度微基准测试（不参与排名） 专用的冷/热反编译计时（**不**更新语义排名或 Pages）： ``` # 本地（adapter 已启动） python -m runner.speed_microbench \ --endpoint fission=http://localhost:8000 \ --endpoint ghidra=http://localhost:8001 \ --binary corpus/dev/binaries/c/SOME_gcc_O0.exe \ --addr 0x140001000 --addr 0x140001050 \ --trials 5 \ --output results/speed/microbench_latest.json # CI gh workflow run "Speed Smoke" --repo fission-systems/fission-benchmark \ -f fission_version=v0.1.6 \ -f trials=5 \ -f decompilers=fission,ghidra ``` 信封附件：`attach_summary_to_envelope` 会写入 `summary.extensions.speed`（行 `time_ms` 聚合 + 可选的微基准数据，来自 `results/speed/microbench_latest.json`）。仪表盘的 `/speed` 会同时显示这两者。

标签：Docker, Python, 云资产清单, 反编译器, 安全防御评估, 性能基准测试, 无后门, 请求拦截, 运行时操纵, 逆向工具, 逆向工程