bach619/sc_auditor

# 🛡️ VYPER — 智能合约漏洞猎手 [](https://python.org) [](https://fastapi.tiangolo.com) [](https://docker.com) [](https://react.dev) [](LICENSE) ## 📋 目录 - [VYPER 是什么？](#apa-itu-vyper) - [架构](#arsitektur) - [审计流水线](#pipeline-audit) - [19 个微服务](#19-microservices) - [技术栈](#tech-stack) - [快速开始](#quick-start) - [CLI 工具](#cli-tool) - [仪表盘](#dashboard) - [开发状态](#status-pengembangan) - [项目结构](#struktur-project) - [常见问题](#faq) ## VYPER 是什么？ **VYPER** 是一个 **智能合约安全审计** 平台，通过 Docker Compose 完全在本地运行。专为以下场景设计： - 🎯 **漏洞赏金猎人** — 扫描 Immunefi 项目中的合约，发现 True Positive，生成可直接提交的报告 - 🔬 **安全研究员** — 使用 Anvil fork 引擎验证发现的漏洞，证明漏洞存在 - 📊 **平台指标** — 追踪每个工具（Slither、Mythril、AI）的精确度，从 False Negative 中学习 ### 设计理念 ``` ┌──────────────────────────────────────────────────────────────┐ │ VYPER │ │ │ │ 19 microservices, 1 laptop. │ │ │ │ docker compose up │ │ ↓ │ │ Semua service jalan, komunikasi via HTTP/REST. │ │ │ │ Dashboard: http://localhost:8000 │ │ CLI: vyper audit 0x4c9edd... │ └──────────────────────────────────────────────────────────────┘ ``` ### 为什么选择微服务？ | 因素 | 单体架构 | VYPER（微服务） | |------|----------|-----------------| | **隔离性** | Slither 崩溃 → 全部停止 | Scanner 崩溃 → 其他服务继续运行 | | **扩展性** | 单一进程 | `docker compose up --scale scanner=3` | | **更新** | 全部重新部署 | 更新 Scanner v2 无需触碰 AI | | **调试** | 日志混杂 | `docker logs vyper-04-scanner-1` | | **依赖** | 一个 requirements.txt（冲突） | 每个服务独立管理 | ## 架构 ``` ┌──────────────────────────────────────────────────────────────────┐ │ USER │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 15-DASHBOARD (port 8000) React SPA + API Gateway │ │ │ │ Proxy ke semua service backend via ServiceProxy │ │ │ └────────┬─────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ 11-ORCHESTRATOR (port 8009) Jantung Pipeline │ │ │ │ - Priority queue & daemon mode │ │ │ │ - State machine 10 stage │ │ │ │ - Contract similarity & retroactive re-run │ │ │ │ - Resource governor (tool concurrency) │ │ │ └──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬───────────────────┘ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼ │ │ ┌────┐┌────┐┌────┐┌────┐┌────┐┌────┐┌────┐┌────┐┌────┐┌────┐ │ │ │ CFG││ IM ││ SRC││SCN ││ SLS││ECH ││ FRG││HAL ││MTH ││ AI │ │ │ │8011││8001││8002││8003││8014││8015││8016││8017││8013││8004│ │ │ └────┘└────┘└────┘└────┘└────┘└────┘└────┘└────┘└────┘└────┘ │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ │ │ ┌────┐┌────┐┌────┐┌────┐┌────┐┌────┐┌────┐┌────┐ │ │ │CLS ││EXP ││RPT ││NTF ││WHK ││UPK ││AGNT││DSH │ │ │ │8005││8006││8007││8008││8010││8012││8018││8000│ │ │ └────┘└────┘└────┘└────┘└────┘└────┘└────┘└────┘ │ └──────────────────────────────────────────────────────────────────┘ ``` ### 服务地图 | # | 服务 | 端口 | 角色 | |---|------|------|------| | 01 | **Config** | 8011 | 全局配置 + API 密钥 | | 02 | **Immunefi** | 8001 | 同步 234+ 漏洞赏金项目，检测仓库 | | 03 | **Source** | 8002 | 多源获取（GitHub、Sourcify、Etherscan、Blockscout） | | 04 | **Scanner** | 8003 | 主扫描器 — 路由到特定工具 | | 04a | **Scanner Slither** | 8014 | 静态分析（控制流、继承） | | 04b | **Scanner Echidna** | 8015 | Fuzzing 与基于属性的测试 | | 04c | **Scanner Forge** | 8016 | 构建验证（Foundry） | | 04d | **Scanner Halmos** | 8017 | 符号执行与形式化验证 | | 05 | **Scanner Mythril** | 8013 | 符号执行（深度路径探索） | | 06 | **AI** | 8004 | LLM 分析（OpenAI/Anthropic）、判定、修复建议 | | 07 | **Classifier** | 8005 | TP/FP/TN/FN 分类 + 指标 | | 08 | **Exploit** | 8006 | Anvil Docker 引擎 + PoC 生成 | | 09 | **Reporter** | 8007 | 生成 Immunefi 报告 + 完整报告 | | 10 | **Notifier** | 8008 | Discord / Telegram / Email / 桌面通知 | | 11 | **Orchestrator** | 8009 | 流水线协调器 + 状态机 | | 12 | **Webhook** | 8010 | Webhook 投递 + 签名 | | 13 | **Upkeep** | 8012 | 备份、更新、指标聚合 | | 14 | **Agent** | 8018 | 自主 Agent 编排 | | 15 | **Dashboard** | 8000 | React SPA + API Gateway + SSE 事件 | ## 审计流水线 每次审计通过 **8 个阶段** 由 Orchestrator 顺序执行： ``` ┌─────────────┐ │ PENDING │ └──────┬──────┘ │ start ▼ ┌─────────────────────┐ │ FETCHING_PROGRAM │ ← 02-Immunefi:8001 └──────────┬──────────┘ │ success ▼ ┌─────────────────────┐ │ FETCHING_SOURCE │ ← 03-Source:8002 └──────────┬──────────┘ │ success ▼ ┌─────────────────────┐ │ SCANNING │ ← 04-Scanner + 04a/b/c/d + 05 │ Slither + Mythril │ │ + Echidna + Halmos │ └──────┬──────────────┘ │ success ▼ ┌─────────────────────┐ │ AI_ANALYSIS │ ← 06-AI (LLM verdict) └──────┬──────────────┘ │ success ▼ ┌─────────────────────┐ │ CLASSIFYING │ ← 07-Classifier (TP/FP) └──────┬──────────────┘ │ success ▼ ┌─────────────────────┐ │ EXPLOITING │ ← 08-Exploit (Anvil) │ HANYA jika TP │ │ critical/high │ └──────┬──────────────┘ │ success ▼ ┌─────────────────────┐ │ REPORTING │ ← 09-Reporter └──────┬──────────────┘ │ success ▼ ┌─────────────────────┐ │ NOTIFYING │ ← 10-Notifier └──────┬──────────────┘ │ success ▼ ┌─────────────────────┐ │ COMPLETED │ ✓ └─────────────────────┘ State: pending → fetching_program → fetching_source → scanning → ai_analysis → classifying → exploiting? → reporting → notifying → completed ``` 每个状态都有 **失败状态**（source_failed、scan_failed、timeout 等），具备重试机制和 Saga 模式回滚。 ## 技术栈 ### 基础层 | 层级 | 技术 | |------|------| | **语言** | Python 3.11+（19 个服务） | | **框架** | FastAPI + Pydantic v2 | | **HTTP 客户端** | httpx（异步，连接池） | | **运行** | 每个服务独立 uvicorn | | **容器** | python:3.11-slim | | **编排** | Docker Compose v3.9 | | **存储** | 基于文件的 JSON（Docker volumes） | ### 审计工具 | 工具 | 功能 | 语言 | |------|------|------| | **Slither** | 静态分析（控制流、继承、重入） | Python | | **Mythril** | 符号执行（深度路径探索） | Python | | **Echidna** | Fuzzing 与基于属性的测试 | Haskell（二进制） | | **Halmos** | 符号执行与形式化验证 | Python | | **Foundry（Forge）** | 构建验证、测试运行器 | Rust（二进制） | | **Anvil** | 用于漏洞利用的本地 fork 以太坊节点 | Rust（Docker） | ### 前端与 CLI | 层级 | 技术 | |------|------| | **仪表盘** | React 18 + TypeScript + Tailwind v4 | | **CLI** | Typer + Rich + httpx 异步 | | **构建** | Vite 8 | ## 快速开始 ### 前置条件 ``` # 1. 安装 Docker 和 Docker Compose # 2. 克隆 repo git clone sc_auditor cd sc_auditor # 3. （可选）复制 environment cp .env.example .env # 根据需要填写 API key（OpenAI、Anthropic、Etherscan 等） ``` ### 启动所有服务 ``` # 构建并启动 19 个 service docker compose up --build -d # 检查所有 service 的健康状态 docker compose ps # 查看特定 service 的日志 docker compose logs -f 15-dashboard docker compose logs -f 11-orchestrator ``` ### 访问仪表盘 ``` http://localhost:8000 ``` React SPA 仪表盘，包含： - 📊 概览指标与发现 - 📋 Immunefi 项目列表 - 🔍 每个合约的审计详情 - 📈 平台指标与工具性能 - ⚙️ 设置与配置 ### 流水线 CLI ``` # 安装 CLI 工具 pip install -e . # 查看所有命令 vyper --help # Docker 生命周期 vyper up # Start semua service vyper down # Stop semua service vyper status # Cek status service vyper logs # Stream log # 审计 pipeline vyper audit 0x4c9edd5852cd905f086c759e8383e09bff1e68b3 --chain ethereum vyper scan contract.sol --tools slither,mythril vyper exploit finding-001 --attack reentrancy # 监控 vyper dashboard # Buka dashboard di browser vyper status aud_abc123 # Cek status audit vyper list # Lihat semua audit vyper stats # Lihat metrics platform ``` ### 数据存储 所有数据持久化在 Docker volumes 中： ``` ~/.vyper/ ├── config/config.json # Global config ├── immunefi/programs.json # 234+ program ├── scanner/results/{audit_id}/ # Scan results ├── ai/cache/ # LLM response cache ├── classifier/metrics.json # TP/FP metrics ├── exploit/results/{id}/ # PoC scripts ├── reports/{audit_id}/ # immunefi.md + full.md └── learning/ # Feedback & improvements ``` ## CLI 工具 通过 **Typer** CLI 提供 17 个命令： | 命令 | 功能 | |------|------| | `vyper up` | 启动 Docker Compose 服务 | | `vyper down` | 停止所有服务 | | `vyper logs` | 流式日志 | | `vyper ps` | 容器状态 | | `vyper restart` | 重启服务 | | `vyper audit` | 完整流水线审计 | | `vyper scan` | 快速扫描（仅扫描器） | | `vyper exploit` | 生成 PoC | | `vyper status` | 检查审计状态 | | `vyper list` | 列出所有审计 | | `vyper stats` | 平台指标 | | `vyper queue` | 查看优先级队列 | | `vyper health` | 所有服务健康检查 | | `vyper dashboard` | 打开浏览器仪表盘 | | `vyper config` | 配置管理 | | `vyper init` | 初始化配置文件 | ## 仪表盘 仪表盘是一个运行在 8000 端口的 **React SPA**，替代了 Jinja2 模板。 ### 主要页面 | 路由 | 页面 | |------|------| | `/` | 仪表盘概览 — 指标、发现、过滤器 | | `/programs` | Immunefi 项目列表 | | `/programs/:slug` | 项目详情与合约 | | `/audits` | 审计历史 | | `/audits/:id` | 审计详情 — 发现、漏洞利用、报告 | | `/scanner` | 各工具的扫描器详情 | | `/exploit` | 漏洞利用查看器 | | `/reports` | 报告中心 | | `/config` | 配置编辑器 | | `/webhooks` | Webhook 日志 | | `/settings` | 设置 | | `/scheduler` | 定时审计 | ### 功能 - 🔍 **过滤与搜索** — 按分类（TP/FP/TN/FN）、严重程度、项目过滤发现 - 💥 **漏洞利用详情** — 查看 PoC、交易哈希、风险价值、模拟账户 - 📊 **指标** — 各工具的精确率/召回率/F1、混淆矩阵、趋势图表 - ⚡ **SSE 事件** — 流水线进度实时更新 - 🌙 **深色模式** — 内置主题切换 ## 开发状态 ### ✅ 已完成（v0.4.x） | 优先级 | 状态 | |--------|------| | **P1: E2E 流水线** | ✅ 7/7 步骤 — Immunefi → Source → Scanner → AI → Classifier → Exploit → Reporter → Notifier | | **P2: CLI 工具** | ✅ 17 个命令 — Typer + Rich + httpx | | **Scanner 拆分** | ✅ 04 → 04a（Slither）+ 04b（Echidna）+ 04c（Forge）+ 05（Mythril）+ 04d（Halmos） | | **Mythril Sidecar** | ✅ 通过容器实现模块化隔离 | | **仪表盘 React SPA** | ✅ 从 Jinja2 迁移到 React + Vite + Tailwind | | **15 个服务** | ✅ 所有服务运行中，健康检查通过 | ### 🔄 进行中 | 优先级 | 目标 | |--------|------| | **Halmos 集成** | 符号执行形式化验证 | | **自定义 Slither 检测器** | 自定义检测器插件系统 | | **GitHub Actions** | 每次 PR 自动审计 | ### 📅 路线图 ``` Minggu: 1 2 3 4 5 6 7 8 E2E: ████████░░░░░░░░░░░░░░░░░░░░░░░░░░ CLI: ░░░░░░░░████████░░░░░░░░░░░░░░░░░░ Halmos: ░░░░░░░░░░░░░░░░████████░░░░░░░░░░ GitHub: ░░░░░░░░░░░░░░░░░░░░░░░░████░░░░░░ Detectors: ░░░░░░░░░░░░░░░░░░░░░░░░░░░░████░░ ``` ## 项目结构 ``` sc_auditor/ │ ├── docker-compose.yml # Orkestrasi 19 service ├── Dockerfile.base # Base Python 3.11-slim image ├── .env.example # Template environment │ ├── vyper_lib/ # Shared library (model, solc manager) │ ├── models.py # Finding, ToolResult, ApiResponse │ └── solc_manager.py # Compiler version management │ ├── cli/ # CLI tool (Typer) │ ├── main.py # Entry point │ ├── client.py # HTTP client wrapper │ ├── output.py # Rich output formatter │ ├── config.py # Config management │ └── commands/ # 6 command groups │ ├── docker.py # up/down/logs/ps/restart │ ├── audit.py # Full pipeline │ ├── scan.py # Quick scan │ ├── exploit.py # PoC generation │ ├── status.py # Status monitoring │ └── config_cmd.py # Config CLI │ ├── services/ # 19 microservices │ ├── 01-config/ # Config management │ ├── 02-immunefi/ # Immunefi scraper │ ├── 03-source/ # Multi-source fetcher │ ├── 04-scanner/ # Main scanner router │ ├── 04a-scanner-slither/ # Slither │ ├── 04b-scanner-echidna/ # Echidna │ ├── 04c-scanner-forge/ # Foundry Forge │ ├── 04d-scanner-halmos/ # Halmos │ ├── 05-scanner-mythril/ # Mythril │ ├── 06-ai/ # LLM analysis │ ├── 07-classifier/ # TP/FP classifier │ ├── 08-exploit/ # Anvil exploit engine │ ├── 09-reporter/ # Report generator │ ├── 10-notifier/ # Discord/Telegram/Email │ ├── 11-orchestrator/ # Pipeline coordinator │ ├── 12-webhook/ # Webhook dispatcher │ ├── 13-upkeep/ # Backup & metrics │ ├── 14-agent/ # Autonomous agent │ └── 15-dashboard/ # React SPA + API Gateway │ ├── tests/ # Integration tests ├── scripts/ # Utility scripts │ ├── VYPER.md # Arsitektur lengkap ├── VYPER_ROADMAP.md # Roadmap & prioritas ├── ARCHITECTURE.md # Detailed architecture (protobuf) ├── DASHBOARD.md # Dashboard spec ├── SCANNER_SPLIT_PLAN.md # Scanner split plan └── IMPLEMENTATION_PLAN.md # Build plan ``` ## 常见问题 ### 需要互联网吗？ 部分需要。需要互联网的服务： - **AI 服务** — 调用 OpenAI/Anthropic API（可选，可跳过） - **Immunefi** — 从 GitHub 同步项目数据 - **Source** — 从 Etherscan/GitHub 获取源码 其他服务完全**离线**运行。 | 资源 | 最低配置 | 推荐配置 | |------|----------|----------| | **CPU** | 4 核 | 8 核 | | **RAM** | 8 GB | 16 GB | | **磁盘** | 20 GB | 50 GB（SSD） | | **Docker** | 24 GB | 50 GB | ### 可以扫描 arbitrum/polygon/bsc 上的合约吗？ 可以。Source 服务支持 5 个提供商： - Etherscan（Ethereum、Polygon、Arbitrum、BSC 等） - Sourcify（多链） - GitHub（完整仓库） - Blockscout（Gnosis、Celo 等） - 手动（上传文件） ### 如何提交到 Immunefi？ 流水线生成 `immunefi.md` — Immunefi 期望的格式： - 仅 TP（false positive 自动过滤） - 标题、严重程度、SWC/CWE、描述、影响、PoC、修复建议、参考资料 - 可直接复制粘贴到 Immunefi 仪表盘 ### 可以扩展吗？ 可以。所有服务均为无状态，可通过 Docker Compose 扩展： ``` docker compose up --scale 04-scanner=3 -d ``` ## 许可证 MIT License — 详见 [LICENSE](LICENSE)。 ## 致谢 用 ❤️ 为 Web3 安全生态打造。

标签：AI安全分析, Anvil Fork, AV绕过, Bug Bounty, Dashboard监控, DeFi安全, DevSecOps, Docker Compose, EVM, False Negative分析, FastAPI, Gas优化, Immunefi, Metrics追踪, Mythril, React, Slither, Smart Contract Auditing, Solidity, Syscalls, True Positive, Vyper Python, Web3安全, 上游代理, 云安全监控, 以太坊, 区块链安全, 可自定义解析器, 多工具集成, 安全工具链, 安全报告生成, 对称加密, 开源安全工具, 微服务架构, 整数溢出, 智能合约审计, 智能合约开发, 智能合约漏洞, 本地部署, 权限控制, 版权保护, 自动化审计, 运行时操纵, 逆向工程平台, 重入攻击, 静态分析