Vulnerability Assessment MCP Server

Real-time CVE intelligence and Pentesting RAG (Retrieval-Augmented Generation) for AI agents.
Built with FastMCP, ChromaDB, and SentenceTransformers.

The Problem • Features • Architecture • Quick Start • Tools • Configuration

---

The Problem

AI agents are great at analyzing data, but they lack up-to-date vulnerability intelligence and deep technical pentesting context — content that's often too large to fit in a standard prompt.

Vulnerability Assessment MCP gives your AI agent two powerful capabilities:

1. Live API Access: Instantly query NVD, CISA KEV, and GitHub for real-world exploitability data, CVSS scores, and public proof-of-concept repositories.
2. Local RAG Database: A fully automated vector database (ChromaDB) that indexes thousands of pages from HackTricks and PayloadsAllTheThings, allowing the AI to search for precise pentesting techniques using natural language.

---

Features

• Smart Initialization: Automatically clones and indexes HackTricks & PayloadsAllTheThings on the first run. Subsequent runs use the cached ChromaDB index instantly.
• CPU-Friendly Embeddings: Uses all-MiniLM-L6-v2 for fast, local semantic search — no GPU or external API required.
• Context-Aware Chunking: Splits markdown files into overlapping 900-character chunks so the AI never loses context at chunk boundaries.
• Triage Ready: Cross-references CVEs with CISA's Known Exploited Vulnerabilities (KEV) catalog to flag actively exploited issues.
• Multi-Source Search: Combines NVD (vulnerability details & CVSS), CISA KEV (active exploitation status), and GitHub (public PoC repositories) in a single query.
• Incremental Updates: Runs git pull on subsequent startups to keep knowledge bases current.

---

Architecture

┌──────────────────────────────────────────────────────┐
│                    MCP Client                        │
│            (Claude Desktop, Cursor, etc.)             │
└──────────────────┬───────────────────────────────────┘
                   │ stdio
┌──────────────────▼───────────────────────────────────┐
│             FastMCP Server                           │
│                                                      │
│  ┌─────────────────────┐  ┌────────────────────────┐ │
│  │ search_vulnerability │  │  search_techniques     │ │
│  │                     │  │                        │ │
│  │  • NVD API          │  │  • ChromaDB            │ │
│  │  • CISA KEV         │  │  • SentenceTransformers│ │
│  │  • GitHub Search    │  │  • HackTricks          │ │
│  │                     │  │  • PayloadsAllTheThings │ │
│  └─────────────────────┘  └────────────────────────┘ │
└──────────────────────────────────────────────────────┘

---

Quick Start

1. Clone & Install

git clone https://github.com/YOUR_USERNAME/vulnerability-assessment-mcp.git
cd vulnerability-assessment-mcp

# Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install mcp[cli] chromadb sentence-transformers requests GitPython

2. Environment Variables (Optional)

Create a .env file in the root directory to increase GitHub API rate limits:

GITHUB_TOKEN=ghp_your_github_token_here

Without a token, GitHub API is limited to 10 requests/minute. With a token, this increases to 30 requests/minute.

3. Run the Server

python server.py

On the first run, the server will:

1. Clone HackTricks (~500 MB) and PayloadsAllTheThings (~100 MB) into ./data/repos/
2. Index all markdown files into ChromaDB at ./data/chromadb/
3. This process takes 5–15 minutes depending on your machine

On subsequent runs, the server starts instantly using the cached index.

---

Tools

search_vulnerability

Searches for a vulnerability across three sources simultaneously: NVD, CISA KEV, and GitHub PoC repositories.

Parameter	Type	Default	Description
query	str	required	CVE ID (e.g., CVE-2021-44228) or keyword (e.g., log4shell, apache rce)
max_results	int	5	Maximum number of results from each source

Example prompts:

• "Search for CVE-2021-44228"
• "Find vulnerabilities related to Apache Log4j"
• "Look up recent Spring Framework RCE exploits"

Returns: Combined results from NVD (CVE details, CVSS scores, descriptions), CISA KEV (active exploitation status, remediation deadlines), and GitHub (starred PoC repositories with links).

---

search_techniques

Performs semantic search over locally indexed HackTricks and PayloadsAllTheThings content using ChromaDB.

Parameter	Type	Default	Description
query	str	required	Natural language question (e.g., linux priv esc suid, bypass WAF SQL injection)
top_k	int	5	Number of results to return
source	str	None	Filter by source: "hacktricks" or "payloads" (optional)

Example prompts:

• "How do I escalate privileges using SUID binaries on Linux?"
• "Show me techniques for bypassing WAF in SQL injection"
• "Search for SSRF payloads in cloud environments"

Returns: Ranked results with similarity scores, source file paths, and relevant text excerpts (up to 700 characters each).

---

Configuration

Key constants defined at the top of server.py:

Constant	Default	Description
DATA_DIR	./data/repos	Directory where git repositories are cloned
CHROMA_DIR	./data/chromadb	Directory for ChromaDB persistent storage
CHUNK_SIZE	900	Character length of each text chunk
CHUNK_OVERLAP	150	Overlap between consecutive chunks
BATCH_SIZE	128	Number of embeddings per ChromaDB upsert batch

---

Project Structure

RAG-MCP-PENTESTING/
├── vulnerability-assessment-server.py   # Main MCP server with tool definitions
├── requirements.txt                     # Python dependencies
├── .env.example                         # Example environment variables
├── data/
│   ├── chromadb/
│   └── repos/
│       ├── hacktricks/                  # Auto-cloned on first run
│       └── payloadsallthethings/        # Auto-cloned on first run

---

Requirements

• Python 3.10+
• ~2 GB disk space (for repositories and vector database)
• Internet connection (for initial clone and live API queries)

Python Dependencies

Package	Purpose
mcp[cli]	FastMCP server framework
chromadb	Vector database for semantic search
sentence-transformers	Local embedding model (all-MiniLM-L6-v2)
requests	HTTP client for NVD, CISA, and GitHub APIs
GitPython	Git operations for cloning and updating repos

---

Disclaimer

This tool is intended for authorized security testing and research only. Always obtain proper authorization before conducting any security assessments. The authors are not responsible for misuse of this tool.

---

License

MIT License — see LICENSE for details.