VulnPilot

Overview

What It Is

VulnPilot is an open-source Model Context Protocol (MCP) server that arms AI coding assistants with deep, contextual dependency analysis. It enables AI agents to query vulnerability advisories in real time, analyze whether vulnerable code paths are actually imported in your project, enrich findings with real-world threat telemetry, and output self-contained HTML security dashboards.

Why It Is

Modern AI coding assistants (such as Claude Desktop, Cursor, and VS Code Copilot) excel at writing code, suggesting libraries, and refactoring projects. However, AI agents operate blindly regarding security posture:

• They do not know if a recommended package version contains known security vulnerabilities.

• They cannot differentiate between a vulnerability in production code versus one isolated in test utilities.

• They lack real-world threat intelligence to determine if a CVE is actively exploited by threat actors or merely a theoretical risk.

VulnPilot bridges this gap by giving AI assistants native MCP tools to inspect package manifests, parse source code parse-trees, evaluate active exploit databases, and prioritize remediation accurately.

How Beneficial It Is

• Noise Reduction: Avoid blanket package upgrades by identifying whether vulnerable code is actually reachable in your project or restricted to test suites.

• Real-World Threat Telemetry: Enriches raw CVE identifiers with FIRST EPSS probability scores (likelihood of exploitation in the next 30 days) and CISA KEV catalog indicators (known active cyberattacks and ransomware campaigns).

• Direct vs. Transitive Detection: Automatically inspects lock files (uv.lock, poetry.lock, package-lock.json, yarn.lock, etc.) and manifests to distinguish top-level dependencies from sub-dependencies.

• Zero Friction Setup: No external API keys, complex setup, or cloud subscriptions required. Runs locally via STDIO.

• Polished HTML Security Dashboards: Generates interactive, portable HTML reports complete with executive summaries, sortable vulnerability tables, and color-coded risk gauges.

For Whom It Is

VulnPilot is built for:

• Software Engineers: Seeking automated security checks while writing code alongside AI assistants.

• Security & DevOps Teams: Requiring evidence-based vulnerability triage without false-alarm alerts.

• AI Pair Programmers: Developers using Claude Desktop, Cursor, VS Code Copilot, Zed, Windsurf, or custom agentic workflows who want their AI assistants to write secure, audited code by default.

Related MCP server: mcp-pypi

Core Ecosystems & Intelligence Sources

Supported Ecosystems

Threat Intelligence Telemetry

• OSV.dev API: Real-time vulnerability advisories from PyPI, npm, Maven, and OSV databases.

• FIRST EPSS (Exploit Prediction Scoring System): Probability metrics detailing the likelihood of a vulnerability being exploited in the wild within 30 days.

• CISA KEV (Known Exploited Vulnerabilities): Catalog flagging vulnerabilities actively exploited in real-world cyberattacks or ransomware campaigns.

Quickstart

Prerequisites

Installation

# Clone the repository
git clone https://github.com/arojit/vulnpilot-mcp.git
cd vulnpilot-mcp

# Sync environment and install dependencies
uv sync

Verify Installation

Optionally, run this to confirm the server starts correctly before configuring your MCP client:

uv run vulnpilot-mcp

Note: You do not need to run this manually during normal use. Your MCP client (Claude Desktop, Cursor, VS Code, etc.) launches the server process automatically via the configuration below. Simply configure the client and restart it.

MCP Client Setup

Configure VulnPilot in your preferred AI environment:

Add the server configuration to claude_desktop_config.json:

{
  "mcpServers": {
    "vulnpilot": {
      "command": "/absolute/path/to/uv",
      "args": [
        "--directory", "/absolute/path/to/vulnpilot-mcp",
        "run", "vulnpilot-mcp"
      ]
    }
  }
}

Add the server configuration to .cursor/mcp.json:

{
  "mcpServers": {
    "vulnpilot": {
      "command": "/absolute/path/to/uv",
      "args": [
        "--directory", "/absolute/path/to/vulnpilot-mcp",
        "run", "vulnpilot-mcp"
      ]
    }
  }
}

Add the server configuration to .vscode/mcp.json:

{
  "servers": {
    "vulnpilot": {
      "command": "/absolute/path/to/uv",
      "args": [
        "--directory", "/absolute/path/to/vulnpilot-mcp",
        "run", "vulnpilot-mcp"
      ]
    }
  }
}

