ArmaghanRazaChaudhary/ContractAudit

# ContractAudit RAG ### 面向 EVM 智能合约安全知识的本地优先检索系统 —— 抓取、索引、引用。 **ContractAudit** 是一个审计**研究助手**：它会对显式定义的源白名单进行抓取，提取 HTML/PDF，构建保留溯源信息的文本块（基于 LlamaIndex），将密集向量和 BM25 稀疏向量混合存储在 **Qdrant** 中，并通过 **MCP** 暴露只读搜索接口。 它可以帮你找到审计人员和文档*已经指出过*的某类漏洞信息。但它**不是**证明任何合约安全的凭证。 ``` approved sources → governed crawler → parsers → LlamaIndex chunks → Qdrant (hybrid) → retrieval service → MCP tools → (optional) local LLM host ``` ## 它的功能 | 功能 | 详情 | |------------|---------| | **受控抓取** | 域名/路径白名单，抓取延迟，大小限制，`storage_approved` 许可门控 | | **数据摄取** | HTML + PDF 提取，具备稳定 ID 和溯源信息的分块处理 | | **混合搜索** | 密集向量 (`BAAI/bge-small-en-v1.5`) + 基于 Qdrant 的稀疏向量/BM25 | | **MCP server** | 面向 IDE / agent 宿主的只读工具 (`stdio` 或本地 HTTP) | | **评估工具** | 位于 `eval/evm_queries.yaml` 的入门基准查询 | | **LLM 接入层** | 宿主可选地通过 MCP 检索证据，随后调用你本地的 `ask()` | **MCP 工具：** `search_security_knowledge` · `get_audit_finding` · `get_document_context` · `list_sources` · `corpus_status` 抓取和索引始终是**由操作员控制的 CLI** 行为，因此 prompt 内容无法修改语料库。 ## 技术栈 | 层级 | 技术 | |-------|------------| | 语言 | Python **3.11+**，使用 Hatchling 打包 | | CLI | **Typer** (`contract-audit-rag`, `contract-audit-mcp`) | | 配置 | **Pydantic Settings**，YAML 来源策略 | | 抓取 / 解析 | **httpx**，BeautifulSoup，**trafilatura**，**pypdf** | | 分块 / RAG | **LlamaIndex** + HuggingFace embeddings | | Vector DB | **Qdrant** (内嵌模式或服务器 URL) | | 稀疏向量 | **fastembed** | | Agent 接口 | **MCP** (`mcp[cli]`) — stdio / streamable-HTTP | | 质量 | **pytest**，**ruff**，**mypy** (严格模式) | 可选项：OCR 扩展包 (`pymupdf`, `pytesseract`) · 文档 PDF 构建器 (`reportlab`)。 ## 隐私与仓库维护 | 包含内容 | 不包含内容 (仅限本地) | |----------|------------------------| | 源码、测试、`config/sources.yaml` | `.env` | | `.env.example`、评估查询、文档 | `.venv/`、缓存 | | 学习指南 (md/pdf) | `data/raw/`、`data/qdrant/`、`data/manifest.sqlite3` | 默认的本地 embedding 路径不需要 API 密钥。请勿提交抓取的语料库或向量存储。 ## 快速开始 (Windows) ``` python -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install --upgrade pip python -m pip install -e ".[dev]" Copy-Item .env.example .env ``` 首次搜索或摄取数据时会下载 embedding 模型。默认的密集向量模型运行在 **CPU** 上；仅在 VRAM 允许的情况下才设置 `CAR_EMBEDDING_DEVICE=cuda`。 内嵌的 Qdrant (`data/qdrant`) 同一时间只允许**一个**进程访问。如需并发执行数据摄取和 MCP，请将 Qdrant 作为服务运行，并设置 `CAR_QDRANT_URL=http://localhost:6333`。 ### 构建小型语料库 请先查阅 `config/sources.yaml`（了解 robots 协议、服务条款及报告版权许可）。 ``` contract-audit-rag sources validate contract-audit-rag crawl --source trailofbits_secure_contracts --limit 30 contract-audit-rag ingest contract-audit-rag stats contract-audit-rag search "How should oracle price freshness be checked?" contract-audit-rag benchmark ``` ### MCP ``` contract-audit-mcp ``` 针对本地网络客户端：`CAR_MCP_TRANSPORT=streamable-http`（默认为 `127.0.0.1:8765`）。在没有 auth/TLS 的情况下请勿暴露到公网。 ### 测试 ``` ruff check . mypy src pytest ``` ## 可选的本地模型阶段 通过 `contract_audit_rag.llm.base.CallableAdapter` 接入任何本地模型可调用对象，然后与已连接的 MCP `ClientSession` 一起使用 `MCPQwenHost.answer()`。该 Host 会： 1. 调用 `search_security_knowledge` 2. 验证结构化证据 3. 构建 `evidence_prompt`（包含不可信的网页内容、必需的引用说明以及证据不足时的处理路径） 原始模型**不是** MCP 客户端 —— 工具调用的控制权归属于应用程序 Host。 ## 仓库结构图 ``` ContractAudit/ ├── config/sources.yaml # Crawl allowlist (review before use) ├── src/contract_audit_rag/ │ ├── cli.py # Typer CLI │ ├── ingestion/ # Crawler, parsers, pipeline, chunking │ ├── retrieval/ # Search service │ ├── indexing.py # Qdrant index store │ ├── mcp/server.py # MCP tools │ └── llm/ # Optional host + adapter seam ├── eval/evm_queries.yaml ├── tests/ ├── docs/ # Learning guide (md + pdf) ├── tools/build_learning_guide.py ├── .env.example └── pyproject.toml ``` ## 设计说明 - **白名单优先的安全态势**，适用于任何访问网络的操作。 - **保留溯源信息的文本块**，确保答案可以被明确引用，而非凭空捏造。 - **只读的 MCP 接口** —— 语料库的变更绝对不会作为工具的副作用发生。 - **混合检索机制**，兼顾语义匹配与包含大量关键词的审计专业术语。 - **诚实的产品边界：** 研究助手 ≠ 自动化的审计批准。 ## 学习指南 详细操作指南：[`docs/Contract_Audit_RAG_Learning_Guide.pdf`](docs/Contract_Audit_RAG_Learning_Guide.pdf)（随附 Markdown 源文件）。 ``` python -m pip install -e ".[docs]" python tools\build_learning_guide.py ``` ## License MIT — 请参阅 [LICENSE](LICENSE)。在抓取或重新分发报告时，请遵守第三方内容的版权许可。

标签：EVM, LlamaIndex, MCP, Qdrant, RAG, Splunk, 安全规则引擎, 智能合约审计, 本地知识库, 运行时操纵, 逆向工具