LaelaZorana/solidity-audit-ai
GitHub: LaelaZorana/solidity-audit-ai
一款基于纯 Python 的离线 Solidity 智能合约审计工具，内置 SWC 漏洞检测器并提供 LLM 辅助修复建议。
Stars: 0 | Forks: 0
# solidity-audit-ai
[](https://github.com/LaelaZorana/solidity-audit-ai/actions/workflows/ci.yml)
## 问题所在
智能合约的漏洞极其致命：代码一旦部署即不可篡改，并且
直接持有资金，因此遗漏一个重入或访问控制的漏洞就可能
导致数百万的损失。专业审计既缓慢又昂贵，而大多数现有的
静态分析工具要么需要完整的 Solidity 工具链（solc、node、编译步骤），
要么直接输出原始的检测结果，缺乏可操作的修复建议。开发者希望有一个快速、本地的
预审计工具，可以在每次提交时运行，指出*哪里有问题、为什么严重，以及确切的修复方法*，
而无需将源代码发送到 SaaS 平台。
## 功能简介
`solidity-audit-ai` 会对 `.sol` 文件或目录运行一套**纯 Python 的静态检测器**，
将每个检测结果映射到对应的 [SWC](https://swcregistry.io)
类别和严重程度，然后通过**可选的 LLM 修复层**（默认为确定性离线引擎）
处理每个问题，生成通俗易懂的英文解释和具体的代码修复方案。它会输出终端摘要、Markdown 报告、带有严重程度徽章的
独立 HTML 报告，以及用于 CI 门控的 JSON。它完全**离线运行**：
静态分析无需任何第三方依赖，且未设置 API key 时，LLM 层会自动回退到
确定性的离线引擎。
```
flowchart LR
A[".sol file / directory"] --> B["Source model
(strip comments + strings,
brace-matched functions,
preserve line numbers)"] B --> C["Static detectors
(10 SWC-mapped checks)"] C --> D{"Findings
+ severity + SWC id"} D --> E["LLM remediation layer
(provider interface)"] E -->|no API key| E1["Offline deterministic stub
(explanation + code fix)"] E -->|API key set| E2["OpenAI / Anthropic
(optional)"] E1 --> F["Reports"] E2 --> F F --> G["Terminal summary"] F --> H["Markdown report"] F --> I["HTML report
(severity badges)"] F --> J["JSON
(CI gate via --fail-on)"] K["CLI: python -m auditor.cli"] --> A L["Web UI: FastAPI paste → report"] --> A ``` ## 结果与影响 在附带的测试用例（`make demo`，包含 8 个故意包含漏洞的合约和 4 个安全合约）上运行审计工具，结果如下： **包含漏洞的用例（`samples/vulnerable/`，8 个文件）：发现 23 项问题** | 严重程度 | 数量 | 代表性问题 | |---|---|---| | Critical | 2 | 重入攻击 (SWC-107)，未受保护的 `selfdestruct` (SWC-106) | | High | 9 | `tx.origin` 授权 (SWC-115)，缺失访问控制 (SWC-105)，不受信任的 `delegatecall` (SWC-112) | | Medium | 4 | 未检查的底层调用 (SWC-104)，弱随机数 (SWC-120)，0.8 之前版本溢出 (SWC-101) | | Low | 0 | (无) | | Informational | 8 | 浮动 pragma (SWC-103) | **安全用例（`samples/safe/`，4 个文件）：发现 0 项问题**：每个检测器在经过加固的 对照合约上均保持静默，证明其具有较低的误报率。 测试套件对每个检测器的正反两方面进行了验证：它在 包含漏洞的用例上**触发**警报，并在安全用例上**不会**发生误报。 ## 快速开始 核心审计工具无需任何依赖；它仅依靠 Python 标准库即可运行。 ``` # 克隆，然后从 repo 根目录： python -m auditor.cli samples/vulnerable # audit a directory python -m auditor.cli samples/vulnerable/Reentrancy.sol # audit one file # 编写报告： python -m auditor.cli samples --md report.md --html report.html # One-shot 演示（审计样本并打开 HTML 报告）： make demo # JSON 输出 + CI gate（遇到 High 或更严重情况时以非零值退出）： python -m auditor.cli samples --format json --fail-on high ``` 运行测试（离线）： ``` python -m pytest -q ``` 可选的 Web UI：一个精心打造的**粘贴合约**工作台（支持浅色/深色模式、Tailwind、 一键加载示例合约，并将检测结果渲染为带有严重程度徽章的卡片和 摘要标题）。完全离线运行；Tailwind 已内置，因此无需网络： ``` pip install -r requirements.txt make serve # or: uvicorn auditor.webapp:app --port 8000 # 打开 http://localhost:8000 ``` 默认情况下，AI 修复使用确定性的**离线**引擎。如果想改用 真实模型，可以设置 API key（完全可选）： ``` export OPENAI_API_KEY=... # or ANTHROPIC_API_KEY=... python -m auditor.cli samples --provider openai ``` ## 技术栈 - **Python 3.9+**，核心部分（分析引擎、 检测器、报告、CLI）仅使用标准库，无需 solc、node 或工具链。 - **定制的轻量级源码模型：** 去除注释/字符串的同时保留 行号 + 基于括号匹配的函数提取，确保检测器绝不会针对 被注释掉或写成字符串的代码触发警报。 - **可插拔的 LLM provider 接口：** 默认为确定性离线 stub； 可选的 OpenAI / Anthropic 后端在不可用时会平滑降级到该 stub。 - **FastAPI + Uvicorn** 用于可选的 Web UI。 - **pytest** 用于测试，**ruff** 用于代码检查，**GitHub Actions** 用于 CI （跨 Python 3.9 / 3.11 / 3.12 的矩阵测试 + Docker 构建），**Docker** 用于 容器化部署。 - **可选的 Slither 桥接：** 如果安装了 `slither`，其结果会被合并进来；如果 未安装，则静默跳过。 ## 部署 **容器（推荐）。** 该镜像在 8000 端口提供 Web UI，并 支持运行 CLI： ``` docker build -t solidity-audit-ai . docker run --rm -p 8000:8000 solidity-audit-ai # web UI # 针对挂载的 contracts 目录使用 CLI： docker run --rm -v "$PWD/contracts:/data" solidity-audit-ai \ python -m auditor.cli /data --format json ``` 容器以非 root 用户身份运行，并公开了 `/health` 健康检查接口，因此它 可以直接适配任何容器平台（Fly.io、Render、Cloud Run、ECS、 Kubernetes）。无需提供任何密钥；只有在需要实时的 LLM 修复时， 才需设置 `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`。 **CI 集成。** 在任何流水线中添加一个门控： ``` python -m auditor.cli contracts/ --format json --fail-on high ``` ## 检测器 每个检测器都映射到一个 [SWC Registry](https://swcregistry.io) 类别。 | 漏洞类别 | SWC ID | 严重程度 | 检测器 ID | |---|---|---|---| | 重入攻击：外部调用后状态发生改变 | SWC-107 | Critical | `reentrancy` | | 未受保护的 `selfdestruct` | SWC-106 | Critical | `unprotected-selfdestruct` | | 通过 `tx.origin` 进行身份验证 | SWC-115 | High | `tx-origin-auth` | | 敏感函数缺失访问控制 | SWC-105 | High | `missing-access-control` | | 对不受信任/用户控制的目标进行 `delegatecall` | SWC-112 | High | `delegatecall-untrusted` | | 未检查的底层调用返回值 | SWC-104 | Medium | `unchecked-call` | | 基于区块属性的弱随机数 | SWC-120 | Medium | `weak-randomness` | | 整数溢出/下溢风险（0.8 之前版本 / `unchecked`） | SWC-101 | Medium | `integer-overflow` | | 浮动/未锁定的编译器 pragma | SWC-103 | Informational | `floating-pragma` | | 可疑的一元表达式（`=+` 拼写错误） | SWC-129 | Low | `dangerous-unary` | ## 截图 MIT 许可证。版权所有 (c) 2026 Laela Zorana。
(strip comments + strings,
brace-matched functions,
preserve line numbers)"] B --> C["Static detectors
(10 SWC-mapped checks)"] C --> D{"Findings
+ severity + SWC id"} D --> E["LLM remediation layer
(provider interface)"] E -->|no API key| E1["Offline deterministic stub
(explanation + code fix)"] E -->|API key set| E2["OpenAI / Anthropic
(optional)"] E1 --> F["Reports"] E2 --> F F --> G["Terminal summary"] F --> H["Markdown report"] F --> I["HTML report
(severity badges)"] F --> J["JSON
(CI gate via --fail-on)"] K["CLI: python -m auditor.cli"] --> A L["Web UI: FastAPI paste → report"] --> A ``` ## 结果与影响 在附带的测试用例（`make demo`，包含 8 个故意包含漏洞的合约和 4 个安全合约）上运行审计工具，结果如下： **包含漏洞的用例（`samples/vulnerable/`，8 个文件）：发现 23 项问题** | 严重程度 | 数量 | 代表性问题 | |---|---|---| | Critical | 2 | 重入攻击 (SWC-107)，未受保护的 `selfdestruct` (SWC-106) | | High | 9 | `tx.origin` 授权 (SWC-115)，缺失访问控制 (SWC-105)，不受信任的 `delegatecall` (SWC-112) | | Medium | 4 | 未检查的底层调用 (SWC-104)，弱随机数 (SWC-120)，0.8 之前版本溢出 (SWC-101) | | Low | 0 | (无) | | Informational | 8 | 浮动 pragma (SWC-103) | **安全用例（`samples/safe/`，4 个文件）：发现 0 项问题**：每个检测器在经过加固的 对照合约上均保持静默，证明其具有较低的误报率。 测试套件对每个检测器的正反两方面进行了验证：它在 包含漏洞的用例上**触发**警报，并在安全用例上**不会**发生误报。 ## 快速开始 核心审计工具无需任何依赖；它仅依靠 Python 标准库即可运行。 ``` # 克隆，然后从 repo 根目录： python -m auditor.cli samples/vulnerable # audit a directory python -m auditor.cli samples/vulnerable/Reentrancy.sol # audit one file # 编写报告： python -m auditor.cli samples --md report.md --html report.html # One-shot 演示（审计样本并打开 HTML 报告）： make demo # JSON 输出 + CI gate（遇到 High 或更严重情况时以非零值退出）： python -m auditor.cli samples --format json --fail-on high ``` 运行测试（离线）： ``` python -m pytest -q ``` 可选的 Web UI：一个精心打造的**粘贴合约**工作台（支持浅色/深色模式、Tailwind、 一键加载示例合约，并将检测结果渲染为带有严重程度徽章的卡片和 摘要标题）。完全离线运行；Tailwind 已内置，因此无需网络： ``` pip install -r requirements.txt make serve # or: uvicorn auditor.webapp:app --port 8000 # 打开 http://localhost:8000 ``` 默认情况下，AI 修复使用确定性的**离线**引擎。如果想改用 真实模型，可以设置 API key（完全可选）： ``` export OPENAI_API_KEY=... # or ANTHROPIC_API_KEY=... python -m auditor.cli samples --provider openai ``` ## 技术栈 - **Python 3.9+**，核心部分（分析引擎、 检测器、报告、CLI）仅使用标准库，无需 solc、node 或工具链。 - **定制的轻量级源码模型：** 去除注释/字符串的同时保留 行号 + 基于括号匹配的函数提取，确保检测器绝不会针对 被注释掉或写成字符串的代码触发警报。 - **可插拔的 LLM provider 接口：** 默认为确定性离线 stub； 可选的 OpenAI / Anthropic 后端在不可用时会平滑降级到该 stub。 - **FastAPI + Uvicorn** 用于可选的 Web UI。 - **pytest** 用于测试，**ruff** 用于代码检查，**GitHub Actions** 用于 CI （跨 Python 3.9 / 3.11 / 3.12 的矩阵测试 + Docker 构建），**Docker** 用于 容器化部署。 - **可选的 Slither 桥接：** 如果安装了 `slither`，其结果会被合并进来；如果 未安装，则静默跳过。 ## 部署 **容器（推荐）。** 该镜像在 8000 端口提供 Web UI，并 支持运行 CLI： ``` docker build -t solidity-audit-ai . docker run --rm -p 8000:8000 solidity-audit-ai # web UI # 针对挂载的 contracts 目录使用 CLI： docker run --rm -v "$PWD/contracts:/data" solidity-audit-ai \ python -m auditor.cli /data --format json ``` 容器以非 root 用户身份运行，并公开了 `/health` 健康检查接口，因此它 可以直接适配任何容器平台（Fly.io、Render、Cloud Run、ECS、 Kubernetes）。无需提供任何密钥；只有在需要实时的 LLM 修复时， 才需设置 `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`。 **CI 集成。** 在任何流水线中添加一个门控： ``` python -m auditor.cli contracts/ --format json --fail-on high ``` ## 检测器 每个检测器都映射到一个 [SWC Registry](https://swcregistry.io) 类别。 | 漏洞类别 | SWC ID | 严重程度 | 检测器 ID | |---|---|---|---| | 重入攻击：外部调用后状态发生改变 | SWC-107 | Critical | `reentrancy` | | 未受保护的 `selfdestruct` | SWC-106 | Critical | `unprotected-selfdestruct` | | 通过 `tx.origin` 进行身份验证 | SWC-115 | High | `tx-origin-auth` | | 敏感函数缺失访问控制 | SWC-105 | High | `missing-access-control` | | 对不受信任/用户控制的目标进行 `delegatecall` | SWC-112 | High | `delegatecall-untrusted` | | 未检查的底层调用返回值 | SWC-104 | Medium | `unchecked-call` | | 基于区块属性的弱随机数 | SWC-120 | Medium | `weak-randomness` | | 整数溢出/下溢风险（0.8 之前版本 / `unchecked`） | SWC-101 | Medium | `integer-overflow` | | 浮动/未锁定的编译器 pragma | SWC-103 | Informational | `floating-pragma` | | 可疑的一元表达式（`=+` 拼写错误） | SWC-129 | Low | `dangerous-unary` | ## 截图 MIT 许可证。版权所有 (c) 2026 Laela Zorana。
标签：Python, Solidity, 人工智能, 区块链安全, 安全规则引擎, 无后门, 智能合约审计, 用户模式Hook绕过, 聊天机器人, 请求拦截, 逆向工具, 错误基检测, 静态代码分析