mddotcodes/auditor

# Auditor **Auditor** 是一个自包含的引擎，用于审计 Solidity 智能合约，并以结构化的技术输出形式流式传输结果。 将其指向你的合约（或一个小型 Foundry 项目），它将： 1. 使用 Foundry **编译** 2. 使用 [Slither](https://github.com/crytic/slither) **扫描**已知的漏洞类别 3. 使用 LLM **生成**模糊测试和不变量测试（可选 — 使用你的 API 密钥） 4. 在 Foundry 下**运行**这些测试 5. **生成**机器可读的产物：发现的 JSON 结果、生成的 `.t.sol` 文件、覆盖率，以及用于后续链上匹配的字节码指纹 所有操作都在一个 Docker 镜像内运行，因此工具链是固定的，并且你的主机保持干净。 ## 你能得到什么 | 输出 | 描述 | |--------|-------------| | 静态发现 | 标准化的 Slither 结果（重入、访问控制等）加上原始工具日志 | | 生成的测试 | 针对状态更改函数的 Foundry 模糊/不变量测试 | | 测试报告 | 通过/失败摘要、失败时的输入（如果有）、启用时的覆盖率 | | 字节码指纹 | 编译器设置 + 字节码/元数据哈希，用于部署后的精确匹配验证 | | 实时进度 | 任务运行期间通过 HTTP + WebSocket 进行阶段更新 | ## 适用人群 - 希望获得**本地、可重复**审计流水线，而无需手动组装 Foundry + Slither + 脚本的开发者 - 希望获得**原始技术产物**，以便将其接入 CI、自定义 UI 或他们自己的审查流程的团队 - 任何想要**可选的 LLM 辅助测试生成**，而不必将特定供应商硬编码到核心扫描器中的人 ## 快速开始 ``` make build-image # needs Docker; tags auditor:local ./scripts/run-local.sh # hardened run → versions (default) # 或： docker compose run --rm auditor versions docker compose run --rm auditor forge --version ``` 强化的标志（只读 root、丢弃 cap、network none、cgroup 限制）与 [`docs/security/runtime-defaults.md`](docs/security/runtime-defaults.md) 相匹配。可选的 LLM 密钥：复制 [`.env.example`](.env.example) → `.env`，并使用 `./scripts/run-local.sh --llm …` 或 Compose profile `llm`（以便稍后需要供应商出口流量时使用）。 示例合约和草拟的产物清单位于 [`examples/`](examples/) 中。 ### 预期的 API 用户体验（尚未实现） ``` docker run --rm -p 8080:8080 \ -e OPENROUTER_API_KEY=sk-… \ # optional; omit for static-only ghcr.io//auditor:latest ``` ``` curl -s -X POST http://localhost:8080/v1/audit \ -H 'Content-Type: application/json' \ -d '{ "sources": { "src/Token.sol": "// SPDX-License-Identifier: MIT\npragma solidity ^0.8.20;\n..." } }' # → { "job_id": "…" } ``` ``` WS /v1/ws/jobs/{job_id} GET /v1/jobs/{job_id} ``` ### CLI（计划中） ``` auditor-cli run ./src/Token.sol auditor-cli run ./my-foundry-project auditor-cli metrics ./src/Token.sol # quick size / complexity estimate ``` ## 模式 | 模式 | 需要 | 行为 | |------|--------|----------| | **静态** | 仅 Docker | 编译 + Slither + 指纹 | | **完整** | Docker + LLM API 密钥 | 静态路径，然后生成并运行模糊/不变量测试 | | **指标** | 仅 Docker | 快速预检：LOC、复杂度估算、粗略的 token 估算 — 不进行完整审计 | 支持的 LLM 提供商（通过环境变量）：OpenAI、Anthropic、OpenRouter。 ## 流水线 ``` input (sources | project | gist) │ ▼ materialize Foundry project │ ▼ forge build ──fail──► optional LLM auto-fix (≤3) ──or──► fail job │ ▼ Slither (JSON findings) │ ▼ [if API key] LLM writes .t.sol ──compile feedback loop ≤3──► forge test / fuzz │ ▼ artifacts + bytecode fingerprint ``` 每个任务都有硬性的实际耗时限制，因此失控的模糊测试或糟糕的测试不会永远挂起。 ## 配置 | 变量 | 默认值 | 用途 | |----------|---------|---------| | `OPENAI_API_KEY` | — | 用于测试生成/自动修复的 OpenAI | | `ANTHROPIC_API_KEY` | — | Anthropic | | `OPENROUTER_API_KEY` | — | OpenRouter | | `AUDIT_TIMEOUT_SECONDS` | `300` | 在此秒数后终止任务 | | `AUTO_FIX_COMPILE` | `false` | 让 LLM 尝试修复编译错误（最多 3 次） | 使用本地 `.env` 存放密钥；切勿提交它们。请参阅 [`.env.example`](.env.example)。 ## 安全默认值 合约和生成的测试是不可信代码。容器构建为在约束条件下运行它们： - 非 root 用户 - 每个任务独立的工作目录（并发任务之间不共享） - 通过常规 Docker 标志配置 CPU/内存限制 - 默认情况下编译/测试时关闭网络；仅当你提供密钥时才进行 LLM 调用 建议的本地运行方式（阶段 1 — 仅工具链；完整标志列表见 [`docs/security/runtime-defaults.md`](docs/security/runtime-defaults.md)）： ``` ./scripts/run-local.sh versions # 等价的 compose： docker compose run --rm auditor versions ``` ## 开发 ``` git clone https://github.com//auditor.git cd auditor make lint # format + static checks make test # unit / integration make build-image # local Docker image ``` 工具链和布局将随首批实现 PR 一起发布。 ## 路线图（宏观） - [ ] 可运行的 Docker 镜像 + `POST /v1/audit` - [ ] Slither 发现 + 产物清单 - [ ] WebSocket 任务流 - [ ] LLM 测试生成 + 模糊执行 - [ ] CLI - [ ] 发布的 GHCR 镜像和 semver 标签 ## 贡献 欢迎提交 Bug 报告和 PR。对于较大的设计更改，请先开启一个 issue，以便我们在公开 API 和产物 schema 上达成一致。 ## 许可证 [MIT](LICENSE)

标签：Docker, Foundry, Petitpotam, Solidity, Web报告查看器, 代码安全扫描, 区块链安全, 安全防御评估, 对称加密, 智能合约审计, 自动化审计, 请求拦截