vulnicheck

VulniCheck

What is VulniCheck?

VulniCheck is a Python-based MCP server designed to provide real-time security advice for Python modules. It achieves this by querying a comprehensive set of authoritative vulnerability databases, including OSV.dev, NVD, GitHub Advisory Database, CIRCL Vulnerability-Lookup, and Safety DB. Beyond dependency vulnerability scanning, VulniCheck offers advanced features such as Docker analysis, secrets detection, MCP configuration validation, and LLM-powered risk assessment for interactive security audits. It provides detailed CVE information, CVSS scores, and actionable remediation guidance.

How to use VulniCheck?

VulniCheck can be integrated with MCP-compatible clients like Claude Desktop or Claude Code. The recommended installation method is using uvx directly from GitHub.

Quick Start with uvx (Recommended):

1. Claude Desktop/Code Setup:

   # Basic setup
   claude mcp add vulnicheck -- uvx --from git+https://github.com/andrasfe/vulnicheck.git vulnicheck
   
   # With environment variables for enhanced features (API keys)
   claude mcp add vulnicheck \
     -e NVD_API_KEY=your-nvd-key \
     -e GITHUB_TOKEN=your-github-token \
     -e OPENAI_API_KEY=your-openai-key \
     -- uvx --from git+https://github.com/andrasfe/vulnicheck.git vulnicheck
   

   Note: Environment variables like NVD_API_KEY, GITHUB_TOKEN, OPENAI_API_KEY, and ANTHROPIC_API_KEY are optional but highly recommended for increased API rate limits and AI-powered features.

Traditional Installation:

1. Clone the repository: git clone https://github.com/andrasfe/vulnicheck.git
2. Navigate to the directory: cd vulnicheck
3. Run the local setup script: ./run-local.sh (This script handles virtual environment creation, dependency installation, and Claude Desktop configuration).
4. Alternatively, manual installation involves creating a virtual environment, installing dependencies (pip install -e .), and running the server (python -m vulnicheck.server).

Once configured, you can interact with VulniCheck using natural language commands within your IDE, such as:

• "Check if numpy has any vulnerabilities"
• "Scan my requirements.txt file for security issues"
• "Scan the GitHub repository https://github.com/numpy/numpy for vulnerabilities"
• "Do a comprehensive security check on https://github.com/owner/repo"
• "Scan this directory for exposed secrets"

Key Features of VulniCheck

• Real-time Vulnerability Checking: Scans Python packages against multiple databases (OSV.dev, NVD, GitHub Advisory DB, CIRCL, Safety DB).
• Comprehensive Scanning: Analyzes dependencies from requirements.txt, pyproject.toml, lock files, and even Python import statements.
• GitHub Repository Scanning: Performs in-depth security analysis of entire GitHub repositories, including dependencies, secrets, and Dockerfiles. Supports private repositories.
• Secrets Detection: Identifies exposed API keys, passwords, and credentials within files and directories using detect-secrets.
• Docker Security Scanning: Analyzes Dockerfiles for vulnerable Python dependencies.
• MCP Security Validation: Enables LLMs to self-assess their security posture by validating MCP configurations.
• AI-Powered Risk Assessment: Leverages LLMs (OpenAI/Anthropic) for advanced risk assessment of MCP operations and responses when API keys are configured.
• Detailed CVE Information: Provides full CVE details, CVSS scores, CWE mapping, and remediation guidance.
• Secure MCP Passthrough: Validates and monitors cross-server MCP operations with built-in security constraints and an approval workflow for high-risk actions.
• Conversation Logging: Automatically logs all MCP interactions for audit and debugging purposes, with hourly rotation.
• Smart Caching: Implements commit-level caching for GitHub repository scans to improve efficiency.
• Pre-operation Safety Assessment: Evaluates the risks associated with file operations, command execution, and API calls before they are performed.

Use Cases of VulniCheck

• Proactive Security Audits: Regularly scan projects and dependencies to identify and mitigate vulnerabilities before they are exploited.
• CI/CD Integration: Integrate VulniCheck into development pipelines to automatically enforce security checks on code changes.
• Third-Party Code Assessment: Evaluate the security posture of external libraries and GitHub repositories before incorporating them into projects.
• LLM Security Self-Assessment: Allow AI agents to validate their own security configurations and operational risks.
• Secrets Management: Detect and remediate accidentally exposed secrets and credentials in codebases.
• Docker Image Security: Ensure Docker images are free from vulnerable Python dependencies.
• Compliance and Reporting: Generate security reports for compliance purposes, detailing identified vulnerabilities and remediation steps.

FAQ from VulniCheck

• How do I improve API rate limits? Obtain free API keys for NVD (https://nvd.nist.gov/developers/request-an-api-key) and GitHub (https://github.com/settings/tokens) and configure them via environment variables (NVD_API_KEY, GITHUB_TOKEN) or in your .env file. LLM API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY) enable AI-powered features.
• What happens if I don't provide an API key? You will be subject to lower API rate limits for NVD and GitHub, and AI-powered risk assessments will not be available. Basic functionality will still work, but with potential rate limiting issues.
• How does VulniCheck handle private GitHub repositories? Provide a GITHUB_TOKEN with appropriate permissions as an environment variable or in your .env file when scanning private repositories.
• What is the .vulnicheck directory? This directory stores conversation logs, local cache, and security audit trails. It's recommended to add .vulnicheck/ to your .gitignore file.
• Can VulniCheck scan my local project? Yes, VulniCheck supports scanning local directories. You can use commands like "Run a comprehensive security check on my project" or "Run a comprehensive security check on /path/to/project".
• How does the MCP passthrough tool work? It securely executes MCP tool calls between servers, applying AI-powered risk assessments, pattern matching, and an approval workflow for high-risk operations. All interactions are logged.
• What is the validate_mcp_security tool used for? This tool allows LLMs to perform a self-assessment of their security posture by analyzing their MCP configurations for potential vulnerabilities like prompt injection or tool poisoning.
• How is VulniCheck licensed? VulniCheck is released under the MIT License.

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

# 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

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:

"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:

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

1. 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)

2. Configure Environment Variables:

   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"
   

3. Run with Authentication:

   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
   

4. 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:

# 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:

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

Using with ngrok

Quick Start (No OAuth):

# 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:

# 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

# 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.