<div align="center">

PengStrike AI MCP

AI-Powered MCP Penetration Testing Framework — 150+ security tools, adaptive async task model, crash-proof concurrency

English | 简体中文

</div>

---

Table of Contents

• What is PengStrike?
• Key Features
• Architecture
• Quick Start
• AI Usage Protocol
• A Typical AI Session
• Tool Inventory
• API Reference
• Comparison
• Directory Structure
• FAQ
• Contributing
• Security
• 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)

# 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:

{
  "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:

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_ids.
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:

   {"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:

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"}}'

{"task_id": "a1b2c3d4", "status": "running", "elapsed": 0}

Check live progress, then harvest the batch:

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}'

{"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 — 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 first.

---

Security

Found a security issue in PengStrike itself? Please read our SECURITY.md and follow the coordinated disclosure process. Do not open a public issue for vulnerabilities.

---

License & Disclaimer

Licensed under the MIT 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.