GeezerVison

╔══════════════════════════════════════════════════════════════╗
║                                                              ║
║                 K  A  L  I  M  C  P                          ║
║                                                              ║
║       Kali Linux security tools for AI agents                ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

Mirrored on both GitHub and Codeberg. Issues filed on either are welcome; commits are pushed to both.

KaliMCP exposes offensive security tools — port scanners, web vuln scanners, network logon brute-force, automated SQL injection — to an AI agent. The operator is solely responsible for using it only against targets they are authorized to scan: pentest engagements with written scope, CTFs you have a flag for, your own lab, bug bounty programs whose scope covers what you're scanning. Cracking passwords or injecting SQL against systems without authorization is a federal-grade mistake.

Every invocation appends one JSON line to /var/log/kalimcp.log (target, argv, exit code, elapsed time). That audit trail is the operator-accountability mechanism; the project does not enforce a hard-coded refuse list.

Credential tools (hydra_crack, medusa_crack, netexec_spray, john_crack, hashcat_crack) take password / hash / wordlist values on the command line. Those values are redacted in the audit log — the flag stays, but the value is rewritten to sha256:<8hex> so the literal never lands in the log file.

Tool output is treated as untrusted, attacker-controlled data: a scanned host's banners, page titles and headers can carry a prompt-injection payload. Every active-tool result is tagged untrusted_output: true (with a note telling the agent to treat it as inert data) and the stdout/stderr handed to the model is bounded (default 64 KiB, KALIMCP_MODEL_OUTPUT_LIMIT to change); the full output stays in the capture and, with KALIMCP_AUTORECORD=1, in the engagement loot store.

Exposes the following MCP tools to any compliant client (Claude Code, Claude Desktop, future MCP-aware clients):

Recon / scanning

Auth & credentials

Windows AD post-exploit

Exploitation / delivery (Tier 3 — crosses from capability into delivery; audited, not gated)

Credential-capture listeners (long-lived; start → poll for captured NetNTLM hashes)

Cloud audit (Tier 3 — audit a cloud account via local creds; no single target host)

Interactive sessions (long-lived, keyed by session id; audited, not scope-gated)

Engagement workspace (agent working memory)

Set KALIMCP_AUTORECORD=1 to have active-scan tools mirror their parsed findings into the active engagement automatically (nmap → findings, hydra/netexec → creds, etc.). If the active engagement has a scope list, calls to out-of-scope targets get a non- blocking warning: "out_of_scope" in the result + an audit event.

At most KALIMCP_MAX_CONCURRENCY tool subprocesses run at once (default 8); extra calls queue. Each call still carries its own wall-clock timeout and a 2 MB output cap. Use process_list / process_kill to inspect and stop long-running scans without tearing down the session.

Passive lookups

Loot triage (read-only analysis of a file already on disk)

git clone https://github.com/CryptoJones/KaliMCP.git
cd KaliMCP
docker build -t kalimcp .                # full image (all tools)
# or a leaner image, dropping the two heaviest optional groups:
docker build --build-arg INCLUDE_CLOUD=false --build-arg INCLUDE_ZAP=false -t kalimcp:lean .

INCLUDE_CLOUD=false drops the ScoutSuite/Prowler/kube-hunter pipx layer; INCLUDE_ZAP=false drops OWASP ZAP and its JRE. Both default to true (the full toolset); the excluded MCP tools just report ToolNotInstalled. The Go-built tools (nuclei, gowitness, kerbrute) come from a builder stage, so the Go toolchain never ships in the runtime image.

The image pulls from kalilinux/kali-rolling and installs the full wrapped tool set alongside the Python package:

• recon / web: nmap, nikto, gobuster, sslscan, ffuf, whatweb, enum4linux-ng, snmp, ldap-utils
• auth / credentials: hydra, sqlmap, netexec, medusa, john, hashcat
• Windows AD post-exploit: impacket-scripts, metasploit-framework (only msfvenom is wired — see below)
• passive / triage: whois, dnsutils, exploitdb, openssl, tshark, binutils (strings/nm/objdump), traceroute
• wordlists: wordlists, seclists

