Rami Kali Server

kail-mcp (Model Context Protocol) server that wraps Kali Linux penetration testing tools for authorized security assessments. Designed to be driven by a local LLM via LM Studio.

For AUTHORIZED penetration testing, CTF competitions, and security research ONLY.

---

Quick Start (Docker)

git clone <repo-url> kail-mcp
cd kail-mcp
docker compose up

That's it. No manual dependency installation required.

---

Architecture

┌─────────────┐     JSON-RPC       ┌──────────────────┐      exec      ┌────────────┐
│  LM Studio  │ ◄──── stdin/out ──►│  MCP Server      │ ◄────────────► │ Kali Tools │
│  (local LLM)│                    │  (Python 3)      │                │ MCP tools  │
└─────────────┘                    │                  │                │ nmap, msf, │
                                   │  knowledge/      │                │ bettercap..│
                                   │  (tactical KB)   │                └────────────┘
                                   └───────┬──────────┘
                                           │
                                    ┌──────▼──────┐
                                    │  SQLite DB  │
                                    │  + Reports  │
                                    └─────────────┘

---

Docker Setup

Prerequisites

• Docker Engine 20.10+
• Docker Compose v2+
• 8 GB RAM minimum (Metasploit alone needs ~2 GB)

Build & Run

# Build and start
docker compose up

# Build and start in background
docker compose up -d

# Rebuild after code changes
docker compose up -d --build --force-recreate

# View logs
docker compose logs -f

# Open a shell inside the container (for debugging)
docker compose exec mcp-server zsh

# Stop
docker compose down

Faster Rebuilds & Migration

The full image installs a large Kali toolchain, so the first build, or any change to the tool install layers, can take a long time. Normal MCP code changes are in the final application layer and Docker should reuse the heavy cached layers.

For repeated code-only rebuilds, keep a separate tool baseline image:

# Build the heavy tool baseline once
sh scripts/build-tools-base.sh

# Rebuild only the MCP application layer from that baseline
docker compose -f docker-compose.yml -f docker-compose.fast.yml up -d --build --force-recreate

For another computer, export/import the image instead of downloading all tools again:

# Source machine
sh scripts/export-image.sh kail-mcp-images.tar.gz

# Target machine
sh scripts/import-image.sh kail-mcp-images.tar.gz
docker compose up -d

If you built only kail-mcp:latest and want to use it as the fast-rebuild baseline:

sh scripts/promote-tools-base.sh

Environment Variables

Override any setting without modifying config.yaml:

Variable	Default	Description
MCP_LOG_LEVEL	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)
MCP_DATABASE	/opt/kail-mcp/data/scan_results.db	SQLite database path
MCP_AUDIT_LOG	/opt/kail-mcp/data/audit.log	Audit trail file path
MCP_REPORT_DIR	/opt/kail-mcp/reports	Directory for generated reports
MCP_CONFIG_PATH	/opt/kail-mcp/config.yaml	Path to YAML config file

Example with overrides:

MCP_LOG_LEVEL=DEBUG docker compose up

Or add to a .env file in the project root:

MCP_LOG_LEVEL=DEBUG

Persistent Data

Two Docker volumes keep data across container restarts:

Volume	Container Path	Contents
mcp-data	/opt/kail-mcp/data/	SQLite scan database, audit log
mcp-reports	/opt/kail-mcp/reports/	Generated markdown reports

To back up your data:

# Copy database out of the container
docker compose cp mcp-server:/opt/kail-mcp/data/scan_results.db ./backup.db

# Copy reports
docker compose cp mcp-server:/opt/kail-mcp/reports/ ./reports-backup/

To wipe all data and start fresh:

docker compose down -v

Configuration

The config.yaml file is bind-mounted read-only into the container. Edit it on your host and restart:

# Edit config
vim config.yaml

# Restart to pick up changes
docker compose restart

Key config sections:

security:
  audit_log: audit.log
  allowed_scope: []
  require_scope_check: false
  resolve_hostnames: false

