PengStrike AI MCP
README.md
<div align="center">
# PengStrike AI MCP
### AI-Powered MCP Penetration Testing Framework — 150+ security tools, adaptive async task model, crash-proof concurrency
[](https://www.python.org/)
[](LICENSE)
[](https://modelcontextprotocol.io/)
[](#)
[](#)
[](https://github.com/wangqiongpeng/pengstrike-mcp/actions/workflows/ci.yml)
[](#)
[](#)
**English** | [简体中文](README_zh.md)
</div>
---
## Table of Contents
- [What is PengStrike?](#what-is-pengstrike)
- [Key Features](#key-features)
- [Architecture](#architecture)
- [Quick Start](#quick-start)
- [AI Usage Protocol](#ai-usage-protocol)
- [A Typical AI Session](#a-typical-ai-session)
- [Tool Inventory](#tool-inventory)
- [API Reference](#api-reference)
- [Comparison](#comparison)
- [Directory Structure](#directory-structure)
- [FAQ](#faq)
- [Contributing](#contributing)
- [Security](#security)
- [License & Disclaimer](#license--disclaimer)
---
## What is PengStrike?
PengStrike is an **MCP (Model Context Protocol) server** that turns any MCP-capable AI agent (Trae, Claude, GPT, Cursor, etc.) into a **professional penetration testing platform**. The AI calls 150+ real security tools — `nmap`, `nuclei`, `sqlmap`, `metasploit`, `hydra`, `ghidra`, and more — through a single unified MCP interface, while the server handles the hard parts: **concurrent job scheduling, task lifecycle management, streaming output, and memory protection**.
It is a **two-script system**:
| Script | Role | Where it runs |
| --- | --- | --- |
| `pengstrike_server.py` | HTTP server: executes real tools, manages tasks, streams output, protects memory | Kali Linux / any Linux with Python 3.10+ |
| `pengstrike_mcp.py` | MCP client: thin FastMCP wrapper that connects the AI IDE to the server | Any machine hosting the AI IDE (Windows / macOS / Linux) |
**Who is it for?**
- **Red teams & pentesters** who want AI-assisted reconnaissance, scanning, and exploitation with real, battle-tested tools.
- **CTF players** who need automated scanning + binary/pwn analysis from a single chat interface.
- **Security researchers** building AI agents that need a reliable, concurrent tool-execution backend.
**What problem does it solve?** Naive MCP tool integrations run tools synchronously: a long `nmap` scan blocks the whole conversation for minutes, the AI misjudges it as "failed" and retries (spawning duplicate scans), and a heavy scan starves fast queries like `curl`. PengStrike's **adaptive task model** removes all of that pain: fast tools return instantly, slow tools return a `task_id` immediately, and the AI collects results later with a single `harvest_tasks` call.
---
## Key Features
### 1. Adaptive Sync/Async Task Model
Every tool call behaves optimally without the AI doing anything special:
- **Fast tools (<10s)** — `httpx`, `dig`, `curl`, quick probes — return the **full result synchronously**. The AI sees a normal answer, no change in behavior.
- **Slow tools** — `nmap`, `nuclei`, `sqlmap`, `hydra` — return `{task_id, status: "running"}` **immediately**, and keep running in the background. The AI can launch many scans in parallel, then collect all results in one `harvest_tasks` call.
- **Python scripts** get an extended 120s synchronous window (`PY_SCRIPT_SYNC_WINDOW`) so typical analysis/probing scripts return complete output without flip-flopping between success and a "running snapshot".
### 2. Hard Concurrency Cap of 10 with QoS Scheduling
- Fixed `ThreadPoolExecutor(10)` pool — never more than 10 concurrent jobs, protecting the server from task storms.
- **QoS two-tier scheduling**: 2 fast slots (immediate tools like `httpx`/`dig`/`curl`) + 8 heavy slots (`nmap`/`sqlmap`). A long-running heavy scan **cannot starve** a quick status query.
### 3. Streaming Output Engine (Memory-Stable by Design)
- Output is **written to disk as it streams**; memory keeps only `head (16KB) + tail (64KB)` per stream.
- With 10 concurrent jobs producing 140MB of combined output, the server RSS stays at ~15MB — **memory is structurally bounded, not reactively trimmed**.
### 4. SQLite (WAL) Task Ledger
- Every task and its result is persisted to `pengstrike_tasks.db` (WAL mode).
- **Server restart does not lose completed results** — the AI can still harvest by `task_id` from the ledger.
- Running tasks interrupted by a restart are honestly marked `interrupted` (never falsely "completed").
### 5. Orphan Task Reclamation
- When the AI finishes an answer and disappears, background scans that are **unqueried for 25 minutes with no new output** are automatically canceled, freeing concurrency slots.
- Long scans that keep producing live output are **not** affected.
### 6. Four-Level Memory Protection
- Per-stream truncation at 8MB, 60MB global budget, plus a **runtime memory monitor** with escalation: `ok → tight → critical → kill`. OOM is impossible by design.
### 7. Aggregate Harvest / Incremental Sync / Live Progress
- `harvest_tasks(task_ids=[...])` collects **multiple** tasks in one round-trip.
- `list?since_seq=N` gives incremental task sync (polling-efficient).
- Each running task carries live progress: `elapsed`, `bytes`, `lines`, `last_line`, PID.
### 8. Robust Transport Layer
- Client auto-retries transient connection errors (with backoff) — no more "MCP 偶发失败" during heavy parallel scans.
- Read timeouts never spawn duplicate scans (ReadTimeout is not retried).
- Large outputs are truncated with a hint pointing to `read_output_file` for paging.
---
## Architecture
```
┌─ AI Agent (Trae / Claude / GPT / Cursor) ───────────────────┐
│ Rule 1: any tool call → result within 10s; else task_id │
│ Rule 2: got task_id → do other work in parallel → │
│ harvest_tasks() collects everything at once │
└───────────────────── MCP protocol ─────────────────────────┘
┌─ MCP Client (pengstrike_mcp.py, thin shell) ───────────────┐
│ safe_post: pure submit, no hidden polling │
│ Tools: harvest_tasks / get_task_result / cancel_task / │
│ list_active_tasks / read_output_file │
└───────────────────── HTTP ─────────────────────────────────┘
┌─ Server (pengstrike_server.py, TaskManager v2) ────────────┐
│ ThreadPoolExecutor(10) + QoS (2 fast + 8 heavy) │
│ SQLite(WAL) task ledger + orphan reaper + TTL cleanup │
│ Streaming to disk: memory keeps head+tail only │
└────────────────────────────────────────────────────────────┘
```
The design rule is simple: **everything returns immediately, and harvesting is explicit**. There is no hidden blocking, no implicit polling magic — the AI always knows exactly what is running and how to get its results.
---
## Quick Start
### Requirements
| Side | Requirements |
| --- | --- |
| **Server** | Kali Linux 2024.1+ (or any Linux with Python 3.10+), 150+ external security tools installed from their official sources |
| **Client** | Windows / macOS / Linux, any MCP-capable AI IDE |
### Step 1 — Deploy the server (Kali / Linux)
```bash
# Create and activate a virtualenv
python3 -m venv pengstrike_env
source pengstrike_env/bin/activate
# Install Python dependencies
pip install -r requirements.txt
# Start the server (SINGLE INSTANCE ONLY!)
python3 pengstrike_server.py --port 8888
# Verify health
curl http://127.0.0.1:8888/health
# Verify the task API is live
curl -X POST http://127.0.0.1:8888/api/task/cleanup_all \
-H "Content-Type: application/json" -d '{"reason":"check"}'
# Expected: {"success":true,"canceled_count":0}
```
> **IMPORTANT**: SQLite(WAL) is single-writer. **Never run multiple server instances** against the same database. The schema may change between versions — delete `pengstrike_tasks.db` when upgrading.
### Step 2 — Configure the MCP client (AI IDE)
Edit `pengstrike-ai-mcp.json` with your real paths, then import it in your AI IDE's MCP settings:
```json
{
"mcpServers": {
"pengstrike-ai": {
"command": "C:\\path\\to\\pengstrike_env\\Scripts\\python.exe",
"args": [
"C:\\path\\to\\pengstrike_mcp.py",
"--server",
"http://127.0.0.1:8888"
],
"description": "PengStrike AI v6.0 - Advanced Cybersecurity Automation Platform",
"timeout": 1200,
"alwaysAllow": []
}
}
}
```
If the server is not on the same machine, expose it through an SSH tunnel:
```bash
ssh -L 8888:127.0.0.1:8888 kali@<server-ip>
```
### Step 3 — Verify end-to-end
1. In your AI IDE, ask the agent: *"Run `nmap -sV` against 127.0.0.1"*.
2. You should see either a full result (fast) or a `task_id` returned instantly.
3. Ask the agent to *"harvest the tasks"* — results come back in one call.
---
## AI Usage Protocol
The AI follows a simple, deterministic protocol:
1. **Fast tool (<10s)** → full result returned. Use as normal.
2. **Received `{task_id, status:"running"|"queued"}`** → do **NOT** retry the same tool. Launch other reconnaissance in parallel and accumulate a batch of `task_id`s.
3. **Harvest** → call `harvest_tasks(task_ids=[...], wait=120)` to collect all completed results at once.
4. **Decide** → use `list_active_tasks()` to check progress of unfinished tasks; use `cancel_task()` on worthless tasks to free slots.
5. **Huge output** → when `output_truncated=true`, use `read_output_file` to page through the rest.
---
## A Typical AI Session
Here is what a real session looks like end-to-end — no magic, just the protocol:
**User:** *"Scan 127.0.0.1 and tell me what's running."*
1. **AI** calls `nmap_scan(target="127.0.0.1", args="-sV -sC -O")`.
2. **Server** knows the scan will take >10s and replies **immediately**:
```json
{"task_id": "a1b2c3d4", "status": "running", "elapsed": 0}
```
3. **AI does NOT retry.** Instead it launches parallel work while `nmap` runs in the background:
- `subfinder_scan(target="example.com")` — domain recon
- `httpx_probe(targets=["127.0.0.1"])` — web discovery
- a quick `curl http://127.0.0.1/` — fast tools return synchronously
4. **AI** collects everything with a single call:
`harvest_tasks(task_ids=["a1b2c3d4", "e5f6g7h8"], wait=120)`
5. **Server** waits up to 120s for the batch, then returns the full `nmap` + `httpx` output in one JSON payload.
6. **AI** analyzes the open ports and proceeds with the next step — e.g. `nuclei_scan` for known CVEs, or `hydra_attack` against a discovered SSH service.
The same pattern scales to a 20-step engagement: every slow tool returns a `task_id`, the AI juggles many in parallel, and harvests them in batches. Fast, predictable, and crash-proof.
---
## Tool Inventory
PengStrike integrates 150+ external security tools (installed separately from official sources) across these categories:
- **Network & Reconnaissance (25+):** nmap, masscan, rustscan, autorecon, amass, subfinder, fierce, dnsenum, theharvester, responder, netexec, enum4linux-ng, smbmap, ...
- **Web Application (40+):** gobuster, feroxbuster, ffuf, dirb, dirsearch, nuclei, nikto, sqlmap, wpscan, arjun, paramspider, x8, katana, httpx, dalfox, jaeles, hakrawler, gau, waybackurls, wafw00f, ...
- **Authentication & Password (12+):** hydra, john, hashcat, medusa, patator, netexec, evil-winrm, ...
- **Binary Analysis & Reverse Engineering (25+):** ghidra, radare2, gdb, binwalk, ropgadget, checksec, strings, objdump, volatility, foremost, steghide, exiftool, pwntools, angr, ...
- **Cloud & Container (20+):** prowler, scout-suite, trivy, kube-hunter, kube-bench, docker-bench-security, checkov, terrascan, falco, ...
- **CTF & Forensics (20+):** volatility3, autopsy, sleuthkit, stegsolve, zsteg, outguess, photorec, testdisk, scalpel, bulk-extractor, ...
- **OSINT & Intelligence (20+):** sherlock, social-analyzer, recon-ng, maltego, spiderfoot, shodan-cli, censys-cli, ...
> Each tool is exposed as an MCP tool with a clear description. The server builds shell commands safely (quoting, path escaping) and executes them with full task-model semantics.
---
## API Reference
| Endpoint | Method | Description |
| --- | --- | --- |
| `/api/command` | POST | Execute a tool (sync result or `task_id`) |
| `/api/task/harvest` | POST | Aggregate harvest of multiple tasks |
| `/api/task/status/<task_id>` | GET | Task status + live progress |
| `/api/task/result/<task_id>?wait=N` | GET | Single-task harvest (head+tail payload) |
| `/api/task/cancel/<task_id>` | POST | Cancel a task (kills the process tree) |
| `/api/task/list?since_seq=N` | GET | Incremental task list sync |
| `/api/task/cleanup_all` | POST | Cancel all active tasks |
| `/api/output/read` | GET | Page through huge outputs |
| `/health` | GET | Health check |
### Example request flow
Submit a slow tool — the server returns a `task_id` immediately:
```bash
curl -s -X POST http://127.0.0.1:8888/api/command \
-H "Content-Type: application/json" \
-d '{"tool": "nmap_scan", "args": {"target": "127.0.0.1", "args": "-sV"}}'
```
```json
{"task_id": "a1b2c3d4", "status": "running", "elapsed": 0}
```
Check live progress, then harvest the batch:
```bash
curl -s http://127.0.0.1:8888/api/task/status/a1b2c3d4
curl -s -X POST http://127.0.0.1:8888/api/task/harvest \
-H "Content-Type: application/json" \
-d '{"task_ids": ["a1b2c3d4"], "wait": 120}'
```
```json
{"results": [{"task_id": "a1b2c3d4", "status": "completed", "stdout": "...", "output_truncated": false}]}
```
When `output_truncated: true`, page through the rest with
`GET /api/output/read?path=<full_output_path>&offset=<bytes>`.
---
## Comparison
| Capability | Typical MCP tool integration | PengStrike |
| --- | --- | --- |
| Long scans (nmap/sqlmap) | Block the conversation / risk misjudged as "failed" | Return `task_id` instantly; harvest later |
| Parallel scans | Serial by default | 10 concurrent, QoS two-tier |
| Server memory under load | Grows with output | Stable ~15MB (streams to disk) |
| Server restart | Loses all task state | SQLite ledger preserves results |
| Orphaned scans | Keep running, waste slots | Auto-reclaimed after 25 min |
| Duplicate retries | AI retries → duplicate scans | ReadTimeout never retried; `task_id` semantics |
---
## Directory Structure
```
pengstrike_server.py # HTTP server (tool execution / task management / memory guard)
pengstrike_mcp.py # MCP client (FastMCP wrapper)
pengstrike-ai-mcp.json # MCP server configuration example
TASK_MODEL_DESIGN.md # Task model architecture design (v1 → v2 evolution)
requirements.txt # Python dependencies
```
---
## FAQ
**Q: Why does the AI sometimes get a `task_id` instead of a result?**
Because the tool takes longer than 10s. This is by design — the task runs in the background, and you collect it with `harvest_tasks` / `get_task_result`. Do not retry the same tool.
**Q: Can I run the server on Windows?**
The client can run on Windows, but the server is designed for Kali/Linux (many external tools are Linux-only, e.g. `enum4linux-ng`, `responder`). Use the SSH tunnel pattern if your AI IDE is on Windows.
**Q: How do I avoid OOM during big parallel scans?**
You don't need to — the server bounds memory structurally: per-stream 8MB truncation, 60MB global budget, and a runtime monitor that escalates to kill before OOM.
**Q: Can multiple server instances share the database?**
No. SQLite(WAL) is single-writer. Run exactly one server instance.
**Q: Where does `read_output_file` come in?**
When a scan's output exceeds the returned chunk, the result includes `output_truncated=true` plus the path of the full output file. Call `read_output_file(file_path=..., offset=...)` to page through it.
**Q: Is this a Metasploit / Cobalt Strike replacement?**
No. PengStrike is the *orchestration layer*: it lets an AI drive 150+ standalone tools (including Metasploit itself, via `metasploit_run`) through one MCP interface. It complements existing frameworks rather than replacing them.
**Q: Can the AI really run arbitrary commands?**
Yes — `execute_command` runs shell commands and `execute_python_script` runs Python. That is by design (it is a pentesting tool). Only deploy the server on a host you fully trust, and only use it against targets you are authorized to test.
**Q: How do I add a tool that is not in the inventory?**
Read [CONTRIBUTING.md](CONTRIBUTING.md#adding-a-new-tool) — adding a tool takes one endpoint on the server plus one MCP registration on the client, and usually less than 30 lines.
**Q: Is output still available after a server restart?**
Completed results live in the SQLite ledger and can be harvested after a restart. Tasks that were interrupted mid-run are honestly marked `interrupted` — never falsely reported as completed.
---
## Contributing
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
---
## Security
Found a security issue in PengStrike itself? Please read our [SECURITY.md](SECURITY.md) and follow the coordinated disclosure process. Do **not** open a public issue for vulnerabilities.
---
## License & Disclaimer
Licensed under the [MIT License](LICENSE).
> **DISCLAIMER**: PengStrike is intended for **authorized** security testing, penetration testing, CTF, and security research only. You must have explicit written authorization for every target you test. The developers assume no responsibility for any misuse. Illegal use is strictly prohibited.
This server cannot be deployed
Maintenance
ActivitySlowing
ResponsivenessNo issues