# Kali MCP Server

A production-quality MCP (Model Context Protocol) server that exposes 20+ Kali Linux security tools through an AI-friendly interface, enabling AI assistants to perform penetration testing and security assessments in a controlled, structured manner.

## ⚠️ LEGAL NOTICE

**This tool is intended for AUTHORIZED security testing only.**

- You MUST have explicit written permission to test any systems
- Unauthorized access to computer systems is ILLEGAL
- Users are responsible for ensuring proper authorization
- The authors assume NO LIABILITY for misuse of this tool

By using this tool, you acknowledge that you have proper authorization and accept full responsibility for your actions.

## Features

- **20+ Security Tools** across multiple categories
- **Type-safe** using TypeScript and Zod validation
- **Safe execution** with command allowlists, timeouts, and output limits
- **Input validation** to prevent command injection
- **Rate limiting** to prevent abuse
- **Structured output** with proper error handling
- **MCP-compliant** for seamless AI integration

## Supported Tools

### Network Tools (6)
- **nmap** - Network port scanning and service detection
- **nmap discover** - Host discovery on networks
- **masscan** - High-speed port scanner
- **netdiscover** - ARP reconnaissance
- **tcpdump** - Packet capture
- **tshark** - Wireshark CLI for packet analysis

### Web Security Tools (7)
- **gobuster dir** - Directory/file enumeration
- **gobuster dns** - Subdomain enumeration
- **sqlmap** - SQL injection testing
- **nikto** - Web server scanner
- **wpscan** - WordPress security scanner
- **ffuf** - Web fuzzer
- **nuclei** - Template-based vulnerability scanner

### Password Tools (3)
- **hydra** - Network login brute-forcer
- **john** - John the Ripper password cracker
- **hashcat** - Advanced password recovery

### Exploitation Tools (3)
- **searchsploit** - Exploit database search
- **searchsploit examine** - View exploit details
- **msfvenom** - Metasploit payload generator

## Installation

### Prerequisites

1. **Kali Linux** (or any Linux distribution with security tools installed)
2. **Node.js** 18+ and npm
3. **Security tools** installed on your system

### Install Security Tools (Kali Linux)

```bash
sudo apt update
sudo apt install -y \
  nmap masscan netdiscover tcpdump tshark \
  gobuster sqlmap nikto wpscan ffuf nuclei \
  hydra john hashcat \
  exploitdb metasploit-framework
```

### Install MCP Server

```bash
cd kali-mcp-server
npm install
npm run build
```

## Usage

### Running the Server

```bash
# Start the server
npm start

# Or run directly
node dist/index.js
```

### Testing with MCP Inspector

```bash
# Launch the MCP Inspector for interactive testing
npm run inspector

# Or
npx @modelcontextprotocol/inspector node dist/index.js
```

