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

Capability	Details
Governed crawling	Domain / path allowlists, crawl delay, size caps, storage_approved gate
Ingestion	HTML + PDF extraction, chunking with stable IDs + provenance
Hybrid search	Dense embeddings (BAAI/bge-small-en-v1.5) + sparse/BM25 via Qdrant
MCP server	Read-only tools for IDE / agent hosts (stdio or local HTTP)
Eval harness	Starter benchmark queries in eval/evm_queries.yaml
LLM seam	Optional host retrieves evidence via MCP, then calls your local ask()

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

Layer	Technology
Language	Python 3.11+, packaged with Hatchling
CLI	Typer (contract-audit-rag, contract-audit-mcp)
Config	Pydantic Settings, YAML source policies
Crawl / parse	httpx, BeautifulSoup, trafilatura, pypdf
Chunking / RAG	LlamaIndex + HuggingFace embeddings
Vector DB	Qdrant (embedded path or server URL)
Sparse vectors	fastembed
Agent interface	MCP (mcp[cli]) — stdio / streamable-HTTP
Quality	pytest, ruff, mypy (strict)

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

---

Privacy & repo hygiene

Included	Excluded (local only)
Source code, tests, config/sources.yaml	.env
.env.example, eval queries, docs	.venv/, caches
Learning guide (md/pdf)	data/raw/, data/qdrant/, data/manifest.sqlite3

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.