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.

Inspired by zebbern-kali-mcp. See 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

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):

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

Optional: link the binary globally:

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):

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

Or with npm link:

{
  "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 cover most APT tools. To match the parent Docker image extras (Go tools, pip tools, /opt clones):

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

4. HTB / lab networking (optional)

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.

#	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

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 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 · Node.js reimplementation of zebbern-kali-mcp by Zebbern