# pentest-mcp-extended

![CI](https://github.com/RafaDiazRios/pentest-mcp-extended/actions/workflows/ci.yml/badge.svg)

An MCP server that extends [`kali-mcp`](https://github.com/pabpereza/kali-mcp)
into three areas it doesn't cover: **Cloud (AWS/Azure/GCP)**,
**API / GraphQL / JWT**, and **OSINT depth**. Same architecture as kali-mcp —
a Dockerized toolbox exposed over an HTTP MCP endpoint with an `execute_command`
escape hatch plus typed, per-technique tools — so it drops straight into the
same agent workflow and runs *alongside* kali-mcp.

> **Authorized use only.** This is red-team / penetration-testing tooling. Use it
> exclusively against systems you own or have **written permission** to test
> (engagement scope, your own lab, or a CTF). Set `PENTEST_SCOPE` and keep it
> accurate — network-facing tools refuse out-of-scope targets. You are
> responsible for staying within your authorization and the law.

## What it adds

| Category | MCP tools |
|----------|-----------|
| **Cloud** | `cloud_enum`, `aws_whoami`, `scoutsuite_scan`, `prowler_scan` |
| **API / GraphQL / JWT** | `graphql_fingerprint`, `graphql_introspect`, `api_route_scan`, `param_discover`, `jwt_analyze`, `jwt_crack`, `jwt_tamper` |
| **OSINT** | `harvester`, `subdomain_enum`, `username_hunt`, `email_recon` |
| **Container / K8s** | `trivy_image`, `trivy_fs`, `kube_bench`, `kube_hunter`, `docker_bench` |
| **K8s / escape (deep-dive)** | `kubectl_access_review`, `kubectl_enum`, `kubeaudit_scan`, `trivy_k8s`, `container_escape_check`, `amicontained` |
| **IaC / secrets / SAST** | `checkov_scan`, `tfsec_scan`, `gitleaks_scan`, `trufflehog_scan`, `semgrep_scan` |
| **Mobile (static)** | `apk_decode`, `apk_to_java`, `apk_manifest`, `mobile_sast` |
| **Binary / RE / exploit-dev** | `bin_checksec`, `bin_info`, `bin_strings`, `rop_gadgets`, `r2_script` |
| **Reporting** | `add_finding`, `list_findings`, `clear_findings`, `generate_report` |
| **Core** | `execute_command` (arbitrary tool), `list_capabilities` (self-test) |

Underlying tools: cloud_enum, ScoutSuite, Prowler, awscli · graphw00f,
kiterunner, arjun, jwt_tool · theHarvester, amass, sherlock, holehe · Trivy,
kube-bench, kube-hunter, docker-bench · Checkov, tfsec, gitleaks, trufflehog,
Semgrep · apktool, jadx, mobsfscan · checksec, radare2, ROPgadget, pwntools.

File-based scanners (IaC, mobile, binary) read from `/work` — drop the target
code/APK/binary into `./work` on the host.

## Architecture

```
Agent (Claude Code / Cursor / …)
        │  MCP over HTTP
        ▼
http://localhost:6667/mcp   ── FastMCP (streamable-http)
        │
        ▼
Kali container ── cloud / api / osint CLI tools
```

- `app/common.py` — shared FastMCP instance, command runner, scope guard.
- `app/tools_cloud.py`, `tools_api.py`, `tools_osint.py` — typed tool wrappers.
- `app/server.py` — registers modules, adds `execute_command`, serves MCP.

## Quick start

```bash
cp .env.example .env       # set PENTEST_SCOPE to your engagement scope
docker compose up --build  # builds the toolbox, serves MCP on :6667
```

Register it with your agent (already provided in `.mcp.json` for Claude Code):

```json
{ "mcpServers": { "pentest-extended": { "type": "http", "url": "http://localhost:6667/mcp" } } }
```

Then drive a session with the bundled commands:

```
/pentest-ext-audit acme-lab.com     # remote assessment: cloud / API / OSINT
/pentest-ext-artifacts              # static analysis of files dropped in ./work
```

## Running natively on Kali (no Docker)

On a Kali host you can install every tool and run the server directly:

```bash
./setup-kali.sh          # install all tools (apt + pipx + release binaries)
./setup-kali.sh --run    # install, then start the MCP server on :6667
```

Then launch Claude Code in this directory — it auto-detects `.mcp.json`
(`localhost:6667`). Docker (above) is still the most reproducible option; the
script is the convenience path when you already live on Kali.

> Starting the server by hand (not via `setup-kali.sh --run`)? Set a writable
> `REPORTS_DIR`, otherwise findings default to the absolute `/reports` and fail
> for a non-root user:
> ```bash
> REPORTS_DIR=./reports python3 -m app.server
> ```

## Smoke-testing the stack

Validate the whole thing in one command on the VM:

```bash
./test.sh --docker          # build + start Docker, then run all checks
./test.sh                    # server already running (Docker or native)
./test.sh --url http://VM-IP:6667/mcp   # test a remote endpoint
```

Three layers, no external target touched: (1) offline unit check of the CVSS 3.1
+ remediation logic, (2) server reachability + tool inventory via
`list_capabilities`, (3) a safe `add_finding` -> `generate_report` dry-run.

**CI vs. host validation.** GitHub CI validates *our code* — it compiles every
module, runs the reporting unit tests, and builds a slim image (`Dockerfile.ci`,
python-slim + our code) to smoke-test the live MCP server, tool registration and
report pipeline. It deliberately does **not** build the full Kali toolchain image
(`Dockerfile`) — that's too heavy for a free runner and is validated on your Kali
host instead, where `./test.sh --docker` and `list_capabilities` confirm all 35+
tools are present.

## Auditing your own cloud accounts

`scoutsuite_scan` / `prowler_scan` use the container's ambient credentials.
Mount them **read-only** (uncomment in `docker-compose.yml`) and point them at
accounts you own:

```yaml
volumes:
  - ${HOME}/.aws:/root/.aws:ro
```

## Scope enforcement

Set `PENTEST_SCOPE=acme-lab.com,10.10.0.0` in `.env`. Any network-facing tool
called with a target outside the list returns a `[scope-block]` refusal instead
of running. Empty scope = tools run but append an authorization reminder.

## Notes & extending

- Add a tool: write a `@mcp.tool()` function in the relevant `tools_*.py`; it's
  auto-registered on import.
- Reports (ScoutSuite/Prowler HTML) land in `./reports`.
- Out of scope by design: victim-facing phishing kits, malware distribution, and
  real-world detection-evasion payloads. Lab detection/evasion for purple-team
  exercises belongs in your kali-mcp knowledge base.