git clone https://github.com/CryptoJones/KaliMCP.git
cd KaliMCP
python3 -m venv .venv
.venv/bin/pip install -e .

Edit (or create) ~/.claude/mcp.json:

{
  "mcpServers": {
    "kalimcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/YOU/.kalimcp:/home/kalimcp/.kalimcp",
        "kalimcp"
      ]
    }
  }
}

(Replace /home/YOU with $HOME.) Or bare-metal:

{
  "mcpServers": {
    "kalimcp": {
      "command": "/path/to/.venv/bin/kalimcp"
    }
  }
}

Restart Claude Code. The tools above will be available to the agent. Ask it to "scan 10.0.0.5 with nmap-fast" and it will issue the call.

Every tool call appends one JSON line to the audit log. The Docker image runs as the non-root kalimcp user and writes to ~/.kalimcp/kalimcp.log (i.e. the bind-mounted state dir) by default. A bare-metal install writes to /var/log/kalimcp.log, falling back to ~/.kalimcp/kalimcp.log if that isn't writable; override the path with KALIMCP_LOG_FILE. The log records:

• event: tool_invoke, passive_invoke, tool_exception.
• tool: which wrapper was called.
• target: the scanned host / URL (full string).
• elapsed_ms, exit_code, timed_out, truncated.

To use the standard system path on a bare-metal install without sudo on every invocation:

sudo touch /var/log/kalimcp.log
sudo chown $(id -un):$(id -gn) /var/log/kalimcp.log

The audit log is a strict side channel. Errors writing it never affect tool execution. KALIMCP_NO_LOG=1 disables it entirely (for tests).

The v0.4 → v0.9 red-team overhaul plus the pentest gap-coverage phase are shipped: recon (incl. nuclei + the ProjectDiscovery trio), web-vuln, auth/credential, Windows AD post-exploit and analysis (BloodHound collection, Certipy AD CS, Responder/relay capture), traversal (SOCKS pivot + file transfer), exploitation (Metasploit module delivery), cloud audit, and the engagement workspace are all live (see the Status table). What's still deliberately left out:

• BloodHound graph querying — bloodhound_collect gathers the AD graph to a .zip, but path analysis runs in the neo4j-backed BloodHound GUI the operator ingests it into; the server doesn't embed neo4j.
• evil-winrm's interactive shell — winrm_exec covers single-shot PowerShell over WinRM (netexec winrm -X); there's no persistent interactive session.
• Pacu (AWS exploitation REPL) — intentionally omitted: it's an interactive shell, not a one-shot non-interactive command, so it doesn't fit the wrap-a-CLI model. ScoutSuite/Prowler cover cloud audit.
• Wireless / physical / mobile — out of scope by nature: they need radio hardware or a device, which a stdio container can't provide.

See CHANGELOG.md for the per-release detail.

python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'

.venv/bin/ruff check .          # lint (E, F, W, B, I, UP)
.venv/bin/mypy                  # type check (src/)
.venv/bin/pip-audit             # dependency CVE scan
.venv/bin/python -m pytest -q   # tests (no real subprocesses spawn)

CI (Woodpecker + GitHub Actions) runs ruff, mypy, pip-audit, a gitleaks secret scan, a syft CycloneDX SBOM, and pytest on Python 3.11 and 3.12, plus a hadolint pass on the Dockerfile. The Docker base image is pinned by digest (not the moving kali-rolling tag) for reproducible, tamper-evident builds — refresh it with skopeo inspect --format '{{.Digest}}' docker://kalilinux/kali-rolling. See CONTRIBUTING.md for the tool-wrapper checklist.

• CONTRIBUTING.md — dev setup, the tool-wrapper checklist, and the dual-mirror (GitHub + Codeberg) workflow.
• SECURITY.md — authorized-use responsibility and how to report a vulnerability in the server code itself.
• docs/THREAT_MODEL.md — actors, trust boundaries, and the mitigation for each threat (prompt injection via tool output, secret leakage, command/flag injection, resource exhaustion, supply chain).

Apache 2.0. See LICENSE.

Proudly Made in Nebraska. Go Big Red! 🌽 https://xkcd.com/2347/