vulnicheck

VulniCheck - AI 驱动的安全扫描器

VulniCheck 利用 AI 驱动的漏洞检测，为 Python 项目和 GitHub 仓库提供全面的安全分析。它以基于 Docker 的 HTTP MCP 服务运行，使用标准 HTTP 流式传输（无需 SSE），提供安全的容器化部署和全面的漏洞扫描功能。

快速开始

1. 拉取并运行 Docker 容器

# 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. 添加到 Claude Code

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

完成！VulniCheck 现已可在 Claude Code 中使用。

用法

安装后，只需向 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 将会：

• ✅ 扫描依赖项中的已知漏洞（requirements.txt、pyproject.toml、setup.py）
• ✅ 检测泄露的机密信息和凭据
• ✅ 分析 Dockerfile 中的安全问题
• ✅ 验证 MCP 配置
• ✅ 生成 AI 驱动的风险评估
• ✅ 提供可执行的修复建议

主要功能

• Docker 部署：通过 HTTP 流式传输实现安全的容器化部署（无需 SSE/Server-Sent Events）
• 可选身份验证：支持 Google OAuth 2.0，以进行安全访问控制（默认禁用）
• 可用于生产环境：可扩展的 HTTP 服务架构
• 全面覆盖：查询 5+ 个漏洞数据库（OSV.dev、NVD、GitHub Advisory、CIRCL、Safety DB）
• GitHub 集成：直接扫描任何公开或私有的 GitHub 仓库（最大 1GB）
• AI 驱动的分析：使用 OpenAI/Anthropic API 进行智能安全评估
• 机密信息检测：查找泄露的 API 密钥、密码和凭据
• Docker 安全：分析 Dockerfile 中存在漏洞的依赖项
• 智能缓存：通过提交级缓存避免重复扫描
• 空间管理：自动清理，防止磁盘空间耗尽（总量上限为 2GB）
• 零配置：开箱即用，也可通过可选 API 密钥增强功能

可用工具

工具	描述
check_package_vulnerabilities	检查特定 Python 包是否存在漏洞
scan_dependencies	扫描依赖文件（requirements.txt、pyproject.toml 等）
scan_installed_packages	扫描当前已安装的 Python 包
get_cve_details	获取特定 CVE 的详细信息
scan_for_secrets	检测代码中泄露的机密信息和凭据
scan_dockerfile	分析 Dockerfile 中存在漏洞的 Python 依赖项
scan_github_repo	全面扫描 GitHub 仓库的安全性
assess_operation_safety	由 AI 驱动的操作风险评估
validate_mcp_security	验证 MCP 服务安全配置
comprehensive_security_check	交互式 AI 驱动的安全评估

可选 API 密钥

使用 API 密钥增强 VulniCheck，以获得更高的速率限制和 AI 功能：

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

身份验证（可选）

VulniCheck 支持可选的 Google OAuth 2.0 身份验证，以实现安全访问控制。默认情况下，身份验证处于禁用状态。

启用 Google OAuth

1. 获取 Google OAuth 凭据：

   • 前往 Google Cloud Console
   • 创建项目并启用 Google+ API
   • 创建 OAuth 2.0 凭据（Web 应用）
   • 添加授权重定向 URI：http://localhost:3000/oauth/callback（或你的域名）

2. 配置环境变量：

   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. 启用身份验证运行：

   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. 使用 docker-compose： 完整配置示例请参阅 docker-compose.auth-example.yml。

注意：OAuth 令牌会保存在 /home/vulnicheck/.vulnicheck/tokens。使用 Docker 卷可在容器重启后保留令牌。

⚠️ 已知 OAuth 限制

FastMCP OAuth 与 HTTP 传输不兼容

由于 FastMCP 2.12.4 的限制，OAuth 身份验证与 HTTP 传输（streamable-http）配合使用时无法正常工作。授权端点（/oauth/authorize、/oauth/callback）未正确挂载，因此会返回 404 错误。

OAuth 可用的情况：

• ✅ 本地连接（未来版本的 FastMCP 支持时）
• ✅ OAuth 发现端点可用（/.well-known/oauth-protected-resource）

OAuth 不可用的情况：

• ❌ 外部客户端（ChatGPT、Claude Desktop 等）使用 HTTP 传输
• ❌ 授权端点返回 404
• ❌ 令牌交换失败

外部客户端（ChatGPT 等）的解决方法：

通过 ngrok 或其他公开 URL 访问时，不使用身份验证运行 VulniCheck：

# 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

在 MCP 客户端（ChatGPT 等）中：

• URL：https://your-ngrok-url.ngrok-free.dev/mcp
• 身份验证：无

安全注意事项：

• ✅ 流量通过 HTTPS（ngrok）加密
• ⚠️ 无身份验证——任何拥有 URL 的人都可以访问
• 💡 ngrok 免费 URL 会在重启后改变（依靠隐蔽性实现安全）
• 🔒 在生产环境中，请使用带密码保护或 IP 白名单的 ngrok 付费套餐

未来的解决方案： 此限制将在以下情况得到解决：

1. FastMCP 修复对 OAuth + HTTP 传输的支持，或
2. 实现其他身份验证机制

使用 ngrok

快速开始（无 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

可选 OAuth 脚本（实验性——OAuth 不可用）：

提供了便捷脚本 restart-vulnicheck-ngrok.sh，用于测试 OAuth，但由于 FastMCP 的限制，OAuth 目前无法正常工作：

# 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

注意：此脚本供未来使用，待 FastMCP 修复 OAuth + HTTP 传输后即可使用。目前，外部客户端始终应在不使用 OAuth 的情况下运行。

从源代码构建

# 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

官方 Docker 镜像可在以下位置获取：

• Docker Hub：andrasfe/vulnicheck
• 最新标签：andrasfe/vulnicheck:latest

要求

• Docker
• Claude Code 或任何支持 HTTP 传输的 MCP 客户端（标准 HTTP，无需 SSE）
• 可选：用于增强功能的 API 密钥

支持的文件类型

• 依赖项：requirements.txt、pyproject.toml、setup.py、锁定文件
• 容器：Dockerfile、docker-compose.yml
• 机密信息：所有基于文本的源文件
• GitHub：任何公开或私有仓库 URL

支持

• 问题：在 https://github.com/andrasfe/vulnicheck/issues 报告问题
• 开发：查看 CLAUDE.md 了解开发详情
• 安全：通过 GitHub Security Advisories 私下报告安全问题

---

免责声明：漏洞数据按“原样”提供，不作任何保证。用户有责任进行验证和修复。