Path Configuration Note: Replace /absolute/path/to/uv with your system path to uv (obtain via which uv) and replace /absolute/path/to/vulnpilot-mcp with the exact directory location where you cloned the repository.

Corporate Network & SSL Custom Root CAs: If your system uses corporate SSL proxies or custom root certificates, include the --system-certs argument:

"args": [
  "--directory", "/absolute/path/to/vulnpilot-mcp",
  "run", "--system-certs", "vulnpilot-mcp"
]

Recommended Audit Prompt: Use this prompt with your connected AI client to invoke all VulnPilot tools (check_package, analyze_reachability, generate_report) in a single automated workflow:

Run a full VulnPilot security audit on this project: check package vulnerabilities, analyze code reachability, and generate the HTML security report.

How It Works

VulnPilot follows a structured five-stage workflow to deliver contextual security intelligence to your AI assistant:

[ 1. Package Vulnerability Check ] ──> [ 2. Direct vs. Transitive Inspection ]
                                                      │
[ 5. HTML Report Generation ] <── [ 4. Priority Triage Engine ] <── [ 3. Reachability Analysis ]

Stage 1: Package Vulnerability Lookup (check_package)

1. The AI assistant invokes check_package with a package coordinate and version number.

2. VulnPilot fetches advisories from OSV.dev and normalizes vulnerability records.

3. Extracted CVE identifiers are cross-referenced with FIRST EPSS and CISA KEV databases.

Stage 2: Direct vs. Transitive Dependency Classification

1. VulnPilot inspects project manifests (pyproject.toml, package.json, pom.xml, build.gradle) and lock files (uv.lock, poetry.lock, package-lock.json, yarn.lock, etc.).

2. The dependency is categorized as direct (declared explicitly) or transitive (pulled in indirectly by sub-dependencies).

Stage 3: Static Code Reachability Analysis (analyze_*_reachability)

1. VulnPilot scans source code files using Abstract Syntax Tree (AST) parsing for Python, or structured token scanning for JavaScript, TypeScript, and Java.

2. It detects import statements and determines whether usage exists in production source code or is restricted to test directories.

Stage 4: Triage Priority Engine

VulnPilot calculates a remediation priority score based on deterministic risk criteria:

Stage 5: Interactive HTML Report Generation (generate_report)

1. Results from vulnerability checks and reachability analyses are aggregated.

2. VulnPilot renders a self-contained HTML report featuring executive statistics, interactive tables, color-coded badges, and remediation recommendations.

3. The generated report file is saved to .vulnpilot/vulnpilot-report-{timestamp}.html.

Sample Report: View an interactive sample report generated by VulnPilot: https://arojit.github.io/vulnpilot-mcp/

Tool Reference

VulnPilot exposes native MCP Tools, Prompts, and Resources.

check_package

Queries vulnerability databases for a given package version and enriches results with EPSS probability and CISA KEV indicators.

Arguments

Reachability Analysis Tools

Static code analysis tools verify whether a package is imported in project source files and classify code locations as production vs. test.

• analyze_python_reachability: Scans Python projects using ast parse-trees. Inspects pyproject.toml, setup.cfg, requirements.txt, and lock files (uv.lock, poetry.lock, pdm.lock, pylock.toml).

• analyze_javascript_reachability: Scans JavaScript and TypeScript projects (.js, .ts, .jsx, .tsx, .mjs, .cjs). Inspects package.json and lock files (package-lock.json, yarn.lock, pnpm-lock.yaml).

• analyze_java_reachability: Scans Java projects. Detects Maven (pom.xml) and Gradle (build.gradle, build.gradle.kts) dependencies.

Common Arguments

generate_report

Compiles scan results into a self-contained, interactive HTML security dashboard.

Arguments

The generated file is saved to .vulnpilot/vulnpilot-report-{timestamp}.html.

Sample HTML Report Output: Inspect a live sample report output: https://arojit.github.io/vulnpilot-mcp/

Example Usage

MCP Prompts

Prompts provide structured, multi-step instruction templates for AI clients:

• security_audit: Guides the AI assistant to audit an entire list of dependencies, evaluate reachability for vulnerable findings, and construct an executive security summary.

• triage_vulnerability: Conducts a deep-dive triage on a specific package version, checking exploit telemetry and code reachability.

