MCP Pentest

🚀 MCP Pentest - Automated Penetration Testing Framework

MCP (Model Context Protocol) server for intelligent automated penetration testing. This framework can automatically perform reconnaissance, vulnerability scanning, and controlled exploitation based on the detected target technologies.

🚀 Features

🔍 Reconnaissance Tools

• Port Scanning - Comprehensive Nmap integration with various scan modes
• Subdomain Enumeration - Certificate transparency logs + DNS bruteforcing
• Technology Detection - Automatic web technology fingerprinting
• Directory Bruteforcing - Intelligent directory and file discovery

🛡️ Vulnerability Assessment

• Nuclei Integration - Automated vulnerability scanning with a template database
• Nikto Scanning - Web server vulnerability detection
• SQLMap Integration - SQL injection testing
• Custom Web Vulnerability Checks - XSS, Directory Traversal, Command Injection, etc.

⚡ Exploitation Modules

• Metasploit Integration - Automatic exploit search and execution
• Custom Exploit Attempts - Framework-specific exploitation
• Technology-Specific Exploits - Targeted attacks based on the tech stack
• Proof-of-Concept Generation - Automated PoC creation

🤖 Intelligent Workflow Engine

• Adaptive Decision Making - AI-driven next step recommendations
• Risk-Based Prioritization - Smart vulnerability prioritization
• Technology-Aware Testing - Customized testing based on detected technologies
• Automated Workflow Management - Sequential phase execution with dependency handling

📊 Comprehensive Reporting

• Multi-Format Reports - HTML, PDF, JSON, Markdown output
• Executive Summaries - Business-friendly risk assessments
• Technical Details - Detailed vulnerability descriptions and remediation
• Evidence Collection - Automatic proof collection and documentation

📋 Prerequisites

Required Tools

Make sure the following tools are installed on your system:

# Network scanning
sudo apt install nmap

# Web vulnerability scanning
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest

# Web server scanning
sudo apt install nikto

# SQL injection testing
sudo apt install sqlmap

# Optional: Metasploit (for advanced exploitation)
curl https://raw.githubusercontent.com/rapid7/metasploit-omnibus/master/config/templates/metasploit-framework-wrappers/msfupdate.erb > msfinstall
chmod 755 msfinstall
sudo ./msfinstall

Node.js Dependencies

npm install

📦 Installation

1. Clone the repository

git clone <repository-url>
cd mcp-pentest

2. Install dependencies

npm install

3. Build the project

npm run build

4. Configure the MCP client Add the following to your MCP client configuration file:

{
  "mcpServers": {
    "pentest": {
      "command": "node",
      "args": ["path/to/mcp-pentest/dist/index.js"],
      "env": {}
    }
  }
}

💻 Usage Examples

Basic Automated Pentest

// Full scope automated pentest
await mcp.call("auto_pentest", {
  target: "example.com",
  scope: "full",
  intensity: "active"
});

Reconnaissance Only

// Port scanning
await mcp.call("nmap_scan", {
  target: "192.168.1.1",
  scan_type: "aggressive"
});

// Technology detection
await mcp.call("tech_detection", {
  url: "https://example.com"
});

// Subdomain enumeration
await mcp.call("subdomain_enum", {
  domain: "example.com"
});

Vulnerability Scanning

// Nuclei scan with specific templates
await mcp.call("nuclei_scan", {
  target: "https://example.com",
  templates: ["cves", "vulnerabilities"],
  severity: "high"
});

// SQL injection testing
await mcp.call("sqlmap_scan", {
  url: "https://example.com/login.php",
  data: "username=admin&password=test"
});

Exploitation Attempts

// Search for Metasploit modules
await mcp.call("metasploit_search", {
  service: "Apache 2.4.41",
  platform: "linux"
});

// Attempt exploitation
await mcp.call("exploit_attempt", {
  target: "192.168.1.100",
  vulnerability: "SQL Injection",
  payload: "UNION SELECT"
});

Intelligent Next Steps

