gorka2354/audit-copilot

# audit-copilot  **智能合约审计 AI Copilot。** 构建于静态检测引擎之上的自主层： 通过检测器运行合约，利用来自安全知识库 (RAG) 的上下文丰富每个信号，并合成带有引用的合理报告 — 提供**可衡量的质量**，而非简单的“相信模型”。 ## 理念 经典的静态分析回答了“风险可能在**哪里**”的问题，但无法回答“这是**真正的** bug 吗、**多**严重以及**为什么**”。最后这一步通常由人类审计员完成。`audit-copilot` 正是自动化了这一步：agent 协调检测器和知识库，并且每个结论都必须有来源支撑——否则该发现将被丢弃（幻觉控制）。 核心不变式：**发现 = 检测器 1:1**。LLM 不会凭空捏造漏洞，也不会遗漏漏洞——它只评估 severity、解释风险、提出修复建议并引用来源。因此，报告中每一条发现的溯源都可以追踪到具体的检测器。 ## 架构 六边形架构：领域层对基础设施一无所知，所有外部组件都隐藏在端口（`typing.Protocol`）之后，并且可互换。 ``` app/ ├── domain/ модели и порты (чистый Python, без зависимостей) ├── adapters/ │ ├── analyzer/ статический движок за портом StaticAnalyzer (security-lab) │ ├── llm/ LLM-провайдеры за единым портом (Ollama + Anthropic) + роутер с бюджетом │ ├── vectorstore/ pgvector И Qdrant за портом VectorStore (переключаются конфигом) │ └── embedder/ эмбеддинги за портом Embedder ├── rag/ чанкинг → эмбеддинги → гибридный поиск (dense + BM25, RRF) → class-фильтр → реранк ├── agent/ агент-аудитор: recon → RAG(class) → LLM-синтез, провенанс цитат ├── eval/ измеримое качество: recall детекторов, faithfulness, cross-model judge, стоимость ├── api/ FastAPI (/audit, /search, /health) └── observability/ учёт токенов и стоимости (BudgetTracker) ``` 静态引擎作为**外部组件**通过端口接入：adapter 从 `SECURITY_LAB_PATH` 路径导入检测器，并将其输出标准化为领域层的 `Finding`。 ## 快速开始 ``` uv sync # окружение (Python 3.12) cp .env.example .env # SECURITY_LAB_PATH и (опц.) ANTHROPIC_API_KEY docker compose up -d postgres # pgvector make audit SOL=examples/VulnerableVault.sol # аудит контракта в терминале ``` 对 `VulnerableVault.sol` 进行审计将生成一份包含 severity、理由、修复建议以及真实知识库引用的报告（使用 Claude 处理每个合约约需 $0.07）。 ### API ``` make serve # uvicorn на :8000 (нужен .env + postgres) curl localhost:8000/health curl -X POST localhost:8000/audit -H 'content-type: application/json' \ -d '{"code": "contract V { function setOwner(address o) public { owner = o; } }"}' ``` | 方法 | 路由 | 用途 | |---|---|---| | `GET` | `/health` | 进程存活状态 + LLM 配置（无网络调用） | | `POST` | `/audit` | 合约审计：侦测 (recon) → RAG(class) → LLM 丰富上下文 → 带引用的报告 | | `POST` | `/search` | 知识库混合检索（class 过滤器 + 可选 LLM 重排） | | `GET` | `/docs` | Swagger UI / OpenAPI schema | `/audit` 和 `/search` 在本地是开放的；在 `.env` 中设置 `API_KEY` 后——两者都需要 `X-API-Key` 请求头（防止在公开部署中他人滥用你的 LLM 额度）。领域错误会映射到 HTTP 状态码：预算耗尽 → `429`，provider 故障 → `502`。 ### Docker 一键部署全栈 ``` make up # postgres + api на :8000 одной командой (Ollama/Anthropic — внешние) make down # остановить ``` ## 可衡量的质量 (eval) 与“又一个 RAG 包装器”的区别在于：该系统**实事求是地衡量自身的质量**。 ``` make eval # detector-recall по всему корпусу DeFiVulnLabs (offline, бесплатно) make eval SAMPLE=5 EVAL_ARGS=--judge # + агент на подвыборке + cross-model judge ``` 在 DeFiVulnLabs 数据集上（57 个复现样本，漏洞 class 包含在文件名中）： - **detector recall 71%**（覆盖了 34 个 class 中的 24 个）——这是我们能真正抓取到的，并展示了遗漏的部分； - **结构化 faithfulness 100%** —— 每一条引用都可以从传入的上下文中复现（溯源），没有任何捏造； - **跨模型 grounding 48%** —— 评估器 (Ollama) 对生成器 (Anthropic) 的引用进行评分；这是客观真实的数据，而非自吹自擂； - 以及各 provider 的成本和延迟。 因为 agent 严格遵循 1:1 反幻觉机制，`agent recall ≡ detector recall` —— 我们故意不构建“agent 提升了 recall”这种虚假指标。 ## 基于端口的可扩展性 所有外部组件都隐藏在端口（`typing.Protocol`）之后，因此只需通过**添加 adapter 即可扩展，无需修改核心代码** —— agent、RAG 和 API 依赖于抽象，而不是具体的引擎。 **其他的检测器引擎**（Slither、Mythril 或自定义引擎）——只需为 `StaticAnalyzer` 端口添加一个 adapter： ``` from app.domain.models import Finding, SoliditySource class SlitherAnalyzer: # реализует порт StaticAnalyzer name = "slither" def analyze(self, source: SoliditySource) -> list[Finding]: raw = run_slither(source.code) # запустить любой движок return [_to_finding(r) for r in raw] # нормализовать в доменный Finding ``` security-lab 只是第一个 adapter（`SecurityLabAnalyzer`）；接入第二个引擎完全不会触及 agent、RAG 或 API。 **其他的 vectorstore** —— 已经实现：`pgvector` 和 `Qdrant` 位于 `VectorStore` 端口之后，只需一个变量即可切换： ``` docker compose --profile qdrant up -d qdrant VECTOR_STORE=qdrant make serve # весь стек переезжает на Qdrant ``` **其他的 LLM provider** —— 位于 `LLMProvider` 端口之后（带有 fallback 和预算控制的路由器）；Ollama 和 Anthropic 已经接入，添加 OpenAI 只需一个 adapter。 **其他领域**（非智能合约）：基础设施层 —— LLM 路由器、RAG、eval harness、API —— 原样复用；你只需将特定领域的逻辑（`classify.py` 中的 class、合成 prompt、知识语料库、eval 数据集）根据新任务重写即可。本项目的核心是可移植的模式：“检测器信号 → RAG → 带有可衡量质量的 agent”，不仅限于合约审计。 ## 路线图 | # | 增量 | 状态 | |---|---|---| | 0 | 骨架 + StaticAnalyzer 端口（通往检测器引擎的桥梁） | ✅ | | 1 | 统一端口后的 LLM：Ollama + Anthropic + 预算控制 | ✅ | | 2 | RAG：摄取知识语料库 → pgvector，混合检索 | ✅ | | 3 | 审计 agent：检测器 + RAG → 带引用的报告 | ✅ | | 4 | FastAPI + docker-compose | ✅ | | 5 | Eval harness：recall + faithfulness + 跨模型评估 + 成本 | ✅ | | 6 | CI + 端口控制下的第二个 vectorstore (Qdrant) | ✅ | 每一个增量在合并前都经过了工程方案审查和独立的代码审查。 ## 质量 测试（单元测试 + pgvector/qdrant/LLM 的实时集成测试）、`mypy --strict`、`ruff`，以及每次 push 触发的 CI。原子化提交（Conventional Commits）。 ## 技术栈 Python 3.12 · FastAPI · pydantic · PostgreSQL/pgvector · Qdrant · Docker · Ollama · Anthropic · uv · ruff · mypy strict · pytest。

标签：AI智能体, AI风险缓解, AV绕过, DLL 劫持, FastAPI, RAG, 云安全监控, 大语言模型, 安全规则引擎, 智能合约审计, 测试用例, 请求拦截, 逆向工具, 静态分析