# Penetration Testing MCP Server v2.0

A comprehensive MCP (Model Context Protocol) server for authorized penetration testing and security assessments, now with **CVE Monitoring** and **Nuclei Integration**.

## ⚠️ IMPORTANT LEGAL NOTICE

**This tool is designed EXCLUSIVELY for authorized security testing.**

Users MUST:
- Have explicit written permission from the system owner
- Comply with all applicable laws and regulations
- Use only for defensive security purposes
- Not use for malicious purposes or unauthorized access

**Unauthorized use may violate computer crime laws and result in severe penalties.**

---

## 🆕 Version 2.0 Features

### CVE Monitoring
- **Real-time CVE Fetching** - Get latest CVEs from NVD database
- **CVE Search** - Search CVEs by keyword
- **Detailed CVE Information** - CVSS scores, affected products, descriptions
- **Local Vulnerability Database** - Store and search CVEs locally

### Nuclei Integration
- **Automated Vulnerability Scanning** - Use nuclei templates for scanning
- **Template Management** - Update and search nuclei templates
- **Severity-based Filtering** - Scan by severity level
- **Template Discovery** - Find templates for specific CVEs

---

## Features

### Phase 1: Reconnaissance (Passive)
- `whois_lookup` - Domain WHOIS information
- `dns_enum` - DNS record enumeration
- `subdomain_enum` - Subdomain discovery
- `osint_search` - Open Source Intelligence gathering

### Phase 2: Scanning (Active)
- `port_scan` - TCP/UDP port scanning
- `service_detection` - Service version detection
- `vuln_scan` - Vulnerability scanning

### Phase 3: Enumeration
- `web_enum` - Web directory/file enumeration
- `smb_enum` - SMB share enumeration
- `ldap_enum` - LDAP directory enumeration

### Phase 4: Vulnerability Analysis
- `ssl_analyze` - SSL/TLS configuration analysis
- `web_vuln_check` - OWASP Top 10 checks
- `cve_lookup` - CVE database lookup
- **NEW** `fetch_recent_cves` - Fetch recent CVEs from NVD
- **NEW** `search_cve` - Search CVEs by keyword
- **NEW** `get_cve_exploit_info` - Get detailed exploit info

### Phase 5: Exploitation (Safe/Limited)
- `password_audit` - Password strength auditing
- `generate_payload` - Test payload generation

### Phase 6: Post-Exploitation (Safe/Limited)
- `privilege_check` - Privilege escalation vectors
- `persistence_check` - Persistence mechanisms

### Phase 7: Reporting
- `generate_report` - Penetration test report generation
- `risk_score` - Risk score calculation

### NEW: Nuclei Integration
- `nuclei_scan` - Run nuclei vulnerability scan
- `update_nuclei_templates` - Update nuclei templates
- `search_nuclei_templates` - Search nuclei templates
- `list_nuclei_templates` - List templates by severity
- `check_nuclei_status` - Check nuclei installation

### NEW: Vulnerability Database
- `add_cve_to_db` - Add CVE to local database
- `search_local_vuln_db` - Search local database

### Utility Tools
- `set_scope` - Define authorized testing scope
- `verify_authorization` - Verify target authorization

---

## Installation

### Prerequisites

```bash
# macOS
brew install nmap whois samba dnsutils python3 go

# Install nuclei
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest

# Download nuclei templates
nuclei -update-templates

# Ubuntu/Debian
sudo apt install nmap whois smbclient dnsutils python3 python3-pip golang-go

# Arch Linux
sudo pacman -S nmap whois samba dnsutils python3 go
```

### Install the MCP Server

```bash
cd pentest-mcp-server
pip install -e .
```

### Configure with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "pentest": {
      "command": "python",
      "args": ["-m", "pentest_mcp.server"]
    }
  }
}
```

---

## Usage

### 1. Set Authorized Scope First

```
Use set_scope to define your authorized targets:
- targets: ["example.com", "192.168.1.0/24"]
- engagement_id: "PENTEST-2024-001"
- tester_name: "Your Name"
```

### 2. Verify Authorization

Before testing any target, verify it's in scope:

```
verify_authorization(target="example.com")
```

### 3. CVE Monitoring Workflow

```bash
# Fetch recent critical CVEs
fetch_recent_cves(days=7, severity="critical")