// Get AI-powered recommendations
await mcp.call("suggest_next_steps", {
  scan_results: JSON.stringify(previousResults)
});

Report Generation

// Generate a comprehensive report
await mcp.call("generate_report", {
  target: "example.com",
  format: "html"
});

🔧 Technical Details

Scan Intensity Levels

Passive

• Certificate transparency logs
• DNS enumeration
• Header analysis
• Public information gathering

Active

• Port scanning
• Directory bruteforcing
• Vulnerability scanning
• Service enumeration

Aggressive

• Full port range scanning
• Intensive directory bruteforcing
• Active exploitation attempts
• Comprehensive vulnerability testing

Scope Options

Network

• Port scanning
• Service enumeration
• Network vulnerability assessment

Web

• Web application testing
• Technology fingerprinting
• Web vulnerability scanning

Full

• Comprehensive assessment
• Network + Web testing
• Complete attack surface analysis

🛡️ Security Considerations

Ethical Usage

⚠️ Important Note

This framework should only be used for:

• Authorized penetration testing
• Security research with permission
• Testing on your own systems
• Educational purposes

Safety Features

• Rate limiting - Automatic request throttling
• Timeout controls - Prevent long-running scans
• Scope validation - Target validation and restriction
• Safe exploitation - Controlled and reversible tests

Legal Compliance

• Ensure you have written authorization before testing
• Comply with local laws and regulations
• Respect responsible disclosure practices
• Document all testing activities

📊 Sample Output

Automated Pentest Results

{
  "workflow": {
    "target": "example.com",
    "scope": "full",
    "phases": [
      {
        "name": "reconnaissance",
        "status": "completed",
        "tools": ["nmap_scan", "subdomain_enum", "tech_detection"]
      }
    ],
    "results": {
      "reconnaissance": {
        "open_ports": [
          {"port": 80, "service": "http", "version": "Apache 2.4.41"},
          {"port": 443, "service": "https", "version": "Apache 2.4.41"}
        ],
        "technologies": [
          {"technology": "WordPress", "version": "5.8", "confidence": 95}
        ]
      },
      "vulnerabilities": [
        {
          "name": "Outdated WordPress",
          "severity": "medium",
          "description": "WordPress version 5.8 has known vulnerabilities"
        }
      ],
      "risk_score": 65,
      "threat_level": "medium"
    }
  }
}

🔄 Workflow Engine

The framework uses an intelligent workflow engine that can:

1. Analyze scan results - Automatically interpret findings
2. Make decisions - Determine next testing steps
3. Adapt strategy - Modify approach based on discoveries
4. Prioritize actions - Focus on high-impact vulnerabilities
5. Generate insights - Provide actionable recommendations

Decision Making Logic

Reconnaissance → Technology Detection → Vulnerability Assessment → Risk Analysis → Exploitation → Reporting
     ↓              ↓                    ↓                    ↓             ↓            ↓
 Port Discovery → CMS/Framework → Targeted Scanning → Priority Queue → Controlled → Evidence
 Subdomain Enum → Version Info → Custom Checks → Risk Scoring → Attempts → Collection

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │    │  MCP Protocol    │    │  Pentest Server │
│  (Claude/etc)   │◄──►│   Transport      │◄──►│    (Node.js)    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                                        │
                                               ┌─────────────────┐
                                               │ Tool Integration │
                                               │   - Nmap        │
                                               │   - Nuclei      │
                                               │   - Nikto       │
                                               │   - SQLMap      │
                                               │   - Metasploit  │
                                               └─────────────────┘

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Implement changes with tests
4. Submit a pull request
5. Follow security best practices

📄 License

MIT License - See the LICENSE file for details

⚠️ Disclaimer

This tool is created for educational and authorized security testing purposes. The user is responsible for ensuring legal and ethical use. The developer is not responsible for misuse of this tool.

🆘 Support

• 📖 Documentation: Wiki
• 🐛 Bug Reports: Issues
• 💬 Discussions: Forum
• 📧 Contact: Email