# chungus-kali-mcp

## IMPORTANT - Highly recommended to run this inside a Kali VM, not your base system.

A **Model Context Protocol (MCP)** server that gives AI agents (Cursor, Claude, Copilot, etc.) direct access to a Kali Linux penetration testing toolkit. The MCP server runs natively on your Kali VM as a single Node.js process — tool calls spawn CLI commands directly on the host. No Docker, no Flask, no HTTP middle layer.

[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-20+-green)](https://nodejs.org)
[![MCP Tools](https://img.shields.io/badge/MCP%20tools-155-green)]()
[![Platform](https://img.shields.io/badge/platform-Kali%20Linux-black)](https://www.kali.org)

Inspired by [zebbern-kali-mcp](https://github.com/zebbern/zebbern-kali-mcp). See [ATTRIBUTION.md](ATTRIBUTION.md).

---

## Architecture

Unlike the upstream Docker design (MCP client on host → HTTP → Flask in container), **chungus-kali-mcp** is a single-process server:

```
┌─────────────────────────────────────────────────────────────┐
│                     Kali Linux VM                           │
│                                                             │
│  AI Agent (Cursor / Claude / Copilot)                       │
│          │                                                  │
│          ▼  MCP (stdio)                                     │
│  chungus-kali-mcp  (Node.js)                                │
│          │                                                  │
│          ├── src/tools/        155 MCP tool handlers        │
│          ├── src/managers/     SSH, MSF, pivot, VPN, …      │
│          ├── src/runners/      kali-tools, forensics, js    │
│          ├── src/parsers/      output-parser                │
│          └── child_process / node-pty                       │
│                    │                                        │
│                    ▼                                        │
│  Kali CLI tools (nmap, sqlmap, impacket-*, netexec, …)      │
└─────────────────────────────────────────────────────────────┘
```

| Component | Location | Role |
|-----------|----------|------|
| **MCP server** | `src/index.ts` | Registers 155 tools, speaks MCP over stdio |
| **Tool handlers** | `src/tools/` | Zod-validated inputs → manager/runner calls |
| **Managers** | `src/managers/` | Stateful sessions (SSH, reverse shells, Metasploit, pivot, VPN, callback catcher, CTF) |
| **Runners** | `src/runners/` | Stateless CLI wrappers (kali-tools, forensics, js-analysis) |
| **Parsers** | `src/parsers/` | Structured output parsing (nmap XML, nuclei JSONL, gobuster text) |
| **Network init** | `src/lib/network-init.ts`, `scripts/kali-init.sh` | HTB routes, `/etc/hosts`, TUN, IP forwarding |

**Request flow:** AI Agent → MCP tool → Node handler → `spawn` / `node-pty` → Kali CLI → JSON result back.

---

## Quick Start

### 1. Install on Kali VM

```bash
git clone <your-repo-url>
cd chungus-kali-mcp
npm install
npm run build
```

Verify the server starts (it will wait on stdio for an MCP client):

```bash
node dist/index.js
# Ctrl+C to exit — normally Cursor/VS Code launches this for you
```

Optional: link the binary globally:

```bash
npm link
# then use command "chungus-kali-mcp" in MCP config
```

### 2. Add to Cursor / VS Code

Project config (`.cursor/mcp.json` or `.vscode/mcp.json`):

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

Or with `npm link`:

```json
{
  "mcpServers": {
    "chungus-kali-mcp": {
      "command": "chungus-kali-mcp"
    }
  }
}
```

Restart the editor — the agent can now call all 155 tools.

### 3. Docker parity setup (optional)

Stock [Kali packages](https://www.kali.org/tools/) cover most APT tools. To match the parent Docker image extras (Go tools, pip tools, `/opt` clones):

```bash
sudo ./scripts/kali-docker-parity.sh        # essentials
sudo ./scripts/kali-docker-parity.sh --full  # + PEAS, PetitPotam, krbrelayx, etc.
```

### 4. HTB / lab networking (optional)

```bash
export HTB_ROUTES=10.129.0.0/16,10.10.0.0/16
export EXTRA_HOSTS=target.htb:10.10.10.5
./scripts/kali-init.sh
```

Network init also runs automatically when the MCP server starts.

---

## MCP Tool Modules

19 modules, **155 tools** total. Full spec in [`TOOL_CATALOG.json`](TOOL_CATALOG.json).

| # | Module | Tools | Description |
|---|--------|------:|-------------|
| 1 | `kali_tools` | 35 | Nmap, Nikto, Gobuster, Dirb, SQLMap, Hydra, John, Nuclei, FFuf, Hashcat, Commix, Dalfox, WhatWeb, masscan, katana, amass, and more |
| 2 | `ad_tools` | 15 | Active Directory — netexec, BloodHound, impacket, Responder, evil-winrm, certipy, bloodyAD, coercion |
| 3 | `forensics_tools` | 6 | binwalk, steghide, exiftool, foremost, strings, Volatility3 |
| 4 | `js_analysis` | 6 | getJS, jsluice, xnLinkFinder, ParamSpider, TruffleHog, js-beautify |
| 5 | `command_exec` | 6 | `kali_exec`, streaming exec, health check, network info, interactive session I/O |
| 6 | `ssh_manager` | 8 | SSH session lifecycle — connect, execute, upload/download, transfer estimates |
| 7 | `reverse_shell` | 8 | Reverse shell listeners, commands, payload generation, file transfer |
| 8 | `metasploit` | 5 | Persistent `msfconsole` sessions via `node-pty` |
| 9 | `network_pivot` | 13 | Chisel, Ligolo-ng, SSH tunnels, socat, ProxyChains config |
| 10 | `vpn` | 3 | WireGuard & OpenVPN connect/disconnect/status |
| 11 | `api_security` | 11 | GraphQL, JWT, FFUF, Nuclei, rate-limit and auth-bypass tests |
| 12 | `web_fingerprinter` | 3 | URL (whatweb + fetch fallback), WAF, security headers |
| 13 | `exploit_suggester` | 5 | searchsploit search, nmap-based suggestions, exploit copy |
| 14 | `payload_generator` | 6 | msfvenom generation, HTTP hosting, one-liners |
| 15 | `file_operations` | 4 | Upload/download on Kali and target sessions (chunked + SHA256) |
| 16 | `callback_catcher` | 9 | Built-in HTTP + DNS callback listener for isolated networks |
| 17 | `ctf_platform` | 7 | CTFd API — challenges, flags, scoreboard |
| 18 | `hosts_management` | 4 | `/etc/hosts` management |
| 19 | `output_parser` | 1 | Structured parsing of nmap XML, nuclei JSONL, gobuster text |

### Renames from upstream

| Upstream | chungus-kali-mcp |
|----------|------------------|
| `zebbern_exec` | `kali_exec` |
| `KALI_API_URL` / Flask | *(removed — direct execution)* |
| `/app/tmp` | `~/.chungus-kali-mcp/tmp` |

---

## Expected Kali Tools

chungus-kali-mcp does **not** bundle tools — it expects a standard Kali install (or equivalent). Run `sudo ./scripts/kali-docker-parity.sh` for Docker-image parity. The `health` tool reports availability by category (network, web, dns, brute, ad, forensics, js, pivot, exploit).

### Network Scanning
| Tool | Description |
|------|-------------|
| **nmap** | Port scanning, service/version detection, NSE scripts |
| **masscan** | High-speed port scanner |
| **sslscan** | SSL/TLS configuration analysis |

### Web Application Scanning
| Tool | Description |
|------|-------------|
| **nikto** | Web server vulnerability scanner |
| **gobuster** | Directory/file/DNS brute-forcing |
| **dirb** | Web content scanner |
| **wpscan** | WordPress vulnerability scanner |
| **sqlmap** | Automated SQL injection |
| **ffuf** | Fast web fuzzer |
| **nuclei** | Template-based vulnerability scanner |
| **katana** | Web crawler |
| **amass** | Attack surface mapping |
| **commix** | Command injection exploitation |
| **ghauri** | Advanced SQL injection detection |
| **dalfox** | XSS scanning and exploitation |
| **byp4xx** | 403 Forbidden bypass |
| **whatweb** | Technology detection |

### Subdomain & DNS Enumeration
| Tool | Description |
|------|-------------|
| **subfinder** | Passive subdomain discovery |
| **httpx** | HTTP probing and technology detection |
| **assetfinder** | Subdomain discovery via various sources |
| **waybackurls** | URLs from the Wayback Machine |
| **fierce** | DNS reconnaissance |
| **subzy** | Subdomain takeover checking |
| **massdns** | High-performance DNS resolver |
| **mapcidr** | CIDR range manipulation |

### Brute Force & Password Cracking
| Tool | Description |
|------|-------------|
| **hydra** | Network login brute-forcer |
| **john** | John the Ripper password cracker |
| **hashcat** | GPU-accelerated hash cracking |

### Active Directory
| Tool | Description |
|------|-------------|
| **netexec** | SMB/LDAP/WinRM (replaces crackmapexec) |
| **impacket-*** | AD attack scripts (secretsdump, GetNPUsers, psexec, wmiexec, …) |
| **bloodhound-python** | AD relationship graphing |
| **certipy-ad** | ADCS exploitation |
| **bloodyAD** | AD privilege escalation |
| **responder** | LLMNR/NBT-NS poisoner |
| **evil-winrm** | WinRM shell with upload/download |
| **coercer** / **petitpotam** | Authentication coercion |
| **ldapdomaindump** | LDAP domain information |

### JavaScript Analysis
| Tool | Description |
|------|-------------|
| **getJS** | Extract JavaScript files from pages |
| **jsluice** | Extract URLs, paths, and secrets from JS |
| **xnLinkFinder** | Link and parameter discovery from JS |
| **ParamSpider** | Parameter discovery from web archives |
| **TruffleHog** | Secret scanning across repos and files |
| **js-beautify** | JavaScript deobfuscation/beautification |

### Forensics & CTF
| Tool | Description |
|------|-------------|
| **binwalk** | Firmware analysis and file extraction |
| **steghide** / **stegseek** | Steganography tools |
| **exiftool** | Metadata reader/writer |
| **foremost** | File carving/recovery |
| **volatility3** | Memory forensics framework |
| **radare2** | Reverse engineering (quick triage via strings tool) |
| **sleuthkit** | Disk forensics utilities |

### Exploitation & Payloads
| Tool | Description |
|------|-------------|
| **metasploit-framework** | `msfconsole`, `msfvenom` |
| **searchsploit** | Exploit-DB search |

### API Testing
| Tool | Description |
|------|-------------|
| **jwt_tool** | JWT analysis and exploitation |
| **clairvoyance** | GraphQL schema introspection |

### Pivoting & VPN
| Tool | Description |
|------|-------------|
| **chisel** | TCP/UDP tunnel over HTTP |
| **ligolo-proxy** | Ligolo-ng tunneling |
| **socat** | Port forwarding and relay |
| **openvpn**, **wg-quick** | VPN clients |
| **proxychains4** | Proxy routing |

### Privilege Escalation (with `--full` setup)
| Tool | Location |
|------|----------|
| **LinPEAS** | `/opt/privesc-tools/linpeas.sh` |
| **WinPEAS** | `/opt/privesc-tools/` |

### Wordlists
Default paths reference Kali standard locations: **rockyou.txt**, **SecLists**, `/usr/share/wordlists/dirb/`.

---

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `CHUNGUS_KALI_MCP_TMP_DIR` | `~/.chungus-kali-mcp/tmp` | Working directory for scans, payloads, CTF files |
| `VPN_DIR` | `~/.chungus-kali-mcp/vpn` | Directory for VPN config files (`.ovpn`, WireGuard) |
| `HTB_ROUTES` | — | Comma-separated CIDRs to route (e.g. `10.129.0.0/16,10.10.0.0/16`) |
| `EXTRA_HOSTS` | — | Comma-separated `hostname:ip` pairs added to `/etc/hosts` |
| `BLOCKING_TIMEOUT` | `30` | Streaming startup detection timeout (seconds) |

### VPN configs

Place OpenVPN or WireGuard configs in `VPN_DIR` (default `~/.chungus-kali-mcp/vpn/`), then use the `vpn_connect` MCP tool.

### Node dependencies

| Package | Purpose |
|---------|---------|
| `@modelcontextprotocol/sdk` | MCP server protocol |
| `zod` | Tool input validation |
| `node-pty` (optional) | Metasploit PTY sessions |

---

## Design Decisions

| Decision | Rationale |
|----------|-----------|
| **Native VM, no Docker** | Direct access to host network, VPN interfaces (`tun0`, `wg0`), and GPU (hashcat) without port mapping |
| **Single Node process** | Eliminates HTTP client/server split; lower latency, simpler deployment |
| **CLI spawning** | Reuses Kali's installed tools (`impacket-*`, `netexec`, etc.) — no Python server to maintain |
| **Custom callback catcher** | HTTP + DNS listener for isolated CTF/pentest networks where webhook.site can't reach targets |
| **Heavy-task semaphore** | Max 5 concurrent long scans (nmap, nuclei, gobuster) to avoid overwhelming the VM |
| **TOOL_CATALOG.json** | Machine-readable contract for all 155 tools; parity-tested in CI |

---

## Project Structure

```
chungus-kali-mcp/
├── src/
│   ├── index.ts                 # MCP server entry (stdio)
│   ├── config.ts                # paths, env vars
│   ├── lib/                     # command-executor, tool-config, session-registry, health
│   ├── tools/                   # MCP tool registration (155 tools)
│   ├── managers/                # SSH, reverse shell, MSF, pivot, VPN, callback, CTF, AD, …
│   ├── runners/                 # Stateless CLI wrappers (kali-tools, forensics, js)
│   └── parsers/                 # output-parser (nmap XML, nuclei JSONL, gobuster text)
├── scripts/
│   ├── kali-init.sh             # HTB routes, hosts, TUN setup
│   ├── kali-docker-parity.sh    # Install Docker-image tool parity on Kali VM
│   └── extract-catalog.py       # (upstream only) regenerate from parent Python reference
├── test/                        # Catalog + registration parity tests
├── .github/workflows/ci.yml     # GitHub CI (build, lint, test)
├── .gitignore
├── CHEATSHEET.md                 # Quick reference for all 155 MCP tools
├── TOOL_CATALOG.json            # All 155 tools — source of truth
├── COMMAND_PATTERNS.md          # Handler types and command patterns
├── ATTRIBUTION.md               # Credit to original zebbern-kali-mcp author
├── package.json
└── README.md
```

---

## Usage

Once connected, ask your AI assistant to use the Kali tools:

> "Scan 10.10.10.5 with nmap"
> "Run nuclei against example.com"
> "Connect to the HTB VPN and start recon"
> "Enumerate AD with bloodhound against dc01.corp.local"
> "Start a callback listener on port 8080"

The assistant calls MCP tools directly on the Kali VM — no manual commands needed.

---

## Development

```bash
npm run dev              # tsx src/index.ts (stdio MCP server)
npm run build            # compile to dist/
npm run lint             # tsc --noEmit
npm test                 # verify 155 tools registered vs TOOL_CATALOG.json
npm run extract-catalog  # (upstream only) regenerate from parent Python reference
```

See [AGENTS.md](AGENTS.md) for contributor/agent guidance.

---

## Security Warning

> **This server provides unrestricted access to powerful penetration testing tools.**

- **Never** expose the Kali VM to the public internet
- Only run on isolated networks or authorized test environments
- Ensure you have proper authorization before testing any systems
- The server typically runs as **root** on Kali — required for many pentest tools but increases risk
- MCP uses stdio transport — only local editor/agent processes should launch the server

---

## Contributing

Contributions welcome. Please open a pull request with a clear summary and test notes (`npm test` must pass).

---

Built on the [Model Context Protocol](https://github.com/modelcontextprotocol) · Node.js reimplementation of [zebbern-kali-mcp](https://github.com/zebbern/zebbern-kali-mcp) by [Zebbern](https://github.com/zebbern)