{
  "markdown": "# VulniCheck - AI-Powered Security Scanner\n\nVulniCheck 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.\n\n## Quick Start\n\n### 1. Pull and Run the Docker Container\n\n```bash\n# Pull the latest image from Docker Hub\ndocker pull andrasfe/vulnicheck:latest\n\n# Run with OpenAI API key (for enhanced AI-powered risk assessment)\ndocker run -d --name vulnicheck-mcp -p 3000:3000 \\\n  --restart=unless-stopped \\\n  -e OPENAI_API_KEY=your-openai-api-key \\\n  andrasfe/vulnicheck:latest\n\n# Or run without API key (basic vulnerability scanning)\ndocker run -d --name vulnicheck-mcp -p 3000:3000 \\\n  --restart=unless-stopped \\\n  andrasfe/vulnicheck:latest\n```\n\n### 2. Add to Claude Code\n\n```bash\nclaude mcp add --transport http vulnicheck http://localhost:3000/mcp\n```\n\nThat's it! VulniCheck is now available in Claude Code.\n\n## Usage\n\nOnce installed, simply ask Claude:\n\n```\n\"Run a comprehensive security check on my project\"\n\n\"Scan https://github.com/owner/repo for vulnerabilities\"\n\n\"Check my dependencies for security issues\"\n\n\"Scan my Dockerfile for vulnerable packages\"\n```\n\nVulniCheck will:\n- ✅ Scan dependencies for known vulnerabilities (requirements.txt, pyproject.toml, setup.py)\n- ✅ Detect exposed secrets and credentials\n- ✅ Analyze Dockerfiles for security issues\n- ✅ Validate MCP configurations\n- ✅ Generate AI-powered risk assessments\n- ✅ Provide actionable remediation recommendations\n\n## Key Features\n\n- **Docker Deployment**: Secure containerized deployment with HTTP streaming (no SSE/Server-Sent Events required)\n- **Optional Authentication**: Supports Google OAuth 2.0 for secure access control (disabled by default)\n- **Production Ready**: Scalable HTTP server architecture\n- **Comprehensive Coverage**: Queries 5+ vulnerability databases (OSV.dev, NVD, GitHub Advisory, CIRCL, Safety DB)\n- **GitHub Integration**: Scan any public/private GitHub repository directly (up to 1GB)\n- **AI-Powered Analysis**: Uses OpenAI/Anthropic APIs for intelligent security assessment\n- **Secrets Detection**: Finds exposed API keys, passwords, and credentials\n- **Docker Security**: Analyzes Dockerfiles for vulnerable dependencies\n- **Smart Caching**: Avoids redundant scans with commit-level caching\n- **Space Management**: Automatic cleanup prevents disk exhaustion (2GB total limit)\n- **Zero Config**: Works out of the box, enhanced with optional API keys\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `check_package_vulnerabilities` | Check a specific Python package for vulnerabilities |\n| `scan_dependencies` | Scan dependency files (requirements.txt, pyproject.toml, etc.) |\n| `scan_installed_packages` | Scan currently installed Python packages |\n| `get_cve_details` | Get detailed information about a specific CVE |\n| `scan_for_secrets` | Detect exposed secrets and credentials in code |\n| `scan_dockerfile` | Analyze Dockerfiles for vulnerable Python dependencies |\n| `scan_github_repo` | Comprehensive security scan of GitHub repositories |\n| `assess_operation_safety` | AI-powered risk assessment for operations |\n| `validate_mcp_security` | Validate MCP server security configurations |\n| `comprehensive_security_check` | Interactive AI-powered security assessment |\n\n## Optional API Keys\n\nEnhance VulniCheck with API keys for better rate limits and AI features:\n\n```bash\ndocker run -d --name vulnicheck-mcp -p 3000:3000 \\\n  --restart=unless-stopped \\\n  -e OPENAI_API_KEY=your-key \\           # AI-powered risk assessment\n  -e ANTHROPIC_API_KEY=your-key \\        # Alternative AI provider\n  -e GITHUB_TOKEN=your-token \\           # Higher GitHub API rate limits\n  -e NVD_API_KEY=your-key \\              # Higher NVD rate limits\n  andrasfe/vulnicheck:latest\n```\n\n## Authentication (Optional)\n\nVulniCheck supports optional Google OAuth 2.0 authentication for secure access control. By default, authentication is **disabled**.\n\n### Enabling Google OAuth\n\n1. **Get Google OAuth Credentials**:\n   - Go to [Google Cloud Console](https://console.cloud.google.com/)\n   - Create a project and enable Google+ API\n   - Create OAuth 2.0 credentials (Web application)\n   - Add authorized redirect URI: `http://localhost:3000/oauth/callback` (or your domain)\n\n2. **Configure Environment Variables**:\n   ```bash\n   export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID=\"your-client-id.apps.googleusercontent.com\"\n   export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET=\"GOCSPX-your-secret-here\"\n   export FASTMCP_SERVER_BASE_URL=\"http://localhost:3000\"\n   ```\n\n3. **Run with Authentication**:\n   ```bash\n   docker run -d --name vulnicheck-mcp -p 3000:3000 \\\n     --restart=unless-stopped \\\n     -e FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID=your-client-id \\\n     -e FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET=your-secret \\\n     -e FASTMCP_SERVER_BASE_URL=http://localhost:3000 \\\n     -v vulnicheck_tokens:/home/vulnicheck/.vulnicheck/tokens \\\n     andrasfe/vulnicheck:latest \\\n     python -m vulnicheck.server --auth-mode google\n   ```\n\n4. **Using docker-compose**:\n   See `docker-compose.auth-example.yml` for a complete configuration example.\n\n**Note**: OAuth tokens are persisted in `/home/vulnicheck/.vulnicheck/tokens`. Use a Docker volume to persist tokens across container restarts.\n\n### ⚠️ Known OAuth Limitations\n\n**FastMCP OAuth + HTTP Transport Incompatibility**\n\nDue 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.\n\n**When OAuth Works:**\n- ✅ Local connections (when supported in future FastMCP versions)\n- ✅ OAuth discovery endpoint works (`/.well-known/oauth-protected-resource`)\n\n**When OAuth Does NOT Work:**\n- ❌ HTTP transport with external clients (ChatGPT, Claude Desktop, etc.)\n- ❌ Authorization endpoints return 404\n- ❌ Token exchange fails\n\n**Workaround for External Clients (ChatGPT, etc.):**\n\nRun VulniCheck **without authentication** when accessing through ngrok or other public URLs:\n\n```bash\n# Start without OAuth (recommended for external clients)\ndocker run -d --name vulnicheck-mcp -p 3000:3000 \\\n  --restart=unless-stopped \\\n  andrasfe/vulnicheck:latest\n\n# Then configure ngrok\nngrok http 3000\n```\n\nIn your MCP client (ChatGPT, etc.):\n- **URL**: `https://your-ngrok-url.ngrok-free.dev/mcp`\n- **Authentication**: None\n\n**Security Considerations:**\n- ✅ Traffic is encrypted via HTTPS (ngrok)\n- ⚠️ No authentication - anyone with URL can access\n- 💡 ngrok free URLs change on restart (security through obscurity)\n- 🔒 For production, use ngrok paid tier with password protection or IP whitelisting\n\n**Future Resolution:**\nThis limitation will be resolved when:\n1. FastMCP fixes OAuth + HTTP transport support, OR\n2. Alternative authentication mechanisms are implemented\n\n### Using with ngrok\n\n**Quick Start (No OAuth):**\n\n```bash\n# 1. Start VulniCheck\ndocker run -d --name vulnicheck-mcp -p 3000:3000 \\\n  --restart=unless-stopped \\\n  andrasfe/vulnicheck:latest\n\n# 2. Start ngrok\nngrok http 3000\n\n# 3. Use the ngrok URL in your MCP client\n# URL: https://your-generated-url.ngrok-free.dev/mcp\n# Authentication: None\n```\n\n**Optional OAuth Script (Experimental - OAuth Not Functional):**\n\nA convenience script `restart-vulnicheck-ngrok.sh` is provided for testing OAuth, but **OAuth does not currently work** due to FastMCP limitations:\n\n```bash\n# Copy the example environment file\ncp .env.example .env\n\n# Edit .env and add your credentials\nGOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGOOGLE_CLIENT_SECRET=GOCSPX-your-secret-here\nNGROK_URL=https://your-ngrok-url.ngrok-free.dev\n\n# Run the script (OAuth will not work)\n./restart-vulnicheck-ngrok.sh\n```\n\n**Note**: The script is provided for future use when FastMCP OAuth + HTTP transport is fixed. Currently, always run without OAuth for external clients.\n\n## Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/andrasfe/vulnicheck.git\ncd vulnicheck\n\n# Build Docker image\ndocker build -t vulnicheck .\n\n# Run locally built image (no auth)\ndocker run -d --name vulnicheck-mcp -p 3000:3000 --restart=unless-stopped vulnicheck\n\n# Run with Google OAuth\ndocker run -d --name vulnicheck-mcp -p 3000:3000 \\\n  --restart=unless-stopped \\\n  -e FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID=your-client-id \\\n  -e FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET=your-secret \\\n  -e FASTMCP_SERVER_BASE_URL=http://localhost:3000 \\\n  -v vulnicheck_tokens:/home/vulnicheck/.vulnicheck/tokens \\\n  vulnicheck \\\n  python -m vulnicheck.server --auth-mode google\n```\n\n## Docker Hub\n\nThe official Docker image is available at:\n- **Docker Hub**: [andrasfe/vulnicheck](https://hub.docker.com/r/andrasfe/vulnicheck)\n- **Latest Tag**: `andrasfe/vulnicheck:latest`\n\n## Requirements\n\n- Docker\n- Claude Code or any MCP client with HTTP transport support (standard HTTP, no SSE required)\n- Optional: API keys for enhanced features\n\n## Supported File Types\n\n- **Dependencies**: `requirements.txt`, `pyproject.toml`, `setup.py`, lock files\n- **Containers**: `Dockerfile`, `docker-compose.yml`\n- **Secrets**: All text-based source files\n- **GitHub**: Any public or private repository URL\n\n## Support\n\n- **Issues**: Report problems at https://github.com/andrasfe/vulnicheck/issues\n- **Development**: See [CLAUDE.md](CLAUDE.md) for development details\n- **Security**: Report security issues privately via GitHub Security Advisories\n\n---\n\n**DISCLAIMER**: Vulnerability data provided \"AS IS\" without warranty. Users are responsible for verification and remediation.\n",
  "bytes": 9775,
  "sha": "7349291299d6566c1610c4c7365a7a4811b2dee6a177818265e916da7ffbef4e",
  "repo_slug": "andrasfe/vulnicheck",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_andrasfe_vulnicheck_77591bb5/readme"
}