debvulns 0.2.0

Debian Vulnerability Analyzer — MCP server, CLI, and Prometheus exporter

[!WARNING] This package has been renamed to debvulns. debsecan-mcp 0.1.5 is the final release under this name. Please update your dependency:

pip install debvulns

debvulns

Debian vulnerability analysis toolkit — MCP server, standalone CLI, and Prometheus exporter. Integrates with AI assistants (like Claude) and monitoring stacks (Prometheus + Grafana) to track, prioritize, and alert on package vulnerabilities across Debian systems.

[!NOTE] This project was previously published on PyPI as debsecan-mcp. The final release under that name is 0.1.5. All future development happens here as debvulns.

Features

• MCP Server (debvulns-mcp): Integrates with Claude Desktop, VSCode, and opencode for AI-assisted vulnerability analysis
• Standalone CLI (debvulns): Scan and report vulnerabilities from the command line in JSON or CSV format
• Prometheus Exporter (debvulns-exporter): Expose vulnerability metrics for Grafana dashboards and alerting
• List Vulnerabilities: Scan all installed packages for known vulnerabilities
• CVE Research: Get detailed information about specific CVEs including EPSS scores
• Automatic Suite Detection: Automatically detects your Debian suite (bookworm, trixie, sid, etc.)
• EPSS Integration: Enriches vulnerability data with Exploit Prediction Scoring System (EPSS) scores

Installation

pip install debvulns

Or from source:

pip install -e .

Usage

Running the MCP Server

debvulns-mcp

Or with a specific Debian suite:

DEBSECAN_SUITE=bookworm debvulns-mcp

Command Line Options

debvulns-mcp --help

Options:

• --transport {stdio,sse,streamable-http} - Transport mode (default: stdio)
• --mount-path PATH - Mount path for HTTP transports (default: /mcp)
• --host HOST - Host to bind to for HTTP transport (default: 0.0.0.0)
• --port PORT - Port to bind to for HTTP transport (default: 8000)

Transport Modes

STDIO Mode (Default)

Used for direct integration with AI assistants like Claude Desktop or VSCode.

debvulns-mcp --transport stdio

HTTP Modes

For HTTP-based access, use sse or streamable-http:

# SSE mode
debvulns-mcp --transport sse --port 8080 --mount-path /mcp

# Streamable HTTP mode
debvulns-mcp --transport streamable-http --port 8080 --mount-path /mcp

Note: HTTP modes require running behind a web server. See HTTP Server Setup below.

HTTP Server Setup

The HTTP transport modes need to be served by a WSGI/ASGI server. Example with uvicorn:

# Install uvicorn
pip install uvicorn

# Run with stdio transport and wrap with uvicorn
uvicorn debvulns.main:mcp_app --app-dir src --host 0.0.0.0 --port 8000 --path /mcp

Or use the built-in development server:

# SSE mode
debvulns-mcp --transport sse --host 0.0.0.0 --port 8000 --mount-path /mcp

Standalone CLI Tool (debvulns)

The package includes a standalone CLI tool debvulns that allows you to scan for vulnerabilities directly from the command line without running the MCP server.

On first run, debvulns downloads the vulnerabilities and EPSS data and caches them locally (defaulting to /var/cache/debvulns or falling back to ~/.cache/debvulns if the default path is unwritable). The cache is refreshed automatically if it is older than 24 hours.

Running the CLI Tool

debvulns

Command Line Options

debvulns --help

Options:

• -s, --severity {critical,high,medium,low,negligible} - Filter vulnerabilities by severity. By default, lists all vulnerabilities grouped by severity.
• -f, --format {json,csv} - Output format (default: json).
• --sort-by {package,cve} - Sort vulnerabilities by package name or CVE ID.
• --suite SUITE - Debian suite name (e.g., bookworm, sid). Automatically detected by default.
• --cache-dir PATH - Directory to cache fetched and parsed data (default: /var/cache/debvulns).
• --no-cache - Do not use cached data, force downloading and parsing.
• --vuln-url URL - Custom URL or local path for Debian Security Tracker data.
• --epss-url URL - Custom URL or local path for EPSS scores data.
• -v, --verbose - Enable verbose debug logging (sent to stderr).

Examples

Filter high severity vulnerabilities, sort by CVE, and output in CSV format:

debvulns --severity high --sort-by cve --format csv

Run for a specific suite without using cached data:

debvulns --suite trixie --no-cache

Available Tools

list_vulnerabilities

Lists all vulnerabilities affecting the currently installed packages on the system. Categorises them by severity (critical, high, medium, low, negligible) and EPSS score.

research_cves

Provides detailed information for a list of CVE IDs, including:

• Package name
• Urgency level
• EPSS score and percentile
• Whether a fix is available
• Remote exploitability
• Description

Adding to VSCode

To use this MCP server with VSCode and AI assistants:

1. Open VSCode Settings (JSON):

   • On macOS: Cmd + Shift + P → "Preferences: Open Settings (JSON)"
   • On Linux/Windows: Ctrl + Shift + P → "Preferences: Open Settings (JSON)"

2. Add the MCP server configuration:

{
  "mcpServers": {
    "debvulns": {
      "command": "debvulns-mcp",
      "args": [],
      "env": {
        "DEBSECAN_SUITE": "bookworm"
      }
    }
  }
}

3. Replace bookworm with your Debian suite codename (e.g., trixie, sid, GENERIC)

4. Restart VSCode or reload the window

Adding to opencode

Option 1: STDIO Mode (Default)

For local usage with opencode, use the default stdio transport:

{
  "mcpServers": {
    "debvulns": {
      "command": "debvulns-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "DEBSECAN_SUITE": "bookworm"
      }
    }
  }
}

Option 2: HTTP Mode

For remote or containerized setups, you can run the MCP server over HTTP:

1. Start the server:

debvulns-mcp --transport streamable-http --port 8080 --mount-path /mcp

2. Configure opencode to connect via HTTP:

{
  "mcpServers": {
    "debvulns": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Note: HTTP mode requires the MCP client to support HTTP transport.

How It Works

1. Package Discovery: Uses python-apt to enumerate all installed packages on the system
2. Vulnerability Data: Fetches compressed vulnerability data from the Debian Security Tracker
3. EPSS Enrichment: Downloads EPSS scores from CISA to prioritize vulnerabilities
4. Analysis: Compares installed package versions against vulnerability data using APT version comparison

Requirements

• Python 3.11+
• Debian-based distribution (Debian, Ubuntu, etc.)
• Network access to download vulnerability data