npm package: @mseep/pentest-mcp
Description: NOT for educational use: An MCP server for Nmap and John the Ripper, for professional penetration testers.
Author: David Montgomery
Latest version: 0.2.0

*Currently this is being very finnicky about PATH issues, I have a working version stable on my end (npm prod version 0.2.7); if you are having any issues, please paste logs into Issues so I can tackle the problem ASAP*

# Pentest MCP: Professional Penetration Testing Toolkit

Pentest MCP is a Model Context Protocol server that integrates essential pentesting tools into a unified natural language interface. It allows security professionals to execute, chain, and analyze multiple tools through conversational commands.

## Comprehensive Toolkit for Professional Pentesters

This toolkit integrates four core penetration testing utilities under a single, intuitive interface:

- **Network Reconnaissance** with Nmap
- **Web Directory Enumeration** with Gobuster
- **Web Vulnerability Scanning** with Nikto
- **Password Cracking** with John the Ripper

## Key Benefits

- **Workflow Integration:** Chain tools together for comprehensive assessments
- **Natural Language Interface:** Run complex commands with simple English descriptions
- **Automated Reporting:** Generate client-ready findings with proper categorization
- **Time Efficiency:** Execute common pentesting sequences with minimal typing
- **Voice Control Compatible:** When paired with speech-to-text, allows hands-free operation
- **Context Awareness:** Tools understand previous scan results and can suggest logical next steps

## System Requirements

- **Platform:** Works on any OS, optimized for Kali Linux
- **Tools:** Requires Nmap, John the Ripper, Gobuster, and Nikto in your PATH
- **Node.js:** v16+ (for ESM support)
- **MCP Support:** A local MCP file server for handling log files (mcp-fileserver or equivalent)
- **Permissions:** Root/admin for privileged scans (SYN scan, OS detection)

## Installation

```bash
npm install -g pentest-mcp
```

## MCP Configuration

Add this to your MCP configuration file:

```json
{
  "servers": [
    {
      "name": "pentest-mcp",
      "command": "npx pentest-mcp -y"
    }
  ]
}
```

## Workflow Examples

### Network Discovery & Service Enumeration

```
Set the working mode to professional.
Scan the target 192.168.1.0/24 using a SYN scan technique with service detection.
```

### Web Application Testing

```
Use Gobuster to search for hidden directories on http://192.168.1.10 with the common.txt wordlist.
Run Nikto against the target http://192.168.1.10 to check for security issues.
```

### Multi-Tool Assessment Chain

```
Scan 10.0.1.0/24 for web servers.
For each web server found, use Gobuster to enumerate directories with the directory-list-2.3-medium.txt wordlist.
Then run Nikto against each web server to identify vulnerabilities.
Create a report for client "Acme Corp" summarizing all findings.
```

### Custom Password Cracking

```
Generate a wordlist from the target's company name "Acme", founder "Smith", and founding date "1984-06-12".

Crack these password hashes using the wordlist I just created:
admin:$1$xyz$anotherFakeHash
user:$1$abc$definitelyNotARealHash
```

### Analysis & Reporting

```
Create a report for client "Example Corp" titled "Q1 External Assessment" including all scans from today.
Summarize the findings from the scan of 10.0.0.5.
Suggest next steps for this assessment based on all tool results collected so far.
```

## Tool Details

### Nmap

The network mapper integration offers full support for:

- Port scanning (TCP SYN, TCP Connect, UDP) with custom port ranges
- Service and version detection with configurable intensity
- OS fingerprinting
- NSE script execution
- Custom timing templates and scan options

### Gobuster

Directory and file enumeration for web applications with options for:

- Multiple wordlists and file extension scanning
- Authentication options (basic auth, cookies)
- Customizable threading and status code filtering
- TLS configuration and redirect following

### Nikto

Web server vulnerability scanning with support for:

- Comprehensive vulnerability checks
- Authentication and proxy support
- Tunable scan options and timeout configuration
- Finding categorization by vulnerability type

### John the Ripper

Password cracking utility with enhanced features:

- Direct hash cracking with wordlists
- Integrated custom wordlist generation
- Pattern-based password creation
- Leetspeak and case variations

## Security Notice

**AUTHORIZED USE ONLY:** This toolkit is for professional penetration testers operating under a valid scope of work. Use only on systems and networks for which you have explicit, written authorization.

**OPERATIONAL SECURITY:**
- Use VPN for external scanning
- Run in isolated environments
- Monitor scan intensity on sensitive networks

**LEGAL COMPLIANCE:** Follow all applicable laws and client agreements

## Troubleshooting

- **Path Issues:** Ensure all tools are installed and in your PATH
- **Privilege Requirements:** SYN scans and OS detection require root/admin
- **Permission Errors:** Check that the server can write to `scan_logs` and `temp_wordlists`
- **MCP File Access:** Verify that mcp-fileserver (or equivalent) is configured correctly

## Contributing

This tool is built for professionals by professionals. Pull requests welcome at the [GitHub repository](https://github.com/dmontgomery40/pentest-mcp).