• generate_dependency_evidence: Provides terminal commands needed to produce dependency tree metadata for ecosystems lacking default lock files.

MCP Resources

Read-only reference documents for AI assistants:

Dependency Evidence Guide

VulnPilot automatically parses existing lock files and project manifests. For projects without built-in lock files, generate dependency metadata using these commands (run from your target project root):

If using standard pip without a lockfile, export package metadata:

mkdir -p .vulnpilot
python -m pip inspect --local > .vulnpilot/pip-inspect.json

If the virtual environment is not activated:

mkdir -p .vulnpilot
.venv/bin/python -m pip inspect --local > .vulnpilot/pip-inspect.json

No command required when standard lock files exist:

• uv.lock (uv)

• poetry.lock (Poetry)

• pdm.lock (PDM)

• pylock.toml (PEP 751)

No command required when standard lock files exist:

• package-lock.json (npm)

• yarn.lock (Yarn)

• pnpm-lock.yaml (pnpm)

Export the dependency tree report:

mkdir -p .vulnpilot
mvn dependency:tree -DoutputFile=.vulnpilot/maven-dependency-tree.txt

Export the runtime dependency tree:

mkdir -p .vulnpilot
./gradlew dependencies --configuration runtimeClasspath > .vulnpilot/gradle-dependencies.txt

For test dependencies:

mkdir -p .vulnpilot
./gradlew dependencies --configuration testRuntimeClasspath > .vulnpilot/gradle-test-dependencies.txt

Git Configuration Tip: Add .vulnpilot/ to your project's .gitignore file to avoid committing local scan reports and evidence dumps.

Development & Testing

Installation for Contributors

# Install all development tools and dependencies
uv sync --all-groups

Running Test Suites

# Execute pytest suite
uv run pytest

Testing with MCP Inspector

Test tools interactively in your browser using the MCP Inspector GUI:

uv run mcp dev src/vulnpilot/server.py

Project File Hierarchy

vulnpilot-mcp/
├── src/vulnpilot/
│   ├── __init__.py               # Package marker
│   ├── server.py                 # MCP server tools, prompts, and resources
│   ├── models.py                 # Pydantic data schemas
│   ├── osv_client.py             # OSV.dev API client & normalizer
│   ├── epss_client.py            # FIRST EPSS API client
│   ├── cisa_kev_client.py        # CISA KEV catalog client
│   ├── triage.py                 # Priority triage engine
│   ├── cve_utils.py              # CVE regex and utility parsers
│   ├── report_generator.py        # Interactive HTML report renderer
│   └── reachability/             # Language-specific reachability scanners
│       ├── __init__.py          # Module re-exports
│       ├── _common.py           # Shared path parsing & evidence classification
│       ├── python_reachability.py
│       ├── python_dependencies.py
│       ├── javascript_reachability.py
│       ├── javascript_dependencies.py
│       ├── java_reachability.py
│       └── java_dependencies.py
├── tests/                        # Comprehensive unit & integration tests
├── pyproject.toml                # Project build metadata & dependencies
└── README.md

Enhancements

This section documents planned and shipped improvements that increase scanning efficiency and developer ergonomics.

Batch Package Scanning with Concurrent API Calls

Status: Planned

Problem: The current check_package tool accepts a single package at a time, meaning an AI agent auditing 30 dependencies must make 30 sequential API calls - each waiting for the previous one to complete.

Enhancement: Accept a list of { package_name, version, ecosystem, is_reachable, dependency_scope } objects in a single check_package invocation, then dispatch each lookup concurrently using Python's concurrent.futures.ThreadPoolExecutor. Results are collected and returned as an ordered list, preserving per-package attribution.

Benefits:

• Speed: Wall-clock scan time for N packages approaches the latency of a single lookup instead of N × latency.

• Ergonomics: AI agents issue one tool call per audit instead of one per dependency.

• Unchanged interface contract: Each individual result object retains the same schema as today.

Example batch input (proposed):

{
  "packages": [
    { "package_name": "django",   "version": "3.2.0",  "dependency_scope": "production" },
    { "package_name": "requests", "version": "2.25.0", "dependency_scope": "production" },
    { "package_name": "pytest",   "version": "7.1.0",  "dependency_scope": "development" }
  ],
  "ecosystem": "PyPI"
}

Technology Stack

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.