VulHunter

EVM 兼容链节点漏洞挖掘平台。支持 Web 前端、REST API 和命令行 CLI 三种使用方式。

架构概览

vulhunter/
├── backend/      FastAPI + Celery + PostgreSQL + Redis
├── cli/          命令行工具（独立运行或连接后端）
└── frontend/     React 18 + Ant Design 5

扫描流程： 爬取（GitHub / 网页）→ AI 分析（Ollama）→ 扫描（网络层 / RPC 层 / 共识层）→ AI 循环建议

快速启动（Docker）

前置要求

Docker + Docker Compose
网络畅通（首次需拉取 qwen3-coder 模型，约 10~20 GB）

如果本地已运行 Ollama，可跳过 Docker 内的 ollama 服务，见下方「本地 Ollama 模式」。

第一步：准备配置文件

cd /Users/jesse/code/vulhunter
cp .env.example .env
# 按需编辑 .env（默认配置可直接使用）

第二步：启动基础设施和 Ollama

# 先启动 postgres、redis 和 ollama
docker-compose up -d postgres redis ollama

# 查看 ollama 拉模型进度（首次需要等待，看到 "success" 后继续）
docker-compose logs -f ollama
# 出现类似 "pulling manifest ... success" 后按 Ctrl+C

第三步：启动后端和前端

docker-compose up -d backend worker frontend

访问地址

服务	地址
前端 Web UI	http://localhost:5173
后端 API	http://localhost:8000
API 文档（Swagger）	http://localhost:8000/docs
健康检查	http://localhost:8000/health
Ollama	http://localhost:11434

后续启动（模型已缓存）

cd /Users/jesse/code/vulhunter
docker-compose up -d

常用运维命令

# 查看所有服务状态
docker-compose ps

# 查看实时日志
docker-compose logs -f backend
docker-compose logs -f worker
docker-compose logs -f ollama

# 重启某个服务（后端已开启 --reload，代码修改后自动热重载）
docker-compose restart backend

# 停止所有服务（保留数据）
docker-compose down

# 停止并清除所有数据（含数据库、模型缓存）
docker-compose down -v

本地 Ollama 模式（宿主机已运行 ollama serve）

如果你已在本机运行 ollama serve，无需在 Docker 中重复启动 ollama，只需修改 .env：

# .env
OLLAMA_BASE_URL=http://host.docker.internal:11434

然后启动时跳过 ollama：

docker-compose up -d postgres redis backend worker frontend

本地开发启动（不用 Docker）

前置要求

Python 3.13+
Node.js 20+
PostgreSQL 16+
Redis 7+
Ollama 已安装并运行，且已拉取模型：

ollama pull qwen3-coder

第一步：配置环境

cd /Users/jesse/code/vulhunter
cp .env.example .env
# 编辑 .env，确保数据库和 Redis 连接信息正确

第二步：启动后端

cd backend
pip3.13 install -r requirements.txt
playwright install chromium --with-deps

# 启动 API 服务
uvicorn app.main:app --reload --port 8000

# 新开终端，启动 Celery 任务队列
celery -A app.tasks.scan_tasks.celery_app worker --loglevel=info

第三步：启动前端

cd frontend
npm install
npm run dev
# 访问 http://localhost:5173

第四步：安装 CLI（可选）

# 在项目根目录执行
pip3.13 install -e .
vulhunter --help

CLI 使用指南

CLI 支持两种模式：

独立模式：直接在本地运行扫描，不需要启动后端服务
连接模式：--backend 指定后端地址，任务提交到后端运行，支持实时 WebSocket 流

命令总览

vulhunter init      # 生成配置文件模板
vulhunter validate  # 验证配置文件
vulhunter scan      # 执行扫描
vulhunter status    # 查看后端任务状态
vulhunter results   # 获取后端任务结果

`vulhunter init` — 生成配置模板

vulhunter init
vulhunter init --output my-node-scan.yaml

参数	默认值	说明
`--output`, `-o`	`vulhunter-scan.yaml`	生成的模板文件路径

