io.github.andrasfe/vulnicheck
HTTP MCP Server for comprehensive Python vulnerability scanning and security analysis.
Open source Open in the app JSON README (API)
About
HTTP MCP Server for comprehensive Python vulnerability scanning and security analysis.
Details
- Kind
- MCP servers
- Topic
- Security & identity
- Publisher
- andrasfe
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.0
- Stars
- 11
- Forks
- 3
- Last push
- 2026-02-22T14:45:13Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:25
- Updated
- 2026-08-29 03:02:25
- Origin id
io.github.andrasfe/vulnicheck
README
# 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:
```
"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
1. **Get Google OAuth Credentials**:
- Go to [Google Cloud Console](https://console.cloud.google.com/)
- 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**:
```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"
```
3. **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
```
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:
```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:
1. FastMCP fixes OAuth + HTTP transport support, OR
2. 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](https://hub.docker.com/r/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](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.