io.github.andrasfe/vulnicheck

Official

by andrasfe · Python

HTTP MCP Server for comprehensive Python vulnerability scanning and security analysis.

Scan Python code for vulnerabilities and security issues.

VulniCheck - AI-Powered Security Scanner

VulniCheck provides comprehensive security analysis for Python projects and GitHub repositories using AI-powered vulnerability detection. It runs as a Docker-based HTTP MCP server with standard HTTP streaming (no SSE required), providing secure containerized deployment with comprehensive vulnerability scanning capabilities.

Quick Start

1. Pull and Run the Docker Container

bash

# Pull the latest image from Docker Hub
docker pull andrasfe/vulnicheck:latest

# Run with OpenAI API key (for enhanced AI-powered risk assessment)
docker run -d --name vulnicheck-mcp -p 3000:3000 \
  --restart=unless-stopped \
  -e OPENAI_API_KEY=your-openai-api-key \
  andrasfe/vulnicheck:latest

# Or run without API key (basic vulnerability scanning)
docker run -d --name vulnicheck-mcp -p 3000:3000 \
  --restart=unless-stopped \
  andrasfe/vulnicheck:latest

2. Add to Claude Code

bash

claude mcp add --transport http vulnicheck http://localhost:3000/mcp

That's it! VulniCheck is now available in Claude Code.

Usage

Once installed, simply ask Claude:

code

"Run a comprehensive security check on my project"

"Scan https://github.com/owner/repo for vulnerabilities"

"Check my dependencies for security issues"

"Scan my Dockerfile for vulnerable packages"

VulniCheck will:

✅ Scan dependencies for known vulnerabilities (requirements.txt, pyproject.toml, setup.py)
✅ Detect exposed secrets and credentials
✅ Analyze Dockerfiles for security issues
✅ Validate MCP configurations
✅ Generate AI-powered risk assessments
✅ Provide actionable remediation recommendations

Key Features

Docker Deployment: Secure containerized deployment with HTTP streaming (no SSE/Server-Sent Events required)
Optional Authentication: Supports Google OAuth 2.0 for secure access control (disabled by default)
Production Ready: Scalable HTTP server architecture
Comprehensive Coverage: Queries 5+ vulnerability databases (OSV.dev, NVD, GitHub Advisory, CIRCL, Safety DB)
GitHub Integration: Scan any public/private GitHub repository directly (up to 1GB)
AI-Powered Analysis: Uses OpenAI/Anthropic APIs for intelligent security assessment
Secrets Detection: Finds exposed API keys, passwords, and credentials
Docker Security: Analyzes Dockerfiles for vulnerable dependencies
Smart Caching: Avoids redundant scans with commit-level caching
Space Management: Automatic cleanup prevents disk exhaustion (2GB total limit)
Zero Config: Works out of the box, enhanced with optional API keys

Available Tools

Tool	Description
`check_package_vulnerabilities`	Check a specific Python package for vulnerabilities
`scan_dependencies`	Scan dependency files (requirements.txt, pyproject.toml, etc.)
`scan_installed_packages`	Scan currently installed Python packages
`get_cve_details`	Get detailed information about a specific CVE
`scan_for_secrets`	Detect exposed secrets and credentials in code
`scan_dockerfile`	Analyze Dockerfiles for vulnerable Python dependencies
`scan_github_repo`	Comprehensive security scan of GitHub repositories
`assess_operation_safety`	AI-powered risk assessment for operations
`validate_mcp_security`	Validate MCP server security configurations
`comprehensive_security_check`	Interactive AI-powered security assessment

Optional API Keys

Enhance VulniCheck with API keys for better rate limits and AI features:

bash

docker run -d --name vulnicheck-mcp -p 3000:3000 \
  --restart=unless-stopped \
  -e OPENAI_API_KEY=your-key \           # AI-powered risk assessment
  -e ANTHROPIC_API_KEY=your-key \        # Alternative AI provider
  -e GITHUB_TOKEN=your-token \           # Higher GitHub API rate limits
  -e NVD_API_KEY=your-key \              # Higher NVD rate limits
  andrasfe/vulnicheck:latest

Authentication (Optional)

VulniCheck supports optional Google OAuth 2.0 authentication for secure access control. By default, authentication is disabled.

Enabling Google OAuth

Get Google OAuth Credentials:
- Go to Google Cloud Console
- Create a project and enable Google+ API
- Create OAuth 2.0 credentials (Web application)
- Add authorized redirect URI: http://localhost:3000/oauth/callback (or your domain)

Configure Environment Variables:

bash

export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET="GOCSPX-your-secret-here"
export FASTMCP_SERVER_BASE_URL="http://localhost:3000"

Run with Authentication:

bash

docker run -d --name vulnicheck-mcp -p 3000:3000 \
  --restart=unless-stopped \
  -e FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID=your-client-id \
  -e FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET=your-secret \
  -e FASTMCP_SERVER_BASE_URL=http://localhost:3000 \
  -v vulnicheck_tokens:/home/vulnicheck/.vulnicheck/tokens \
  andrasfe/vulnicheck:latest \
  python -m vulnicheck.server --auth-mode google

Using docker-compose: See docker-compose.auth-example.yml for a complete configuration example.

Note: OAuth tokens are persisted in /home/vulnicheck/.vulnicheck/tokens. Use a Docker volume to persist tokens across container restarts.

⚠️ Known OAuth Limitations

FastMCP OAuth + HTTP Transport Incompatibility