`vulhunter validate` — 验证配置文件

vulhunter validate --config my-scan.yaml

参数	必填	说明
`--config`, `-c`	是	配置文件路径（YAML 或 JSON）

`vulhunter scan` — 执行扫描

# 独立模式（不需要后端）
vulhunter scan --config my-scan.yaml

# 连接后端模式
vulhunter scan --config my-scan.yaml --backend http://localhost:8000

# 输出 JSON 并保存文件
vulhunter scan --config my-scan.yaml --format json --output results.json

# 跳过确认提示直接执行
vulhunter scan --config my-scan.yaml --yes

参数	默认值	说明
`--config`, `-c`	必填	配置文件路径
`--backend`, `-b`	无	后端地址。指定后提交到后端运行，覆盖配置文件中的 `backend.url`
`--format`, `-f`	`terminal`	输出格式：`terminal` \| `json` \| `markdown`
`--output`, `-o`	无	结果保存路径（始终以 JSON 格式保存）
`--verbose`, `-v`	false	显示所有测试结果，不只是漏洞
`--yes`, `-y`	false	跳过开始确认提示

`vulhunter status` — 查看任务状态

vulhunter status <task-id>
vulhunter status <task-id> --backend http://prod:8000

参数	说明
`task-id`	后端任务 UUID
`--backend`, `-b`	后端地址（默认 `http://localhost:8000`）

`vulhunter results` — 获取任务结果

vulhunter results <task-id>
vulhunter results <task-id> --vuln-only          # 只显示漏洞
vulhunter results <task-id> --backend http://prod:8000

参数	说明
`task-id`	任务 UUID
`--vuln-only`	只显示已确认的漏洞
`--backend`, `-b`	后端地址

配置文件参考

通过 vulhunter init 生成模板。只有 targets.rpc_endpoints 是必填项，其余均有默认值。

# vulhunter-scan.yaml

name: "目标节点扫描"        # 任务名称
description: ""             # 备注（可选）

# ── 信息来源 ─────────────────────────────────────────────────────────────────
# 提供节点的源码和文档，AI 会从中分析 RPC 接口结构和内部解析逻辑
# 两者均为可选，但提供越多上下文，扫描越精准
sources:
  github:
    - https://github.com/org/evm-node       # 会执行 git clone（depth=1）
  web:
    - https://docs.example.com/rpc-api      # 会用 Playwright 渲染并提取内容

# ── 扫描目标 ─────────────────────────────────────────────────────────────────
targets:
  rpc_endpoints:                            # 必填，至少一个
    - http://192.168.1.100:8545             # HTTP JSON-RPC
    - ws://192.168.1.100:8546              # WebSocket JSON-RPC

# ── 扫描模块 ─────────────────────────────────────────────────────────────────
scanners:
  network:
    enabled: true
    extra_ports: []                         # 额外扫描的端口（默认已包含 30303/8545/8546/6060/9090 等）
    ddos_duration_seconds: 10              # DDoS 压测持续时间（秒）
    ddos_concurrency: 50                   # 压测并发数
    check_pprof: true                      # 检测 pprof / Prometheus 是否暴露

  rpc:
    enabled: true
    max_fuzz_iterations: 50                # 每个接口最多生成的 fuzz 用例数
    extra_sensitive_methods: []            # 追加到敏感方法测试列表
      # - custom_adminMethod
    skip_methods: []                       # 跳过某些接口的 fuzz（已知需要授权的）
      # - eth_getLogs

  consensus:
    enabled: false                         # 默认关闭（侵入性较强）
    test_malformed_blocks: true            # 提交字段非法但签名正确的块
    test_fork_handling: true               # 探测孤块/重组处理逻辑

# ── Ollama 配置 ───────────────────────────────────────────────────────────────
ollama:
  base_url: "http://localhost:11434"
  model: "qwen3-coder"                    # 需提前拉取：ollama pull qwen3-coder
  timeout: 300                            # 超时秒数（大型仓库分析需要更长时间）

