Nursca/Contract-Auditor
GitHub: Nursca/Contract-Auditor
一款结合确定性静态规则与 LLM 推理的 Solidity 智能合约安全审计工具，可在数秒内输出按严重程度排名的漏洞报告。
Stars: 0 | Forks: 0
# 合约审计工具
**专为 Solidity 开发者打造的 AI 驱动智能合约安全审计工具。**
粘贴一段合约，几秒钟即可获得按严重程度排名的漏洞报告 —— 结合了确定性静态分析与基于 LLM 的推理能力，能够捕获静态规则无法发现的逻辑层缺陷。
为 **Web3LadiesBuildWithAI Ship It Challenge** 专属打造。
## 工作原理
```
Frontend (paste contract)
│
▼
API orchestrator (/api/analyze)
│
┌────┴────┐
▼ ▼
Static LLM
scanner analysis engine
(7 rules) (Claude API)
│ │
└────┬────┘
▼
Report generator
(dedupe, rank by severity, risk score)
│
▼
Results screen
```
静态扫描器和 LLM 引擎是**并发**执行的，而非顺序执行，以将总分析时间控制在约 15 秒以内。如果 LLM 调用失败或超时，应用会优雅降级为仅显示静态分析结果，而不会报错 —— 这已经过测试并确认正常工作（API 响应中的 `meta.partial: true`）。
## 功能特性
- **混合分析**：7 条确定性静态规则（重入攻击、`tx.origin` 身份验证、未检查的调用、缺少访问控制、无限制的 `selfdestruct`、浮动 pragma、无限循环）+ 一个专门设定以捕获支付/退款/算术错误的 LLM 引擎
- **按严重程度排名的报告**：严重 → 高 → 中 → 低 → 信息，并附带 0–100 的加权风险评分
- **置信度信号**：被静态扫描器和 AI 引擎*同时*捕获的发现将被标记为 `static+ai` —— 这是一个直接在 UI 中展示的更高置信度信号
- **优雅降级**：如果 AI 分析失败或超时，您仍会获得静态分析结果，而不会遇到页面崩溃
- **无数据持久化**：合约在内存中进行分析，绝不记录或存储 —— 当人们粘贴真实的、未经审计的代码时，这是一种值得具备的隐私默认设置
## 技术栈
| 层级 | 选择 |
|---|---|
| 前端 | Next.js (App Router) + TypeScript + Tailwind |
| 静态扫描器 | 自定义基于正则表达式的规则引擎，零外部依赖 |
| AI 引擎 | Claude API (`claude-sonnet-4-6`)，结构化 JSON 输出 |
| 字体 | JetBrains Mono (代码/技术文本)，Inter (正文/UI) |
| 部署 | Vercel |
## 透明地使用 AI 构建
本项目同时也是一个展示在整个开发流程中进行 AI 辅助开发的演示：
- **[Antigravity](https://antigravity.google)** — 实现了核心引擎（数据 schema、静态扫描器规则、LLM 引擎封装、报告生成器、API 协调器）以及完整的前端，基于书面的实施计划和设计系统构建，在人工审查的逐步监督下完成任务
- **[Stitch](https://stitch.withgoogle.com)** — 生成了 UI 设计系统和界面设计（输入、加载、结果、错误状态），导出为 `design/DESIGN.md` 并在前端实施期间直接被 Antigravity 所使用
- **Claude (Anthropic)** — 不仅在开发期间使用，还为应用程序本身的实时漏洞分析引擎提供支持，此外还参与了指导构建的架构/PRD 规划和实施计划编写
## 快速开始
### 前置条件
- Node.js 18+
- 一个 [Anthropic API 密钥](https://console.anthropic.com/)
### 安装
```
git clone https://github.com/Nursca/Contract-Auditor.git
cd Contract-Auditor
npm install
```
### 环境变量
在项目根目录下创建一个 `.env.local` 文件：
```
ANTHROPIC_API_KEY=your_key_here
```
### 本地运行
```
npm run dev
```
打开 [http://localhost:3000](http://localhost:3000)。
## 使用方法
1. 将 Solidity 合约源码粘贴到文本框中（如果启用，也可以上传 `.sol` 文件）
2. 点击 **Analyze Contract**
3. 查看按严重程度排名的漏洞发现 —— 每一项都包含代码行参考、通俗易懂的描述以及建议的修复方案
### API
核心分析作为单个 endpoint 暴露：
```
POST /api/analyze
Content-Type: application/json
{ "source": "" }
```
返回一个 `AnalysisReport`：
```
{
"summary": {
"total_findings": 4,
"by_severity": { "critical": 1, "high": 1, "medium": 2, "low": 0, "informational": 0 },
"risk_score": 56
},
"findings": [
{
"id": "…",
"source": "static+ai",
"severity": "critical",
"category": "reentrancy",
"line": 42,
"title": "Reentrancy in withdraw()",
"description": "…",
"suggested_fix": "…",
"confidence": "high"
}
],
"meta": {
"analyzed_at": "2026-07-04T12:00:00.000Z",
"contract_length_lines": 118,
"analysis_duration_ms": 4230,
"partial": false
}
}
```
输入上限为 50KB，以控制延迟和 API 成本。
## 项目结构
```
Contract-Auditor/
├── app/
│ ├── page.tsx # Main flow: input → loading → results
│ └── api/analyze/route.ts # API orchestrator
├── components/
│ ├── InputScreen.tsx
│ ├── LoadingState.tsx
│ ├── ResultsScreen.tsx
│ └── ui/
│ ├── Button.tsx
│ ├── SeverityBadge.tsx
│ └── FindingCard.tsx
├── lib/
│ ├── types.ts # Shared Finding / AnalysisReport schema
│ ├── staticScanner.ts # 7 deterministic vulnerability rules
│ ├── llmEngine.ts # Claude API wrapper + prompt
│ └── reportGenerator.ts # Merge, dedupe, rank, risk score
├── design/
│ ├── DESIGN.md # Design system (Stitch export)
│ └── stitch-reference/ # Reference markup for screens
└── .agents/
└── CONTEXT.md # Persistent context for Antigravity
```
## 已知限制（实事求是，刻意为之）
- 静态扫描器使用正则表达式/字符串匹配，而非完整的 AST 解析 —— 速度快且无依赖，但可能会漏掉 AST 遍历能发现的深层嵌套或混淆模式
- 即使在低 temperature 下，LLM 的发现在不同运行之间的措辞也可能略有不同；被标记的潜在漏洞应保持一致，但确切表述可能不会
- 仅支持单文件分析 —— 尚不支持跨合约或多文件项目分析
- 没有用户账户或保存的历史记录 —— 每次分析都是无状态的，这是设计使然
## 路线图
- 基于 AST 的静态分析，以实现更准确的规则匹配
- GitHub URL / repo 级别分析（多文件）
- 可下载的 PDF 报告导出
- 自定义规则配置（允许团队添加自己的静态模式）
## 鸣谢
由 [@DeFiNursca](https://x.com/DeFiNursca) 为 Web3LadiesBuildWithAI Ship It Challenge 构建。
标签：Solidity, Web3, 云安全监控, 人工智能, 后端开发, 智能合约, 用户模式Hook绕过, 静态分析