truongtruong04/SmartAudit-AI-Powered-Smart-Contract-Security-Scanner

# SmartAudit — AI 驱动的智能合约安全扫描器 ## 概述 SmartAudit 是一个多 Agent 系统，可自动审计 Solidity 智能合约的安全漏洞。用户上传或粘贴 `.sol` 文件后，系统将运行一个顺序执行的 3 Agent AI pipeline，扫描漏洞、验证发现、评估风险，并输出完全重构的安全合约。 核心 pipeline 使用 **CrewAI** 进行 Agent 编排，使用 **Groq** 进行快速 LLM 推理（Llama 模型），以及 **Mistral** 进行代码生成（Codestral）。界面是一个提供单页前端（`index.html`）的 **Flask** Web 服务器 —— 无需前端构建工具。 该系统覆盖了基于 SWC Registry 和 OWASP 智能合约 Top 10 的 **12 个漏洞类别**，包括 Reentrancy、不安全的随机数、不当的原生 Token 处理、不完全的状态清理（mapping/array）、tx.origin 误用、Front-Running 等。 ## Agent Pipeline 审计作为一个**顺序 CrewAI pipeline** 运行 —— 每个 Agent 将前一个 Agent 的输出作为上下文接收。 | Agent | 角色 | 模型 | 任务 | |---|---|---|---| | **Agent 1** | 智能合约安全审计员 | Llama 3.3 70B (Groq) | 扫描所有 12 个漏洞类别，输出结构化的 `[VULN-XXX]` 发现 | | **Agent 2** | 高级安全风险分析师 | Llama 3.1 8B Instant (Groq) | 验证发现，消除误报，评分 CVSS v3.1，生成风险评级 + 路线图 | | **Agent 3** | Principal Solidity 开发者 | Codestral (Mistral) | 生成完整的重构合约，修复所有已确认的漏洞 | ## 覆盖的漏洞类别 Agent 1 在每次审计运行中检查 SWC Registry 的所有 12 个类别： | # | 类别 | SWC 参考 | |---|---|---| | CAT-01 | Reentrancy（单函数、跨函数、只读） | SWC-107 | | CAT-02 | 整数溢出 / 下溢 | SWC-101 | | CAT-03 | 访问控制（缺少修饰符、tx.origin 认证） | SWC-105, SWC-106, SWC-115 | | CAT-04 | 不安全的随机数（使用 block.timestamp/blockhash 作为 RNG） | SWC-120 | | CAT-05 | Front-Running（approve 竞态条件、三明治攻击） | SWC-114 | | CAT-06 | Gas 限制与 DoS（无界循环、push 模式） | SWC-128 | | CAT-07 | 不当的原生 Token 处理（send/transfer/call 误用、缺少 receive/fallback） | SWC-104, SWC-113 | | CAT-08 | 不完全的状态清理（mapping 未清除、delete 后的幽灵数据） | — | | CAT-09 | 时间戳依赖 | SWC-116 | | CAT-10 | 逻辑与业务错误（差一错误、零地址、整数除法） | — | | CAT-11 | 自毁与强制 ETH 转账 | SWC-132 | | CAT-12 | 已弃用 / 不安全的模式（tx.origin, sha3, throw, floating pragma） | SWC-111, SWC-115 | ## 功能特性 - **双重输入模式** — 通过拖放上传 `.sol` 文件或直接粘贴代码 - **3 Agent 顺序 pipeline** — 审计员 → 评论员 → 开发者，每个都基于前一个输出构建 - **结构化发现** — 每个漏洞报告为 `[VULN-XXX]`，包含严重程度、SWC ID、位置、描述、攻击 PoC 和受影响的代码 - **总体风险评级** — 从 Agent 2 的 CVSS 分析中提取的 CRITICAL / HIGH / MEDIUM / LOW - **执行摘要** — 面向非技术利益相关者的通俗语言摘要 - **修复路线图** — 来自 Agent 2 的优先级行动列表 - **安全合约生成** — Agent 3 生成完全可编译的、已打补丁的 `.sol` 文件，可下载为 `_secured.sol` - **保存完整审计报告** — 每次运行后，所有 3 个 Agent 的输出保存到 `reports/audit_report.md` - **速率限制重试** — 针对 Groq/Mistral API 速率限制的自动指数退避（最多 4 次尝试） - **200 KB 合约大小限制** — 在处理之前在后端进行验证 ## 项目结构 ``` smart_contract_auditor/ ├── main.py # Agent definitions, task prompts, LLM factory, CLI runner ├── app.py # Flask API server + response parser ├── index.html # Single-page frontend (vanilla JS, no build step) ├── .env # API keys (not committed) ├── .env.example # Key template ├── requirements.txt # Python dependencies └── reports/ └── audit_report.md # Auto-generated after each audit run ``` ## 环境要求 - Python 3.11+ - **Groq API Key** — 免费层可在 [console.groq.com/keys](https://console.groq.com/keys) 获取 - **Mistral API Key** — 免费层可在 [console.mistral.ai/api-keys](https://console.mistral.ai/api-keys) 获取 Python 包： ``` crewai>=0.80.0 python-dotenv>=1.0.0 flask flask-cors ``` 安装所有依赖： ``` pip install crewai python-dotenv flask flask-cors ``` ## 安装设置 **1. 克隆仓库** ``` git clone https://github.com/your-username/smart_contract_auditor.git cd smart_contract_auditor ``` **2. 创建虚拟环境** ``` python -m venv venv # Windows venv\Scripts\activate # macOS / Linux source venv/bin/activate ``` **3. 安装依赖** ``` pip install crewai python-dotenv flask flask-cors ``` **4. 配置 API Key** 将 `.env.example` 复制为 `.env` 并填入你的密钥： ``` GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx MISTRAL_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` ## 使用方法 ### Web 界面（推荐） 启动 Flask 服务器： ``` python app.py ``` 在浏览器中打开 `http://localhost:5000`。 - **上传标签页** — 拖放 `.sol` 文件或点击浏览 - **粘贴标签页** — 直接粘贴 Solidity 源代码 - 点击 **Run Security Audit** - 进度面板实时显示每个 Agent 的状态 - 结果显示：风险徽章、漏洞列表（可展开）、执行摘要、修复路线图 - 如果 Agent 3 生成了安全合约，会出现一个 **Download _secured.sol** 按钮 ### CLI 运行器 要在不使用 Web 界面的情况下直接从终端运行审计： ``` python main.py --contract path/to/YourContract.sol ``` 完整的审计报告将保存到 `reports/audit_report.md`。如果 Agent 3 生成了安全合约，它将作为 `YourContract_secured.sol` 保存在原始文件旁边。 ## API Flask 服务器提供一个端点： **`POST /api/audit`** 请求体 (JSON)： ``` { "code": "// SPDX-License-Identifier: MIT\npragma solidity ^0.8.20;\n...", "filename": "MyContract.sol" } ``` 响应体 (JSON)： ``` { "status": "ok", "risk": "CRITICAL", "summary": "The contract contains multiple critical vulnerabilities...", "findings": [ { "id": "VULN-001", "title": "Reentrancy in withdraw()", "severity": "CRITICAL", "swc": "SWC-107", "location": "withdraw() line ~42", "description": "...", "poc": "1. Attacker deploys malicious contract...", "code": "function withdraw() external { ... }" } ], "roadmap": [ "Apply CEI pattern to withdraw()", "Add ReentrancyGuard to all external call functions" ], "secured_code": "// SPDX-License-Identifier: MIT\npragma solidity ^0.8.20;\n...", "secured_filename": "MyContract_secured.sol", "report": "# AGENT 1 — AUDIT FINDINGS\n..." } ``` ## 使用的模型 | 模型 | 提供商 | 使用者 | 备注 | |---|---|---|---| | `llama-3.3-70b-versatile` | Groq | Agent 1 (审计员) | 深度漏洞扫描，温度 0.1 | | `llama-3.1-8b-instant` | Groq | Agent 2 (评论员) | 快速验证与评分，温度 0.2 | | `codestral-latest` | Mistral | Agent 3 (开发者) | 代码生成，最大 8192 tokens | Groq 和 Mistral 都提供足以运行典型合约审计的免费层。 ## 限制 - **合约大小** — 超过 200 KB 的合约会被拒绝；非常大的合约可能会超出 LLM 上下文窗口 - **语言** — 仅支持 Solidity（`.sol` 文件）；不支持 Vyper 和其他 EVM 语言 - **随机数修复** — Agent 3 输出 Chainlink VRF 存根；在部署前必须手动配置真正的 VRF 订阅 - **编译** — 安全合约由 LLM 生成，在生产环境使用前应在本地审查和编译 - **速率限制** — Groq 免费层有每分钟的 token 限制；系统会通过指数退避自动重试，但非常大的合约可能会达到限制 - **误报** — Agent 2 会过滤发现，但偶尔可能会错误地标记或忽略边缘情况；建议人工审查报告

标签：AI安全, API密钥扫描, Chat Copilot, CISA项目, CrewAI, CVSS评分, DeFi安全, Flask, Llama 3, Mistral, OWASP Top 10, PE 加载器, PyRIT, Solidity, SWC Registry, Web3安全, Web报告查看器, 云安全监控, 代码安全, 代码重构, 以太坊, 区块链开发, 多智能体系统, 对称加密, 整数溢出, 智能合约安全, 智能合约审计, 漏洞枚举, 自动化审计, 逆向工具, 配置审计, 重入攻击, 静态分析