Due to a limitation in FastMCP 2.12.4, OAuth authentication does not work properly with HTTP transport (streamable-http). The authorization endpoints (/oauth/authorize, /oauth/callback) are not correctly mounted, resulting in 404 errors.

When OAuth Works:

✅ Local connections (when supported in future FastMCP versions)
✅ OAuth discovery endpoint works (/.well-known/oauth-protected-resource)

When OAuth Does NOT Work:

❌ HTTP transport with external clients (ChatGPT, Claude Desktop, etc.)
❌ Authorization endpoints return 404
❌ Token exchange fails

Workaround for External Clients (ChatGPT, etc.):

Run VulniCheck without authentication when accessing through ngrok or other public URLs:

bash

# Start without OAuth (recommended for external clients)
docker run -d --name vulnicheck-mcp -p 3000:3000 \
  --restart=unless-stopped \
  andrasfe/vulnicheck:latest

# Then configure ngrok
ngrok http 3000

In your MCP client (ChatGPT, etc.):

URL: https://your-ngrok-url.ngrok-free.dev/mcp
Authentication: None

Security Considerations:

✅ Traffic is encrypted via HTTPS (ngrok)
⚠️ No authentication - anyone with URL can access
💡 ngrok free URLs change on restart (security through obscurity)
🔒 For production, use ngrok paid tier with password protection or IP whitelisting

Future Resolution: This limitation will be resolved when:

FastMCP fixes OAuth + HTTP transport support, OR
Alternative authentication mechanisms are implemented

Using with ngrok

Quick Start (No OAuth):

bash

# 1. Start VulniCheck
docker run -d --name vulnicheck-mcp -p 3000:3000 \
  --restart=unless-stopped \
  andrasfe/vulnicheck:latest

# 2. Start ngrok
ngrok http 3000

# 3. Use the ngrok URL in your MCP client
# URL: https://your-generated-url.ngrok-free.dev/mcp
# Authentication: None

Optional OAuth Script (Experimental - OAuth Not Functional):

A convenience script restart-vulnicheck-ngrok.sh is provided for testing OAuth, but OAuth does not currently work due to FastMCP limitations:

bash

# Copy the example environment file
cp .env.example .env

# Edit .env and add your credentials
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-your-secret-here
NGROK_URL=https://your-ngrok-url.ngrok-free.dev

# Run the script (OAuth will not work)
./restart-vulnicheck-ngrok.sh

Note: The script is provided for future use when FastMCP OAuth + HTTP transport is fixed. Currently, always run without OAuth for external clients.

Building from Source

bash

# Clone the repository
git clone https://github.com/andrasfe/vulnicheck.git
cd vulnicheck

# Build Docker image
docker build -t vulnicheck .

# Run locally built image (no auth)
docker run -d --name vulnicheck-mcp -p 3000:3000 --restart=unless-stopped vulnicheck

# Run with Google OAuth
docker run -d --name vulnicheck-mcp -p 3000:3000 \
  --restart=unless-stopped \
  -e FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID=your-client-id \
  -e FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET=your-secret \
  -e FASTMCP_SERVER_BASE_URL=http://localhost:3000 \
  -v vulnicheck_tokens:/home/vulnicheck/.vulnicheck/tokens \
  vulnicheck \
  python -m vulnicheck.server --auth-mode google

Docker Hub

The official Docker image is available at:

Docker Hub: andrasfe/vulnicheck
Latest Tag: andrasfe/vulnicheck:latest

Requirements

Docker
Claude Code or any MCP client with HTTP transport support (standard HTTP, no SSE required)
Optional: API keys for enhanced features

Supported File Types

Dependencies: requirements.txt, pyproject.toml, setup.py, lock files
Containers: Dockerfile, docker-compose.yml
Secrets: All text-based source files
GitHub: Any public or private repository URL

Support

Issues: Report problems at https://github.com/andrasfe/vulnicheck/issues
Development: See CLAUDE.md for development details
Security: Report security issues privately via GitHub Security Advisories

DISCLAIMER: Vulnerability data provided "AS IS" without warranty. Users are responsible for verification and remediation.

Install

Configuration

Environment variables

NVD_API_KEYsecret

API key for NIST National Vulnerability Database (increases rate limit from 5 to 50 requests per 30 seconds)

GITHUB_TOKENsecret

GitHub token for Advisory Database access (increases rate limit to 5000 requests per hour)

OPENAI_API_KEYsecret

OpenAI API key for LLM-based risk assessment in MCP passthrough operations

ANTHROPIC_API_KEYsecret

Anthropic API key for LLM-based risk assessment (alternative to OpenAI)

MCP_PORT

Port for MCP HTTP server (default: 3000)

CACHE_TTL

Cache time-to-live in seconds for vulnerability data (default: 900)

VULNICHECK_HTTP_ONLY

Enable HTTP-only mode with MCP client delegation (true/false, default: auto-detect)

claude_desktop_config.json

{
  "mcpServers": {
    "vulnicheck": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "docker.io/andrasfe/vulnicheck:main"
      ],
      "env": {
        "NVD_API_KEY": "<YOUR_NVD_API_KEY>",
        "GITHUB_TOKEN": "<YOUR_GITHUB_TOKEN>",
        "OPENAI_API_KEY": "<YOUR_OPENAI_API_KEY>",
        "ANTHROPIC_API_KEY": "<YOUR_ANTHROPIC_API_KEY>",
        "MCP_PORT": "<YOUR_MCP_PORT>",
        "CACHE_TTL": "<YOUR_CACHE_TTL>",
        "VULNICHECK_HTTP_ONLY": "<YOUR_VULNICHECK_HTTP_ONLY>"
      }
    }
  }
}