pentest-mcp-server

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

# 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

cd pentest-mcp-server
pip install -e .

Configure with Claude Desktop

Add to your claude_desktop_config.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

# 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

# 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

# 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.