kali-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A single-file MCP (Model Context Protocol) server preserving 41 Kali Linux calls and adding eight bounded scanning/reporting calls. An MCP client calls the tools over stdio; the server invokes underlying Kali binaries and returns strings. MCP behavior lives in kali_pentest_server.py. Host-side Docker profile selection lives in kali_mcp_launcher.py and its scripts/kali-mcp entry point.

Commands

# Build the image from pinned base and package inputs
docker build -t kali-mcp-server:latest .

# Inspect the hardened launcher command, then run it through an MCP client
scripts/kali-mcp --image kali-mcp-server:latest --dry-run

# Host startup is only a development convenience
python3 kali_pentest_server.py          # host: needs `pip install -r requirements.txt` + the Kali tools on PATH

# Run the native contract, adapter, report, launcher, registry, and browser tests
python3 -m unittest discover -s tests -v

# Redaction gate. NOT collected by unittest discover -- run it directly, and read
# the EXIT STATUS, not the last line of output (a launcher test prints a docker
# line after `OK`). Three states: 0 measured and clean; 3 NOTHING TO MEASURE,
# the base carries a byte-identical kali_pentest_server.py so the run is a pass
# that proves nothing; any other status a failure. 1 is the real verdict -- a
# leak opened, legitimate content destroyed, a parser the corpus never
# exercised, or a sweep combination the base redacted and HEAD does not. 2 is
# not a verdict at all: CPython exits 2 on a script it cannot open and argparse
# exits 2 on a bad flag, which is why "nothing to measure" is 3 and 2 fails.
# Pass --base after this branch merges.
python3 tests/redaction_differential.py [--base <rev>] [--json out.json]

# Mutation check: swap kali_pentest_server.py for the version at <base-rev>, run
# the tests matching <test-pattern> (default `test_scanner_adapters.py`) against
# it, and require a real ASSERTION failure -- 0 the mutation was caught, 1 the
# suite ran clean so those assertions pin nothing, 2 INCONCLUSIVE (nothing
# collected, or an error, neither of which proves anything either way), 3 the
# base is byte-identical to the working tree so nothing was mutated. Same 3 as
# the redaction gate above, and for the same reason: a run that measured nothing
# must not report either a pass or an accusation. Refuses to start while
# kali_pentest_server.py has uncommitted changes. Restores the tree on any exit.
scripts/mutation-check <base-rev> [test-pattern]

# Verify a built image under the required NNP boundary
docker run --rm --security-opt=no-new-privileges \
  --entrypoint verify-kali-mcp-image kali-mcp-server:latest

# Exercise the real MCP/container seam after building the requested platform image
python3 tests/integration/run_container_integration.py \
  --image kali-mcp-server:latest --platform linux/amd64

# Stage an explicitly reviewed, detection-only Nuclei template set
scripts/update-nuclei-templates --source /path/to/upstream \
  --destination /new/staging/directory --version UPSTREAM_VERSION \
  http/cves/example.yaml