ContractAudit RAG

Local-first retrieval for EVM smart-contract security knowledge — crawl, index, cite.

ContractAudit is an audit research assistant: it crawls an explicit source allowlist, extracts HTML/PDF, builds provenance-preserving chunks (LlamaIndex), stores hybrid dense + BM25 vectors in Qdrant, and exposes read-only search through MCP.

It helps you find what auditors and docs already said about a class of bugs. It is not a certificate that any contract is safe.

approved sources → governed crawler → parsers → LlamaIndex chunks
        → Qdrant (hybrid) → retrieval service → MCP tools → (optional) local LLM host

What it does

MCP tools: search_security_knowledge · get_audit_finding · get_document_context · list_sources · corpus_status

Crawling and indexing stay operator-controlled CLI actions so prompt content cannot mutate the corpus.

Tech stack

Optional: OCR extras (pymupdf, pytesseract) · docs PDF builder (reportlab).

Privacy & repo hygiene

No API keys are required for the default local embedding path. Do not commit crawled corpora or vector stores.

Quick start (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

First search/ingest downloads embedding models. Default dense model runs on CPU; set CAR_EMBEDDING_DEVICE=cuda only if VRAM allows.

Embedded Qdrant (data/qdrant) allows one process at a time. For concurrent ingest + MCP, run Qdrant as a service and set CAR_QDRANT_URL=http://localhost:6333.

Build a small corpus

Review config/sources.yaml first (robots, terms, report licenses).

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

For a local network client: CAR_MCP_TRANSPORT=streamable-http (default 127.0.0.1:8765). Do not expose publicly without auth/TLS.

Tests

ruff check .
mypy src
pytest

Optional local-model phase

Wire any local model callable through contract_audit_rag.llm.base.CallableAdapter, then use MCPQwenHost.answer() with a connected MCP ClientSession. The host:

1. Calls search_security_knowledge

2. Validates structured evidence

3. Builds an evidence_prompt (untrusted web content, required citations, insufficient-evidence path)

The raw model is not an MCP client — the application host owns tool calls.

Repo map

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

Design notes

• Allowlist-first security posture for anything that hits the network.

• Provenance-preserving chunks so answers can be cited, not hand-waved.

• Read-only MCP surface — corpus mutation is never a tool side effect.

• Hybrid retrieval for both semantic and keyword-heavy audit jargon.

• Honest product boundary: research assistant ≠ automated audit sign-off.

Learning guide

Detailed walkthrough: docs/Contract_Audit_RAG_Learning_Guide.pdf (Markdown source alongside).

python -m pip install -e ".[docs]"
python tools\build_learning_guide.py

License

MIT — see LICENSE. Respect third-party content licenses when crawling or redistributing reports.