baguskto/mcp-pentest

MCP Pentest Server

A comprehensive Model Context Protocol (MCP) server for penetration testing with educational guidance. Designed to make professional security testing accessible to beginners while providing powerful capabilities for experienced pentesters.

⚠️ LEGAL DISCLAIMER

AUTHORIZED USE ONLY

This tool is for authorized security testing purposes only. Unauthorized use may violate:

• Computer Fraud and Abuse Act (CFAA) - United States
• UK Computer Misuse Act - United Kingdom
• Similar laws in other jurisdictions

ALWAYS obtain written permission before testing any target.

Features

Comprehensive Coverage

• Web Application Testing: Nmap, Nikto, Gobuster, SQLMap, WPScan, SSLScan
• Mobile App Testing: JADX (APK decompilation), APKTool, MobSF, Frida/Objection
• Network Testing: Port scanning, service detection, network mapping
• Professional Reporting: Markdown, PDF, and JSON formats

Educational Approach

• Maximum Guidance: Each finding includes explanations of what it is, why it's dangerous, and how to fix it
• OWASP References: Direct links to OWASP testing guides and remediation resources
• CWE Mappings: Common Weakness Enumeration references for each vulnerability
• Step-by-Step Remediation: Detailed fix instructions for beginners

Security Features

• Authorization System: Token-based access control with audit logging
• Rate Limiting: Prevents abuse and manages concurrent scans
• Input Validation: Comprehensive validation to prevent command injection
• Audit Logging: Complete logging of all pentesting activities

Installation

Prerequisites

# Node.js 18+ required
node --version

# Install required pentesting tools
# macOS (using Homebrew)
brew install nmap nikto gobuster sqlmap

# Ubuntu/Debian
sudo apt-get install nmap nikto gobuster sqlmap

# For APK analysis
brew install jadx  # macOS
# or download from https://github.com/skylot/jadx

Install MCP Server

cd mcp-pentest
npm install
npm run build

Configure with Claude Code

