# Kali Ethical Hacking MCP Server

[![Python 3.12+](https://img.shields.io/badge/python-3.12,3.13-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

A personal, advanced **Model Context Protocol (MCP) server for authorized penetration testing
and ethical hacking**. It lets an MCP client (Claude Desktop, Claude Code) drive the standard
Kali/pentest toolchain — reconnaissance, scanning, web application testing, exploitation support,
credential work, and reporting — with **authorization scoping, exploitation gating, and audit
logging enforced on every action**.

Built on the [Red Hat `template-mcp-server`](https://github.com/redhat-data-and-ai/template-mcp-server)
(FastMCP, tools-first architecture).

> ## ⚠️ Authorized use only
>
> This server operates real offensive security tooling. Use it **only** against systems you own
> or have **explicit, written authorization** to test. Unauthorized scanning, exploitation, or
> credential attacks are illegal in most jurisdictions. The server enforces an engagement scope
> and refuses to act on targets you have not declared as authorized — **keep `REQUIRE_SCOPE=True`**.
> You are responsible for operating within the law and your rules of engagement.

## How it works

```
Claude (MCP client)  ──►  Kali MCP Server  ──►  ┌─ host binary (nmap on PATH)        [mode: host]
                          (scope + audit)        └─ Kali container (docker exec ...)  [mode: docker]
```

- **Hybrid execution** — each tool runs on a host binary if present, otherwise inside a persistent
  `kalilinux/kali-rolling` container the server starts on demand (missing tools are `apt`-installed
  into it automatically). Controlled by `EXECUTION_MODE` (`auto` | `host` | `docker`).
- **Scope enforcement** — every active tool validates its target against your declared engagement
  scope (`ScopeManager`). Out-of-scope targets are refused.
- **Exploitation gating** — active exploitation / brute-force tools (`sqlmap`, `hydra`) additionally
  require `ALLOW_EXPLOITATION=True`.
- **Audit logging** — every invocation is appended to `~/.kali-mcp/audit.jsonl`.
- **Engagement session** — scans and findings are recorded and can be rendered into a report.

## Tool catalog (24 tools)

| Category | Tools |
|----------|-------|
| **Recon & Scanning** | `nmap_scan`, `masscan_scan`, `host_discovery`, `dns_recon`, `subdomain_enum`, `whois_lookup` |
| **OSINT (passive)** | `username_osint` (Sherlock), `email_harvest` (theHarvester) |
| **Web App Testing** | `nikto_scan`, `dir_bruteforce`, `vhost_enum`, `whatweb_fingerprint`, `nuclei_scan`, `sqlmap_test`†, `wpscan_scan` |
| **Exploitation & Creds** | `searchsploit_lookup`, `hash_identify`, `hash_crack`, `hydra_bruteforce`† |
| **Reporting & Workflow** | `scope_manage`, `list_tools_status`, `record_finding`, `session_summary`, `generate_report` |

† Gated behind `ALLOW_EXPLOITATION=True` **and** an in-scope target.

## Requirements

- Python 3.12+ and [`uv`](https://github.com/astral-sh/uv)
- **Docker** (for the Kali fallback). No security tools need to be installed on the host — they run
  in the Kali container. If you *do* have tools on your `PATH`, they're used directly.

## Install

```bash
uv venv --python 3.12
source .venv/bin/activate
uv pip install -e ".[dev]"
cp .env.example .env   # then review the settings
```

## Run

**stdio (local — for Claude Desktop / Claude Code):**

```bash
MCP_TRANSPORT_PROTOCOL=stdio kali-mcp-server
```

**HTTP (shared / remote):**

```bash
MCP_TRANSPORT_PROTOCOL=http MCP_PORT=5001 kali-mcp-server
```

### Connect it to Claude

**Claude Code:**

```bash
claude mcp add kali-ethical -- /ABSOLUTE/PATH/ethical-mcp/.venv/bin/kali-mcp-server
```

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "kali-ethical": {
      "command": "/ABSOLUTE/PATH/ethical-mcp/.venv/bin/kali-mcp-server",
      "env": { "MCP_TRANSPORT_PROTOCOL": "stdio", "EXECUTION_MODE": "auto" }
    }
  }
}
```

## Typical workflow

1. **Authorize the engagement** — record who approved it and the reference:
   ```
   scope_manage(action="set_engagement", client="Acme", authorized_by="J. Smith", ticket="PT-42")
   ```
2. **Declare scope** — only targets you're permitted to test:
   ```
   scope_manage(action="add", targets=["10.0.0.0/24", "app.acme.com"])
   ```
3. **Check tooling** — `list_tools_status()` shows host vs Docker availability.
4. **Recon & scan** — `nmap_scan("app.acme.com", "service")`, `subdomain_enum("acme.com")`, …
5. **Web testing** — `nikto_scan(...)`, `nuclei_scan(...)`, `dir_bruteforce(...)`.
6. **Exploitation** (only with `ALLOW_EXPLOITATION=True`) — `sqlmap_test(...)`, `hydra_bruteforce(...)`.
7. **Record & report** — `record_finding(...)` then `generate_report("markdown")`.

Anything against a target not in scope is refused; gated tools are refused unless explicitly enabled.

## Configuration

Key settings (see `.env.example` for all):

| Variable | Default | Purpose |
|----------|---------|---------|
| `MCP_TRANSPORT_PROTOCOL` | `stdio` | `stdio`, `http`, `streamable-http`, `sse` |
| `EXECUTION_MODE` | `auto` | `auto` \| `host` \| `docker` |
| `KALI_DOCKER_IMAGE` | `kalilinux/kali-rolling` | Fallback toolbox image |
| `REQUIRE_SCOPE` | `True` | Refuse out-of-scope targets |
| `ALLOW_EXPLOITATION` | `False` | Enable active exploitation/brute-force tools |
| `TOOL_TIMEOUT_SECONDS` | `300` | Per-run timeout |
| `DATA_DIR` | `~/.kali-mcp` | Scope, audit log, outputs, wordlists |

## Safety model

- **No target contact without scope.** Recon/scan/exploit tools call the scope gate first.
- **Two-key exploitation.** `sqlmap`/`hydra` need `ALLOW_EXPLOITATION=True` *and* an in-scope target.
- **Rate limits.** `masscan` packet rate is capped to avoid turning a scan into a flood.
- **Full audit trail.** `~/.kali-mcp/audit.jsonl` records every command (incl. blocked attempts).
- **No DoS / mass-internet scanning helpers.** The toolset is engagement-scoped by design.

## Development

```bash
make test     # run the test suite
make lint     # ruff + formatting checks
pytest tests/ # scope, executor, gating, reporting tests
```

## License

Apache-2.0. This tool is provided for authorized security testing and education only.