bigdevxrd/scrypto-audit-kit
GitHub: bigdevxrd/scrypto-audit-kit
针对 Radix Scrypto 智能合约的 LLM 驱动型审前分析工具集，结合静态规则与 AI 检查自动输出结构化审计报告。
Stars: 0 | Forks: 0
# scrypto-audit-kit
[](https://github.com/bigdevxrd/scrypto-audit-kit/actions/workflows/lint.yml)
[](LICENSE)
[](https://docs.radixdlt.com/docs/scrypto-1)
[](#limitations--read-this-before-relying-on-the-output)
[](CONTRIBUTING.md)
针对 Radix 网络上 [Scrypto](https://docs.radixdlt.com/docs/scrypto-1) blueprints 的审前测试工具集。它运行 **混合分析** —— 确定性的静态规则加上基于精选检查清单和参考模式的 LLM 检查 —— 并生成可供人类审计员使用的审计报告（markdown + JSON）（或用于自行修复问题）。仅静态检查是免费的，且不需要 API key。
这是一个**审前**工具，而不是正式的审计。它捕获的是细心的审查者在初次阅读时会发现的问题，以便让付费的审计员把时间花在更难、需要二次阅读的发现上。**在主网部署之前，它不能代替人工审计。**
## 它的功能
对于你指定的每个 scrypto package，该工具集会：
1. 运行 **确定性的静态检查**（免费，无需 API） —— 一套精选的高精度 Scrypto 规则（无限制抽取、无 owner 的 globalize、自轮换角色、浮点数、硬编码地址等）。
2. 将 package 的源代码（`Cargo.toml` 以及 `src/` 和 `tests/` 下的所有内容）加载到 [aider](https://aider.chat) 会话中。
3. 将漏洞**检查清单**（11 个类别 —— 授权、重入、小数位、资源处理、时间、状态机、外部调用、升级、预言机、滑点、配额）和**参考模式**目录（Ignition、CaviarNine HyperStake、subintents、策略金库威胁模型、常规 scrypto 知识）作为只读上下文加载。
4. 要求 Claude Sonnet 4.6 生成一份结构化的审计报告 —— 总结、发现（Critical → Info）、检查清单覆盖情况检查、模式一致性检查、测试覆盖率缺口，以及留给人类审计员的疑问。
5. 合并这两个步骤的结果，并将 markdown 报告写入 `audit-reports/--.md`，**同时**生成一个可供机器读取的 `report.json`（[schema](schema/audit-report.schema.json)），供 agent 和 CI 检测关卡使用。
该工具集在**设计上是只读的**。它只生成报告；不会编辑你的 blueprint。对审计级代码的修改必须通过单独的、人工监督的会话进行。
## 快速开始
```
pip install scrypto-audit-kit # the deterministic toolkit + MCP server, no API key needed
# ...或 clone 完整的 LLM audit harness (audit.sh)：
git clone https://github.com/bigdevxrd/scrypto-audit-kit
```
pip 包为你提供免费的静态分析、测试脚手架生成、attestation
bridge 以及 MCP 服务器 —— 它们可以被导入，也可作为 `sak-*` 命令使用。完整的 `./audit.sh`（LLM 检查清单检查）包含在克隆的代码库中。**[docs/quickstart.md](docs/quickstart.md)** 详细介绍了这三个层级的端到端流程。
### 环境要求（适用于完整的 `./audit.sh` 审计）
- [aider](https://aider.chat)（`pip install aider-chat` —— 0.86 或更高版本）
- 一个 Anthropic API key（该工具集默认使用 Claude Sonnet 4.6 —— 可在 获取）
- bash, awk, find（macOS / Linux 标准配置）
- `python3` —— 可选；仅在需要生成可供机器读取的 `report.json` 时需要（没有它，markdown 报告也能正常运行）
可以通过以下三种方式之一提供该 key：
```
# 1. 在你的 shell 中 export（推荐用于 CI）
export ANTHROPIC_API_KEY=sk-ant-...
# 2. 将 AIDER_ENV_FILE 指向现有的 env 文件
AIDER_ENV_FILE=~/some/.env ./audit.sh /path/to/package
# 3. 在 kit 目录中放置一个 .env 文件（gitignored）
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env
```
使用以下命令验证：
```
make check-deps
```
### 运行审计
```
git clone https://github.com/bigdevxrd/scrypto-audit-kit
cd scrypto-audit-kit
chmod +x audit.sh
./audit.sh /path/to/your/scrypto/package
# 或：
make audit TARGET=/path/to/your/scrypto/package
```
目标必须是一个 scrypto package 目录（包含 `Cargo.toml` 和 `src/lib.rs`）。该工具集将读取 `src/` 和 `tests/` 下的所有内容。
报告会存放在 `audit-reports/--.md` 中。报告已被 gitignore 忽略 —— 请通过其他方式分享它们，不要提交它们。
### 示例
```
./audit.sh ~/scrypto/my-vault
[pre-flight] cargo check (release wasm)...
[pre-flight] compile OK
==> scrypto-audit-kit
target: scrypto / my-vault
path: /home/me/scrypto/my-vault
model: claude
sources: 3 files
refs: 6 files (read-only)
report -> audit-reports/scrypto-my-vault-2026-05-11.md
[aider runs ...]
==> done. report: audit-reports/scrypto-my-vault-2026-05-11.md
```
### 选择模型
默认模型是 Claude Sonnet 4.6。可以使用 `--model` 标志来选择分析模型：
```
./audit.sh --model claude # default — Sonnet 4.6, best pattern depth
./audit.sh --model deepseek # cheaper broad scan (needs DEEPSEEK_API_KEY)
./audit.sh --model both # DeepSeek broad pass, then Claude deep pass,
# with a cross-model confidence summary
```
`both` 会优先运行 DeepSeek 以扩大覆盖范围，然后将其发现作为上下文提供给 Claude，并将两个模型都认同的发现标记为 HIGH（高）置信度。当你需要对高风险的 blueprint 提供双重确认时，请使用此选项。
### 免费层级：确定性静态分析
每次审计都会运行静态检查，你也可以*单独*运行它，**无需 API key、无需 aider、也无需工具链**：
```
./audit.sh --static-only # free, instant, deterministic
```
它应用了一套精选的高精度 Scrypto 规则 —— 具有注释/字符串感知能力，因此代码规则不会匹配注释或字符串字面量 —— 并会写入相同的 `report.json`。可以使用 `// sak:allow ` 注释来忽略某项发现；在全量运行时添加 `--no-static` 可以跳过此检查。请参阅 [docs/static-analysis.md](docs/static-analysis.md) 了解规则列表以及如何添加新规则。
### 在内置示例上尝试
该代码库附带了一个故意包含漏洞的 blueprint，因此你无需编写任何代码即可看到真实的输出 —— 静态层级不需要 API key：
```
./audit.sh --static-only examples/vulnerable-vault # free; drop --static-only for the full hybrid run
```
预期的结果已提交在其旁边 —— [`examples/vulnerable-vault.pre-audit.md`](examples/vulnerable-vault.pre-audit.md)（供人类阅读）和 [`.json`](examples/vulnerable-vault.pre-audit.json)（供机器读取）。其中的每一个 `file:line` 都是准确的，因为这些 bug 是刻意植入的。
### 机器可读输出
除了 markdown 之外，该工具集还会写入符合 [`schema/audit-report.schema.json`](schema/audit-report.schema.json) 的 `report.json` —— 包含稳定的 ID（来自 LLM 的 `F-###`，来自静态检查的 `S-###`，每个 ID 都标有其 `source`）、严重程度、完整的检查清单覆盖情况，以及来源信息块（工具集版本、模型、检查清单版本以及所分析源代码的 sha256）。这是供 agent、CI 关卡以及（未来的）链上 attestation 使用的；markdown 只是它的一种渲染形式。
### 持续集成与徽章
在每个 PR 上运行审前检查并显示状态徽章 —— 完整设置请见 [docs/ci.md](docs/ci.md)。简而言之，调用可重用的工作流即可：
```
jobs:
scrypto-pre-audit:
uses: bigdevxrd/scrypto-audit-kit/.github/workflows/pre-audit.yml@main
with:
package: packages/my-blueprint
fail-on: high
secrets:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
```
它会进行编译、审计、上传报告，并在发现 High/Critical 问题时判定失败 —— 这是一个诚实的“审前检查通过”的信号，而不是安全保证。
### 在 agent 中使用它（MCP + Claude Code）
该工具集附带了一个 **MCP 服务器**，因此 agent 可以将审前检查作为工具运行，并指导你完成 **审计 → 修复 → 重新验证** 流程：
```
pip install "mcp[cli]"
claude mcp add --transport stdio scrypto-audit-kit -- python3 "$PWD/bin/mcp_server.py"
```
工具包括：`static_scan`（免费）、`audit_package`、`propose_tests`、`attestation_payload`、`get_findings`、`show_finding_source`、`reaudit_diff`、`gate`、`get_checklist`。此外还有一个 Claude Code 技能（`/scrypto-pre-audit`）和一份适用于任何 agent 的 [AGENTS.md](AGENTS.md) 指南。完整设置 —— 包括审计→修复→验证循环 —— 请见 [docs/agents.md](docs/agents.md)；这九个工具及其正式契约请见 [docs/mcp-tools.md](docs/mcp-tools.md)。
### 在此基础上构建 —— Python SDK
`pip install scrypto-audit-kit` 使得确定性核心代码可被导入，且没有任何必需的
依赖项：
```
from scrypto_audit_kit import static_analysis, sak_lib
findings = static_analysis.analyze_package("path/to/package") # free, no API key
verdict = sak_lib.gate_verdict(sak_lib.build_report(findings), "high")
```
完整的 API、进程内的九个工具以及 `sak-*` 控制台脚本请见
[docs/sdk.md](docs/sdk.md)。三个可运行的示例 agent —— 免费层级的 CI 关卡、
审计→修复→验证循环，以及 MCP 客户端 —— 位于 [examples/agents/](examples/agents/)。
### 生成测试，在链上 attest
- **属性测试。** `propose_tests`（或 `python3 bin/gen_tests.py `）会为覆盖率缺口生成可编译的 `#[ignore]` `scrypto-test` 脚手架 —— 授权的异常路径、正常执行路径、数值不变式 —— 因此填补这些缺口就如同填空一样简单。
- **链上 attestation (L3)。** `attestation_payload`（或 `python3 bin/attest.py `）将报告转换为 Radix 交易清单，通过 [attestation/](attestation/) registry blueprint 在账本上记录 attestation —— 绑定到你确切的源代码哈希（确定性锚点）。这是一种覆盖率记录，而非安全保证，并且对于 LLM 层级来说，其字节不具备可复现性（参见 [attestation/README.md](attestation/README.md)）。
## 工具集内容
```
scrypto-audit-kit/
├── audit.sh The harness — wraps aider with the right flags + context.
├── Makefile Convenience targets (audit, lint, test, check-deps).
├── pyproject.toml Pip packaging — importable SDK + sak-* console scripts.
├── VERSION Kit version, stamped into every report.
├── VISION.md / ROADMAP.md The trust-ladder strategy + the live phase checklist.
├── AGENTS.md How an agent should drive the kit (audit → fix → verify).
├── .mcp.json MCP server config (auto-wires the tools in Claude Code).
├── .aider.conf.yml Tuned config: model=Sonnet 4.6, no editor/commits, cache on.
├── prompts/
│ ├── audit.md Auditor-role prompt + report structure (incl. the JSON appendix).
│ └── checklist.md Eleven vulnerability classes with concrete questions per class.
├── references/ Read-only context — production patterns + threat models (5 files).
├── schema/ JSON Schemas — the report + the MCP tool contracts.
├── bin/ engine + tools: static_analysis.py, gen_tests.py, attest.py, mcp_server.py, …
├── tests/ Stdlib unit tests for the tooling (`make test`).
├── docs/ The docs suite (quickstart · sdk · mcp-tools · architecture · …).
├── attestation/ On-chain attestation registry blueprint (Scrypto, L3).
├── .claude/skills/ The scrypto-pre-audit Claude Code skill.
├── audit-reports/ Output dir, gitignored.
└── examples/
├── vulnerable-vault/ Deliberately-vulnerable fixture + its committed report.
├── agents/ Runnable example agents (CI gate, audit→fix→verify, MCP client).
└── ci/ Drop-in pre-audit workflow for your repo.
```
## 文档
所有内容都在 **[docs/](docs/README.md)** 中；简要列表如下：
- [quickstart.md](docs/quickstart.md) —— 安装与运行，包含全部三个层级
- [static-analysis.md](docs/static-analysis.md) —— 确定性规则（以及如何添加规则）
- [agents.md](docs/agents.md) · [mcp-tools.md](docs/mcp-tools.md) —— 通过 agent / 经由 MCP 进行操作
- [sdk.md](docs/sdk.md) —— Python API + 控制台脚本
- [ci.md](docs/ci.md) —— CI 关卡 + 徽章
- [architecture.md](docs/architecture.md) —— 各个组件是如何组合在一起的
- [VISION.md](VISION.md) · [ROADMAP.md](ROADMAP.md) · [CHANGELOG.md](CHANGELOG.md) —— 策略、状态与历史记录
## 限制 —— 在依赖输出结果之前请阅读此内容
该工具集对其自身定位非常坦诚。以下是它明确**不做**的事情：
- **它不是形式化验证工具。** 没有定理证明、没有符号执行、也没有模糊测试。审计发现是由 LLM 通过对照检查清单进行模式匹配而得出的。
- **它不会运行 `cargo build` 或 `cargo test`。** 编译问题、依赖项漏洞和测试失败不在范围之内。请单独运行这些检查。
- **它无法捕捉新型的攻击类别。** 它能可靠地呈现已知的常见陷阱，并将新型隐患作为低置信度的开放性问题提出。新型攻击的发现是人类审计员的工作。
- **LLM 可能会产生幻觉（虚构）出 file:line 引用。** 每一项发现都会引用一个位置；在采取行动之前，你必须验证这些引用。审计提示明确要求模型进行引用，但验证的责任在于读者。
- **它不是部署关卡。** 不要仅凭一份干净的报告就阻止部署。该工具集是一个辅助工具，而不是批准印章。
如果这些限制对你的用例有重大影响，请不要将此工具集作为付费审计的替代品。
## 成本
使用默认配置（Sonnet 4.6，开启 prompt 缓存，跨运行缓存引用）：
- 会话的首次审计：约 50k 输入 token（引用） + 5–20k 输入 token（目标源码） + 约 5–15k 输出 token → 每次运行大约 $0.20–$0.40。
- 同一 prompt 缓存窗口中的后续审计：缓存引用可降低约 70% 的成本 → 每次运行大约 $0.10。
这些数据是 2026 年时的估算值。请查看当前的 [Anthropic 定价](https://www.anthropic.com/pricing) 以获取准确数字。该工具集故意*不*使用 architect/editor 分割（这会增加第二次模型调用），因为我们需要的是分析，而不是代码修改。
## 许可证
[Apache 2.0](LICENSE) —— 与大部分上游 Radix 生态系统使用的许可证相同。欢迎 Fork、二次开发和商业使用；根据许可证保留署名。
## 相关链接
- [Radix Scrypto 文档](https://docs.radixdlt.com/docs/scrypto-1)
- [radixdlt/Ignition](https://github.com/radixdlt/Ignition) —— 由 Radix 团队维护的权威参考代码库（我们的 `references/ignition-patterns.md` 大部分内容提取于此）
- [caviarnine/caviarnine-scrypto](https://github.com/caviarnine/caviarnine-scrypto) —— 基于 Apache 许可证的 CaviarNine 生产级 blueprints
- [aider](https://aider.chat) —— 该工具集所封装的 LLM 编码 agent
标签：LLM, LNA, Radix, Rust, Unmanaged PE, 区块链, 可视化界面, 应用安全, 智能合约审计, 网络流量审计, 逆向工具, 错误基检测, 静态代码分析