Networking

By default the container runs with network_mode: host so it can scan your local network. If you only scan remote targets or want isolation, change to bridge mode in docker-compose.yml:

services:
  mcp-server:
    # network_mode: host    # comment out
    ports:
      - "8080:8080"         # if you add an HTTP transport later

Metasploit Database (Optional)

Metasploit works out of the box with its built-in database. For a dedicated PostgreSQL instance, uncomment the msf-db service in docker-compose.yml:

# Edit docker-compose.yml — uncomment the msf-db service and depends_on
vim docker-compose.yml
docker compose up

---

Installed MCP Tools (56 exposed)

The container includes these Kali tools (auto-detected at startup):

Category	Tools
Recon	nmap, masscan, naabu, subfinder, pd-httpx, whatweb, whois, dig, theHarvester, searchsploit
CVE Intelligence	cve_lookup (NVD 2.0 API — exact CVE ID, keyword+exact_match, cpe_name, virtual_match_string, cvss_severity filter, publication and modification date ranges, no_rejected flag; returns CVSS, SERVICE BINDING annotation, CPEs, references)
Web Scanning	gobuster, feroxbuster, dirsearch, ffuf, nuclei, katana, nikto, dirb, wfuzz, wpscan, joomscan, zaproxy
Exploitation	sqlmap, metasploit (msfconsole, msfvenom)
Credential Attacks	hydra, medusa, ncrack, kerbrute, hashcat, john, crunch, cewl
SMB / AD	enum4linux, enum4linux-ng, smbclient, smbmap, crackmapexec, netexec, evil-winrm (non-interactive command mode), certipy-ad, bloodhound-python, impacket example scripts
MITM	bettercap, ettercap, responder
Wireless	aircrack-ng, wifite
C2 / Social Engineering	beef-xss, setoolkit
Proxy Routing	proxychains4 (Burp profile /etc/proxychains4.conf + Tor profile /etc/proxychains4-tor.conf)
Network	tcpdump, netcat, socat
Wordlists / Templates	rockyou.txt, dirb lists, SecLists (/usr/share/seclists), pinned nuclei templates (/usr/share/nuclei-templates)

Tool dependency availability is logged at startup. MCP tools remain exposed in this test build.

seclists and nuclei-templates are installed resource packs, not MCP tools. Their paths are included in the relevant tool schemas and tactical knowledge so the model can use them with gobuster_dir, ffuf_fuzz, wfuzz_scan, feroxbuster_scan, dirsearch_scan, nuclei_scan, and sqlmap_scan.

Tools Not Available in Docker

The following tools are generally not runnable in this Docker container unless you provide/install them separately:

Tool	Reason
mimikatz	Windows-only binary
cobaltstrike	Commercial license required
burpsuite	Runs on the Windows host separately; its MCP server is added as an independent server in the host UI — not part of kail-mcp
powersploit	PowerShell modules, not a Linux binary
empire	Deprecated / complex install
shellter	Windows PE injector (Wine-dependent)
xhydra	GTK GUI, useless headless
pyrit, ewsa	Deprecated / unavailable in repos
zap-cli, patator, mitmproxy, ngrep, hping3, fragrouter, macchanger, veil, kismet, reaver, bully, pixiewps, cowpatty, wireshark-common	Not exposed by this MCP server, too heavy for the default image, GUI-dependent, or unsuitable for portable Docker use
wifiphisher, fluxion, airgeddon, wifi-honey, ghost-phisher, fern-wifi-cracker	Not in Kali repos or require GUI

Shell Environment

The container runs zsh as the default shell with:

• zsh-syntax-highlighting: commands turn green when valid, red when invalid — real-time feedback before you press Enter
• zsh-autosuggestions: suggests commands from history; press Tab or → to accept

When the host UI's Docker Terminal opens a session it detects the shell in order: zsh → bash → sh.

# Open an interactive zsh session
docker exec -it kail-mcp zsh

