```text
                      __            __                                   __              ____   _ __
    ____  ___  ____  / /____  _____/ /_      ____ ___  _________        / /_____  ____  / / /__(_) /_
   / __ \/ _ \/ __ \/ __/ _ \/ ___/ __/_____/ __ `__ \/ ___/ __ \______/ __/ __ \/ __ \/ / //_/ / __/
  / /_/ /  __/ / / / /_/  __(__  ) /_/_____/ / / / / / /__/ /_/ /_____/ /_/ /_/ / /_/ / / ,< / / /_
 / .___/\___/_/ /_/\__/\___/____/\__/     /_/ /_/ /_/\___/ .___/      \__/\____/\____/_/_/|_/_/\__/
/_/                                                     /_/

  50 Kali security tools · one MCP server over Docker stdio · driven 100% by AI agents
```

> **You are responsible for authorization.** For authorized self-environment
> pentests of systems you own.

## About

**Pentest MCP Toolkit** is a [FastMCP](https://github.com/jlowin/fastmcp) server
that exposes **50 Kali Linux security tools over MCP stdio**, packed into a
`kalilinux/kali-rolling` Docker container. It is built to be **driven 100% by
AI agents**: point an MCP client like **Claude Code** or **Codex** (or Cursor /
Gemini CLI / LM Studio / Open WebUI) at the container and the agent becomes the
operator — it picks the tool, builds the argv, validates the target, and reads
the output. The agent runs the pentest; the toolkit just makes Kali available
as a set of callable MCP tools.

Scope (`MCP_PENTEST_SCOPE`) controls *where* the agent may scan, not *whether*
it may. It ships **default-open with a loud warning**; you are the
authorization gate. Use it only against systems you own or are explicitly
authorized to test — see the [Legal disclaimer](#-legal--educational-disclaimer)
at the bottom.

Pick a tier, run one command, connect your client.

---

## Quick start

Run **one command** — it checks Docker, builds the tier image, and registers the
`pentest` MCP server with your client. Then open the client; the tool is ready.

Pick a tier, pick a client, paste. macOS / Linux / Git-Bash use the `curl | bash`
line; Windows PowerShell uses the `irm` line. Both do the same thing.

### 50 tools — full set (default, recommended)

**Claude Code** — registers `pentest` at user scope (available in every project):

```bash
# macOS / Linux / Git-Bash
curl -fsSL https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.sh | bash -s -- --tier 50 --client claude-code
```
```powershell
# Windows PowerShell
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.ps1))) -Tier 50 -Client claude-code
```

**Codex** — writes `~/.codex/config.toml`:

```bash
# macOS / Linux / Git-Bash
curl -fsSL https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.sh | bash -s -- --tier 50 --client codex
```
```powershell
# Windows PowerShell
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.ps1))) -Tier 50 -Client codex
```

First build pulls Kali + tool packages (~5–10 min). Image ~1.5 GB (metasploit is large).

### 25 tools — lightweight TCP-only subset

**Claude Code**:

```bash
# macOS / Linux / Git-Bash
curl -fsSL https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.sh | bash -s -- --tier 25 --client claude-code
```
```powershell
# Windows PowerShell
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.ps1))) -Tier 25 -Client claude-code
```

**Codex**:

```bash
# macOS / Linux / Git-Bash
curl -fsSL https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.sh | bash -s -- --tier 25 --client codex
```
```powershell
# Windows PowerShell
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/KoaBrown/pentest-mcp-toolkit/main/install/install.ps1))) -Tier 25 -Client codex
```

Faster build, ~370 MB image. No raw-socket or heavy tools.

Need another client, or building by hand? See [docs/CLIENTS.md](docs/CLIENTS.md)
and [Build from source](#build-from-source--verify) below.

---

## Connect your client

The canonical launch command (every client speaks stdio, so only the **config
file + key** differs per client):

```bash
docker run -i --rm \
  --cap-add=NET_RAW --cap-add=NET_ADMIN \
  -e MCP_PENTEST_SCOPE= \
  -e MAX_OUTPUT=50000 \
  -e CMD_TIMEOUT=300 \
  -e PENTEST_TIER=50 \
  -v "$(pwd)/work:/work" \
  pentest-mcp-toolkit:50
