giselleevita/solidity-vuln-scanner
GitHub: giselleevita/solidity-vuln-scanner
面向以太坊智能合约的专业级安全审计工具，融合静态分析、可选大模型审计与外部工具交叉验证，输出符合SWC等标准的审计报告。
Stars: 0 | Forks: 0
# Solidity Vuln Scanner
**专业级 Ethereum 智能合约安全审计工具包。**
结合确定性静态分析、可选 LLM 审计以及外部工具交叉验证，生成**映射 SWC 的发现**、合规上下文（CWE/OWASP/DASP）以及**专业审计报告**（JSON/HTML/PDF）。
**用途：**
- 部署前安全评估
- CI/CD 安全门禁（支持 SARIF）
- 辅助手动审计并提供标准化发现
- 专业审计文档与修复指导
## 🚀 快速开始
### 最快运行方式（无 LLM，无外部工具）
```
# 1. 安装依赖
pip install -r requirements.txt
# 2. 启动 API (终端 1)
python fastapi_api.py
# 3. 启动 UI (终端 2)
streamlit run streamlit_ui.py
# 4. 打开 http://localhost:8501 并粘贴合约！
```
**使用此包含漏洞的合约进行测试：**
```
pragma solidity ^0.8.0;
contract VulnerableVault {
mapping(address => uint256) balances;
function withdraw(uint256 amount) public {
require(balances[msg.sender] >= amount);
(bool success, ) = msg.sender.call{value: amount}("");
require(success);
balances[msg.sender] -= amount;
}
}
```
### 完整运行（配合 Slither/Mythril）
```
# 使用 Docker (推荐)
docker-compose up --build
# 或者本地安装工具
pip install slither-analyzer mythril
# 然后按上述方式运行
```
详细设置请参见 [docs/INSTALL.md](docs/INSTALL.md)。
## ✨ 功能特性
- **Static Analysis**：基于模式的 18+ 种漏洞类型检测（重入、未检查调用、溢出/下溢、访问控制等）
- **Professional Audit**：SWC/CWE/OWASP/DASP 分类及合规性摘要
- **LLM Audit**：可选的 AI 分析（支持 OpenAI GPT-4o 或 Claude）
- **Risk Scoring**：严重性评级、置信度水平与代码指标
- **Cross-Validation**：与 Slither 和 Mythril 集成
- **REST API**：用于集成的 FastAPI 后端
- **Web UI**：Streamlit 界面，便于合约分析
- **Report Generation**：JSON、HTML、PDF、SARIF
## 📖 文档
- **[使用说明](HOW_TO_USE.md)** - 完整的分步使用指南 ⭐ **从这里开始**
- **[安装指南](docs/INSTALL.md)** - 设置与前置条件
- **[Usage Guide](docs/USAGE.md)** - API 示例与工作流
- **[Docker Guide](docs/DOCKER.md)** - 容器化部署
- **[Architecture](docs/ARCHITECTURE.md)** - 系统设计与性能特征
- **[Security & Limitations](SECURITY.md)** - 负责任使用指南
- **[Professional Audit Guide](PROFESSIONAL_AUDIT_GUIDE.md)** - 专业审计工作流与报告
## 🛠️ 安装
### 前置条件
- Python 3.10+（**3.11/3.12 已测试**；部分依赖尚未正式支持 3.14）
- Git
- （可选）用于 AI 功能的 OpenAI API key 或 Claude API key
- （可选）用于容器化部署的 Docker Desktop
### 快速安装
```
# 克隆仓库
git clone https://github.com/yourusername/solidity-vuln-scanner.git
cd solidity-vuln-scanner
# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# 安装依赖
pip install -r requirements.txt
# 配置 (可选)
cp .env.example .env
# 编辑 .env 设置 USE_LLM=false 以使用免费模式，或添加 LLM_API_KEY 以启用 AI 功能
```
详细说明请参见 [docs/INSTALL.md](docs/INSTALL.md)。
## 🎯 使用方法
### Web UI
1. 启动应用（见上方“快速开始”）
2. 打开 http://localhost:8501
3. 粘贴 Solidity 合约代码
4. 点击“Analyze”
5. 查看漏洞、风险评分与建议
### REST API
```
# 分析合约 (仅静态分析)
curl -X POST "http://localhost:8001/analyze" \
-H "Content-Type: application/json" \
-d '{
"contract_code": "pragma solidity ^0.8.0; contract X { function f() public {} }",
"contract_name": "X",
"use_llm_audit": false
}'
# 分析并输出 SARIF (用于 CI/CD)
curl -X POST "http://localhost:8001/analyze-sarif" \
-H "Content-Type: application/json" \
-d '{
"contract_code": "pragma solidity ^0.8.0; contract X { function f() public {} }",
"contract_name": "X",
"use_llm_audit": false
}'
# 使用外部工具交叉验证
curl -X POST "http://localhost:8001/cross-validate" \
-H "Content-Type: application/json" \
-d '{
"contract_code": "pragma solidity ^0.8.0; contract X { function f() public {} }",
"contract_name": "X",
"run_slither": true,
"run_mythril": true
}'
# 批量分析 (多个合约)
curl -X POST "http://localhost:8001/analyze-batch" \
-H "Content-Type: application/json" \
-d '[
{"contract_code": "...", "contract_name": "Contract1"},
{"contract_code": "...", "contract_name": "Contract2"}
]'
```
**API 文档：** 访问 `http://localhost:8001/docs` 查看交互式文档（Swagger UI）
### 专业审计端点
```
curl -X POST "http://localhost:8001/professional-audit" \
-H "Content-Type: application/json" \
-d '{
"contract_code": "pragma solidity ^0.8.0; contract X { function f() public {} }",
"contract_name": "X",
"report_format": "pdf"
}' --output audit_report.pdf
```
更多示例与工作流请参见 [docs/USAGE.md](docs/USAGE.md)。
## 🧪 测试
```
# 运行所有测试
pytest -v
# 运行覆盖率测试
pytest --cov=. --cov-report=term-missing
# 运行特定测试套件
pytest tests/test_static_analyzer.py -v
pytest tests/test_fastapi_cross_validate.py -v
```
## 📊 性能基准
性能基准用于跟踪不同合约大小下的静态分析速度并检测性能回归。完整文档见 [benchmarks/README.md](benchmarks/README.md)。
**快速运行：**
```
pytest benchmarks/test_performance.py -v
```
**CI：** 基准在 main 分支合并时运行，结果作为 artifacts 上传。访问结果请参见 [docs/CI_ARTIFACTS.md](docs/CI_ARTIFACTS.md)。
## 📊 能检测什么？
该扫描器使用基于模式的分析检测 **18+ 种漏洞类型**：
| 漏洞 | 严重性 | 描述 |
|---|---|---|
| **Reentrancy** | Critical | 状态更新前进行外部调用 |
| **Unchecked Call** | High | 低级调用未进行错误处理 |
| **Overflow/Underflow** | High | 整数运算未使用 SafeMath |
| **Access Control** | High | 缺少权限检查 |
| **Bad Randomness** | Medium | 可预测的随机性来源 |
| **tx.origin Misuse** | High | 通过 tx.origin 进行授权 |
| **Delegatecall Risk** | High | 不安全的 delegatecall 模式 |
| **Gas DoS** | Medium | 无界循环 |
| **Timestamp Dependency** | Low | 不可靠的时间依赖 |
| **Selfdestruct** | Medium | 合约自毁能力 |
| **Missing Events** | Low | 状态变更未触发事件 |
| **Front-Running** | Medium | 交易排序漏洞 |
| **Logic Error** | Medium | 常见逻辑错误 |
| **Centralization Risk** | Medium | 单点控制风险 |
| **Missing Input Validation** | High | 函数参数未校验 |
| **Uninitialized Storage** | Medium | 未初始化的存储指针 |
| **Locked Ether** | Low | Ether 被锁定且无提取路径 |
详细检测方法与限制请参见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
## 🐳 Docker
```
# 启动所有服务 (API + UI + Tools)
docker-compose up --build
# 访问
# - UI: http://localhost:8501
# - API: http://localhost:8001
# - API Docs: http://localhost:8001/docs
```
详细 Docker 指南与故障排查请参见 [docs/DOCKER.md](docs/DOCKER.md)。
## ⚙️ 配置
编辑 `.env`：
```
# LLM 设置 (可选 - 可在免费模式下运行)
USE_LLM=false # Set to true for AI features
LLM_PROVIDER=openai # or "anthropic"
LLM_API_KEY=sk-... # Your API key
LLM_MODEL=gpt-4o-mini # Model name
# API 设置
API_PORT=8001
API_HOST=0.0.0.0
DEBUG=False
```
## 🚨 安全与免责声明
**本工具仅供教育与科研目的。** 它**不能替代**专业安全审计。
详细限制、负责任使用指南以及何时选择专业审计，请参见 [SECURITY.md](SECURITY.md)。
## 📈 性能
| 指标 | 数值 |
|---|---|
| 平均分析时间（100 LoC） | ~1-2 秒 |
| 最大合约大小 | 10,000 LoC |
| 静态分析误报率 | ~15% |
| LLM 误报率 | ~20% |
| API 速率限制 | 60 请求/分钟（可配置） |
详细性能指标请参见 [benchmarks/README.md](benchmarks/README.md)，可扩展性特征请参见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。
## 🤝 贡献
欢迎贡献！指南请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 📜 许可证
MIT License – 见 [LICENSE](LICENSE) 文件。
## 🔗 资源
- [DASP TOP 10 Smart Contract Risks](https://dasp.org/)
- [Solidity Security Guidelines](https://docs.soliditylang.org/en/v0.8.0/security-considerations.html)
- [OpenZeppelin Security Best Practices](https://docs.openzeppelin.com/contracts/)
- [Ethereum Smart Contract Security](https://consensys.io/research/smart-contract-best-practices/)
**最后更新**：2026 年 1 月
标签：AI安全, AV绕过, Chat Copilot, Claude, CVE检测, CWE分类, DApp安全, DASP, DLL 劫持, Docker, FastAPI, GPT-4, Kubernetes, Mythril, Petitpotam, Python, SARIF, Slither, Solidity, Streamlit, SWC标准, Web3安全, 云安全监控, 以太坊, 区块链安全, 去中心化应用, 大语言模型, 安全专业人员, 安全合规, 安全防御评估, 密码学, 对称加密, 手动系统调用, 文档安全, 无后门, 智能合约安全, 网络代理, 网络测绘, 自动化审计, 访问控制, 误配置预防, 请求拦截, 逆向工具, 配置审计, 重入攻击检测, 静态分析