Proxy Routing (proxychains4)

Two ready-made profiles are installed for routing tool traffic without modifying tool configuration:

Profile	Path	Target
Burp	/etc/proxychains4.conf	127.0.0.1:8080 (Windows host Burp proxy)
Tor	/etc/proxychains4-tor.conf	127.0.0.1:9050 (Tor SOCKS in container)

Usage:

# Route through Burp for traffic analysis
proxychains nmap -sV 10.10.10.1

# Route through Tor for anonymity
proxychains -f /etc/proxychains4-tor.conf curl https://example.com

# Chain tool → Burp → Tor (configure Burp SOCKS upstream first)
# In Burp: Settings → Network → Connections → SOCKS proxy → 127.0.0.1:9050
proxychains nmap -sV 10.10.10.1

The gobuster_dir MCP tool accepts a proxy parameter to route directory bruteforce through a proxy directly (e.g., http://127.0.0.1:8080 for Burp or socks5://127.0.0.1:9050 for Tor) — no proxychains required for that tool.

Because the container uses network_mode: host, 127.0.0.1 inside the container resolves to the Windows/Linux host, so Burp running on the host is reachable at 127.0.0.1:8080.

Wireless Tools Caveat

Wireless tools (aircrack-ng, reaver, wifite, etc.) are installed but require USB WiFi adapter passthrough to function. Uncomment the following in docker-compose.yml:

privileged: true
devices:
  - /dev/bus/usb:/dev/bus/usb

Without a physical adapter passed through, wireless tools will start but have no interfaces to work with.

---

Knowledge Base

The knowledge/ directory contains a tactical reasoning system for the LLM:

knowledge/
  core_principles.md      — Decision axioms
  engagement_rules.md     — Scope & risk rules
  pivot_map.md            — "If X found → do Y" decision trees
  tools/*.md              — Per-tool tactical memory
  interpretation/*.md     — Result parsing guides
  tactics/*.md            — Phase-by-phase methodology

The tools/cve_lookup.md file provides the LLM with NVD 2.0 query strategy, all supported parameters with examples, CVSS severity bands, the CVE Query Lock decision sequence (extract product → extract version → build query), SERVICE BINDING rules (bind CVE only to matching detected service), evidence rules, and chaining workflows (nmap version → cve_lookup → searchsploit).

See knowledge/README.md for the full structure and integration guide.

---

LM Studio Integration

1. Start LM Studio and load a model (e.g., Qwen 2.5 7B, Mistral 7B)
2. Enable the MCP server in LM Studio's tool settings
3. Point it to the MCP server's stdin/stdout interface
4. The LLM can now call penetration testing tools via the MCP protocol

---

Project Structure

kail-mcp/
├── Dockerfile              ← Kali-based container image (60+ tools)
├── docker-compose.yml      ← One-command startup + optional PostgreSQL
├── docker-entrypoint.sh    ← Startup checks & tool verification
├── .dockerignore           ← Build context exclusions
├── config.yaml             ← Server configuration
├── requirements.txt        ← Python dependencies
├── mcp_server.py           ← Compatibility launcher for python3 mcp_server.py
├── mcp_server/             ← Modular MCP server package (protocol, registry, executor)
├── knowledge/              ← Tactical knowledge base (27 files)
│   ├── core_principles.md
│   ├── pivot_map.md
│   ├── tools/
│   ├── interpretation/
│   └── tactics/
└── README.md               ← This file

---

Security

This is currently a test build with MCP-side security boundary restrictions disabled.

• Scope enforcement: disabled; allowed_scope is empty and _scope_check() is a no-op
• Input sanitization: permissive pass-through helpers are used
• Shell command: unrestricted shell execution
• Rate limiting / timeout cap: MCP-side semaphore limiting and max-timeout capping are disabled
• Audit logging: every tool invocation is still recorded with timestamp and arguments
• Binary availability: dependencies are logged, but tools remain exposed