# ── 输出配置 ─────────────────────────────────────────────────────────────────
output:
  format: "terminal"                      # terminal | json | markdown
  file: null                              # 结果保存路径，如 ./results/scan.json
  report_dir: "./reports"
  verbose: false                          # true 时显示所有测试项，不只是漏洞

# ── 后端连接（可选）──────────────────────────────────────────────────────────
# 指定 url 后，CLI 将任务提交到运行中的后端，并通过 WebSocket 流式接收结果
backend:
  url: null                               # 如 http://localhost:8000
  api_key: null                           # Bearer Token（如后端启用了认证）

环境变量说明（`.env`）

变量	默认值	说明
`DATABASE_URL`	`postgresql+asyncpg://vulhunter:vulhunter@localhost:5432/vulhunter`	异步 PostgreSQL 连接（后端 API 使用）
`DATABASE_URL_SYNC`	`postgresql://vulhunter:vulhunter@localhost:5432/vulhunter`	同步连接（Celery Worker 使用）
`REDIS_URL`	`redis://localhost:6379/0`	Redis 连接
`CELERY_BROKER_URL`	`redis://localhost:6379/0`	Celery 消息队列
`CELERY_RESULT_BACKEND`	`redis://localhost:6379/1`	Celery 结果存储
`OLLAMA_BASE_URL`	`http://localhost:11434`	Ollama API 地址
`OLLAMA_MODEL`	`qwen3-coder`	使用的模型名称
`OLLAMA_TIMEOUT`	`300`	Ollama 请求超时（秒）
`ANTHROPIC_API_KEY`	空	Claude API Key（可选，用于云端 AI 分析）
`GITHUB_TOKEN`	空	GitHub Token（私有仓库或提高 API 限额）
`WORKSPACE_DIR`	`/tmp/vulhunter/workspace`	克隆仓库的本地存储路径
`REPORT_DIR`	`/tmp/vulhunter/reports`	报告输出目录
`NETWORK_SCAN_TIMEOUT`	`30`	nmap 扫描超时（秒）
`RPC_REQUEST_TIMEOUT`	`10`	每次 RPC 请求超时（秒）
`MAX_FUZZ_ITERATIONS`	`50`	每个接口最大 fuzz 用例数
`DDOS_DURATION_SECONDS`	`10`	压力测试持续时间
`DDOS_CONCURRENCY`	`50`	压力测试并发数
`DEBUG`	`false`	开启 SQLAlchemy 查询日志

REST API 参考

Base URL：http://localhost:8000/api/v1

任务管理

方法	路径	说明
`POST`	`/scan/tasks`	创建扫描任务
`GET`	`/scan/tasks`	列出所有任务（最近 50 条）
`GET`	`/scan/tasks/{id}`	获取任务详情
`POST`	`/scan/tasks/{id}/start`	启动待执行任务
`POST`	`/scan/tasks/{id}/cancel`	取消运行中的任务
`DELETE`	`/scan/tasks/{id}`	删除任务及所有结果

结果查询

方法	路径	说明
`GET`	`/scan/tasks/{id}/results`	获取扫描结果，`?vulnerabilities_only=true` 只返回漏洞
`GET`	`/scan/tasks/{id}/analysis`	获取 Ollama 代码分析结果（接口列表、节点信息）
`GET`	`/scan/tasks/{id}/suggestions`	获取 AI 生成的下一步建议

AI 交互接口

这组接口专为交互式测试设计，支持在测试过程中由 Claude Code 直接调用。

方法	路径	说明
`POST`	`/scan/tasks/{id}/execute-test`	执行单条临时 RPC 测试并保存结果
`POST`	`/scan/tasks/{id}/ai-analyze`	触发新一轮 AI 分析，基于当前结果生成建议
`POST`	`/scan/tasks/{id}/suggestions/{sid}/approve`	审批 AI 建议（批准后自动执行建议中的测试用例）

`POST /scan/tasks/{id}/execute-test` 请求体

{
  "rpc_endpoint": "http://192.168.1.100:8545",
  "method": "personal_listAccounts",
  "params": [],
  "note": "测试未授权访问"
}

