PXLabs-code/AISolidityAuditor
GitHub: PXLabs-code/AISolidityAuditor
该项目将 Slither 静态分析结果与大语言模型解释相结合，为 Solidity 智能合约开发者生成易于理解的漏洞分诊报告。
Stars: 0 | Forks: 0
# AISolidityAuditor
[](https://github.com/PXLabs-code/AISolidityAuditor/actions/workflows/ci.yml)
[](LICENSE)
**Solidity 安全分诊助手**
基于 Slither 的静态分析，并提供 AI 辅助解释，用于开发者教育和早期风险审查。
AISolidityAuditor 将 Slither 的输出转换为对开发者友好的 Markdown 报告、原始 JSON、发现结果 JSON，以及用于 GitHub code scanning 的 SARIF。它专为早期风险分诊和学习而构建，不能替代专业的审计。
## 目录
- [问题](#problem)
- [适用人群](#who-it-helps)
- [为何这是公共基础设施](#why-this-is-public-good-infrastructure)
- [功能](#features)
- [工作原理](#how-it-works)
- [快速开始](#quick-start)
- [演示](#demo)
- [示例报告](#example-reports)
- [GitHub Action](#github-action)
- [安全模型](#security-model)
- [评估与基准](#evaluation-and-benchmark)
- [局限性](#limitations)
- [路线图](#roadmap)
- [开发](#development)
- [API 参考](#api-reference)
- [配置](#configuration)
- [测试](#testing)
- [文档](#documentation)
- [免责声明](#disclaimer)
## 问题
Slither 是 Solidity 生态系统中最有用的静态分析器之一，但对于新团队来说，其原始输出可能难以直接采取行动。早期协议、黑客松团队、资助申请者和学生通常需要一种快速的方法来了解发现结果的含义、它在源代码中出现的位置，以及还需要进行何种类型的人工审查。
AISolidityAuditor 通过结合 Slither 发现结果、附近的源代码上下文、可选的 AI 解释以及可共享的机器可读输出，弥补了这一差距。
## 适用人群
- 需要plain-English解释静态分析结果的 Solidity 学习者。
- 在寻求反馈之前进行预审查检查的黑客松团队和早期项目。
- 需要 CI artifacts 和 SARIF code scanning 结果的开源维护者。
- 需要针对常见漏洞类别提供可重复示例的教育者和导师。
- 希望对提交的代码进行轻量级、可重复的风险分诊的资助审查者。
## 为何这是公共基础设施
本项目被设计为开放的开放式基础设施，而不是一个封闭的审计产品：
- 它保留原始的 Slither JSON，绝不将 AI 文本视为事实来源。
- 它生成 SARIF，以便结果可以显示在 GitHub code scanning 中。
- 它可以作为自托管的 Web 应用程序或可重用的 GitHub Action 运行。
- 它包含针对常见 Solidity 风险模式的评估测试基线。
- 它明确标出需要人工审查的要求，并避免声称可以替代审计。
## 功能
| 功能 | 描述 |
|---------|-------------|
| ZIP 上传 | 支持带有安全限制和文件白名单的多文件 Solidity 项目 |
| Slither 分诊 | 静态分析、发现结果去重和严重性排序 |
| AI 辅助 | 基于源代码上下文的 OpenAI 兼容、Claude 或 DeepSeek 解释 |
| Markdown 报告 | 包含主要风险、源代码片段、折叠的信息类发现 |
| SARIF 输出 | 兼容 GitHub code scanning 的结果 |
| GitHub Action | 包含 artifacts、SARIF 上传、可选的 PR 评论以及可配置的失败策略的 CI 分诊模式 |
| 评估测试基线 | 30 个带有预期检测器、严重性、SARIF 检查和解释关键字的示例合约 |
| Glamsterdam 就绪检查 | 针对 gas、EVM、ETH 传输日志、区块上下文和合约大小关注点的 Solidity 升级就绪分诊的可选 Action 模式 |
## 工作原理
```
ZIP or GitHub workspace
-> safe project extraction / checkout
-> Slither JSON
-> finding deduplication and severity ordering
-> source-context extraction
-> optional AI explanation and validation
-> Markdown, findings JSON, Slither JSON, SARIF
```
AI 解释会验证必需的 JSON 字段，并针对 Slither 发现结果和源上下文进行基础验证。缺失或脱离上下文的解释会被标记为低置信度。所有解释仅供参考，始终需要进行人工审查。
## 快速开始
```
git clone https://github.com/PXLabs-code/AISolidityAuditor.git
cd AISolidityAuditor
cp backend/.env.example backend/.env
# 可选：设置 OPENAI_API_KEY=sk-...
# 或者设置 AI_PROVIDER=claude 和 ANTHROPIC_API_KEY=sk-ant-...
# 或者设置 AI_PROVIDER=deepseek 和 DEEPSEEK_API_KEY=sk-...
docker compose up --build
```
打开 `http://localhost:8000`。
1. 上传 `examples/reentrancy-example.zip`。
2. 可选地提供 AI 提供商的 API 密钥。
3. 点击 **Start Triage**。
4. 审查发现结果、源代码上下文、Markdown 报告和 SARIF 输出。
如果未配置 AI 密钥，Slither 分诊仍会完成，并且报告会记录无法提供 AI 解释的原因。
## 演示
包含一个存在漏洞的重入漏洞示例：
| 文件 | 用途 |
|------|---------|
| `examples/reentrancy/Reentrancy.sol` | 源合约 |
| `examples/reentrancy-example.zip` | 可直接上传的 ZIP 文件 |
| `examples/evaluation/` | 30 个涵盖常见风险模式的评估测试基线 |
有关简短的演示流程，请参见 [docs/demo-script.md](docs/demo-script.md)。
## 示例报告
生成的示例报告可供快速查看：
- [重入漏洞报告](examples/reports/reentrancy-report.md)
- [干净合约报告](examples/reports/clean-report.md)
- [多项发现报告](examples/reports/multi-finding-report.md)
这些示例展示了该项目如何将 Slither 发现结果、源代码上下文、AI 解释、置信度和人工审查要求区分开来。
## GitHub Action
AISolidityAuditor 可以作为 Solidity 存储库中的安全分诊步骤运行。它会生成：
- `audit-report.md`
- `slither.json`
- `findings.json`
- `audit-results.sarif`
- GitHub Actions artifact
- 可选的 pull request 评论
- 可选地上传 SARIF 到 GitHub code scanning
```
name: Solidity Security Triage
on:
pull_request:
push:
permissions:
contents: read
security-events: write
pull-requests: write
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: PXLabs-code/AISolidityAuditor@371a1b5d87425296dfec289dcc822ebcd15d0df1
with:
openai_api_key: ${{ secrets.OPENAI_API_KEY }}
ai_provider: openai
comment_on_pr: "true"
```
对于 Claude：
```
- uses: PXLabs-code/AISolidityAuditor@371a1b5d87425296dfec289dcc822ebcd15d0df1
with:
ai_provider: claude
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
```
对于 DeepSeek：
```
- uses: PXLabs-code/AISolidityAuditor@371a1b5d87425296dfec289dcc822ebcd15d0df1
with:
ai_provider: deepseek
deepseek_api_key: ${{ secrets.DEEPSEEK_API_KEY }}
```
对于遇到高危发现即失败，并保持 SARIF 专注于主要风险的无 AI CI 门禁：
```
- uses: PXLabs-code/AISolidityAuditor@371a1b5d87425296dfec289dcc822ebcd15d0df1
with:
upload_sarif: "true"
comment_on_pr: "true"
fail_on_high: "true"
include_informational: "false"
```
对于与当前 ESP 愿望清单对齐的 Glamsterdam 就绪运行。设置 `readiness_path` 可将启发式扫描限制在应用程序源代码（例如 Foundry 存储库中的 `src/`），而 Slither 仍会分析完整的 `project_path`：
```
- uses: PXLabs-code/AISolidityAuditor@371a1b5d87425296dfec289dcc822ebcd15d0df1
with:
project_path: .
readiness_path: src
mode: glamsterdam-readiness
upload_sarif: "true"
comment_on_pr: "true"
include_informational: "false"
```
在此存储库中，可以使用 `uses: ./` 来执行相同的 action，这也是端到端演示工作流（[.github/workflows/action-e2e-demo.yml](.github/workflows/action-e2e-demo.yml)）验证完整 Action、SARIF 上传、artifact 和 PR 评论链的方式。
此模式除了输出常规的 Slither 分诊 artifacts 外，还会输出：
- `glamsterdam-readiness-report.md`
- `glamsterdam-findings.json`
- 带有 `glamsterdam`、`gas-repricing`、`evm-compatibility`、`eth-transfer-logs` 和 `contract-size` 等标签的 SARIF 规则
每个就绪检查发现结果都带有规则置信度级别（低置信度规则特意设计为高召回率）、规则依据以及相关的 Glamsterdam 分叉候选方案（例如 EIP-7732 ePBS、EIP-7928 BALs、EIP-7708 ETH 转账日志）。已审查的匹配项可以通过内联的 `// glamsterdam-ignore` 标记或位于扫描根目录的 `glamsterdam-baseline.json` 文件进行抑制。
## 安全模型
上传的 ZIP 文件被视为不受信任的输入。
- 拒绝路径遍历、绝对路径和符号链接。
- 强制执行上传大小、文件数量、单个文件限制以及总解压大小限制。
- 仅允许 Solidity 源代码和常见的项目配置文件。
- 使用 `SLITHER_TIMEOUT_SEC` 运行 Slither。
- 将每个任务存储在一个隔离的目录中。
- Docker Compose 使用只读的根文件系统、tmpfs `/tmp`、丢弃的 Linux capabilities、`no-new-privileges`，以及进程/内存/CPU 限制。
- 不持久化或记录用户提供的 AI 密钥。
- 保留原始 Slither 输出以供独立审查。
- 将所有结果（包括成功的 AI 解释）标记为需要进行人工审查。
请参见 [docs/threat-model.md](docs/threat-model.md) 和 [docs/sandbox.md](docs/sandbox.md)。
## 评估与基准
评估套件将 `examples/evaluation/` 转化为有 CI 支持的测试工具。它针对测试基线合约运行 Slither，检查预期的检测器 ID 和严重性，验证 SARIF 的生成，并通过与用于 AI 响应相同的基础验证守卫来验证确定性的、有根据的解释 payload。
有关原始 Slither 与 AISolidityAuditor 的基准测试计划以及测试基线扩展待办事项，请参见 [docs/benchmark-report.md](docs/benchmark-report.md)。
## ESP 愿望清单对齐
当前的小额资助范围是一个 **Glamsterdam Solidity 就绪分诊工具包**。它建立在 AISolidityAuditor 的基础之上，帮助 Ethereum 构建者审查 Solidity 项目，找出随着 Glamsterdam 候选方案演进可能需要关注的模式，包括 gas 重定价、EVM/操作码假设、原生 ETH 转账日志、区块上下文假设以及合约大小讨论。
有关 6-8 周的资助范围，请参见 [docs/glamsterdam-solidity-readiness-triage-toolkit-proposal.md](docs/glamsterdam-solidity-readiness-triage-toolkit-proposal.md)。
## 局限性
- 不是正式的审计，也不能替代专业审查。
- 静态分析无法可靠地检测业务逻辑错误。
- 即使有基础验证检查，AI 解释也可能不完整或错误。
- 复杂的 Foundry 或 Hardhat 项目可能需要手动准备 ZIP 文件。
- 目前的范围仅限于 Solidity/EVM 项目。
## 路线图
近期：
1. 发布专门的 `AISolidityAuditor-action` 存储库和 `v1` 标签。
2. 添加 SARIF 严重性调整和特定检测器的文档链接。
3. 增加 2-3 个真实项目的 Action 演示运行，并附带报告、JSON 和 SARIF artifacts。
4. 改进 Foundry 和 Hardhat 项目检测。
5. 为更多检测器类别添加生成的示例报告。
长期：
1. 添加多工具聚合功能，例如 Slither 加上 Aderyn。
2. 添加基于源代码感知的误报分诊。
3. 添加本地/离线 LLM 支持。
4. 添加 Etherscan 合约导入。
5. 添加 PDF 导出功能。
## 开发
### 后端
```
cd backend
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # Linux/macOS
pip install -r requirements-dev.txt
uvicorn app.main:app --reload --port 8000 --app-dir .
```
### 前端
```
cd frontend
npm install
npm run dev
```
打开 `http://localhost:5173`；Vite 会将 `/api` 代理到后端。
## API 参考
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `POST` | `/api/v1/audits` | 上传 ZIP (`file`，可选 `api_key`，可选 `ai_provider`) |
| `GET` | `/api/v1/audits/{taskId}` | 任务状态 |
| `GET` | `/api/v1/audits/{taskId}/findings` | 包含 AI 和源代码上下文字段的发现结果 |
| `GET` | `/api/v1/audits/{taskId}/report` | Markdown 报告 |
| `GET` | `/api/v1/audits/{taskId}/sarif` | 用于 GitHub code scanning 的 SARIF |
| `GET` | `/api/v1/audits/{taskId}/slither` | 原始 Slither JSON |
| `GET` | `/api/health` | Slither、solc 和 AI 提供商配置 |
## 配置
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `DATA_DIR` | `./data/jobs` | 任务存储目录 |
| `AI_PROVIDER` | `openai` | 默认 AI 提供商 (`openai`、`claude` 或 `deepseek`) |
| `OPENAI_API_KEY` | 空 | OpenAI 兼容的 API 密钥 |
| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | OpenAI 兼容的 endpoint |
| `OPENAI_MODEL` | `gpt-4o-mini` | OpenAI 兼容的模型 |
| `ANTHROPIC_API_KEY` | 空 | Claude API 密钥 |
| `CLAUDE_MODEL` | `claude-3-5-haiku-latest` | Claude 模型 |
| `DEEPSEEK_API_KEY` | 空 | DeepSeek API 密钥 |
| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com/v1` | DeepSeek 兼容 OpenAI 的 endpoint |
| `DEEPSEEK_MODEL` | `deepseek-chat` | DeepSeek 模型 |
| `MAX_UPLOAD_MB` | `10` | ZIP 上传最大大小 |
| `MAX_ZIP_FILES` | `200` | 最大解压文件数量 |
| `MAX_ZIP_MB` | `2` | 单个 ZIP 成员的最大未压缩大小 |
| `MAX_EXTRACTED_MB` | `30` | ZIP 文件的最大总未压缩大小 |
| `SLITHER_TIMEOUT_SEC` | `120` | Slither 子进程超时时间 |
| `MAX_AI_FINDINGS` | `20` | 使用 AI 解释的最大发现结果数量 |
| `JOB_RETENTION_HOURS` | `24` | 自动清理保留时间 |
| `CORS_ORIGINS` | localhost 源 | 允许的 CORS 源 |
## 测试
```
cd backend
ruff check app tests
pytest tests -v
cd ../frontend
npm run build
cd ..
docker build -f docker/Dockerfile .
```
对于没有安装本地 Python、Node、Slither 或 solc 的资助审查者和贡献者，基于 Docker 的验证非常有用：
```
# 构建生产镜像，包括前端资产和 Slither runtime。
docker build -f docker/Dockerfile .
# 在安装了 solc 的一次性 Python 容器中运行后端测试。
docker run --rm -v "$PWD:/workspace" -w /workspace/backend python:3.11-slim bash -lc "\
apt-get update && apt-get install -y --no-install-recommends curl git build-essential && \
curl -fsSL https://github.com/ethereum/solidity/releases/download/v0.8.20/solc-static-linux -o /usr/local/bin/solc && \
chmod +x /usr/local/bin/solc && \
pip install -r requirements-dev.txt && \
ruff check app tests && \
pytest tests -v"
```
PowerShell 等效命令：
```
docker build -f docker/Dockerfile .
docker run --rm -v "${PWD}:/workspace" -w /workspace/backend python:3.11-slim bash -lc "apt-get update && apt-get install -y --no-install-recommends curl git build-essential && curl -fsSL https://github.com/ethereum/solidity/releases/download/v0.8.20/solc-static-linux -o /usr/local/bin/solc && chmod +x /usr/local/bin/solc && pip install -r requirements-dev.txt && ruff check app tests && pytest tests -v"
```
测试套件涵盖了上传安全性、Slither 解析、发现结果去重、AI 输出验证、源上下文提取、SARIF 生成、报告生成、评估测试基线元数据，以及在 Slither 和 solc 可用时由 CI 支持的评估运行。
## 文档
| 文档 | 描述 |
|----------|-------------|
| [docs/architecture.md](docs/architecture.md) | 系统设计和数据流 |
| [docs/threat-model.md](docs/threat-model.md) | ZIP 上传安全模型 |
| [docs/sandbox.md](docs/sandbox.md) | Docker 沙箱边界和强化路线图 |
| [docs/benchmark-report.md](docs/benchmark-report.md) | 评估和基准测试计划 |
| [docs/demo-script.md](docs/demo-script.md) | 演示录制指南 |
| [docs/real-project-demo.md](docs/real-project-demo.md) | 真实的公开 Solidity 存储库演示指南 |
| [docs/glamsterdam-solidity-readiness-triage-toolkit-proposal.md](docs/glamsterdam-solidity-readiness-triage-toolkit-proposal.md) | Ethereum 资助提案 |
## 免责声明
本工具仅提供自动化辅助。它不是正式的安全审计。AI 解释可能不完整或不准确。在将合约部署到 mainnet 之前，请务必进行人工审查。
## 许可证
[MIT](LICENSE)
标签：DLL 劫持, GitHub Action, Petitpotam, Solidity, 云安全监控, 代码安全, 大语言模型, 智能合约审计, 漏洞枚举, 请求拦截, 逆向工具, 静态分析