Content
# MCPwn
<div align="center">
**AI-Powered Offensive Security Toolkit**
Bridge your AI assistant to Kali Linux security tools via Model Context Protocol
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](#-docker)
</div>
---
## Overview
**MCPwn** bridges your AI assistant (Claude, GitHub Copilot, 5ire, etc.) to a full Kali Linux environment via **Model Context Protocol (MCP)**. Default MCP surface is **agent** mode: a focused preset of high-value direct tools with native MCP schemas/annotations, plus **4 catalog meta-tools** (`list_catalog`, `get_tools`, `get_tool`, `run_tool`) that can still reach all **122 tool wrappers** and **124 Flask API routes**. Use **compact** for a minimal catalog-only surface, or **full** to expose all 122 wrappers directly.
```
You: "RSA challenge: n=851889..., e=65537, c=345771..."
AI: → create_analysis_session(user_id="mcpwn")
→ get_tools(query="factordb") → get_tool("factordb_query")
→ run_tool("factordb_query", {"number": n}) # catalog fallback
→ rsa_attack(session_id="<session_id>", n=n, e=e, c=c, attack="wiener")
→ "Flag: CTF{weak_rsa_exponent}"
```
### Burp Suite Integration (Optional)
Add PortSwigger's official MCP server as a second MCP server alongside MCPwn for direct Burp proxy/repeater/scanner access:
- Install: [Burp MCP BApp](https://portswigger.net/bappstore/9952290f04ed4f628e624d0aa9dccebc) or [GitHub](https://github.com/PortSwigger/mcp-server)
- Community: 21 tools (proxy history, repeater, intruder) — Professional: +3 (scanner, Collaborator)
- MCPwn complements Burp with: SSTI (tplmap), XSS deep scan (dalfox), GraphQL enum (clairvoyance), SSRF (SSRFmap), template scanning (nuclei)
---
## Quick Start
### Docker (Recommended)
```bash
git clone https://github.com/AeonDave/mcpwn.git
cd mcpwn
docker compose up -d
```
> **MCPwn** is a standalone project, not a fork.
Default compose publishes a single host port:
- **MCP endpoint (direct FastMCP)** → `http://localhost:5000/mcp`
Flask stays internal on container port `5000` for `/api/*` and `/health`; FastMCP listens on container port `8080` and is published on host port `5000`.
Default Docker config starts MCP in **agent** mode via `MCP_EXPOSURE_MODE=agent` and `MCP_AGENT_PRESET=ctf-basic`.
### Native (Kali Linux)
```bash
git clone https://github.com/AeonDave/mcpwn.git
cd mcpwn
pip install -e .
sudo apt install -y golang-go cargo rustc \
nmap gobuster feroxbuster sqlmap wpscan hydra john \
enum4linux-ng netexec amass subfinder arjun seclists \
checksec binwalk steghide radare2 tshark zaproxy nuclei httpx-toolkit
go install github.com/projectdiscovery/katana/cmd/katana@v1.6.0
cargo install rustscan --version 2.4.1 --locked
python3 kali_server.py &
PYTHONPATH=src python3 src/mcpwn/mcp_server.py --server http://localhost:5000 --exposure-mode agent --agent-preset ctf-basic
```
---
## MCP Exposure Modes
`/mcp` always stays same endpoint. What changes is tool surface exposed by FastMCP.
| Mode | MCP-visible tools | Use case |
|------|-------------------|----------|
| `agent` *(default)* | Preset-selected direct tools + `list_catalog`, `get_tools`, `get_tool`, `run_tool` | Best default for Claude/Copilot and operational agents: common tools have native schemas/annotations, long tail stays discoverable. |
| `compact` | Only `list_catalog`, `get_tools`, `get_tool`, `run_tool` | Minimal catalog-only surface for clients that need the smallest possible tool list. |
| `full` | 122 direct wrappers | Power users, tool-specific clients, backwards-compatible direct calls. |
`agent` and `compact` both still reach all 122 wrappers through `run_tool(name, arguments, save_to_file="")`.
Agent presets are selected with `MCP_AGENT_PRESET` or `--agent-preset`:
| Preset | Direct-tool focus |
|--------|-------------------|
| `ctf-basic` *(default)* | Sessions, health, nmap/rustscan, core web, pwn triage/exploit, crypto basics, binwalk/zsteg/Volatility |
| `web` | Sessions, network recon, web recon/fuzzing/scanning/request helpers |
| `pwn` | Sessions, binary triage, GDB batch/structured analysis, ROP, pwntools, seccomp |
| `crypto` | Sessions, hash ID/cracking, RSA, Sage Python, FactorDB, OpenSSL, ZIP cracking |
| `forensics` | Sessions, binwalk, carving, stego, OCR, Volatility, disk/memory automation |
| `network` | Sessions, health, nmap, rustscan |
| `base` | Sessions, shell/workspace helpers, health only |
Presets can be combined: `MCP_AGENT_PRESET=web,pwn` exposes the union and keeps the catalog fallback.
Examples:
```text
list_catalog()
get_tools(family="recon", domain="web")
get_tool("nmap_scan")
run_tool("nmap_scan", {"target": "10.10.10.10", "ports": "80,443"})
run_tool("ffuf_scan", {"url": "http://target/FUZZ"}, save_to_file="ffuf.json")
```
Switch modes/presets:
- **Docker**: set `MCP_EXPOSURE_MODE=agent` and `MCP_AGENT_PRESET=web,pwn` in `docker-compose.yml`
- **Native**: run `src/mcpwn/mcp_server.py --exposure-mode agent --agent-preset web,pwn`
- **Minimal catalog**: use `MCP_EXPOSURE_MODE=compact`
- **All direct wrappers**: use `MCP_EXPOSURE_MODE=full`
Resources from `src/tools/resources.py` stay available in all modes.
---
## MCP Client Configuration
### Claude CLI
```bash
claude mcp add mcpwn --transport http http://localhost:5000/mcp
```
### GitHub Copilot in VS Code
`.vscode/mcp.json` in project root (VS Code 1.99+ required):
```json
{
"servers": {
"mcpwn": {
"type": "http",
"url": "http://localhost:5000/mcp"
}
}
}
```
Open Chat (`Ctrl+Alt+I`) → Agent mode → `mcpwn` tools available.
### Claude Desktop
`%AppData%\Claude\claude_desktop_config.json` (Windows) / `~/.config/Claude/claude_desktop_config.json` (Linux/Mac):
```json
{
"mcpServers": {
"mcpwn": {
"type": "http",
"url": "http://localhost:5000/mcp"
}
}
}
```
#### With Burp Suite (dual server)
```json
{
"mcpServers": {
"mcpwn": {
"type": "http",
"url": "http://localhost:5000/mcp"
},
"burp": {
"command": "java",
"args": ["-jar", "/path/to/burp-mcp-proxy-all.jar", "--sse-url", "http://127.0.0.1:9876"]
}
}
}
```
### 5ire / Other HTTP clients
Any MCP client supporting streamable-http:
```
http://localhost:5000/mcp
```
### Remote Kali via SSH tunnel
```bash
ssh -L 5000:localhost:5000 user@kali-server.example.com
```
---
## Tools Reference
### Default MCP Surface (`agent` mode)
Agent mode exposes common tools directly with native schemas and annotations, while keeping the catalog meta-tools for everything else. The default `ctf-basic` preset exposes 28 direct tools plus the 4 meta-tools.
Call direct tools by exact name when they are listed in your active preset. For tools outside the preset, use the catalog workflow: `get_tools(...)` → `get_tool(name)` → `run_tool(name, arguments)`.
### Catalog Meta-Tools (`agent` and `compact` modes)
| Tool | Purpose |
|------|---------|
| `list_catalog` | List families/domains with counts + descriptions |
| `get_tools` | Filter/search wrappers by family, domain, keyword |
| `get_tool` | Show full docstring + input schema for 1 wrapper |
| `run_tool` | Execute any wrapper by name; optional `save_to_file` into `/output` |
Set `MCP_EXPOSURE_MODE=compact` if you want only these 4 tools. Set `MCP_EXPOSURE_MODE=full` if you want every wrapper below exposed directly as an MCP tool.
### Full-Mode Tool Inventory
| Module | Tools | Description |
|--------|------:|-------------|
| `network.py` | 12 | nmap, rustscan, gobuster, sqlmap, metasploit, hydra, john, wpscan, enum4linux-ng, netexec, execute_command, server_health |
| `sessions.py` | 10 | Persistent workspaces, upload/download, context storage, interactive shell (nc/ssh/gdb) |
| `pwn.py` | 17 | Binary analysis, tracing, pwntools, GDB/pwndbg, patching, seccomp |
| `crypto.py` | 9 | hashcat, RSA attacks, SageMath, hash ID, ZIP cracking, OpenSSL, factordb |
| `forensics.py` | 13 | Volatility3, binwalk, steghide, foremost, exiftool, Saleae `.sal` parsing, PDF inspection, OCR, zsteg, stegseek, automated workflows |
| `cloud.py` | 5 | AWS/gcloud CLI, S3 scanning, IMDS, Pacu |
| `web3.py` | 5 | Slither, Mythril, web3.py, solc, Foundry cast |
| `pcap.py` | 5 | tshark, tcpdump, stream extraction, credential harvesting |
| `osint.py` | 5 | theHarvester, Sherlock, holehe, subfinder, amass |
| `web.py` | 18 | ZAP, nuclei, ffuf, feroxbuster, katana, arjun, raw HTTP, tplmap, dalfox, GraphQL request/probe, SSRFmap, XXE, jwt_tool, httpx, wafw00f |
| `ics.py` | 6 | Modbus read/write, MQTT sniff/publish, ICS nmap scripts, firmware extraction |
| `mobile.py` | 7 | apktool, jadx, dex2jar, androguard, ADB, APK strings |
| `llm.py` | 5 | Prompt fuzzing, multi-turn chat, agentic injection, system prompt leak |
| `ml.py` | 5 | PyTorch/Keras/sklearn inspection, LSB stego, Lambda deserialization, vec2text inversion |
| `resources.py` | — | MCP resources: server status, wordlists, safe-testing guide |
| **Total direct MCP tools (`full`)** | **122** | Verified by `tests/test_mcp_runtime.py` |
---
### Network & Web (Basic)
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `nmap_scan` | Port scan, version detection | `target` |
| `rustscan_scan` | Fast port scan + nmap handoff | `target`, `ports` |
| `gobuster_scan` | DNS/vhost brute-force | `url`, `mode` |
| `sqlmap_scan` | SQL injection detection + exploitation | `url` |
| `wpscan_analyze` | WordPress security scan | `url` |
| `enum4linux_ng_scan` | SMB/Samba enumeration | `target` |
| `netexec_smb` | SMB fingerprinting and credentialed enum | `target`, `username`, `password` |
| `metasploit_run` | Exploit module execution | `module`, `options` |
| `hydra_attack` | Online password brute-force | `target`, `service`, `username`, `password_file` |
| `john_crack` | Offline hash cracking | `hash_file` |
| `execute_command` | Generic shell command | `command` |
| `server_health` | Check Kali API health | — |
### Web (Advanced)
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `zap_spider` | Crawl target, enumerate all paths | `target` |
| `zap_active_scan` | Full automated vuln scan (spider + attack) | `target`, `timeout` |
| `zap_alerts` | Retrieve ZAP findings without re-scan | `target`, `risk_filter` |
| `nuclei_scan` | Template-based scanning (6000+ checks) | `target`, `templates`, `severity` |
| `ffuf_scan` | Web fuzzing with FUZZ placeholder | `url`, `wordlist`, `filter_code` |
| `feroxbuster_scan` | Recursive content discovery | `url`, `wordlist`, `extensions` |
| `katana_crawl` | JS-aware crawling and endpoint discovery | `url`, `depth` |
| `arjun_scan` | Hidden parameter discovery | `url`, `method` |
| `raw_http_request` | Literal raw HTTP/1.x over TCP/TLS | `raw_request`, `host`, `port`, `use_https` |
| `tplmap_scan` | SSTI detection + exploitation | `url` (mark with `*`), `os_cmd` |
| `dalfox_scan` | XSS scanner with DOM verification | `url`, `blind_xss_url` |
| `graphql_request` | Arbitrary GraphQL GET/POST request with vars/headers | `url`, `query`, `variables`, `operation_name` |
| `graphql_probe` | GraphQL fingerprint / schema enum / injection | `url`, `technique` |
| `ssrf_test` | SSRF exploitation via SSRFmap | `request_file`, `parameter`, `module` |
| `xxe_test` | XXE injection payloads | `url`, `target_file` |
| `jwt_tool_attack` | JWT attack and token analysis | `jwt_token`, `mode` |
| `httpx_probe` | HTTP fingerprinting across many hosts | `targets`, `ports` |
| `wafw00f_scan` | WAF detection/fingerprinting | `target` |
### Pwnable / Binary Exploitation
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `checksec_binary` | Show protections (NX, PIE, Canary, RELRO) | `session_id`, `binary_filename` |
| `find_rop_gadgets` | ROPgadget search | `session_id`, `binary_filename` |
| `analyze_with_radare2` | Disassemble/analyse with r2 | `session_id`, `binary_filename`, `commands` |
| `disassemble_binary` | objdump disassembly | `session_id`, `binary_filename` |
| `trace_syscalls` | strace | `session_id`, `binary_filename` |
| `trace_library_calls` | ltrace | `session_id`, `binary_filename` |
| `extract_strings` | strings extraction | `session_id`, `binary_filename` |
| `run_pwntools_exploit` | Run pwntools Python exploit script | `session_id`, `exploit_script` |
| `auto_detect_vulnerabilities` | AI-assisted vuln detection | `session_id`, `binary_filename` |
| `gdb_batch_analyze` | GDB non-interactive batch | `session_id`, `binary_filename`, `commands` |
| `gdb_structured_analyze` | Structured GDB/pwndbg analysis | `session_id`, `binary_filename` |
| `gdb_start_interactive` | Interactive GDB/pwndbg shell | `session_id`, `binary_filename` |
| `one_gadget_find` | one_gadget offsets for libc | `libc_path` |
| `patchelf_patch` | Patch ELF interpreter/rpath/needed libs | `session_id`, `binary_filename` |
| `upx_unpack` | Unpack UPX-packed binaries | `session_id`, `binary_filename` |
| `readelf_inspect` | ELF headers/sections/symbols | `session_id`, `binary_filename`, `mode` |
| `seccomp_analyze` | Dump/disassemble seccomp BPF policies | `session_id`, `binary_filename`, `mode` |
### Cryptography
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `hashcat_crack` | GPU/CPU hash cracking | `hash_value`, `hash_type` |
| `factordb_query` | FactorDB factorization lookup | `number` |
| `rsa_attack` | RsaCtfTool multi-attack | `session_id`, `n`, `e`, `c` |
| `sage_execute` | Full SageMath script | `session_id`, `script` |
| `sage_python_execute` | SageMath via Python | `session_id`, `script` |
| `sage_oneshot` | Quick SageMath one-liner | `expression` |
| `identify_hash` | Identify hash type via name-that-hash | `hash_value` |
| `fcrackzip_crack` | ZIP password brute-force | `zip_path`, `wordlist` |
| `openssl_operation` | Encrypt/decrypt/hash/certificates | `operation`, `input_data` |
### Forensics
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `volatility_analyze` | Volatility3 memory analysis | `dump_file`, `plugin` |
| `binwalk_analyze` | Firmware/binary signature scan | `session_id`, `file_path` |
| `steghide_extract` | Steganography extraction | `cover_file` |
| `foremost_carve` | File carving from disk images | `session_id`, `file_path` |
| `exiftool_analyze` | Metadata extraction | `file_path` |
| `saleae_sal_to_csv` | Parse Saleae Logic 2 `.sal` digital captures into clean CSV (`Time [s],channels...`) | `file_path`, `session_id`, `output_file` |
| `pdf_inspect` | PDF metadata/text/resource inspection via pypdf | `file_path`, `password`, `extract_text` |
| `tesseract_ocr` | OCR text extraction | `image_path` |
| `zsteg_analyze` | PNG/BMP LSB stego (zsteg) | `file_path` |
| `stegseek_crack` | Fast steghide passphrase cracking | `cover_file`, `wordlist` |
| `auto_memory_analysis` | Full automated Volatility workflow | `dump_file` |
| `auto_disk_analysis` | Full automated disk forensics | `session_id`, `disk_image` |
| `auto_malware_hunt` | YARA + IOC + entropy analysis | `session_id`, `file_path` |
> `saleae_sal_to_csv` is a best-effort parser for current Logic 2 digital `.sal` captures. Saleae does not guarantee `.sal` format stability, so if a future capture fails to parse, export raw/binary/CSV from Logic 2 as the stable fallback.
### ICS / Hardware
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `modbus_scan` | Read Modbus TCP registers | `host`, `register_type` |
| `modbus_write` | Write Modbus register (exploitation) | `host`, `register`, `value` |
| `mqtt_sniff` | Subscribe and capture MQTT messages | `host`, `topic`, `duration` |
| `mqtt_publish` | Publish MQTT message | `host`, `topic`, `message` |
| `ics_nmap_scan` | ICS/SCADA device fingerprinting (NSE) | `target` |
| `firmware_analyze` | binwalk deep extraction + file listing | `firmware_path` |
### Mobile
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `apktool_decompile` | Decompile APK → smali + resources | `apk_path` |
| `apktool_recompile` | Recompile modified smali → APK | `source_dir` |
| `jadx_decompile` | Decompile APK/DEX/JAR → Java source | `input_path` |
| `dex2jar_convert` | Convert DEX → JAR | `input_path` |
| `androguard_analyze` | Static analysis: permissions, intents, strings | `apk_path` |
| `adb_command` | ADB command on connected device | `command_args` |
| `apk_strings` | Fast string extraction (flag/secret hunting) | `apk_path`, `filter_pattern` |
### LLM / Prompt Injection
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `prompt_fuzz` | Fuzz endpoint with 38 built-in CTF payloads | `endpoint_url`, `request_template` |
| `llm_probe` | Send custom prompts, capture full responses | `endpoint_url`, `prompts` |
| `llm_multiturn` | Multi-turn conversation with history state | `endpoint_url`, `turns` |
| `agentic_probe` | Agentic function injection (file://, tool misuse) | `endpoint_url`, `known_functions` |
| `system_prompt_leak` | Automated system prompt extraction | `endpoint_url` |
### ML Model Analysis
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `torch_model_inspect` | PyTorch: summary, LSB stego, diagonal ASCII | `model_path`, `technique` |
| `keras_model_inspect` | Keras: Lambda layer deserialization, weight analysis | `model_path`, `technique` |
| `sklearn_model_inspect` | sklearn: decision tree path reversal | `model_path`, `technique`, `target_class` |
| `vec2text_invert` | Invert sentence embeddings → text | `embeddings_path` |
| `ml_script_execute` | Custom Python ML analysis script | `script`, `session_id` |
### Cloud Security
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `aws_cli` | AWS CLI enumeration/actions | `subcommand` |
| `gcloud_cli` | GCP CLI enumeration/actions | `subcommand` |
| `s3_bucket_scan` | S3 bucket permission check | `bucket_name` |
| `cloud_metadata_query` | Query IMDS/metadata endpoint | `provider`, `endpoint` |
| `pacu_aws_exploit` | Pacu AWS exploitation framework | `session_id`, `module` |
### Web3 / Blockchain
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `slither_analyze` | Slither static contract analysis | `contract_path` |
| `mythril_analyze` | Mythril symbolic execution (v0.24.8) | `contract_path` |
| `web3_interact` | Python web3.py script execution | `session_id`, `script` |
| `solidity_compile` | solc contract compilation | `contract_path` |
| `foundry_cast` | Foundry cast RPC/subcommand | `subcommand`, `rpc_url` |
### PCAP / Network Capture
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `pcap_analyze` | High-level PCAP summary | `session_id`, `pcap_file` |
| `tshark_query` | tshark field/filter query | `session_id`, `pcap_file` |
| `tcpdump_read` | tcpdump read mode | `session_id`, `pcap_file` |
| `extract_pcap_streams` | Reconstruct TCP/UDP streams | `session_id`, `pcap_file` |
| `extract_pcap_credentials` | Credential harvesting from PCAP | `session_id`, `pcap_file` |
### OSINT
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `theharvester_scan` | Email/subdomain/IP harvesting | `target` |
| `sherlock_search` | Username presence across 300+ sites | `username` |
| `holehe_scan` | Email account existence check | `email` |
| `subfinder_scan` | Passive/active subdomain enum | `target`, `sources` |
| `amass_enum` | Deep subdomain mapping | `target`, `passive`, `brute` |
### Session Management
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `create_analysis_session` | Create persistent workspace | — |
| `upload_binary` | Upload file to session workspace | `session_id`, `filename`, `content_base64` |
| `download_file` | Download session file as base64 | `session_id`, `filename` |
| `list_session_files` | List workspace files | `session_id` |
| `save_analysis_result` | Store key/value in session context | `session_id`, `key`, `value` |
| `load_analysis_results` | Load all session context | `session_id` |
| `start_interactive_shell` | Start nc/ssh/gdb interactive session | `session_id`, `command` |
| `send_to_shell` | Send input to interactive shell | `interactive_id`, `text` |
| `read_shell_output` | Read buffered shell output | `interactive_id` |
| `close_shell` | Terminate interactive shell | `interactive_id` |
---
## Architecture
```
┌──────────────────────┐ HTTP/MCP ┌─────────────────────────────────────────┐
│ AI Client │◄───────────►│ FastMCP (container :8080, host :5000) │
│ (Claude, Copilot, │ :5000/mcp │ agent: preset direct tools + catalog │
│ 5ire, etc.) │ │ compact: 4 meta-tools │
└──────────────────────┘ │ full: 122 direct wrappers │
└─────────────────────────────────────────┘
│ HTTP
▼
┌─────────────────────────────────────────┐
│ kali_server.py (internal :5000 only) │
│ /api/* → 124 tool endpoints │
│ /health → internal readiness │
│ session manager · ZAP daemon │
└─────────────────────────────────────────┘
Docker / Kali Linux
```
**Two processes internally** (managed by `entrypoint.sh`):
- Flask handles `/api/*`, `/health` — tool execution, session workspaces, ZAP daemon
- FastMCP runs on container port `8080` and is published on host port `5000` as the only external endpoint by default
When you need to inspect Flask directly in Docker, use `docker exec mcpwn curl http://localhost:5000/health` or `docker exec mcpwn curl http://localhost:5000/api/...`.
**`src/tools/`** — One module per capability. Each exports `register_*_tools(mcp, kali_client)`.
---
## Usage Examples
Examples below show **default agent mode**. Direct tools are called by name; tools outside the active preset use the catalog fallback. In `compact` mode, wrap all examples with `run_tool(...)`. In `full` mode, every wrapper is direct.
### RSA Cryptography
```
User: "RSA challenge — n=85188..., e=65537, c=34577..."
AI:
create_analysis_session(user_id="mcpwn")
get_tools(query="factordb") → get_tool("factordb_query")
run_tool("factordb_query", {"number": n}) → factors found
rsa_attack(session_id="<session_id>", n=n, e=e, c=c, attack="all") → decrypted
Flag: CTF{weak_rsa_exponent}
```
### Binary Exploitation
```
User: "Exploit challenge.bin — remote nc host 9001"
AI:
create_analysis_session(user_id="mcpwn") → session created
upload_binary(session_id="<session_id>", ...) → challenge.bin uploaded
checksec_binary(session_id="<session_id>", binary_filename="challenge.bin") → No canary, NX on, No PIE
auto_detect_vulnerabilities(session_id="<session_id>", binary_filename="challenge.bin") → buffer overflow in gets()
find_rop_gadgets(session_id="<session_id>", binary_filename="challenge.bin") → pop rdi; ret @ 0x401234
run_pwntools_exploit(session_id="<session_id>", exploit_script="<generated>")
Flag: CTF{r0p_ch41n_ftw}
```
### Web Application Testing
```
User: "Test http://target.lab for vulnerabilities"
AI:
run_tool("httpx_probe", {"targets": ["target.lab"]}) → Apache 2.4, PHP
run_tool("feroxbuster_scan", {"url": "http://target.lab"}) → /admin, /backup
run_tool("katana_crawl", {"url": "http://target.lab"}) → JS routes, hidden endpoints
run_tool("nuclei_scan", {"target": "http://target.lab", "severity": "critical,high"})
run_tool("zap_active_scan", {"target": "http://target.lab"}) → SQLi, XSS found
```
### SSTI / Template Injection
```
User: "Flask app renders user input — check for SSTI"
AI:
run_tool("tplmap_scan", {"url": "http://target/page?name=*"})
→ Engine: Jinja2 → os_cmd="cat /flag.txt" → HTB{j1nj4_5st1_pwn3d}
```
### Prompt Injection (LLM Challenge)
```
User: "Chat AI at http://target:5000/chat — find the hidden flag"
AI:
run_tool("system_prompt_leak", {"endpoint_url": endpoint_url}) → system prompt leaked
run_tool("agentic_probe", {"endpoint_url": endpoint_url, "known_functions": ["fetch_news"]})
→ fetch_news(url='file:///flag.txt') → HTB{ag3nt1c_s5rf}
```
### ML Model Challenge
```
User: "Keras model malicious.keras — find embedded flag"
AI:
run_tool("keras_model_inspect", {"model_path": model_path, "technique": "lambda_extract"})
→ constants: (72,84,66,...) → HTB{k3r4S_L4y3r_1nj3ct10n}
```
### Memory Forensics
```
User: "Analyse Windows memory dump: memory.dmp"
AI (auto_memory_analysis):
run_tool("create_analysis_session", {"user_id": "mcpwn"})
run_tool("auto_memory_analysis", {"dump_file": "memory.dmp", "session_id": "<session_id>"})
OS: Windows 10 x64 · 47 processes · 12 network connections
→ Suspicious injection in svchost.exe
→ C2: 192.168.1.100:4444
```
---
## Docker
```bash
docker compose up -d # start (builds if no image)
docker compose up -d --build # force rebuild after Dockerfile changes
docker compose logs -f # follow logs
docker compose down # stop
```
Persistent session workspaces live in the Docker-managed `workspaces` volume mounted at `/app/workspaces`. This avoids Windows/Docker Desktop bind-mount startup failures while still preserving generated session files across container restarts.
Named volumes used by current Compose config:
- `workspaces` → `/app/workspaces`
- `input_data` → `/input`
- `output_data` → `/output`
- `wordlists_data` → `/wordlists`
Typical file flow:
```bash
docker cp ./artifact.bin mcpwn:/input/
docker cp ./mylist.txt mcpwn:/wordlists/
docker cp mcpwn:/output/. ./output/
```
Directory fuzzers default to `/usr/share/seclists/Discovery/Web-Content/common.txt`. Custom wordlists copied into container become available under `/wordlists/...`.
Tune the MCP surface for your agent:
```yaml
# docker-compose.yml
environment:
- MCP_EXPOSURE_MODE=agent
- MCP_AGENT_PRESET=web,pwn
```
Expose all wrappers directly instead of agent presets:
```yaml
# docker-compose.yml
environment:
- MCP_EXPOSURE_MODE=full
```
**Dev mode** — mount source for live edits without rebuild:
```yaml
# In docker-compose.yml, uncomment:
# - ./src:/app/src
# - ./kali_server.py:/app/kali_server.py
```
> **Note:** ZAP daemon starts on first `zap_spider`/`zap_active_scan` call (~30s cold start). ML libraries (PyTorch, TensorFlow) are CPU-only — image is large (~8GB), suited for dedicated CTF environments.
## Developer Verification
`tests/test_mcp_runtime.py` lives on the host and is meant for in-runtime/import-based validation, not for packaging into the image.
For a live black-box check against a running container, use `tests/test_live_runtime.py` from a separate runner container so the test stays outside the service image:
```bash
docker create --name mcpwn-runner python:3.12-slim sleep infinity
docker cp tests/test_live_runtime.py mcpwn-runner:/tmp/test_live_runtime.py
docker start mcpwn-runner
docker exec mcpwn-runner python /tmp/test_live_runtime.py --base-url http://host.docker.internal:5000 -v
docker rm -f mcpwn-runner
```
That live suite verifies health, MCP reachability, interactive sessions, and timeout handling for the recent runtime fixes.
For compact/agent/full catalog shape inspection:
```bash
python tests/inspect_mcp.py
```
---
## Legal Notice
For **authorized security testing only**: CTF competitions, authorized penetration testing (written permission required), bug bounty programs (within defined scope), personal lab environments.
Unauthorized access to computer systems is illegal. The authors assume no responsibility for misuse.
