copyleftdev/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 stderr 的解析器（堆缓冲区溢出、栈缓冲区溢出、堆使用后释放、双重释放、无效释放、栈使用后释放（返回/作用域））。支持传统的 `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`），可对任意用户提供的谓词进行输入缩减。 - 内存中的语料库，采用香农熵加权选择（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")`，以确保配置错误时明显失败。 - `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` 还需要系统路径中有 `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）、整数溢出未定义行为（UBSan）或对象内溢出，也不会预测可利用性。详见 SPEC §14，了解本工具无法识别的完整列表。 ## 许可证 Apache-2.0 或 MIT（双重许可）。

标签：AddressSanitizer, ASan, ddmin, Docker支持, double-free, Frida, Fuzzing, invalid-free, JSON, libFuzzer, QASan, QEMU, RE, Rust, sanitizer, use-after-free, Waymore结果处理, 二进制分析, 云安全运维, 内存安全, 内存审计, 内存损坏, 内联执行, 反向工程, 可视化界面, 固件审计, 堆溢出, 崩溃报告, 情报收集, 栈溢出, 漏洞研究, 编译器, 网络流量审计, 自动化分析, 跨站脚本, 身份验证强制, 通知系统