```

- **Claude Desktop** / **Codex** / **Claude Code** / **Cursor** / **Gemini CLI** /
  **LM Studio** / **Open WebUI** — exact file path + snippet in
  [docs/CLIENTS.md](docs/CLIENTS.md). The installer writes it for you:
  `bash install/install.sh --tier 50 --client claude-desktop`.

> Tier 25: swap `:50`→`:25` and drop the two `--cap-add` flags.

---

## Scope  ⚠️ important

`MCP_PENTEST_SCOPE` controls **where** the AI may scan, not **whether** it may.
By default it is **empty** = the toolkit can scan **any host**. This matches
"any device, no configuring" but means: **you** are the only authorization
check. Tighten it to your lab when scanning real targets:

```bash
-e MCP_PENTEST_SCOPE=10.0.0.0/8,192.168.0.0/16,my-lab.local
# or at install time:
bash install/install.sh --tier 50 --client codex --scope 192.168.1.0/24
```

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) § Scope guard for the full
behavior (IP-in-CIDR, CIDR `subnet_of`, domain suffix).

---

## Capabilities (raw-socket scans)

Raw-socket scans need **both** file caps (baked at build time) **and** the
runtime cap on `docker run`:

| Tool | Flag |
|---|---|
| `nmap -sS` (syn scan_type) | `--cap-add=NET_RAW` |
| `masscan_scan` | `--cap-add=NET_RAW --cap-add=NET_ADMIN` |
| `naabu` syn | `--cap-add=NET_RAW` |
| `traceroute_host` | `--cap-add=NET_RAW` |

The canonical launch command above already includes them. Default `nmap_scan`
is `-sT` (TCP connect), needs no caps. Tier 25 ships TCP-only by default (no
`--cap-add` needed); setcap on nmap/naabu is baked so you *can* add the flag.

---

## Tools by tier

### Tier 25 (25 tools — lightweight)

| Category | Tools |
|---|---|
| Network (3) | `nmap_scan`, `naabu_port_scan`, `nc_banner_grab` |
| DNS / OSINT (6) | `subfinder_enum`, `assetfinder_enum`, `theharvester_enum`, `dnsrecon_scan`, `dig_lookup`, `whois_lookup` |
| Web (6) | `whatweb_scan`, `http_probe`, `nuclei_scan`, `nikto_scan`, `wapiti_scan`, `wpscan_scan` |
| Content / fuzz (4) | `gobuster_dir`, `ffuf_scan`, `dirsearch_scan`, `feroxbuster_scan` |
| Injection / crawl (4) | `sqlmap_scan`, `dalfox_xss`, `arjun_params`, `hakrawler_crawl` |
| Local / offline (2) | `searchsploit_search`, `hashid_identify` |

### Tier 50 (50 tools — everything)

Tier 25 is a strict subset. Tier 50 adds:

| Category | Added tools (on top of tier 25) |
|---|---|
| Network (5) | + `masscan_scan`, `traceroute_host` |
| DNS / OSINT (10) | + `spiderfoot_scan`, `dnsenum_scan`, `dnstwist_scan`, `fierce_scan` |
| Web (7) | + `joomscan_scan` |
| Content / fuzz (8) | + `dirb_scan`, `gobuster_dns`, `gobuster_vhost`, `wfuzz_scan` |
| Injection / crawl (5) | + `dotdotpwn_traversal` |
| Exploit (2) | `searchsploit_search` + `msfvenom_payload` |
| Net services / brute (8) | `enum4linux_scan`, `smbclient_list`, `smbmap_enum`, `netexec_smb`, `snmpwalk_enum`, `onesixtyone_snmp`, `smtp_user_enum`, `hydra_brute` |
| Hashes / wordlist (4) | `john_crack`, `hashid_identify`, `cewl_wordlist`, `crunch_wordlist` |
| Forensics (1) | `binwalk_scan` |

---

## Build from source / verify

```bash
# syntax check (no deps needed)
python -m py_compile src/_helpers.py src/server.py src/tools/*.py

# MCP round-trip: confirm the tier serves the right tool count
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | \
  docker run -i --rm pentest-mcp-toolkit:50

# full smoke test (init + tools/list + a real tools/call)
python scripts/smoke_test.py --tier both          # hermetic
python scripts/smoke_test.py --tier 50 --net      # + live scanme.nmap.org scan
```

---

## Architecture

One `src/` tree, two Dockerfiles; the `PENTEST_TIER` env gates which tools
register. Tool functions are bare `async def`s in `src/tools/<category>.py`;
`src/server.py` applies `@mcp.tool()` at registration time. The contract —
no shell, validate before run, scope guard, strings out, single-line docstrings —
lives in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). Dev rules in
[docs/CLAUDE.md](docs/CLAUDE.md).

---

## License

[MIT](LICENSE). Kali tool licenses are their upstream projects'; this toolkit
only packages and orchestrates them.

---

## ⚖️ Legal & Educational Disclaimer

> **This is not legal advice.** What follows is a general disclaimer drafted
> from common open-source security-tooling conventions. It does not create an
> attorney-client relationship. If you are unsure whether a given test is
> lawful in your jurisdiction, consult a qualified attorney **before** you run
> it.

This project — source, Docker images, and installer — is provided **strictly
for educational purposes, defensive security auditing, authorized
vulnerability verification, and penetration testing of systems you own or are
explicitly authorized to test.**

**Authorized use only.** The toolkit ships with `MCP_PENTEST_SCOPE`
default-open, meaning an agent can be directed at any reachable host by
default. That default exists for convenience, **not as permission**. Deploying
this container grants **no authorization** to scan any system. You must obtain
explicit, written permission from the owner/operator of every target before
scanning, probing, fuzzing, brute-forcing, or otherwise interacting with it.
"I was just testing" is not consent.

**You bear all responsibility.** The author(s) assume no liability and are
not responsible for any misuse, damage, data loss, service disruption, or
illegal activity conducted with this software. By deploying or using this
toolkit you agree that you — not the author(s) — are solely responsible for
compliance with all applicable local, state, national, and international laws,
including but not limited to:

- **United States** — Computer Fraud and Abuse Act, 18 U.S.C. § 1030;
  Electronic Communications Privacy Act, 18 U.S.C. § 2510 et seq.; and state
  unauthorized-access statutes.
- **United Kingdom** — Computer Misuse Act 1990.
- **EU / EEA** — Directive 2013/40/EU on attacks against information systems,
  as transposed into national law by each member state.
- **Other jurisdictions** — analogous computer-misuse, unauthorized-access,
  data-protection (e.g., GDPR / UK GDPR), and privacy statutes in your country.

Unauthorized access to a computer system is a crime in most jurisdictions,
regardless of intent or whether a tool made it easy. A tool that *can* reach a
host is not a license to scan a host you don't own.

**No warranty.** This software is provided "AS IS" under the
[MIT License](LICENSE), without warranty of any kind, express or implied,
including without limitation the warranties of merchantability, fitness for a
particular purpose, and non-infringement. The entire risk as to the quality
and performance of the software is with you.

**Indemnification.** By using this software you agree to indemnify and hold
harmless the author(s) and contributors from any claim, damages, loss, or
expense (including reasonable attorneys' fees) arising from your use or misuse
of the software, or your violation of any law or third-party right.

**Third-party tools.** The Kali tools orchestrated here (nmap, nuclei, sqlmap,
metasploit, etc.) are copyrighted and licensed by their upstream projects.
This toolkit only packages and invokes them; it claims no rights over them and
is not affiliated with Kali Linux or those projects. Their licenses and usage
terms apply independently of this one.

**Export / re-export.** Some security tooling may be subject to export-control
regulations (e.g., U.S. EAR, EU dual-use regimes). You are responsible for
complying with applicable export and re-export controls when you download,
deploy, or redistribute this software.

**If you do not agree with these terms, do not deploy or use this toolkit.**