# Search for specific CVEs
search_cve(keyword="log4j")

# Get detailed exploit information
get_cve_exploit_info(cve_id="CVE-2021-44228")

# Add CVE to local database
add_cve_to_db(cve_id="CVE-2021-44228")
```

### 4. Nuclei Scanning Workflow

```bash
# Check nuclei installation
check_nuclei_status()

# Update templates
update_nuclei_templates()

# Run vulnerability scan
nuclei_scan(target="https://example.com", severity="high")

# Search for templates
search_nuclei_templates(query="cve-2021")

# List critical templates
list_nuclei_templates(severity="critical")
```

### 5. Full Penetration Testing Workflow

```
# Reconnaissance
whois_lookup(domain="example.com")
dns_enum(domain="example.com")
subdomain_enum(domain="example.com")

# Scanning
port_scan(target="example.com", ports="1-1000")
service_detection(target="example.com")

# Enumeration
web_enum(url="https://example.com")

# Vulnerability Analysis
ssl_analyze(target="example.com:443")
nuclei_scan(target="https://example.com", severity="all")

# Reporting
generate_report(format="markdown", include_remediation=true)
```

---

## CVE Monitoring Details

### NVD API Integration

The server integrates with the National Vulnerability Database (NVD) API to:

- Fetch recent CVEs (last 7 days by default)
- Search CVEs by keyword
- Get detailed CVE information including:
  - CVSS v3.1 scores
  - Affected products (CPEs)
  - Severity ratings
  - Publication dates

### Local Vulnerability Database

Store frequently referenced CVEs locally for:

- Quick offline access
- Custom annotations
- Searchable repository

---

## Nuclei Integration Details

### Template Management

Nuclei templates are stored in `~/nuclei-templates/` and include:

- CVE templates
- Vulnerability classifications
- Severity ratings
- Technical details

### Scanning Capabilities

- HTTP-based vulnerability scanning
- DNS scanning
- SSL/TLS checks
- Headless browser scanning
- Custom template support

### Template Categories

- `cves/` - CVE-specific templates
- `vulnerabilities/` - Generic vulnerability templates
- `exposures/` - Information disclosure templates
- `misconfiguration/` - Security misconfiguration templates

---

## Security Features

### Authorization Enforcement
- All active tools require target authorization
- Scope must be defined before testing
- Clear error messages for unauthorized targets

### Safe Defaults
- Limited exploitation capabilities
- No destructive operations
- Audit logging of all actions

### Legal Compliance
- Clear warnings about legal requirements
- Engagement tracking
- Documentation support

---

## Example Output

### CVE Monitoring

```
🔍 Recent CVEs (Last 7 days)
Severity: critical
==================================================

📊 Found 15 CVEs:

🔴 CVE-2024-12345
   Score: 9.8 | Severity: CRITICAL
   Remote code execution in Apache HTTP Server...

🔴 CVE-2024-12346
   Score: 9.1 | Severity: CRITICAL
   SQL injection in popular CMS...
```

### Nuclei Scan

```
🔍 Nuclei Vulnerability Scan
Target: https://example.com
==================================================

🚀 Running nuclei scan...

🔴 Found 3 vulnerabilities:

🟠 CVE-2021-41773
   Template: cves/2021/CVE-2021-41773.yaml
   Severity: high
   Matched: https://example.com/cgi-bin/
```

---

## Troubleshooting

### Nuclei Not Found

```bash
# Install Go
brew install go  # macOS
sudo apt install golang-go  # Ubuntu

# Install nuclei
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest

# Add to PATH
export PATH=$PATH:$(go env GOPATH)/bin

# Download templates
nuclei -update-templates
```

### CVE API Errors

- Check internet connection
- NVD API has rate limits (wait and retry)
- For heavy usage, consider NVD API key

---

## Contributing

Contributions are welcome! Please ensure:
1. All code follows security best practices
2. No malicious capabilities are added
3. Documentation is updated
4. Tests are included

---

## License

MIT License - For authorized security testing only.

---

## Disclaimer

This tool is provided for educational and authorized security testing purposes only. The authors and contributors are not responsible for any misuse or illegal activities conducted with this software. Always obtain proper authorization before testing any systems.