WebSocket 实时事件

ws://localhost:8000/api/v1/scan/tasks/{id}/ws

事件类型	data 内容	说明
`status`	`{status, progress}`	任务状态变更
`log`	字符串	流程日志
`scan_result`	`ScanResult`	某项测试完成（非漏洞）
`vulnerability`	`ScanResult`	发现漏洞
`analysis_complete`	`AnalysisResult`	Ollama 分析完成
`ai_suggestion`	`AISuggestion`	AI 生成了新建议
`error`	字符串	发生错误
`complete`	`{task_id}`	扫描流程结束

扫描流程详解

用户输入
 ├── GitHub URL  ──→  git clone（depth=1）→ 提取关键文件
 ├── 网页 URL    ──→  Playwright 渲染 → HTML 转 Markdown
 └── RPC 端点    ──→  用于扫描阶段
         │
         ▼
   【Ollama 分析】（qwen3-coder）
   - 识别 RPC 方法、认证要求、参数类型、内部解析逻辑
   - 输出结构化 JSON：接口列表、节点类型、共识机制
         │
         ▼
   【扫描器】（对每个 RPC 端点并发执行）
   ├── NetworkScanner（网络层）
   │   ├── nmap：扫描 30303/8545/8546/6060/9090 等端口
   │   ├── 压力测试：50 并发畸形请求持续 10 秒，检测节点稳定性
   │   └── 暴露检测：pprof、Prometheus metrics 端点
   ├── RPCScanner（接口层）
   │   ├── 未授权访问：28 个敏感方法（personal_* / admin_* / debug_*）
   │   └── AI 引导 Fuzz：基于 Ollama 分析的参数类型和解析逻辑生成测试用例
   └── ConsensusScanner（共识层，可选）
       ├── 畸形块提交：零哈希 / 未来时间戳 / gas 溢出 / PoA 假签名
       └── 分叉处理探测：孤块、叔块处理逻辑
         │
         ▼
   【AI 分析循环】
   - 汇总发现的漏洞，识别攻击模式
   - 生成下一步测试建议（含具体方法和参数）
   - 用户审批后自动执行建议的测试用例

漏洞等级

等级	颜色	含义
`critical`	🔴 红色	远程代码执行、私钥泄露、资金被盗
`high`	🟠 橙色	无需认证的管理员操作、矿工控制
`medium`	🟡 黄色	信息泄露、调试接口暴露
`low`	🔵 青色	轻微信息泄露、非利用性配置问题
`info`	灰色	正常行为、仅供参考

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.claude		.claude
agent		agent
backend		backend
bin		bin
cli		cli
frontend		frontend
tools		tools
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
start.sh		start.sh

Folders and files

Latest commit

History

Repository files navigation

VulHunter

架构概览

快速启动（Docker）

前置要求

第一步：准备配置文件

第二步：启动基础设施和 Ollama

第三步：启动后端和前端

访问地址

后续启动（模型已缓存）

常用运维命令

本地 Ollama 模式（宿主机已运行 ollama serve）

本地开发启动（不用 Docker）

前置要求

第一步：配置环境

第二步：启动后端

第三步：启动前端

第四步：安装 CLI（可选）

CLI 使用指南

命令总览

vulhunter init — 生成配置模板

vulhunter validate — 验证配置文件

vulhunter scan — 执行扫描

vulhunter status — 查看任务状态

vulhunter results — 获取任务结果

配置文件参考

环境变量说明（.env）

REST API 参考

任务管理

结果查询

AI 交互接口

POST /scan/tasks/{id}/execute-test 请求体

WebSocket 实时事件

扫描流程详解

漏洞等级

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`vulhunter init` — 生成配置模板

`vulhunter validate` — 验证配置文件

`vulhunter scan` — 执行扫描

`vulhunter status` — 查看任务状态

`vulhunter results` — 获取任务结果

环境变量说明（`.env`）

`POST /scan/tasks/{id}/execute-test` 请求体

Packages