IamHammadDevX/VulnGaurd-AI
GitHub: IamHammadDevX/VulnGaurd-AI
基于大语言模型的 Solidity 智能合约漏洞扫描器，帮助开发者和审计人员在合约上线前快速发现安全缺陷并获取修复建议。
Stars: 0 | Forks: 0
# VulnGuard AI
**AI 驱动的 Solidity 智能合约漏洞扫描器**
VulnGuard AI 可帮助开发者和审计人员在 Ethereum 智能合约上线之前发现安全漏洞。粘贴你的 Solidity 代码，点击扫描，即可获得由 OpenRouter 托管的 LLM 生成的详细漏洞报告——包含严重性评级、通俗易懂的解释、修复前后的代码，以及可下载的 PDF 审计报告。
## 功能
- **AI 驱动分析** — 使用 OpenRouter 检测 15 种以上的漏洞类别，包括重入、整数溢出、访问控制问题等
- **Monaco 代码编辑器** — 具备语法高亮和支持拖放 `.sol` 文件的全功能 Solidity 编辑器
- **严重性评级** — 每个发现都会以彩色卡片形式标记为 CRITICAL / HIGH / MEDIUM / LOW
- **修复前 / 后代码** — 每个漏洞都会展示存在漏洞的代码片段及修复后的版本
- **AI 深度修复** — 为任何单个漏洞生成增强且详细的修复方案
- **严重性分布图表** — 直观的饼图，总结您合约的风险概况
- **PDF 审计报告** — 下载包含封面、执行摘要和各漏洞详细信息的 PDF 专业报告
- **示例合约** — 内置 VulnerableBank、InsecureToken 和 SafeBank 示例以供探索
## 技术栈
| 层级 | 技术 |
|-------|-----------|
| Frontend | React 19, Vite, Tailwind CSS v4, Monaco Editor |
| Backend | Node.js, Express 5, TypeScript |
| Database | Supabase Postgres + Drizzle ORM |
| AI | OpenRouter（默认为 `anthropic/claude-3.7-sonnet`） |
| API Contract | OpenAPI 3.0, Orval codegen, Zod 验证 |
| PDF | PDFKit |
| Charts | Recharts |
| Package Manager | pnpm (monorepo) |
## 项目结构
```
vulnguard-ai/
├── artifacts/
│ ├── api-server/ # Express backend (port 8080)
│ │ └── src/
│ │ └── routes/
│ │ └── vulnguard/
│ │ ├── scan.ts # POST /api/scan
│ │ ├── generate-fix.ts # POST /api/generate-fix
│ │ ├── report.ts # GET /api/report/:scanId
│ │ ├── store.ts # In-memory scan store
│ │ └── prompts.ts # LLM system prompts
│ └── vulnguard/ # React frontend (Vite)
│ └── src/
│ ├── pages/Home.tsx
│ ├── hooks/use-scanner.ts
│ └── components/
│ ├── VulnerabilityCard.tsx
│ └── SeverityChart.tsx
├── lib/
│ ├── api-spec/openapi.yaml # OpenAPI 3.0 specification
│ ├── api-client-react/ # Generated React Query hooks
│ ├── api-zod/ # Generated Zod validation schemas
│ └── integrations-anthropic-ai/ # OpenRouter client wrapper
├── .env.example # Environment variable template
└── README.md
```
## 快速开始
### 前置条件
- Node.js 20+
- pnpm 9+
- OpenRouter API 密钥 — 请访问 [openrouter.ai/keys](https://openrouter.ai/keys) 获取
### 1. 克隆仓库
```
git clone https://github.com/IamHammadDevX/VulnGaurd-AI.git
cd VulnGaurd-AI
```
### 2. 设置环境变量
```
cp .env.example .env
```
打开 `.env` 并填入你的值：
```
OPENROUTER_API_KEY=sk-or-your-key-here
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_MODEL=anthropic/claude-3.7-sonnet
DATABASE_URL=postgresql://postgres.:@aws-0-.pooler.supabase.com:6543/postgres?sslmode=require
PORT=8080
NODE_ENV=development
LOG_LEVEL=info
```
### 3. 安装依赖
```
pnpm install
```
### 4. 配置数据库 schema (Supabase)
```
pnpm --filter @workspace/db run push
```
### 5. 运行代码生成
```
pnpm --filter @workspace/api-spec run codegen
```
### 6. 启动开发服务器
打开两个终端：
**终端 1 — API 服务器**
```
pnpm --filter @workspace/api-server run dev
```
**终端 2 — 前端**
```
pnpm --filter @workspace/vulnguard run dev
```
然后在浏览器中打开 [http://localhost:5173](http://localhost:5173)。
## API 参考
### `POST /api/scan`
扫描 Solidity 智能合约以查找漏洞。
**请求**
```
{
"code": "pragma solidity ^0.8.0; contract MyContract { ... }",
"contractName": "MyContract"
}
```
**响应**
```
{
"success": true,
"scanId": "uuid-v4",
"contract_name": "MyContract",
"total_vulnerabilities": 3,
"risk_score": 72,
"vulnerabilities": [
{
"id": 1,
"type": "Reentrancy",
"severity": "CRITICAL",
"title": "Reentrancy in withdraw()",
"description": "...",
"technical_risk": "...",
"vulnerable_code": "...",
"fixed_code": "...",
"recommendation": "..."
}
],
"summary": "...",
"analysis_time_ms": 12500,
"timestamp": "2026-01-01T00:00:00.000Z"
}
```
### `POST /api/generate-fix`
为特定漏洞生成增强的 AI 修复方案。
**请求**
```
{
"vulnerability": { ... },
"contractCode": "pragma solidity ..."
}
```
**响应**
```
{
"success": true,
"original_code": "...",
"fixed_code": "...",
"explanation": "...",
"resources": ["https://..."]
}
```
### `GET /api/report/:scanId`
下载已完成扫描的 PDF 审计报告。
**响应** — `application/pdf` 二进制流
## 可检测的漏洞类型
| 类别 | 示例 |
|----------|---------|
| **重入** | 单函数、跨函数、跨合约 |
| **算术** | 整数溢出/下溢、除以零 |
| **访问控制** | 缺少修饰符、tx.origin 用法 |
| **逻辑错误** | 竞态条件、抢跑、TOD |
| **不良随机性** | block.timestamp、blockhash 误用 |
| **拒绝服务** | Gas 限制问题、推送支付模式 |
| **闪电贷** | 价格操纵、预言机攻击 |
| **未检查调用** | 忽略返回值、低级调用 |
| **自毁** | 未受保护的 selfdestruct |
| **时间戳依赖** | 矿工可操纵的时间戳 |
## 在 Replit 上运行
本项目旨在 [Replit](https://replit.com) 上原生运行。请将你的 OpenRouter 凭据添加为环境变量。
1. 在 Replit 上 Fork 或导入该仓库
2. 在 Secrets 中添加 `OPENROUTER_API_KEY` 和可选的 `OPENROUTER_MODEL`
3. 点击 **Run** — 所有三个服务将自动启动
## 环境变量参考
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `DATABASE_URL` | 是 | Drizzle 和 API 运行时使用的 Supabase Postgres 连接字符串 |
| `SUPABASE_DB_URL` | 否 | 如果未设置 `DATABASE_URL`，则使用此回退数据库 URL |
| `SUPABASE_URL` | 是 (用于认证) | API 认证验证使用的 Supabase 项目 URL |
| `SUPABASE_ANON_KEY` | 是 (用于认证) | 前端认证使用的 Supabase 匿名/公共密钥 |
| `VITE_SUPABASE_URL` | 是 (前端认证) | Vite 暴露的 Supabase URL |
| `VITE_SUPABASE_ANON_KEY` | 是 (前端认证) | Vite 暴露的 Supabase 匿名/公共密钥 |
| `OPENROUTER_API_KEY` | 是 | 你的 OpenRouter API 密钥 |
| `OPENROUTER_BASE_URL` | 否 | OpenRouter 基础 URL（默认：`https://openrouter.ai/api/v1`） |
| `OPENROUTER_MODEL` | 否 | OpenRouter 模型 ID（默认：`anthropic/claude-3.7-sonnet`） |
| `OPENROUTER_HTTP_REFERER` | 否 | 发送给 OpenRouter 的可选 referer 请求头 |
| `OPENROUTER_APP_NAME` | 否 | 发送给 OpenRouter 的可选应用标题请求头 |
| `PORT` | 否 | API 服务器端口（默认：`8080`） |
| `NODE_ENV` | 否 | `development` 或 `production` |
| `LOG_LEVEL` | 否 | Pino 日志级别（默认：`info`） |
有关完整的安装演练，请参阅 `docs/SUPABASE_SETUP.md`。
## 安全说明
- API 密钥仅从环境变量中读取——绝不硬编码
- `.env` 已在 `.gitignore` 中列出，绝不能被提交
- AI 响应在使用前会根据 Zod schemas 进行验证——格式错误的模型输出将返回 HTTP 502，而不是传播错误数据
- 每个请求的合约代码限制为 50KB，以防止滥用
- 所有扫描数据仅存储在内存中（无数据库）——服务器重启时数据将被清除
## 许可证
MIT — 详见 [LICENSE](LICENSE)。
## 致谢
- [OpenRouter](https://openrouter.ai/) — LLM 网关和路由
- [OpenZeppelin](https://docs.openzeppelin.com/) — 安全模式和参考资料
- [SWC Registry](https://swcregistry.io/) — 智能合约弱点分类
- [Secureum](https://secureum.substack.com/) — Solidity 安全知识库
标签：AI代码审计, CISA项目, Claude Sonnet, Express, GNU通用公共许可证, MITM代理, Monaco Editor, Node.js, OpenRouter, PDF报告生成, React, Solidity漏洞扫描, Supabase, Syscalls, Tailwind CSS, TypeScript, Vite, Web3安全工具, Web3开发, 代码安全检测, 以太坊安全, 区块链安全, 大语言模型(LLM)应用, 安全插件, 安全防护, 整数溢出检测, 智能合约安全, 智能合约审计, 漏洞修复建议, 自动化攻击, 访问控制漏洞, 重入攻击检测, 静态应用程序安全测试(SAST)