codetestcode/asan-harness

# asan-harness 一个用于驱动 AddressSanitizer 插桩目标并将其输出转换为可分类崩溃报告的 Rust harness。 专为逆向工程工作而构建，目标可能是 Rust crate、FFI 边界后的 C/C++ 库、在 QEMU 下运行的剥离二进制文件，或在 Unicorn 或 QEMU 系统模式下托管的固件镜像。 [SPEC.md](./SPEC.md) 包含了设计、数学模型和操作模式。本 README 涵盖已实现的内容、构建方法和使用方式。 ## 关于 `asan-harness` 位于内存安全 sanitizer 与人工分析员之间。 它读取目标输出的原始 sanitizer 事件，对每个事件进行分类（堆缓冲区溢出、释放后使用、双重释放等），在可用时附加分配与释放的溯源信息，并生成一个稳定的 JSON 报告，供下游工具（分类、最小化、重放）消费。 目标是构建一个适用于常见逆向工程模式的统一流水线： - 使用 `-fsanitize=address` 重新编译的源码可用的 Rust 或 C/C++ - 通过 Frida 插桩的闭源共享库 - 在 QEMU 下运行的 QASan 剥离二进制文件 - 在 Unicorn 或 QEMU 系统模式下托管的固件镜像 Sanitizer 的数学模型、不变量以及该工具能或不能检测的内容边界均在 `SPEC.md` 中完整记录。本仓库即为实现。 ## 状态 当前已实现： - 编译器运行时 AddressSanitizer 标准错误输出的解析器（堆缓冲区溢出、栈缓冲区溢出、堆使用后释放、双重释放、无效释放、栈使用后返回/作用域）。支持传统的 `to the right of` 表述以及 LLVM 20+ 的 `N bytes after` 形式。 - 带稳定 JSON 模式（`schema_version = 1`）的崩溃报告类型，基于前 N 个符号化帧的 FNV-1a-64 哈希去重，并按 SPEC §12.2 进行严重性排名。 - CLI：`doctor`、`ingest`、`triage`、`replay`、`minify`。 - 差分调试最小化器（`ddmin`），可对任意用户提供的谓词收缩输入。 - 带 Shannon 熵加权的语料库内存选择（SPEC §8.4）。 - 端到端演示：Rust 二进制文件使用 nightly `-Zsanitizer=address` **或** 使用 `clang -fsanitize=address` 编译的 C 库 → harness 摄入、聚类、重放。 尚未实现（存根）： - `asan-re-frida`（模式 B）、`asan-re-qemu`（模式 C）、`asan-re-firmware`（模式 D）。`Sanitizer` 特性的实现会返回 `SanError::Runtime("not yet implemented")`，因此配置错误的 harness 会明确失败。 - `asan-harness run` 和 `cov` 子命令。与 `libafl_libfuzzer` 的连接尚未就绪；`fuzz_target!` 宏会发出 libFuzzer ABI，但目前尚未驱动。 ## 构建 用于 harness 自身的稳定工具链： ``` cargo build --workspace cargo test --workspace ``` 两个演示 crate（`rust-asan`、`c-ffi-asan`）需要 nightly，因为它们依赖 `-Zsanitizer=address`： ``` RUSTFLAGS="-Zsanitizer=address" \ cargo +nightly build \ --target x86_64-unknown-linux-gnu \ -p rust-asan -p c-ffi-asan ``` `c-ffi-asan` 还需要 PATH 中有 `clang`；其 `build.rs` 会针对 `c/buggy.c` 调用 `clang -fsanitize=address -O0`。 ## 使用 针对真实 ASan 输出的端到端示例： ``` ./target/x86_64-unknown-linux-gnu/debug/rust-asan-demo hbo 2>asan.log cargo run -q --bin asan-harness -- ingest --file asan.log --out-dir crashes/ cargo run -q --bin asan-harness -- triage --dir crashes/ ``` 机器可读输出： ``` asan-harness --format json ingest --file asan.log asan-harness --format json triage --dir crashes/ ``` 针对合成谓词的最小化崩溃报告（独立运行，无需目标）： ``` asan-harness minify crash.json --keep-byte 0x41 --out crash.min.json ``` 完整流水线（构建两个演示程序，运行所有错误模式，断言产生六个不同的聚类）： ``` ./scripts/verify-asan.sh ``` ## 目录结构 ``` crates/ asan-core Sanitizer trait; shadow-memory math and invariants (§2). asan-alloc GlobalAlloc wrapper routing allocator events through a Sanitizer. asan-oracle CrashReport/CrashKind/Severity; FNV-1a dedup; ASan log parser. asan-driver Target/Oracle traits; fuzz_target! macro; replay runner; ddmin. asan-corpus Seed corpus with Shannon-entropy weighted selection (§8.4). asan-re-frida Mode B stub (closed-source .so via Frida). asan-re-qemu Mode C stub (stripped binary via QEMU/QASan). asan-re-firmware Mode D stub (firmware re-hosting). asan-cli `asan-harness` binary. examples/ demo Canned ASan fixtures → CrashReport → triage. rust-asan Rust binary with planted bugs; requires nightly ASan. c-ffi-asan C library (ASan-instrumented) + Rust FFI harness. scripts/ verify-asan.sh End-to-end pipeline verification. ``` ## 测试 ``` asan-oracle 20 tests (CrashReport, dedup, log parser, schema) asan-core 15 tests ( 9 proptest properties for shadow invariants) asan-driver 7 tests (Target/Oracle, replay, ddmin) asan-corpus 4 tests (entropy, rare-edge dominance, determinism) asan-alloc 2 tests ───────────────────── 48 tests passing ``` `cargo clippy --workspace --all-targets -- -D warnings` 通过无警告。 ## 范围 该 harness 报告 AddressSanitizer 观察到的内存安全事实。 它不会发现未初始化读（MemorySanitizer）、数据竞争（ThreadSanitizer）、整数溢出 UB（UBSan）或对象内溢出。也不会预测可利用性。详见 SPEC §14 本工具无法识别的完整列表。 ## 许可证 Apache-2.0 或 MIT（双重许可）。

标签：AddressSanitizer, asan-harness, corpus, crash report, ddmin, Delta调试, Docker支持, Double-Free, Frida, JSON报告, parser, QEMU, reverse engineering, Rust, Sanitizer, schema_version, Triage, Use-After-Free, 云资产清单, 内存安全, 内联执行, 可视化界面, 固件分析, 堆溢出, 崩溃分析, 无符号二进制, 熵权重选择, 网络流量审计, 身份验证强制, 逆向工程, 通知系统