README.md•12.6 kB
<p align="center">
<img src="logo.png" alt="Vibe tester Logo" width="270"/>
</p>
# MCP Vulnerability Checker Server
A modular Model Context Protocol (MCP) server providing comprehensive security vulnerability intelligence tools including CVE lookup, EPSS scoring, CVSS calculation, exploit detection, and Python package vulnerability checking.
## Demo
<p align="center">
<img src="demo.gif" alt="demo"/>
</p>
## 🔗 Using the Hosted Server
The vulnerability intelligence MCP server is already hosted and ready to use! Simply configure your MCP client to connect to it.
### Claude Desktop Configuration
Add this configuration to your Claude Desktop settings file (`~/.config/claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"vulnerability-intelligence": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-fetch"],
"env": {
"FETCH_URL": "https://vulnerability-intelligence-mcp-server-edb8b15494e8.herokuapp.com/sse"
}
}
}
}
```
### Cursor IDE Configuration
Add this configuration to your Cursor MCP settings file (`~/.cursor/mcp.json`):
```json
{
"mcpServers": {
"vulnerability-intelligence": {
"url": "https://vulnerability-intelligence-mcp-server-edb8b15494e8.herokuapp.com/sse"
}
}
}
```
Alternatively, in Cursor IDE:
1. Open Cursor Settings → Features → MCP Servers
2. Click "Add New Server"
3. Select "Server-Sent Events (SSE)" as the type
4. Enter URL: `https://vulnerability-intelligence-mcp-server-edb8b15494e8.herokuapp.com/sse`
5. Give it a name: `vulnerability-intelligence`
### Test the Connection
Once configured, try these example queries in Claude or Cursor:
- **CVE Lookup**: "Look up CVE-2021-44228" (Log4Shell vulnerability)
- **EPSS Score**: "Get EPSS score for CVE-2021-44228"
- **Package Check**: "Check the 'requests' Python package for vulnerabilities"
- **Exploit Check**: "Check for exploits for CVE-2021-44228"
- **CVSS Calculator**: "Calculate CVSS score for vector CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"
## 🛡️ Available Security Tools
### 🔍 CVE Vulnerability Lookup (`cve_lookup`)
- **Purpose**: Fetches detailed vulnerability information from the National Vulnerability Database (NVD)
- **Data Source**: NIST National Vulnerability Database API 2.0
- **Usage**: `cve_lookup cve_id="CVE-2021-44228"`
- **Features**:
- CVSS scores (v2.0, v3.0, v3.1) with severity ratings
- Comprehensive vulnerability descriptions
- References, advisories, and remediation links
- CWE (Common Weakness Enumeration) mappings
- Publication and modification timeline
- Affected product configurations
### 📊 EPSS Score Lookup (`get_epss_score`)
- **Purpose**: Get Exploit Prediction Scoring System (EPSS) scores for CVEs
- **Data Source**: FIRST EPSS API
- **Usage**: `get_epss_score cve_id="CVE-2021-44228"`
- **Features**:
- Probability of exploitation within 30 days
- AI-powered risk prioritization
- Real-time threat intelligence integration
- Percentile rankings for relative risk assessment
### 🧮 CVSS Score Calculator (`calculate_cvss_score`)
- **Purpose**: Calculate CVSS base scores from vector strings
- **Data Source**: CVSS v3.0/v3.1 specification
- **Usage**: `calculate_cvss_score vector="CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"`
- **Features**:
- Support for CVSS v3.0 and v3.1
- Detailed metric breakdown
- Severity level mapping (Critical, High, Medium, Low)
- Vector string validation and parsing
### 🔎 Vulnerability Search (`search_vulnerabilities`)
- **Purpose**: Search vulnerability databases with advanced filtering
- **Data Source**: Multiple vulnerability databases (NVD, CVE)
- **Usage**: `search_vulnerabilities keywords="apache" severity="HIGH" date_range="1y"`
- **Features**:
- Keyword-based search across vulnerability descriptions
- Severity filtering (CRITICAL, HIGH, MEDIUM, LOW)
- Date range filtering (30d, 90d, 1y, 2y, or custom)
- Advanced query capabilities for threat research
### 🎯 Exploit Availability Check (`get_exploit_availability`)
- **Purpose**: Check for public exploits and proof-of-concepts (PoCs)
- **Data Source**: ExploitDB, Metasploit, GitHub, security advisories
- **Usage**: `get_exploit_availability cve_id="CVE-2021-44228"`
- **Features**:
- Multi-source exploit detection
- Active exploitation indicators
- PoC code availability assessment
- Threat intelligence aggregation
### ⏰ Vulnerability Timeline (`get_vulnerability_timeline`)
- **Purpose**: Get comprehensive timeline and patch status information
- **Data Source**: NVD, vendor advisories, security bulletins
- **Usage**: `get_vulnerability_timeline cve_id="CVE-2021-44228"`
- **Features**:
- Publication and disclosure timeline
- Patch availability status
- Vendor advisory tracking
- Remediation guidance timeline
### 🎯 VEX Status Check (`get_vex_status`)
- **Purpose**: Check Vulnerability Exploitability eXchange (VEX) status for specific products
- **Data Source**: Vendor VEX statements and product security advisories
- **Usage**: `get_vex_status cve_id="CVE-2021-44228" product="Apache HTTP Server"`
- **Features**:
- Product-specific impact assessment
- Vendor-provided exploitability statements
- False positive filtering
- Supply chain impact analysis
### 📦 Python Package Vulnerability Check (`package_vulnerability_check`)
- **Purpose**: Checks Python packages for known security vulnerabilities
- **Data Source**: OSV (Open Source Vulnerabilities) Database + PyPI
- **Usage**: `package_vulnerability_check package_name="requests" version="2.25.1"`
- **Features**:
- Comprehensive vulnerability scanning for PyPI packages
- Version-specific or all-versions checking
- Detailed vulnerability reports with severity scores
- Affected version ranges and fix information
- Integration with CVE, GHSA, and PYSEC databases
- Package metadata from PyPI
## 🏗️ Modular Architecture
The server is built with a clean, modular architecture:
```
mcp_simple_tool/
├── server.py # Main MCP server orchestration
└── tools/ # Individual tool modules
├── cve_lookup.py # CVE vulnerability lookup
├── epss_lookup.py # EPSS score lookup
├── cvss_calculator.py # CVSS score calculator
├── vulnerability_search.py # Advanced vulnerability search
├── exploit_availability.py # Exploit and PoC detection
├── vulnerability_timeline.py # Timeline and patch status
├── vex_status.py # VEX status checking
└── package_vulnerability.py # Python package security check
tests/ # Comprehensive test suite
├── run_tests.py # Automated test runner
└── test_*.py # Individual tool tests
```
## 🔧 Alternative Setup Methods
### Docker Setup (Recommended for Local Development)
1. Initial setup:
```bash
# Clone the repository
git clone https://github.com/firetix/vulnerability-intelligence-mcp-server
cd vulnerability-intelligence-mcp-server
# Create environment file
cp .env.example .env
```
2. Build and run using Docker Compose:
```bash
# Build and start the server
docker compose up --build -d
# View logs
docker compose logs -f
# Check server status
docker compose ps
# Stop the server
docker compose down
```
3. The server will be available at: http://localhost:8000/sse
4. Connect to Cursor IDE:
- Open Cursor Settings → Features
- Add new MCP server
- Type: Select "sse"
- URL: Enter `http://localhost:8000/sse`
### Local Development Setup
1. Install the uv package manager:
```bash
# Install uv on macOS
brew install uv
# Or install via pip (any OS)
pip install uv
```
2. Install dependencies and run:
```bash
# Install the package with development dependencies
uv pip install -e ".[dev]"
# Using stdio transport (default)
uv run mcp-simple-tool
# Using SSE transport on custom port
uv run mcp-simple-tool --transport sse --port 8000
# Run the comprehensive test suite
python tests/run_tests.py
```
3. For Cursor IDE integration (stdio mode):
- Copy the absolute path to `cursor-run-mcp-server.sh`
- Open Cursor Settings → Features → MCP Servers
- Add new server with "stdio" type and the script path
## 🧪 Testing the Tools
Run the comprehensive test suite:
```bash
# Run all tests
python tests/run_tests.py
# Run individual tool tests
python tests/test_cve_lookup.py
python tests/test_package_vulnerability.py
python tests/test_modular_server.py
```
### Example Test Outputs
**CVE Lookup Test:**
```bash
🔍 **CVE Vulnerability Report: CVE-2021-44228**
📅 **Timeline:**
• Published: 2021-12-10T10:15:09.143
• Last Modified: 2023-11-07T04:10:58.217
⚠️ **CVSS Scores:**
• CVSS 3.1: 10.0 (CRITICAL)
```
**Package Vulnerability Test:**
```bash
🚨 **Python Package Security Report: requests**
⚠️ **Found 11 known vulnerabilities**
📦 **Package Information:**
• Latest Version: 2.32.3
• Summary: Python HTTP for Humans.
```
## 🌍 Environment Variables
Available environment variables (can be set in `.env`):
- `MCP_SERVER_PORT` (default: 8000) - Port to run the server on
- `MCP_SERVER_HOST` (default: 0.0.0.0) - Host to bind the server to
- `DEBUG` (default: false) - Enable debug mode
- `MCP_USER_AGENT` - Custom User-Agent for HTTP requests
## 🚀 Deploy Your Own Instance
If you want to deploy your own instance of the vulnerability intelligence server, you can use Heroku for quick deployment:
### Quick Deploy to Heroku
1. Click "Deploy to Heroku" button
[](https://heroku.com/deploy?template=https://github.com/firetix/vulnerability-intelligence-mcp-server)
2. After deployment, your instance will be available at:
- `https://<your-app-name>.herokuapp.com/sse`
3. Configure your MCP client to use your deployed instance:
- For Claude Desktop: Update the `FETCH_URL` in your configuration
- For Cursor IDE: Update the URL in your MCP settings
4. Test your deployment with the same example queries:
- **CVE Lookup**: "Look up CVE-2021-44228"
- **EPSS Score**: "Get EPSS score for CVE-2021-44228"
- **Package Check**: "Check the 'requests' Python package for vulnerabilities"
- **Exploit Check**: "Check for exploits for CVE-2021-44228"
## 📊 Data Sources & APIs
- **CVE Data**: [NIST National Vulnerability Database](https://nvd.nist.gov/) (NVD API 2.0)
- **EPSS Scores**: [FIRST EPSS API](https://www.first.org/epss/) (Exploit Prediction Scoring System)
- **CVSS Calculations**: CVSS v3.0/v3.1 specification compliance
- **Vulnerability Search**: Multiple CVE and vulnerability databases
- **Exploit Intelligence**: ExploitDB, Metasploit, GitHub security advisories
- **Package Vulnerabilities**: [OSV (Open Source Vulnerabilities)](https://osv.dev/)
- **Package Metadata**: [PyPI (Python Package Index)](https://pypi.org/)
- **VEX Data**: Vendor VEX statements and product security advisories
## 🤝 Security Use Cases
This MCP server is designed for security engineers, developers, and teams who need:
### Vulnerability Research & Intelligence
- Quick CVE lookups with comprehensive details
- CVSS and EPSS scoring for accurate risk assessment
- Advanced vulnerability search across multiple databases
- Exploit availability and threat intelligence gathering
- Timeline analysis for understanding vulnerability lifecycle
### Risk Assessment & Prioritization
- EPSS-based exploitation probability scoring
- CVSS vector calculation and validation
- VEX status checking for product-specific impact
- Multi-factor risk analysis combining multiple data sources
### Dependency Management
- Python package security auditing
- Version-specific vulnerability checking
- Supply chain security assessment
- Open source component risk evaluation
### Security Operations & Incident Response
- Rapid vulnerability triage and classification
- Exploit availability assessment for threat modeling
- Security advisory research and correlation
- Timeline-based patch management planning
## 🔄 Extending the Server
The modular architecture makes it easy to add new security tools:
1. Create a new module in `mcp_simple_tool/tools/`
2. Export the function in `tools/__init__.py`
3. Register the tool in `server.py`
4. Add tests in `tests/`
See [README_MODULAR.md](README_MODULAR.md) for detailed extension guide.
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