### Integrating with Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "kali-security": {
      "command": "node",
      "args": ["/path/to/kali-mcp-server/dist/index.js"]
    }
  }
}
```

## Tool Reference

### Network Tools

#### kali_network_nmap_scan

Perform network port scanning using Nmap.

**Example:**
```json
{
  "target": "192.168.1.1",
  "ports": "22,80,443",
  "scan_type": "tcp_syn",
  "timing": "normal",
  "service_version": true
}
```

**Parameters:**
- `target` (required): IP, hostname, or CIDR range
- `ports` (optional): Port specification (default: top 1000)
- `scan_type`: tcp_syn, tcp_connect, udp, ack, null, fin, xmas
- `timing`: paranoid, sneaky, polite, normal, aggressive, insane
- `os_detection`: Enable OS detection (requires root)
- `service_version`: Probe for service versions
- `script_scan`: NSE scripts to run
- `aggressive`: Enable aggressive scan
- `timeout`: Timeout in seconds (default: 300)

#### kali_network_nmap_discover

Discover live hosts on a network.

**Example:**
```json
{
  "network": "192.168.1.0/24",
  "method": "ping",
  "timeout": 120
}
```

### Web Tools

#### kali_web_gobuster_dir

Enumerate directories and files on web servers.

**Example:**
```json
{
  "url": "https://example.com",
  "wordlist": "/usr/share/wordlists/dirb/common.txt",
  "extensions": "php,html,txt",
  "threads": 10
}
```

#### kali_web_sqlmap_test

Automated SQL injection testing.

**Example:**
```json
{
  "url": "https://example.com/page?id=1",
  "level": 1,
  "risk": 1,
  "batch": true
}
```

**WARNING:** Only use on systems you have authorization to test.

### Password Tools

#### kali_password_hydra_brute

Fast network login brute-forcer.

**Example:**
```json
{
  "target": "192.168.1.1",
  "service": "ssh",
  "username": "admin",
  "password_list": "/usr/share/wordlists/rockyou.txt",
  "threads": 16
}
```

**WARNING:** Only use on systems you have authorization to test.

### Exploitation Tools

#### kali_exploit_searchsploit_search

Search the Exploit Database.

**Example:**
```json
{
  "query": "apache 2.4",
  "platform": "linux"
}
```

Or search by CVE:
```json
{
  "cve": "CVE-2021-44228"
}
```

#### kali_exploit_msfvenom_generate

Generate custom payloads.

**Example:**
```json
{
  "payload": "linux/x64/shell_reverse_tcp",
  "lhost": "192.168.1.100",
  "lport": 4444,
  "format": "elf"
}
```

## Security Features

### Command Allowlist

Only pre-approved commands can be executed. The server maintains a strict allowlist of permitted security tools.

### Input Validation

All inputs are validated before execution:
- IP addresses and CIDR ranges
- Hostnames and URLs
- Port numbers and ranges
- File paths (no directory traversal)
- No shell metacharacters

### Output Sanitization

Sensitive information is automatically redacted from output:
- Passwords
- API keys
- Tokens
- Secrets

### Execution Limits

- **Timeouts**: Configurable per tool (default: 5 minutes)
- **Output size**: Maximum 10MB per command
- **Rate limiting**: 10 commands per minute, 100 per hour

### Process Isolation

All commands are executed in isolated child processes with:
- Separate stdout/stderr capture
- Graceful timeout handling
- Resource cleanup

## Configuration

### Environment Variables

Customize tool paths using environment variables:

```bash
export NMAP_PATH=/usr/bin/nmap
export GOBUSTER_PATH=/usr/bin/gobuster
export SQLMAP_PATH=/usr/bin/sqlmap
# ... etc
```

### Wordlist Paths

Default wordlists (Kali Linux):
- `/usr/share/wordlists/rockyou.txt`
- `/usr/share/wordlists/dirb/common.txt`
- `/usr/share/seclists/Discovery/Web-Content/common.txt`

## Error Handling

The server provides detailed, actionable error messages:

```
❌ Command failed: nmap -sS 192.168.1.1

🔢 Exit code: 1

📋 Error output:
You requested a scan type which requires root privileges.

Possible causes:
- TCP SYN scan requires root/sudo
- Try using scan_type="tcp_connect" instead
- Run the server with sudo (not recommended)

