cpprhtn/raon
GitHub: cpprhtn/raon
raon 是一个利用 LLM 在关键决策点辅助 C/C++ 漏洞发现的研究框架，整合了 sanitizer 模糊测试与多 agent 崩溃分类去重流程。
Stars: 1 | Forks: 0
# raon
raon 是一个用于在 C/C++ 中进行 LLM 辅助漏洞发现的研究框架。它会编译目标程序，在 sanitizers 下对它们进行模糊测试，并使用一组协作的 agent 将产生的崩溃进行标准化、去重和排序，最终转化为结构化的发现结果。语言模型被用于合成模糊测试 harness 和对发现结果进行推理，但绝不会在每次执行的循环中运行。raon 编排的是成熟的工具——clang/AddressSanitizer、libFuzzer，而不是重新实现它们。通过 angr 进行无源码（二进制）分析的功能也已包含在内，但目前仍处于实验阶段。
[](https://github.com/cpprhtn/raon/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/)
English | [한국어](README.ko.md) | [中文](README.zh.md)
## 状态
raon 处于早期开发阶段（pre-alpha）；其 API 可能会未经通知即发生更改，因此如果您依赖它，请固定版本（`pip install "raon==0.1.0"`）。它仅用于安全研究、夺旗赛练习和授权测试。使用前请阅读 [POLICY.md](POLICY.md)。
一项独立的评估表明，raon 能够端到端地检测并正确分类多种内存错误类别（参见 [基准测试](#benchmarking)）。通过 Magma 基准测试（需要 x86_64 Linux 主机）复现已知 CVE 的工作尚未运行；在该工作完成之前，不声称任何 CVE 复现率。
## 特性
- 使用 clang 在 AddressSanitizer/UndefinedBehaviorSanitizer 下编译 C/C++ 目标，并针对它们运行输入。
- 通过 libFuzzer harness 进行覆盖率引导的模糊测试（在提供 libFuzzer runtime 的平台上）。
- 将 ASan、UBSan、LeakSanitizer 和 ThreadSanitizer 报告解析为标准化的发现结果。
- 使用在重新构建时保持稳定的标准化栈 key 对崩溃进行去重，并根据可利用性对发现结果进行排序。
- 根据函数签名合成模糊测试 harness，并带有自我修复的编译循环。
- 将目标、语料库和发现结果存储在一个支持并发安全的 SQLite 存储中。
- 可选的 Claude 集成，支持模型分层、响应缓存和完整的请求日志记录。
## 要求
- Python 3.10 或更高版本
- 带有 AddressSanitizer 的 clang，用于编译和模糊测试目标
- Docker（可选），用于提供包含 libFuzzer runtime 的可复现 Linux 环境
- Anthropic API key（可选），仅用于 harness 合成和基于 LLM 的推理
## 安装说明
```
pip install raon # core
pip install 'raon[llm]' # with the Claude provider
pip install 'raon[binary]' # with angr/LIEF for source-less targets (experimental)
pip install 'raon[dev]' # with development tools
```
由于在 pre-alpha 期间 API 可能会发生变化，请固定版本以确保安装可复现：
`pip install "raon==0.1.0"`。
## 用法
### 命令行
```
# 编译目标，运行输入，筛选 crash，然后存储并对发现进行排名
raon run mytarget.c --input seed.bin --input crash.bin --db raon.sqlite
# 将已保存的 sanitizer crash 报告解析为发现（无需编译器）
raon triage crash_report.txt --target-id my_target --db raon.sqlite
# 根据可利用性对存储的发现进行排名，并合并重复项
raon report --db raon.sqlite
```
### Python
```
from raon.store import Blackboard
from raon.agents import AgentB, Supervisor
with Blackboard("raon.sqlite") as store:
finding = AgentB().triage(open("crash.txt").read(),
target_id="my_target", reproducer="poc.bin")
store.put_finding(finding)
result = Supervisor().triage(store.list_findings())
for f in result.representatives:
print(f.category, f.exploitability, f.dedup_key[:12])
```
Harness 合成和推理使用 Claude。只需配置一次 provider；响应会被缓存，并且每个请求都会被记录：
```
from raon.llm import build_provider, PromptCache, JsonlLogger
from raon.llm.anthropic_provider import AnthropicProvider
provider = build_provider(
AnthropicProvider(), # reads ANTHROPIC_API_KEY
cache=PromptCache(".raon/cache"),
logger=JsonlLogger(".raon/llm.jsonl"),
)
```
除了 harness 合成和基于 LLM 的推理之外，其他所有功能都可以在没有 API key 的情况下工作。
## 概述
raon 将 fuzzer 作为原生子进程运行，仅在决策点调用语言模型——例如编写 harness、总结崩溃、提出模糊测试目标。各组件通过在一个存储上的一小组共享记录类型进行通信，因此它们保持独立，并且运行产生的每个工件都可以被检查。
| 包 | 描述 |
|---|---|
| `raon.fuzzing` | 使用 clang 和 sanitizers 编译目标，运行它们，解析崩溃报告，合成 harness |
| `raon.agents` | 将崩溃、静态分析结果和弱接口假设解释为发现结果 |
| `raon.triage` | 对崩溃进行去重，权衡证据，按可利用性排序 |
| `raon.store` | 用于目标、语料库和发现结果的共享 SQLite 存储 |
| `raon.llm` | Claude 集成，支持模型分层、响应缓存和日志记录 |
| `raon.knowledge` | 领域包（例如 PNG），提供种子和弱接口提示 |
| `raon.bench` | 读取 Magma 基准测试的 ground truth 并计算指标 |
| `raon.binary` | 将崩溃地址映射到函数并恢复无源码目标的类型（实验性） |
| `raon.contracts` | 每个组件都会读写的共享记录类型 |
崩溃被表示为一个 `Finding`：包含类别、其证据、置信度、可利用性评分以及一个 `dedup_key`。`dedup_key` 是一个标准化的栈哈希，它会省略地址、行号和构建路径，因此相同的 bug 在多次构建中都会映射到相同的 key。
### Agents
这里的“Multi-agent”是指三个专注的 agent 加上一个 supervisor，它们通过共享存储进行协调，而不是直接相互调用。每个 agent 生成 `Finding`；supervisor 将它们合并。静态和推理 agent 是可选的，并且需要它们各自的工具。
| Agent | 角色 | 产生的证据 |
|---|---|---|
| `AgentA` | 静态分析（运行 Semgrep，解释结果） | 静态路径，中等置信度 |
| `AgentB` | 崩溃分类——解析运行中的 sanitizer 输出 | 动态崩溃，高置信度 |
| `AgentC` | 根据领域知识进行接口推理（弱接口假设） | 推理，低置信度 |
| `Supervisor` | 编排——去重，权衡各 agent 的证据，按可利用性排序 | 合并、排序后的发现结果 |
证据根据类型进行加权（可复现的动态崩溃优先级高于静态路径，而静态路径又优先级高于推理），因此对于同一个 bug，已确认的崩溃优先于推测性的崩溃。为了简洁起见，上面的快速入门仅显示了 `AgentB` + `Supervisor`；`AgentA`/`AgentC` 遵循相同的接口。（这些名称计划在未来的版本中变为基于角色的名称——参见 [CHANGELOG.md](CHANGELOG.md）。）
## 平台支持
| 平台 | ASan 模糊测试 (`raon run`) | 覆盖率引导的模糊测试 (libFuzzer) | 分类 / Python API / CLI |
|---|---|---|---|
| Linux (x86_64) | ✅ | ✅ | ✅ |
| macOS (Apple clang) | ✅ | ❌ (无 libFuzzer runtime) | ✅ |
| Windows | ⚠️ 未测试 (使用 WSL) | ⚠️ 未测试 (使用 WSL) | ✅ |
| Docker (提供的镜像) | ✅ | ✅ | ✅ |
`raon run` 和集成测试需要**带有 AddressSanitizer 的 clang**。覆盖率引导的模糊测试还需要 **libFuzzer runtime**，它随 Linux clang 一起提供，但不随 Apple clang 提供；提供的 `docker/Dockerfile` 提供了一个同时包含这两者的 Linux 环境。分类、Python API 和 CLI 可以在任何运行 Python 3.10+ 的地方工作。
## 基准测试
**独立评估。** raon 附带了一个小型的 libFuzzer 目标基准测试，其中包含植入的 bug（外加一个作为误报检查的安全目标），并针对它们运行完整的 pipeline。测量结果（raon 0.2.0，Docker 镜像）：
| 目标 | Bug 类别 | 已检测到 | Sanitizer 错误 | 崩溃时间 (秒) |
|---|---|---|---|---|
| `heap_overflow.c` | memory | ✅ | heap-buffer-overflow | 0.04 |
| `use_after_free.c` | memory | ✅ | heap-use-after-free | 0.03 |
| `stack_overflow.c` | memory | ✅ | stack-buffer-overflow | 0.03 |
| `global_overflow.c` | memory | ✅ | global-buffer-overflow | 0.03 |
| `safe.c` | — (安全) | 无崩溃 ✓ | — | — |
检测到了 4/4 的有 bug 目标，0 误报。使用以下命令复现
`docker run --rm raon:ci python -m raon.bench.eval`。详情和方法论：
[docs/evaluation.md](docs/evaluation.md)。
**编排价值（单 agent vs. multi-agent）。** 在重复运行的相同 bug 上（原始栈会随 ASLR 变化），简单的单次基准线会将 4 个 bug 过度报告为 12 个（去重 F1 0.00）；而 raon 的标准化去重 + Supervisor 能够准确恢复出 4 个（F1 1.00）。使用以下命令复现
`python -m raon.bench.experiment`。
**Magma（计划中）。** raon 还包含一个适配器（`raon.bench`），用于读取 [Magma](https://github.com/HexHive/magma) 基准测试的 canary ground truth，以获取已知 CVE 的复现指标。运行这些活动需要带有 Docker 的 x86_64 Linux 主机；一旦活动运行，结果将会发布。在此之前，不声称任何 CVE 复现率。
## 文档
- [CONTRIBUTING.md](CONTRIBUTING.md) — 开发设置和约定
- [POLICY.md](POLICY.md) — 授权使用、负责任的漏洞披露、可复现性
- [CHANGELOG.md](CHANGELOG.md) — 发布说明
- [examples/](examples/) — 可运行的端到端演示
## 构建与测试
```
pip install -e '.[dev,llm]'
ruff check src tests # lint
mypy # static type checking
pytest -q # test suite (fuzzing tests run when clang is present)
pytest -q -m "not integration" # unit tests only
```
要在可复现的 Linux 环境中运行全套测试（带有 libFuzzer）：
```
docker build -f docker/Dockerfile -t raon:ci .
docker run --rm raon:ci
```
## 贡献
欢迎贡献。请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发工作流、编码规范以及在提交 pull request 前必须通过的检查。对本项目的所有使用都必须遵循 [POLICY.md](POLICY.md)。
## 许可证
根据 [MIT License](LICENSE) 授权。Copyright © 2026 Junwon Lee。
标签：二进制分析, 云安全运维, 多智能体, 请求拦截, 逆向工具