[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-72505":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":42,"readmeContent":43,"aiSummary":44,"trendingCount":16,"starSnapshotCount":16,"syncStatus":45,"lastSyncTime":46,"discoverSource":47},72505,"pentestagent","GH05TCREW\u002Fpentestagent","GH05TCREW","PentestAgent is an AI agent framework for black-box security testing, supporting bug bounty, red-team, and penetration testing workflows.","",null,"Python",2625,520,27,11,0,19,112,296,57,110.15,"MIT License",false,"main",true,[27,28,29,30,31,32,33,34,35,36,37,38,39,40,41],"ai","ai-agents","ai-assistant","ai-cybersecurity","ai-hacking","ai-security-tool","blackbox-testing","ctf-tools","knowledge-graph","llm","mcp-tools","penetration-testing","pentesting-tools","red-teaming","security-automation","2026-06-12 04:01:06","\u003Cdiv align=\"center\">\n\n\u003Cimg src=\"assets\u002Fpentestagent-logo.png\" alt=\"PentestAgent Logo\" width=\"220\" style=\"margin-bottom: 20px;\"\u002F>\n\n# PentestAgent\n### AI Penetration Testing\n\n[![Python](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPython-3.10%2B-blue.svg)](https:\u002F\u002Fwww.python.org\u002F) [![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-green.svg)](LICENSE.txt) [![Version](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FVersion-0.2.0-orange.svg)](https:\u002F\u002Fgithub.com\u002FGH05TCREW\u002Fpentestagent\u002Freleases) [![Security](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSecurity-Penetration%20Testing-red.svg)](https:\u002F\u002Fgithub.com\u002FGH05TCREW\u002Fpentestagent) [![MCP](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMCP-Compatible-purple.svg)](https:\u002F\u002Fgithub.com\u002FGH05TCREW\u002Fpentestagent)\n\n\u003C\u002Fdiv>\n\nhttps:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fa67db2b5-672a-43df-b709-149c8eaee975\n\n## Requirements\n\n- Python 3.10+\n- API key for OpenAI, Anthropic, or other LiteLLM-supported provider\n\n## Install\n\n```bash\n# Clone\ngit clone https:\u002F\u002Fgithub.com\u002FGH05TCREW\u002Fpentestagent.git\ncd pentestagent\n\n# Setup (creates venv, installs deps)\n.\\scripts\\setup.ps1   # Windows\n.\u002Fscripts\u002Fsetup.sh    # Linux\u002FmacOS\n\n# Or manual\npython -m venv venv\n.\\venv\\Scripts\\Activate.ps1  # Windows\nsource venv\u002Fbin\u002Factivate     # Linux\u002FmacOS\npip install -e \".[all]\"\nplaywright install chromium  # Required for browser tool\n```\n\n## Configure\n\nCreate `.env` in the project root:\n\n```\nANTHROPIC_API_KEY=sk-ant-...\nPENTESTAGENT_MODEL=claude-sonnet-4-20250514\n```\n\nOr for OpenAI:\n\n```\nOPENAI_API_KEY=sk-...\nPENTESTAGENT_MODEL=gpt-5\n```\n\nAny [LiteLLM-supported model](https:\u002F\u002Fdocs.litellm.ai\u002Fdocs\u002Fproviders) works.\n\n## Run\n\n```bash\npentestagent                      # Launch TUI\npentestagent -t 192.168.1.1       # Launch with target\npentestagent tui --docker         # Run tools in Docker container\n```\n\n## Docker\n\nRun tools inside a Docker container for isolation and pre-installed pentesting tools.\n\n### Option 1: Pull pre-built image (fastest)\n\n```bash\n# Base image with nmap, netcat, curl\ndocker run -it --rm \\\n  -e ANTHROPIC_API_KEY=your-key \\\n  -e PENTESTAGENT_MODEL=claude-sonnet-4-20250514 \\\n  ghcr.io\u002Fgh05tcrew\u002Fpentestagent:latest\n\n# Kali image with metasploit, sqlmap, hydra, etc.\ndocker run -it --rm \\\n  -e ANTHROPIC_API_KEY=your-key \\\n  ghcr.io\u002Fgh05tcrew\u002Fpentestagent:kali\n```\n\n### Option 2: Build locally\n\n```bash\n# Build\ndocker compose build\n\n# Run\ndocker compose run --rm pentestagent\n\n# Or with Kali\ndocker compose --profile kali build\ndocker compose --profile kali run --rm pentestagent-kali\n```\n\nThe container runs PentestAgent with access to Linux pentesting tools. The agent can use `nmap`, `msfconsole`, `sqlmap`, etc. directly via the terminal tool.\n\nRequires Docker to be installed and running.\n\n## Modes\n\nPentestAgent has three modes, accessible via commands in the TUI:\n\n| Mode | Command | Description |\n|------|---------|-------------|\n| Assist | `\u002Fassist \u003Ctask>` | One single-shot instruction, with tool execution |\n| Agent | `\u002Fagent \u003Ctask>` | Autonomous execution of a single task |\n| Crew | `\u002Fcrew \u003Ctask>` | Multi-agent mode. Orchestrator spawns specialized workers |\n| Interact | `\u002Finteract \u003Ctask>` | Interactive mode. Chat with the agent, it will help you and guide during the pentesting procedure |\n\n### TUI Commands\n\n```\n\u002Fassist \u003Ctask>    One single-shot instruction.\n\u002Fagent \u003Ctask>     Run autonomous agent on task\n\u002Fcrew \u003Ctask>      Run multi-agent crew on task\n\u002Finteract \u003Ctask>  Chat with the agent in guided mode\n\u002Ftarget \u003Chost>    Set target\n\u002Ftools            List available tools\n\u002Fnotes            Show saved notes\n\u002Freport           Generate report from session\n\u002Fmemory           Show token\u002Fmemory usage\n\u002Fprompt           Show system prompt\n\u002Fconversations    Browse and restore saved conversations\n\u002Fmcp \u003Clist\u002Fadd>   Visualizes or adds a new MCP server.\n\u002Fspawn [target] [--scope CIDR] [--model M] [--no-rag] [--no-mcp]\n                  Manually spawn a child MCP agent from the TUI.\n\u002Fdespawn \u003Cserver_name>\n                  Terminate and remove a previously spawned child agent.\n\u002Fclear            Clear chat and history\n\u002Fquit             Exit (also \u002Fexit, \u002Fq)\n\u002Fhelp             Show help (also \u002Fh, \u002F?)\n```\n\nPress `Esc` to stop a running agent. `Ctrl+Q` to quit.\n\n## Playbooks\n\nPentestAgent includes prebuilt **attack playbooks** for black-box security testing. Playbooks define a structured approach to specific security assessments.\n\n**Run a playbook:**\n\n```bash\npentestagent run -t example.com --playbook thp3_web\n```\n\n![Playbook Demo](assets\u002Fplaybook.gif)\n\n## Tools\n\nPentestAgent includes built-in tools and supports MCP (Model Context Protocol) for extensibility.\n\n**Built-in tools:** `terminal`, `browser`, `notes`, `web_search` (requires `TAVILY_API_KEY`), `spawn_mcp_agent`\n\n### Agent Self-Spawning (`spawn_mcp_agent`)\n\n`spawn_mcp_agent` is a built-in tool that allows a running agent to spawn a child copy of itself as a subordinate MCP server connected over stdio. The child process is fully isolated — its own runtime, LLM client, conversation history, and notes store — and its complete tool set is injected back into the parent agent's available tools after spawning.\n\nThis enables hierarchical, multi-agent workflows without any external orchestration: the agent self-organises by delegating scoped subtasks to children it spawns on demand.\n\n| Argument | Type | Default | Description |\n|----------|------|---------|-------------|\n| `target` | string | — | Pentest target to pass to the child |\n| `scope` | string[] | — | In-scope targets\u002FCIDRs for the child |\n| `model` | string | env var | Model identifier, overrides `PENTESTAGENT_MODEL` on the child |\n| `no_rag` | boolean | `false` | Skip RAG engine initialisation on the child |\n| `no_mcp` | boolean | `true` | Skip external MCP server connections on the child (recommended) |\n\nAfter `spawn_mcp_agent` returns, the child's tools (`run_task`, `run_task_async`, `await_tasks`, etc.) are available on the **next** tool call. The child's server name is assigned automatically (e.g. `child_agent_1`) and returned in the result.\n\n**Example — orchestrator delegating parallel recon to two children:**\n\n```\n# Turn 1: spawn two isolated child agents\nspawn_mcp_agent  target=\"10.0.1.0\u002F24\"  scope=[\"10.0.1.0\u002F24\"]\nspawn_mcp_agent  target=\"10.0.2.0\u002F24\"  scope=[\"10.0.2.0\u002F24\"]\n\n# Turn 2: children's tools are now available — delegate work asynchronously\nchild_agent_1__run_task_async  task=\"Full port scan and service enumeration\"\nchild_agent_2__run_task_async  task=\"Full port scan and service enumeration\"\n\n# Turn 3: wait and collect\nchild_agent_1__await_tasks  task_ids=[\"\u003Cid1>\"]  timeout_seconds=600\nchild_agent_2__await_tasks  task_ids=[\"\u003Cid2>\"]  timeout_seconds=600\nchild_agent_1__get_task_result  task_id=\"\u003Cid1>\"\nchild_agent_2__get_task_result  task_id=\"\u003Cid2>\"\n```\n\n### Manual Child Agent Control (`\u002Fspawn` and `\u002Fdespawn`)\n\nBeyond the automatic `spawn_mcp_agent` tool, the TUI exposes two commands that let you spawn and terminate child agents **manually**, independently of a running agent loop.\n\n#### `\u002Fspawn`\n\n```\n\u002Fspawn [target] [--scope CIDR ...] [--model MODEL] [--no-rag] [--no-mcp]\n```\n\nSpawns a new child MCP agent over stdio and attaches it to the current session. The child appears as a collapsible terminal panel in the TUI sidebar and its tools become available to the parent agent on the next tool call.\n\n| Argument | Description |\n|----------|-------------|\n| `target` | Pentest target to pass to the child (positional or `--target`) |\n| `--scope CIDR` | One or more in-scope CIDRs (repeatable) |\n| `--model MODEL` | Override the model for the child agent |\n| `--no-rag` | Skip RAG engine initialisation on the child |\n| `--no-mcp` | Skip external MCP server connections on the child |\n\n**Examples:**\n\n```\n\u002Fspawn 10.0.1.1\n\u002Fspawn 10.0.1.1 --scope 10.0.1.0\u002F24 --model claude-sonnet-4-20250514\n\u002Fspawn --target 10.0.1.1 --scope 10.0.1.0\u002F24 --no-rag\n```\n\n#### `\u002Fdespawn`\n\n```\n\u002Fdespawn \u003Cserver_name>\n```\n\nTerminates the child agent identified by `server_name` (e.g. `child_agent_1`), removes its terminal panel from the TUI, and disconnects its tools from the parent session. Use `\u002Fmcp list` to see the names of all currently active child agents.\n\n**Example:**\n\n```\n\u002Fdespawn child_agent_1\n```\n\n### MCP RAG Tool Optimizer\n\nWhen an MCP server exposes more than 128 tools, PentestAgent automatically replaces the full catalogue with a single `mcp_\u003Cserver>_rag_optimizer` tool. This meta-tool uses embedding similarity (via LiteLLM, default `text-embedding-3-small`) to retrieve the most relevant tools for the task at hand and injects them into the agent's next turn — keeping the context window manageable without losing access to the full tool set.\n\nThe optimizer is transparent to the agent: it calls the RAG tool with focused natural-language queries describing what it needs, and the matching tools become available on the next turn to call directly.\n\n**Usage guidance for the agent:**\n\n| Argument | Type | Default | Description |\n|----------|------|---------|-------------|\n| `queries` | string[] | *(required)* | One focused query per capability needed. More specific = higher accuracy |\n| `top_k` | integer | `20` | Tools to retrieve per query (max 128). Results are merged and deduplicated |\n\nEmbeddings are computed once at startup and cached, so repeated queries are fast. The optimizer is built per-server, so each MCP server with a large catalogue gets its own independent index.\n\n> **Tip:** Pass one query per distinct capability rather than combining everything into one query. `[\"list open ports on a host\", \"get process memory usage\"]` retrieves better results than `[\"list ports and memory and CPU\"]`.\n\n### MCP Integration\n\nPentestAgent supports MCP (Model Context Protocol) in two directions: **consuming** external MCP servers as tool sources, and **exposing itself** as an MCP server so external clients (Claude Desktop, Cursor, etc.) can drive PentestAgent programmatically.\n\n---\n\n#### Consuming External MCP Servers (Client Mode)\n\nConfigure `mcp_servers.json` to connect PentestAgent to any external MCP servers. Example config:\n\n```json\n{\n  \"mcpServers\": {\n    \"nmap\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"gc-nmap-mcp\"],\n      \"env\": {\n        \"NMAP_PATH\": \"\u002Fusr\u002Fbin\u002Fnmap\"\n      }\n    }\n  }\n}\n```\n\n---\n\n#### Exposing PentestAgent as an MCP Server (Server Mode)\n\nPentestAgent can run as an MCP server, allowing any MCP-compatible client to submit tasks, inspect results, and control the agent remotely. Two transports are supported:\n\n**STDIO** — for local clients (e.g. Claude Desktop, Cursor):\n\n```bash\npentestagent mcp_server --type stdio\npentestagent mcp_server --type stdio --target 192.168.1.1 --scope 192.168.1.0\u002F24\npentestagent mcp_server --type stdio --model claude-sonnet-4-20250514 --docker\n```\n\n**SSE (HTTP)** — for remote or networked clients:\n\n```bash\npentestagent mcp_server --type sse\npentestagent mcp_server --type sse --host 0.0.0.0 --port 8080\npentestagent mcp_server --type sse --target 10.0.0.1 --scope 10.0.0.0\u002F24 --docker\n```\n\nThe SSE transport exposes a single `\u002Fmcp` endpoint supporting `POST` (requests), `GET` (persistent SSE stream for server-initiated push), and `DELETE` (session teardown). Sessions are tracked via the `Mcp-Session-Id` header.\n\n**All `mcp_server` flags:**\n\n| Flag | Default | Description |\n|------|---------|-------------|\n| `--type` | *(required)* | Transport: `stdio` or `sse` |\n| `--host` | `0.0.0.0` | SSE bind host |\n| `--port` | `8080` | SSE bind port |\n| `--target` | none | Primary pentest target (IP \u002F hostname) |\n| `--scope` | `[]` | In-scope targets\u002FCIDRs (space-separated) |\n| `--model` | env var | Model identifier, overrides `PENTESTAGENT_MODEL` |\n| `--docker` | false | Use DockerRuntime instead of LocalRuntime |\n| `--no-rag` | false | Skip RAG engine initialisation |\n| `--no-mcp` | false | Skip external MCP server connections |\n\n##### Example: Claude Desktop config (`claude_desktop_config.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"pentestagent\": {\n      \"command\": \"pentestagent\",\n      \"args\": [\"mcp_server\", \"--type\", \"stdio\"]\n    }\n  }\n}\n```\n\n---\n\n#### MCP Server Tools Reference\n\nWhen acting as an MCP server, PentestAgent exposes the following tools:\n\n**Server Status & Config**\n\n| Tool | Description |\n|------|-------------|\n| `get_server_status` | Live server status: readiness, task counts by state, primary target\u002Fscope, memory store size |\n| `get_config` | Primary agent configuration: target, scope, max iterations, tool list |\n| `update_config` | Update target, scope, or max iterations for all subsequent tasks |\n\n**Task Execution**\n\n| Tool | Description |\n|------|-------------|\n| `run_task` | Submit a task and **block** until it completes. Returns full result, tools used, and notes snapshot |\n| `run_task_async` | Submit a task and **return immediately** with a `task_id`. Poll with `get_task_status` |\n\n**Task Inspection**\n\n| Tool | Description |\n|------|-------------|\n| `list_tasks` | List all tasks with status, target, and summary. Filterable by status |\n| `get_task_status` | Poll the current status and result preview of a task |\n| `get_task_result` | Full task result: final output, thinking steps, all tool calls and results, notes snapshot |\n| `await_tasks` | Block until a set of async task IDs have all finished (polls every 500 ms, configurable timeout) |\n\n**Task Control**\n\n| Tool | Description |\n|------|-------------|\n| `cancel_task` | Cancel a running or pending task by ID |\n\n**Tool Management**\n\n| Tool | Description |\n|------|-------------|\n| `list_tools` | List all tools available to the agent |\n| `enable_tool` | Enable a named tool on the primary agent |\n| `disable_tool` | Disable a named tool on the primary agent |\n\n\n\n**Conversation History**\n\n| Tool | Description |\n|------|-------------|\n| `get_conversation_history` | Return message history for a task or the primary agent. Supports a `limit` parameter |\n| `reset_conversation` | Clear conversation history for a task or the primary agent |\n\n**Memory**\n\n| Tool | Description |\n|------|-------------|\n| `store_memory` | Persist a key-value pair to the in-process memory store |\n| `retrieve_memory` | Retrieve by exact key, search by substring, or list all keys |\n| `clear_memory` | Delete a specific key or wipe all memory with `scope='all'` |\n\n**Observability**\n\n| Tool | Description |\n|------|-------------|\n| `get_logs` | Return recent execution logs, optionally filtered by level (`info` \u002F `warning` \u002F `error`) |\n| `get_metrics` | Runtime metrics: task counts, success rate, total tool calls, memory and log sizes |\n\n---\n\n#### Async Task Workflow Example\n\nFor long-running recon tasks, use the async pattern:\n\n```\n# 1. Submit tasks without blocking\nrun_task_async  task=\"Enumerate subdomains of example.com\"  target=\"example.com\"\nrun_task_async  task=\"Run nmap SYN scan on example.com\"     target=\"example.com\"\n\n# 2. Block until both finish (up to 5 minutes)\nawait_tasks  task_ids=[\"\u003Cid1>\", \"\u003Cid2>\"]  timeout_seconds=300\n\n# 3. Retrieve full results\nget_task_result  task_id=\"\u003Cid1>\"\nget_task_result  task_id=\"\u003Cid2>\"\n```\n\n---\n\n### CLI Tool Management\n\n```bash\npentestagent tools list         # List all tools\npentestagent tools info \u003Cname>  # Show tool details\npentestagent mcp list           # List MCP servers\npentestagent mcp add \u003Cname> \u003Ccommand> [args...]  # Add MCP server\npentestagent mcp test \u003Cname>    # Test MCP connection\n```\n\n## Conversation History Controls\n\nEach user message in the TUI exposes two inline action buttons: **rewind** and **fork**.\n\n### Rewind\n\nClick **rewind** on any user message to truncate the conversation back to just before that message — both in the UI and in the agent's in-memory history. Use it to retry a query from scratch without saving the discarded path.\n\n### Fork\n\nClick **>> fork** on any user message to branch the conversation from that point:\n\n1. The current full conversation is **saved** to the conversation store and a short snapshot ID is shown.\n2. The conversation is then **truncated** to just before the selected message (same as rewind).\n\nThis lets you try an alternative approach from any point while keeping the original thread retrievable via `\u002Fconversations`.\n\n---\n\n## Conversation History\n\nPentestAgent automatically persists every conversation so you can review, compare, and restore past sessions.\n\n**Auto-save** triggers after each `\u002Fassist`, `\u002Fagent`, `\u002Fcrew`, and `\u002Finteract` task, and before `\u002Fclear`. Up to 20 conversations are kept; older ones are pruned automatically.\n\n**Storage location:** `workspaces\u002F\u003Cactive>\u002Fmemory\u002Fconversations\u002F` when a workspace is active, or `conversations\u002F` at the project root otherwise. Each conversation is a JSON file.\n\n**Browse & restore with `\u002Fconversations`:**\n\nThe `\u002Fconversations` command opens a split-pane modal inside the TUI:\n- **Left panel** — list of saved conversations with title and date.\n- **Right panel** — metadata preview plus the first 5 messages (user messages in blue, agent responses in green, tool calls in yellow, tool results in grey). A count shows how many additional messages exist.\n\n\u003Cimg width=\"1657\" height=\"662\" alt=\"imagen\" src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fda42f083-9b7f-445e-8c59-2402ac8e5ddc\" \u002F>\n\n\nSelect a conversation and press **Restore** to reload it into the current session, or **Close** to dismiss the modal.\n\n## Knowledge\n\n- **RAG:** Place methodologies, CVEs, or wordlists in `pentestagent\u002Fknowledge\u002Fsources\u002F` for automatic context injection.\n- **Notes:** Agents save findings to `loot\u002Fnotes.json` with categories (`credential`, `vulnerability`, `finding`, `artifact`). Notes persist across sessions and are injected into agent context.\n- **Shadow Graph:** In Crew mode, the orchestrator builds a knowledge graph from notes to derive strategic insights (e.g., \"We have credentials for host X\").\n\n## Project Structure\n\n```\npentestagent\u002F\n  agents\u002F         # Agent implementations\n  config\u002F         # Settings and constants\n  interface\u002F      # TUI and CLI\n  knowledge\u002F      # RAG system and shadow graph\n  llm\u002F            # LiteLLM wrapper\n  mcp\u002F            # MCP client and server configs\n  playbooks\u002F      # Attack playbooks\n  runtime\u002F        # Execution environment\n  tools\u002F          # Built-in tools\n```\n\n## Development\n\n```bash\npip install -e \".[dev]\"\npytest                       # Run tests\npytest --cov=pentestagent    # With coverage\nblack pentestagent           # Format\nruff check pentestagent      # Lint\n```\n\n## Legal\n\nOnly use against systems you have explicit authorization to test. Unauthorized access is illegal.\n\n## License\n\nMIT\n","PentestAgent 是一个用于黑盒安全测试的AI代理框架，支持漏洞赏金、红队演练和渗透测试工作流程。该项目使用Python编写，核心功能包括通过AI辅助执行渗透测试任务，支持多种模式如单次指令执行、自主任务执行等，并且能够与Nmap、Metasploit等常用渗透测试工具集成。技术特点上，PentestAgent利用了知识图谱和大语言模型来提高自动化水平和测试效率。适用于需要进行网络安全评估、漏洞发现及验证的各种场景，尤其是那些希望引入人工智能以增强现有安全测试能力的企业或团队。",2,"2026-06-11 03:42:21","high_star"]