Suggested actions:
1. Use tcp_connect scan type (doesn't require root)
2. Grant CAP_NET_RAW capability to nmap
3. Check permissions and try again
```

## Troubleshooting

### Tools Not Found

If tools are not in your PATH:

```bash
# Check if tool is installed
which nmap

# Install missing tools
sudo apt install nmap

# Or set custom path
export NMAP_PATH=/custom/path/to/nmap
```

### Permission Errors

Some tools require root privileges:
- nmap TCP SYN scan (-sS)
- masscan
- tcpdump/tshark
- netdiscover

**Solutions:**
1. Use non-privileged alternatives (e.g., nmap TCP connect scan)
2. Grant specific capabilities: `sudo setcap cap_net_raw+ep /usr/bin/nmap`
3. Run server with sudo (not recommended for security reasons)

### Timeout Issues

If scans are timing out:

```json
{
  "target": "192.168.1.1",
  "ports": "1-65535",
  "timeout": 1800  // Increase to 30 minutes
}
```

## Development

### Project Structure

```
kali-mcp-server/
├── src/
│   ├── index.ts           # Main server
│   ├── types.ts           # Type definitions
│   ├── constants.ts       # Configuration
│   ├── utils/
│   │   ├── executor.ts    # Command execution
│   │   ├── validator.ts   # Input validation
│   │   ├── formatter.ts   # Output formatting
│   │   └── parser.ts      # Output parsing
│   ├── tools/
│   │   ├── network.ts     # Network tool handlers
│   │   ├── web.ts         # Web tool handlers
│   │   ├── password.ts    # Password tool handlers
│   │   └── exploit.ts     # Exploit tool handlers
│   └── schemas/
│       ├── network.schemas.ts
│       ├── web.schemas.ts
│       ├── password.schemas.ts
│       └── exploit.schemas.ts
└── dist/                  # Compiled output
```

### Adding New Tools

1. Define Zod schema in `src/schemas/[category].schemas.ts`
2. Implement tool handler in `src/tools/[category].ts`
3. Register tool in `src/index.ts`
4. Add to `ALLOWED_COMMANDS` in `src/constants.ts`

**Example:**

```typescript
// 1. Schema
export const MyToolSchema = z.object({
  target: z.string().describe("Target to scan"),
  option: z.boolean().default(false),
});

// 2. Handler
export async function myTool(input: MyToolInput): Promise<ToolResult> {
  const args = [input.target];
  if (input.option) args.push("--option");

  const result = await executeCommand("mytool", args);
  return formatExecutionResult(result);
}

// 3. Register in index.ts
{
  name: "kali_category_mytool_action",
  description: "Description of what it does",
  inputSchema: zodToJsonSchema(MyToolSchema),
}

// 4. Add to ALLOWED_COMMANDS
export const ALLOWED_COMMANDS = new Set([
  // ... existing commands
  "mytool",
]);
```

### Running Tests

```bash
npm run build
npm start
```

Test with MCP Inspector:
```bash
npm run inspector
```

## Common Workflows

### 1. Network Reconnaissance

```
1. Discover hosts: kali_network_nmap_discover
2. Port scan: kali_network_nmap_scan
3. Service detection: kali_network_nmap_scan with service_version=true
4. Vulnerability scan: kali_network_nmap_scan with script_scan="vuln"
```

### 2. Web Application Testing

```
1. Directory enumeration: kali_web_gobuster_dir
2. Subdomain discovery: kali_web_gobuster_dns
3. Vulnerability scanning: kali_web_nikto_scan
4. SQL injection testing: kali_web_sqlmap_test
```

### 3. Password Assessment

```
1. Network brute force: kali_password_hydra_brute
2. Hash identification: Manual analysis
3. Hash cracking: kali_password_john_crack or kali_password_hashcat_crack
```

### 4. Exploit Research

```
1. Search exploits: kali_exploit_searchsploit_search
2. Examine exploit: kali_exploit_searchsploit_examine
3. Generate payload: kali_exploit_msfvenom_generate
```

## Performance Tips

1. **Use appropriate timing**: Balance speed vs stealth
2. **Limit port ranges**: Scan only necessary ports
3. **Use wordlists wisely**: Smaller wordlists for faster results
4. **Adjust threads**: More threads = faster, but more resource-intensive
5. **Set realistic timeouts**: Complex scans need more time

## Contributing

Contributions are welcome! Please ensure:
- All inputs are validated
- Commands are in the allowlist
- Error messages are actionable
- Documentation is updated
- Security best practices are followed

## License

MIT License - See LICENSE file for details

## Acknowledgments

- Kali Linux team for the excellent security distribution
- Anthropic for the Model Context Protocol
- Security tool authors: nmap, gobuster, sqlmap, hydra, john, hashcat, and many more

## Disclaimer

This tool is provided for educational and authorized security testing purposes only. The authors are not responsible for any misuse or damage caused by this tool. Always ensure you have proper authorization before testing any systems.

---

**Version:** 1.0.0
**Last Updated:** 2025-11-29