Add to your Claude Code MCP settings (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Quick Start

1. Generate Authorization Token

# Generate a sample authorization token (64 characters)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

2. Basic Web Scan

In Claude Code:

Use the nmap_scan tool to scan example.com ports 80,443
Target: example.com
Ports: 80,443
Auth Token: [your-64-char-token]

3. Run Workflow Scan

Use the quick_web_scan workflow to scan my website
Target: https://yourtestsite.com
Auth Token: [your-token]

4. Generate Report

Use generate_report to create a PDF report from my scan results
Format: pdf

Available Tools

Network Scanning

nmap_scan

Performs network reconnaissance and service detection.

Parameters:

• target (required): IP address, domain, or URL
• ports (optional): Port specification (e.g., "80,443" or "1-1000")
• scanType (optional): "quick", "standard", "thorough", or "stealth"
• authToken (required): Authorization token

Example:

{
  "target": "192.168.1.1",
  "ports": "1-10000",
  "scanType": "standard",
  "authToken": "your-token-here"
}

Web Application Scanning

nikto_scan

Scans web servers for known vulnerabilities and misconfigurations.

Parameters:

• target (required): URL of web server
• port (optional): Port number (default: 80/443)
• ssl (optional): Use SSL/TLS
• authToken (required): Authorization token

gobuster_scan

Brute-force directories and files on web servers.

Parameters:

• target (required): Base URL
• wordlist (optional): Path to wordlist file
• extensions (optional): File extensions to check
• authToken (required): Authorization token

sqlmap_scan

Tests for SQL injection vulnerabilities.

Parameters:

• target (required): Target URL
• data (optional): POST data
• cookie (optional): Cookie header
• level (optional): Test level (1-5)
• risk (optional): Risk level (1-3)
• authToken (required): Authorization token

Mobile Application Analysis

jadx_decompile

Decompiles Android APK files to readable Java source code.

Parameters:

• target (required): Path to APK file
• outputDir (optional): Output directory
• deobfuscate (optional): Attempt to deobfuscate code
• authToken (required): Authorization token

Workflow Scans

quick_web_scan

Fast reconnaissance scan (nmap + nikto).

standard_web_scan

Balanced scan (nmap + nikto + gobuster + basic sqlmap).

thorough_web_scan

Comprehensive scan (all web tools with aggressive settings).

Reporting

generate_report

Generates professional security reports.

Parameters:

• format: "markdown", "pdf", or "json"
• type: "executive", "technical", or "detailed"
• scanResults: Array of scan result IDs

Educational Features

Every vulnerability finding includes:

What Is It?

Plain English explanation of the vulnerability suitable for beginners.

Why Is It Dangerous?

Real-world impact and risks explained clearly.

How To Fix It

Step-by-step remediation instructions with code examples.

References

• OWASP Testing Guide links
• CWE (Common Weakness Enumeration) references
• Additional learning resources

Example Output

## Finding: SQL Injection in Login Form

**Severity**: Critical (CVSS: 9.8)
**Category**: WSTG-INPV-05 (SQL Injection)
**CWE**: CWE-89

### What Is It?
SQL Injection is a code injection technique that exploits security
vulnerabilities in an application's database layer. Attackers can
insert malicious SQL statements into application queries...

### Why It's Dangerous
- Unauthorized access to sensitive data
- Complete database compromise
- Possible remote code execution
- Data exfiltration and manipulation

### How To Fix It
1. **Use Prepared Statements** (Most Important)
   ```sql
   PreparedStatement stmt = connection.prepareStatement(
     "SELECT * FROM users WHERE username = ? AND password = ?"
   );
   stmt.setString(1, username);
   stmt.setString(2, password);

2. Use ORM frameworks with built-in protection
3. Implement input validation
4. Apply least privilege to database accounts

References

• https://owasp.org/www-community/attacks/SQL_Injection
• https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html

## Security Considerations

### Authorization System

The MCP server requires authorization tokens for all scanning operations. To add a permanent authorization:

```typescript
import { authManager } from './src/utils/auth-manager.js';

authManager.addAuthorization('your-token', {
  target: '*.example.com',
  grantedBy: 'Security Team',
  grantedAt: new Date(),
  expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
  tools: ['nmap_scan', 'nikto_scan'], // Specific tools allowed
  notes: 'Q4 2024 security assessment'
});

Rate Limiting

Different tool categories have different rate limits:

• Network scans: 1 concurrent, max 5/minute
• Web scans: 2 concurrent, max 10/minute
• Mobile analysis: 3 concurrent, max 20/minute
• Workflows: 1 concurrent, max 3/minute

Audit Logging

All activities are logged to ./logs/audit-YYYY-MM-DD.log:

2024-11-17T10:30:45.123Z [SCAN_INITIATED] | Tool: nmap | Target: example.com | Success: true
2024-11-17T10:32:10.456Z [SCAN_COMPLETED] | Tool: nmap | Target: example.com | Duration: 85333ms | Details: 15 findings

Development

Project Structure

mcp-pentest/
├── src/
│   ├── index.ts                 # MCP server entry point
│   ├── server.ts                # Main server class
│   ├── tools/                   # Tool implementations
│   │   ├── web/                 # Web testing tools
│   │   ├── mobile/              # Mobile testing tools
│   │   ├── network/             # Network testing tools
│   │   └── reporting/           # Report generation
│   ├── utils/                   # Utilities
│   │   ├── command-executor.ts  # Safe command execution
│   │   ├── input-validator.ts   # Input validation
│   │   ├── output-parser.ts     # Tool output parsing
│   │   ├── auth-manager.ts      # Authorization
│   │   ├── audit-logger.ts      # Audit logging
│   │   └── rate-limiter.ts      # Rate limiting
│   ├── services/                # Business logic
│   │   └── vulnerability-knowledge-base.ts
│   ├── types/                   # TypeScript types
│   │   ├── findings.ts
│   │   ├── tools.ts
│   │   └── reports.ts
│   └── templates/               # Report templates
├── config/                      # Configuration files
├── logs/                        # Audit logs
├── package.json
├── tsconfig.json
└── README.md

Adding New Tools

1. Create a new tool class implementing BaseTool interface
2. Add command execution logic using CommandExecutor
3. Validate inputs using InputValidator
4. Parse outputs using OutputParser
5. Register the tool in main server
6. Add educational content from knowledge base

Example:

import { BaseTool } from '../types/tools.js';
import { CommandExecutor } from '../utils/command-executor.js';

export class MyTool implements BaseTool {
  name = 'my_tool';
  description = 'Does something useful';
  category = 'web' as const;

  async execute(args: any) {
    // Validate inputs
    // Execute tool
    // Parse output
    // Return structured result
  }
}

Troubleshooting

Tool Not Found

Error: Failed to spawn process: ENOENT

Solution: Install the required tool:

brew install nmap  # or appropriate tool
which nmap  # verify installation

Authorization Failed

Error: Authorization token required

Solution: Provide a valid authorization token (minimum 32 characters).

Rate Limit Exceeded

Error: Rate limit exceeded. Maximum 10 operations per minute.

Solution: Wait for the rate limit window to clear or adjust rate limits in code.

Best Practices

1. Always Get Written Permission: Never scan targets without explicit authorization
2. Start with Quick Scans: Use quick scans first, then escalate if needed
3. Respect Rate Limits: Don't bypass rate limiting - it protects both you and targets
4. Review Findings Carefully: Not all findings are true positives - verify manually
5. Document Everything: Use the reporting features to document all findings
6. Stay Within Scope: Only test what's authorized in your engagement

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all TypeScript types are correct
5. Update documentation
6. Submit a pull request

License

MIT License - See LICENSE file for details

Support

• Issues: https://github.com/baguskto/mcp-pentest/issues
• Documentation: https://github.com/baguskto/mcp-pentest/wiki
• MCP SDK: https://modelcontextprotocol.io

Acknowledgments

• OWASP for security testing guidelines
• MCP SDK team for the excellent protocol
• Security community for tool development
• Claude Code for the amazing IDE

Remember: With great power comes great responsibility. Use this tool ethically and legally.