# kali-ssh-mcp

[![tests](https://github.com/1337exe/kali-ssh-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/1337exe/kali-ssh-mcp/actions/workflows/tests.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> ⚠️ **For authorized security testing only.** This tool executes offensive
> security tooling (nmap, gobuster, nuclei, nikto) against remote targets.
> Only use it against systems you own or have explicit written authorization
> to test. See [SECURITY.md](SECURITY.md) for the full disclaimer and threat
> model before use.

An MCP server that bridges an LLM client (Claude Desktop, or any
MCP-compatible client) to a **persistent Kali Linux VM over SSH** — with a
hard scope allowlist, structured JSON output, and a full audit log.

> **Read [SECURITY.md](SECURITY.md) before connecting this alongside other
> MCP tools that can browse the web.** Combining always-on tool access with
> web-fetching creates a real prompt-injection risk — this doc explains the
> mitigations built in and what you should still do on your end.

## Why this exists

There are already several good Kali/pentest MCP servers in the community
(PENTEST-MCP-SERVER, pentest-mcp, zebbern-kali-mcp, and others — worth
checking out). Almost all of them share one design decision: **Kali runs as
a disposable Docker container on the same machine as your MCP client.**
That's a great fit if you want zero setup and don't care about state
persisting between sessions.

This project is for the other common setup: **you already have a real,
long-lived Kali VM** — in VMware, VirtualBox, on bare metal, wherever — with
your own tool configs, custom wordlists, and scripts already in place, and
you don't want to lose that every time a container gets torn down. This
server just SSHes into whatever Kali box you already have and drives it,
nothing about your existing setup has to change.

| | This project | Most Docker-based Kali MCPs |
|---|---|---|
| Kali environment | Your existing, persistent VM | Fresh container per run |
| State between sessions | Persists (it's your real VM) | Resets unless you mount volumes |
| Setup | SSH key exchange | Docker install + image build |
| Best for | You already run Kali as a daily driver | Zero-setup, throwaway testing |

## What it does

Exposes four scanning tools to your MCP client, each scope-gated and
returning parsed JSON instead of raw terminal output:

- **`nmap_scan`** — presets for quick/full/service/vuln scans, or an
  explicit port spec
- **`gobuster_scan`** — directory brute-forcing, with optional session
  cookie support for authenticated testing
- **`nuclei_scan`** — template-based vulnerability scanning, filterable by
  severity or template set
- **`nikto_scan`** — web server vulnerability scanning

Plus two read-only utility tools:

- **`list_scope`** — see the current engagement's allowed targets
- **`get_audit_log`** — review recent tool calls (allowed and rejected)

Want to add another tool (`sqlmap`, `subfinder`, `whatweb`, ...)? See
[EXTENDING.md](EXTENDING.md) — the shared scope-gate/audit-log/validation
plumbing means a new tool is usually 20-30 lines, not a rewrite.

## Quick start

```bash
git clone https://github.com/1337exe/kali-ssh-mcp.git
cd kali-ssh-mcp
python3 -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp config.example.yaml config.yaml
```

Edit `config.yaml`:
- `ssh.host` — your Kali VM's IP
- `ssh.username` / `ssh.key_path` — SSH key auth strongly recommended
- `scope.targets` — **only** hosts/CIDRs listed here can be scanned; update
  this every time your authorized scope changes

On the Kali VM, make sure SSH is running and your key is authorized:
```bash
sudo systemctl enable --now ssh
```

Verify the connection manually before wiring up an MCP client:
```bash
ssh -i ~/.ssh/your_key user@<kali-vm-ip> "nmap --version"
```

Run the offline tests (no SSH needed):
```bash
python3 test_logic.py
```

Start the server:
```bash
python3 server.py
```

Connect it to your MCP client — see
[`examples/claude_desktop_config.md`](examples/claude_desktop_config.md)
for a copy-paste Claude Desktop config (macOS, Linux, and Windows). A full
example conversation is in
[`examples/example_session.md`](examples/example_session.md).

## Design principles

- **Scope is enforced in code, not just convention.** Every tool call
  checks the target against `config.yaml`'s allowlist before anything
  executes on the Kali box. No match, no execution — no exceptions.
- **The tool whitelist is small and deliberate.** Only `nmap_scan` and
  `gobuster_scan` exist right now. Adding a new tool is a conscious code
  change (see [CONTRIBUTING.md](CONTRIBUTING.md)), not something the LLM
  can do itself.
- **Structured output only.** Raw nmap XML and gobuster text are parsed
  into JSON before the LLM ever sees them — no asking the model to parse
  terminal output, which is slower and less reliable.
- **Everything is logged.** Every call — allowed or rejected — is appended
  to `audit_log.jsonl`. This is your record of what an LLM session actually
  did, which matters both for your own review and for anyone asking how a
  finding was reached.

## Roadmap / good first contributions

- A session-capture tool pairing with a browser-automation MCP (Playwright,
  Claude in Chrome) to pull authenticated cookies automatically instead of
  pasting them in by hand
- Docker/Portainer-backed tools for long-running scans you don't want tying
  up the Kali VM directly
- `sqlmap` / `subfinder` / `whatweb` wrappers

See [EXTENDING.md](EXTENDING.md) for exactly what a new tool needs to
include before it'll be merged — scope gating and input validation aren't
optional. [CONTRIBUTING.md](CONTRIBUTING.md) covers the PR process itself.

## License

MIT — see [LICENSE](LICENSE).

## Responsible use

This tool is for testing systems you own or are explicitly authorized to
test. See [SECURITY.md](SECURITY.md) for the full disclaimer and threat
model.