From 63721c610495846ea7b65cb20bf3c05ebe657474 Mon Sep 17 00:00:00 2001 From: meichuanyi <35057768+meichuanyi@users.noreply.github.com> Date: Thu, 7 May 2026 08:24:20 +0800 Subject: [PATCH] docs: add FAQ section for common questions --- README.md | 198 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 194 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4901330..6a43daa 100644 --- a/README.md +++ b/README.md @@ -56,9 +56,9 @@ Any [LiteLLM-supported model](https://docs.litellm.ai/docs/providers) works. ## Run ```bash -pentestagent # Launch TUI -pentestagent -t 192.168.1.1 # Launch with target -pentestagent --docker # Run tools in Docker container +pentestagent # Launch TUI +pentestagent -t 192.168.1.1 # Launch with target +pentestagent tui --docker # Run tools in Docker container ``` ## Docker @@ -123,6 +123,10 @@ PentestAgent has three modes, accessible via commands in the TUI: /memory Show token/memory usage /prompt Show system prompt /mcp Visualizes or adds a new MCP server. +/spawn [target] [--scope CIDR] [--model M] [--no-rag] [--no-mcp] + Manually spawn a child MCP agent from the TUI. +/despawn + Terminate and remove a previously spawned child agent. /clear Clear chat and history /quit Exit (also /exit, /q) /help Show help (also /h, /?) @@ -182,6 +186,48 @@ child_agent_1__get_task_result task_id="" child_agent_2__get_task_result task_id="" ``` +### Manual Child Agent Control (`/spawn` and `/despawn`) + +Beyond 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. + +#### `/spawn` + +``` +/spawn [target] [--scope CIDR ...] [--model MODEL] [--no-rag] [--no-mcp] +``` + +Spawns 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. + +| Argument | Description | +|----------|-------------| +| `target` | Pentest target to pass to the child (positional or `--target`) | +| `--scope CIDR` | One or more in-scope CIDRs (repeatable) | +| `--model MODEL` | Override the model for the child agent | +| `--no-rag` | Skip RAG engine initialisation on the child | +| `--no-mcp` | Skip external MCP server connections on the child | + +**Examples:** + +``` +/spawn 10.0.1.1 +/spawn 10.0.1.1 --scope 10.0.1.0/24 --model claude-sonnet-4-20250514 +/spawn --target 10.0.1.1 --scope 10.0.1.0/24 --no-rag +``` + +#### `/despawn` + +``` +/despawn +``` + +Terminates 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 `/mcp list` to see the names of all currently active child agents. + +**Example:** + +``` +/despawn child_agent_1 +``` + ### MCP RAG Tool Optimizer When an MCP server exposes more than 128 tools, PentestAgent automatically replaces the full catalogue with a single `mcp__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. @@ -408,6 +454,150 @@ ruff check pentestagent # Lint Only use against systems you have explicit authorization to test. Unauthorized access is illegal. + +## FAQ + +### General + +**What is PentestAgent?** + +PentestAgent is an AI-powered penetration testing framework for black-box security testing. It supports bug bounty, red-team, and penetration testing workflows with autonomous agent execution, multi-agent collaboration (Crew mode), and MCP tool extensibility. + +**How does PentestAgent differ from Metasploit or Burp Suite?** + +PentestAgent is an AI orchestration layer that can use tools like nmap, msfconsole, and curl. It doesn't replace them — it coordinates them autonomously. You describe the objective, and the agent decides which tools to run, when, and how to chain results. + +### Installation & Setup + +**What Python version is required?** + +Python 3.10+ is required. + +**How do I install PentestAgent?** + +Clone the repo and run the setup script: +```bash +git clone https://github.com/GH05TCREW/pentestagent.git +cd pentestagent +./scripts/setup.sh # Linux/macOS +.\scripts\setup.ps1 # Windows +``` + +Or manually with `pip install -e ".[all]"` and `playwright install chromium`. + +**What API keys do I need?** + +You need an API key from any LiteLLM-supported provider (OpenAI, Anthropic, DeepSeek, etc.). Set it in `.env`: +``` +ANTHROPIC_API_KEY=sk-ant-... +PENTESTAGENT_MODEL=claude-sonnet-4-20250514 +``` + +### LLM Providers + +**Which LLM providers are supported?** + +Any LiteLLM-supported provider works: OpenAI (GPT-4/GPT-5), Anthropic (Claude), DeepSeek, Qwen, local models via Ollama/vLLM, and more. + +**Can I use local models?** + +Yes, via LiteLLM's Ollama or vLLM integration. Set `PENTESTAGENT_MODEL=ollama/llama3` or similar. + +### Modes & Usage + +**What are the different modes?** + +| Mode | Description | +|------|-------------| +| Assist | Single-shot instruction with tool execution | +| Agent | Autonomous execution of a single task | +| Crew | Multi-agent mode with orchestrator spawning specialized workers | +| Interact | Interactive guided mode where the agent helps step-by-step | + +**When should I use Crew mode?** + +Crew mode is best for complex, multi-phase assessments where different agents can work in parallel on reconnaissance, exploitation, and post-exploitation tasks. + +**How do I run a playbook?** + +```bash +pentestagent run -t example.com --playbook thp3_web +``` + +Playbooks provide structured approaches to specific security assessments. + +### MCP & Tools + +**How do I add MCP servers?** + +Edit `mcp_servers.json` or use the CLI: +```bash +pentestagent mcp add nmap npx -y gc-nmap-mcp +``` + +**What is the spawn_mcp_agent tool?** + +It allows a running agent to spawn child copies of itself as MCP servers. Each child is fully isolated with its own runtime, LLM client, and tool set. This enables hierarchical multi-agent workflows. + +**How do I spawn a child agent manually?** + +Use `/spawn` in the TUI: +``` +/spawn 10.0.1.1 --scope 10.0.1.0/24 --model claude-sonnet-4-20250514 +``` + +**What happens when an MCP server has >128 tools?** + +PentestAgent replaces the full catalogue with a `mcp__rag_optimizer` meta-tool that retrieves relevant tools via embedding similarity. + +### Docker + +**Why use Docker mode?** + +Docker provides isolation and pre-installed pentesting tools (nmap, metasploit, sqlmap, etc.) without modifying your host system. + +**How do I run in Docker?** + +```bash +pentestagent tui --docker +# Or pull the pre-built image +docker run -it -e ANTHROPIC_API_KEY=your-key ghcr.io/gh05tcrew/pentestagent:kali +``` + +### Troubleshooting + +**Agent is not executing tools.** + +- Check API key in `.env` +- Verify target is set (`/target ` or `-t` flag) +- Ensure tools are enabled (`/tools` to list) + +**Child agent not responding.** + +- Check child's model override with `--model` +- Use `/mcp list` to verify child is spawned +- Use `/despawn ` to terminate and respawn + +**MCP server connection failed.** + +- Use `pentestagent mcp test ` to diagnose +- Check `mcp_servers.json` for correct command/args +- Verify the MCP server package is installed + +**Where are notes stored?** + +Notes are saved to `loot/notes.json` and persist across sessions. Use `/notes` to view. + +**How do I generate a report?** + +Use `/report` in the TUI to generate a report from the current session. + +### Legal & Ethics + +**Can I use PentestAgent on any system?** + +No. Only use against systems you have **explicit authorization** to test. Unauthorized access is illegal. + ## License -MIT \ No newline at end of file +MIT