PentestAgent

AI पेनेट्रेशन टेस्टिंग

https://github.com/user-attachments/assets/a67db2b5-672a-43df-b709-149c8eaee975

आवश्यकताएँ

Python 3.10+
OpenAI, Anthropic, या अन्य LiteLLM-समर्थित प्रदाता के लिए API कुंजी

इंस्टॉल

# Clone
git clone https://github.com/GH05TCREW/pentestagent.git
cd pentestagent

# Setup (creates venv, installs deps)
.\scripts\setup.ps1   # Windows
./scripts/setup.sh    # Linux/macOS

# Or manual
python -m venv venv
.\venv\Scripts\Activate.ps1  # Windows
source venv/bin/activate     # Linux/macOS
pip install -e ".[all]"
playwright install chromium  # Required for browser tool

कॉन्फ़िगर करें

प्रोजेक्ट रूट में .env बनाएँ:

ANTHROPIC_API_KEY=sk-ant-...
PENTESTAGENT_MODEL=claude-sonnet-4-20250514

या OpenAI के लिए:

OPENAI_API_KEY=sk-...
PENTESTAGENT_MODEL=gpt-5

कोई भी LiteLLM-समर्थित मॉडल काम करता है।

रिले / कस्टम API बेस का उपयोग करना

OPENAI_API_BASE के माध्यम से PentestAgent को किसी भी OpenAI-संगत एंडपॉइंट पर इंगित करें:

OPENAI_API_KEY=your-relay-token
OPENAI_API_BASE=https://relay.example/v1
PENTESTAGENT_MODEL=openai/<model-name-on-your-relay>

Anthropic-संगत एंडपॉइंट के लिए इसके बजाय ANTHROPIC_API_BASE का उपयोग करें। पूर्ण प्रदाता नोट्स और एम्बेडिंग विकल्पों के लिए .env.example देखें।

चलाएँ

pentestagent                      # Launch TUI
pentestagent -t 192.168.1.1       # Launch with target
pentestagent tui --docker         # Run tools in Docker container

डॉकर

अलगाव और पहले से इंस्टॉल किए गए पेनेट्रेशन टेस्टिंग टूल्स के लिए Docker कंटेनर के अंदर टूल्स चलाएँ।

विकल्प 1: पहले से निर्मित इमेज खींचें (सबसे तेज़)

# Base image with nmap, netcat, curl
docker run -it --rm \
  -e ANTHROPIC_API_KEY=your-key \
  -e PENTESTAGENT_MODEL=claude-sonnet-4-20250514 \
  ghcr.io/gh05tcrew/pentestagent:latest

# Kali image with metasploit, sqlmap, hydra, etc.
docker run -it --rm \
  -e ANTHROPIC_API_KEY=your-key \
  ghcr.io/gh05tcrew/pentestagent:kali

विकल्प 2: स्थानीय रूप से बिल्ड करें

# Build
docker compose build

# Run
docker compose run --rm pentestagent

# Or with Kali
docker compose --profile kali build
docker compose --profile kali run --rm pentestagent-kali

कंटेनर Linux पेनेट्रेशन टेस्टिंग टूल्स तक पहुंच के साथ PentestAgent चलाता है। एजेंट टर्मिनल टूल के माध्यम से सीधे nmap, msfconsole, sqlmap, आदि का उपयोग कर सकता है।

Docker को इंस्टॉल और चालू होना आवश्यक है।

मोड

PentestAgent के तीन मोड हैं, जो TUI में कमांड के माध्यम से सुलभ हैं:

TUI कमांड

/assist <task>    One single-shot instruction.
/agent <task>     Run autonomous agent on task
/crew <task>      Run multi-agent crew on task
/interact <task>  Chat with the agent in guided mode
/target <host>    Set target
/tools            List available tools
/notes            Show saved notes
/report           Generate report from session
/memory           Show token/memory usage
/prompt           Show system prompt
/conversations    Browse and restore saved conversations
/mcp <list/add>   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 <server_name>
                  Terminate and remove a previously spawned child agent.
/clear            Clear chat and history
/quit             Exit (also /exit, /q)
/help             Show help (also /h, /?)

चल रहे एजेंट को रोकने के लिए Esc दबाएँ। बाहर निकलने के लिए Ctrl+Q दबाएँ।

प्लेबुक

PentestAgent में ब्लैक-बॉक्स सुरक्षा परीक्षण के लिए पहले से निर्मित अटैक प्लेबुक शामिल हैं। प्लेबुक विशिष्ट सुरक्षा मूल्यांकनों के लिए एक संरचित दृष्टिकोण परिभाषित करते हैं।

प्लेबुक चलाएँ:

pentestagent run -t example.com --playbook thp3_web

प्लेबुक डेमो

टूल्स

PentestAgent में बिल्ट-इन टूल्स शामिल हैं और यह विस्तारशीलता के लिए MCP (मॉडल कॉन्टेक्स्ट प्रोटोकॉल) का समर्थन करता है।

बिल्ट-इन टूल्स: terminal, browser, notes, web_search (TAVILY_API_KEY आवश्यक है), spawn_mcp_agent

एजेंट सेल्फ-स्पॉनिंग (`spawn_mcp_agent`)

spawn_mcp_agent एक बिल्ट-इन टूल है जो चल रहे एजेंट को stdio पर कनेक्टेड अधीनस्थ MCP सर्वर के रूप में अपनी एक चाइल्ड कॉपी स्पॉन करने की अनुमति देता है। चाइल्ड प्रोसेस पूरी तरह से आइसोलेटेड होती है — इसका अपना रनटाइम, LLM क्लाइंट, वार्तालाप इतिहास और नोट्स स्टोर — और स्पॉनिंग के बाद इसका संपूर्ण टूल सेट पैरेंट एजेंट के उपलब्ध टूल्स में वापस इंजेक्ट किया जाता है।

यह बिना किसी बाहरी ऑर्केस्ट्रेशन के पदानुक्रमित, मल्टी-एजेंट वर्कफ़्लो सक्षम करता है: एजेंट मांग पर स्पॉन किए गए चिल्ड्रन को स्कोप्ड सबटास्क सौंपकर स्वयं-संगठित होता है।

spawn_mcp_agent लौटने के बाद, चाइल्ड के टूल्स (run_task, run_task_async, await_tasks, आदि) अगली टूल कॉल पर उपलब्ध होते हैं। चाइल्ड का सर्वर नाम स्वचालित रूप से निर्दिष्ट किया जाता है (जैसे child_agent_1) और परिणाम में लौटाया जाता है।

उदाहरण — ऑर्केस्ट्रेटर दो चिल्ड्रन को समानांतर recon सौंप रहा है:

# Turn 1: spawn two isolated child agents
spawn_mcp_agent  target="10.0.1.0/24"  scope=["10.0.1.0/24"]
spawn_mcp_agent  target="10.0.2.0/24"  scope=["10.0.2.0/24"]

# Turn 2: children's tools are now available — delegate work asynchronously
child_agent_1__run_task_async  task="Full port scan and service enumeration"
child_agent_2__run_task_async  task="Full port scan and service enumeration"

# Turn 3: wait and collect
child_agent_1__await_tasks  task_ids=["<id1>"]  timeout_seconds=600
child_agent_2__await_tasks  task_ids=["<id2>"]  timeout_seconds=600
child_agent_1__get_task_result  task_id="<id1>"
child_agent_2__get_task_result  task_id="<id2>"

मैन्युअल चाइल्ड एजेंट नियंत्रण (`/spawn` और `/despawn`)

स्वचालित spawn_mcp_agent टूल के अलावा, TUI दो कमांड प्रदर्शित करता है जो आपको चल रहे एजेंट लूप से स्वतंत्र रूप से, चाइल्ड एजेंट्स को मैन्युअल रूप से स्पॉन और समाप्त करने देते हैं।

`/spawn`

/spawn [target] [--scope CIDR ...] [--model MODEL] [--no-rag] [--no-mcp]

stdio पर एक नया चाइल्ड MCP एजेंट स्पॉन करता है और इसे वर्तमान सत्र से जोड़ता है। चाइल्ड TUI साइडबार में एक संक्षिप्त (collapsible) टर्मिनल पैनल के रूप में दिखाई देता है और इसके टूल्स अगली टूल कॉल पर पैरेंट एजेंट के लिए उपलब्ध हो जाते हैं।

उदाहरण:

/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 <server_name>

server_name (जैसे child_agent_1) द्वारा पहचाने गए चाइल्ड एजेंट को समाप्त करता है, TUI से इसका टर्मिनल पैनल हटाता है, और पैरेंट सत्र से इसके टूल्स को डिस्कनेक्ट करता है। सभी वर्तमान में सक्रिय चाइल्ड एजेंट्स के नाम देखने के लिए /mcp list का उपयोग करें।

उदाहरण:

/despawn child_agent_1

MCP RAG टूल ऑप्टिमाइज़र

जब कोई MCP सर्वर 128 से अधिक टूल्स प्रदर्शित करता है, तो PentestAgent स्वचालित रूप से पूरी कैटलॉग को एकल mcp_<server>_rag_optimizer टूल से बदल देता है। यह मेटा-टूल हाथ में मौजूद कार्य के लिए सबसे प्रासंगिक टूल्स प्राप्त करने के लिए एम्बेडिंग समानता (LiteLLM के माध्यम से, डिफ़ॉल्ट text-embedding-3-small) का उपयोग करता है और उन्हें एजेंट के अगले टर्न में इंजेक्ट करता है — संपूर्ण टूल सेट तक पहुंच खोए बिना कॉन्टेक्स्ट विंडो को प्रबंधनीय रखता है।

ऑप्टिमाइज़र एजेंट के लिए पारदर्शी है: यह RAG टूल को उसकी आवश्यकता का वर्णन करने वाले केंद्रित प्राकृतिक-भाषा क्वेरी के साथ कॉल करता है, और मिलान वाले टूल्स अगले टर्न पर सीधे कॉल करने के लिए उपलब्ध हो जाते हैं।

एजेंट के लिए उपयोग मार्गदर्शन:

Argument	Type	Default	Description

एम्बेडिंग्स स्टार्टअप पर एक बार गणना की जाती हैं और कैश की जाती हैं, इसलिए बार-बार क्वेरी तेज़ होती हैं। ऑप्टिमाइज़र प्रति-सर्वर बनाया जाता है, इसलिए बड़ी कैटलॉग वाले प्रत्येक MCP सर्वर को अपना स्वतंत्र इंडेक्स मिलता है।

टिप: सब कुछ एक क्वेरी में संयोजित करने के बजाय प्रत्येक अलग क्षमता के लिए एक क्वेरी पास करें। ["list open ports on a host", "get process memory usage"] ["list ports and memory and CPU"] की तुलना में बेहतर परिणाम प्राप्त करता है।

MCP एकीकरण

PentestAgent MCP (मॉडल कॉन्टेक्स्ट प्रोटोकॉल) को दो दिशाओं में समर्थन करता है: बाहरी MCP सर्वरों को टूल स्रोतों के रूप में उपभोग करना, और स्वयं को MCP सर्वर के रूप में प्रदर्शित करना ताकि बाहरी क्लाइंट (Claude Desktop, Cursor, आदि) PentestAgent को प्रोग्रामेटिक रूप से चला सकें।

बाहरी MCP सर्वरों का उपभोग (क्लाइंट मोड)

PentestAgent को किसी भी बाहरी MCP सर्वर से जोड़ने के लिए mcp_servers.json कॉन्फ़िगर करें। उदाहरण कॉन्फ़िगरेशन:

{
  "mcpServers": {
    "nmap": {
      "command": "npx",
      "args": ["-y", "gc-nmap-mcp"],
      "env": {
        "NMAP_PATH": "/usr/bin/nmap"
      }
    }
  }
}

PentestAgent को MCP सर्वर के रूप में प्रदर्शित करना (सर्वर मोड)

PentestAgent MCP सर्वर के रूप में चल सकता है, जिससे कोई भी MCP-संगत क्लाइंट कार्य सबमिट कर सकता है, परिणाम निरीक्षण कर सकता है, और एजेंट को दूरस्थ रूप से नियंत्रित कर सकता है। दो ट्रांसपोर्ट समर्थित हैं:

STDIO — स्थानीय क्लाइंट्स के लिए (जैसे Claude Desktop, Cursor):

pentestagent mcp_server --type stdio
pentestagent mcp_server --type stdio --target 192.168.1.1 --scope 192.168.1.0/24
pentestagent mcp_server --type stdio --model claude-sonnet-4-20250514 --docker

SSE (HTTP) — दूरस्थ या नेटवर्क वाले क्लाइंट्स के लिए:

pentestagent mcp_server --type sse
pentestagent mcp_server --type sse --host 0.0.0.0 --port 8080
pentestagent mcp_server --type sse --target 10.0.0.1 --scope 10.0.0.0/24 --docker

SSE ट्रांसपोर्ट एकल /mcp एंडपॉइंट प्रदर्शित करता है जो POST (अनुरोध), GET (सर्वर-आरंभित पुश के लिए स्थायी SSE स्ट्रीम), और DELETE (सत्र टियरडाउन) का समर्थन करता है। सत्र Mcp-Session-Id हेडर के माध्यम से ट्रैक किए जाते हैं।

सभी mcp_server फ्लैग:

उदाहरण: Claude Desktop कॉन्फ़िग (`claude_desktop_config.json`)

{
  "mcpServers": {
    "pentestagent": {
      "command": "pentestagent",
      "args": ["mcp_server", "--type", "stdio"]
    }
  }
}

MCP सर्वर टूल्स संदर्भ

MCP सर्वर के रूप में कार्य करते समय, PentestAgent निम्नलिखित टूल्स प्रदर्शित करता है:

सर्वर स्थिति और कॉन्फ़िग

Tool	Description
`get_server_status`	लाइव सर्वर स्थिति: तैयारी, स्थिति के अनुसार कार्य गणना, प्राथमिक लक्ष्य/स्कोप, मेमोरी स्टोर आकार
`get_config`	प्राथमिक एजेंट कॉन्फ़िगरेशन: लक्ष्य, स्कोप, अधिकतम पुनरावृत्तियाँ, टूल सूची
`update_config`	सभी बाद के कार्यों के लिए लक्ष्य, स्कोप, या अधिकतम पुनरावृत्तियाँ अपडेट करें

कार्य निष्पादन

Tool	Description
`run_task`	एक कार्य सबमिट करें और पूरा होने तक ब्लॉक करें। पूर्ण परिणाम, उपयोग किए गए टूल्स और नोट्स स्नैपशॉट लौटाता है
`run_task_async`

कार्य निरीक्षण

Tool	Description

कार्य नियंत्रण

Tool	Description
`cancel_task`	ID द्वारा चल रहे या लंबित कार्य को रद्द करें

टूल प्रबंधन

Tool	Description
`list_tools`	एजेंट के लिए उपलब्ध सभी टूल्स सूचीबद्ध करें
`enable_tool`	प्राथमिक एजेंट पर एक नामित टूल सक्षम करें
`disable_tool`	प्राथमिक एजेंट पर एक नामित टूल अक्षम करें

वार्तालाप इतिहास

Tool	Description
`get_conversation_history`	किसी कार्य या प्राथमिक एजेंट के लिए संदेश इतिहास लौटाएँ। `limit` पैरामीटर का समर्थन करता है
`reset_conversation`	किसी कार्य या प्राथमिक एजेंट के लिए वार्तालाप इतिहास साफ़ करें

मेमोरी

Tool	Description
`store_memory`	इन-प्रोसेस मेमोरी स्टोर में एक की-वैल्यू जोड़ी बनाए रखें
`retrieve_memory`	सटीक कुंजी द्वारा प्राप्त करें, सबस्ट्रिंग द्वारा खोजें, या सभी कुंजियाँ सूचीबद्ध करें
`clear_memory`	विशिष्ट कुंजी हटाएँ या के साथ सभी मेमोरी साफ़ करें

ऑब्ज़र्वेबिलिटी

Tool	Description
`get_logs`	हाल के निष्पादन लॉग लौटाएँ, वैकल्पिक रूप से स्तर (`info` / `warning` / `error`) द्वारा फ़िल्टर किया गया
`get_metrics`	रनटाइम मेट्रिक्स: कार्य गणना, सफलता दर, कुल टूल कॉल, मेमोरी और लॉग आकार

Async कार्य वर्कफ़्लो उदाहरण

लंबे समय तक चलने वाले recon कार्यों के लिए, async पैटर्न का उपयोग करें:

# 1. Submit tasks without blocking
run_task_async  task="Enumerate subdomains of example.com"  target="example.com"
run_task_async  task="Run nmap SYN scan on example.com"     target="example.com"

# 2. Block until both finish (up to 5 minutes)
await_tasks  task_ids=["<id1>", "<id2>"]  timeout_seconds=300

# 3. Retrieve full results
get_task_result  task_id="<id1>"
get_task_result  task_id="<id2>"

CLI टूल प्रबंधन

pentestagent tools list         # List all tools
pentestagent tools info <name>  # Show tool details
pentestagent mcp list           # List MCP servers
pentestagent mcp add <name> <command> [args...]  # Add MCP server
pentestagent mcp test <name>    # Test MCP connection

वार्तालाप इतिहास नियंत्रण

TUI में प्रत्येक उपयोगकर्ता संदेश दो इनलाइन एक्शन बटन प्रदर्शित करता है: rewind और fork।

Rewind

किसी भी उपयोगकर्ता संदेश पर rewind क्लिक करें ताकि वार्तालाप उस संदेश से ठीक पहले तक छोटा हो जाए — UI और एजेंट के इन-मेमोरी इतिहास दोनों में। इसका उपयोग किसी क्वेरी को त्यागे गए पथ को सहेजे बिना शुरू से पुनः प्रयास करने के लिए करें।

Fork

किसी भी उपयोगकर्ता संदेश पर >> fork क्लिक करें ताकि उस बिंदु से वार्तालाप शाखाबद्ध हो जाए:

वर्तमान पूर्ण वार्तालाप वार्तालाप स्टोर में सहेजा जाता है और एक छोटा स्नैपशॉट ID दिखाया जाता है।
फिर वार्तालाप चयनित संदेश से ठीक पहले तक छोटा किया जाता है (rewind के समान)।

यह आपको किसी भी बिंदु से एक वैकल्पिक दृष्टिकोण आज़माने देता है, जबकि मूल थ्रेड /conversations के माध्यम से पुनर्प्राप्त करने योग्य रहता है।

वार्तालाप इतिहास

PentestAgent स्वचालित रूप से हर वार्तालाप को सहेजता है ताकि आप पिछले सत्रों की समीक्षा, तुलना और पुनर्स्थापना कर सकें।

ऑटो-सेव प्रत्येक /assist, /agent, /crew, और /interact कार्य के बाद, और /clear से पहले सक्रिय होता है। अधिकतम 20 वार्तालाप रखे जाते हैं; पुराने स्वचालित रूप से हटा दिए जाते हैं।

भंडारण स्थान: जब कोई वर्कस्पेस सक्रिय हो तो workspaces/<active>/memory/conversations/, अन्यथा प्रोजेक्ट रूट पर conversations/। प्रत्येक वार्तालाप एक JSON फ़ाइल है।

/conversations के साथ ब्राउज़ और पुनर्स्थापित करें:

/conversations कमांड TUI के अंदर एक स्प्लिट-पैन मोडल खोलता है:

बायाँ पैनल — शीर्षक और दिनांक के साथ सहेजे गए वार्तालापों की सूची।
दायाँ पैनल — मेटाडेटा पूर्वावलोकन के साथ पहले 5 संदेश (उपयोगकर्ता संदेश नीले रंग में, एजेंट प्रतिक्रियाएँ हरे रंग में, टूल कॉल पीले रंग में, टूल परिणाम ग्रे रंग में)। एक गिनती दिखाती है कि कितने अतिरिक्त संदेश मौजूद हैं।

एक वार्तालाप चुनें और उसे वर्तमान सत्र में पुनः लोड करने के लिए Restore दबाएँ, या मोडल को खारिज करने के लिए Close दबाएँ।

ज्ञान

RAG: स्वचालित संदर्भ इंजेक्शन के लिए pentestagent/knowledge/sources/ में पद्धतियाँ, CVE, या वर्डलिस्ट रखें।
नोट्स: एजेंट श्रेणियों (credential, vulnerability, finding, artifact) के साथ loot/notes.json में निष्कर्ष सहेजते हैं। नोट्स सत्रों में बने रहते हैं और एजेंट संदर्भ में इंजेक्ट किए जाते हैं।
शैडो ग्राफ़: क्रू मोड में, ऑर्केस्ट्रेटर रणनीतिक अंतर्दृष्टि प्राप्त करने के लिए नोट्स से एक ज्ञान ग्राफ़ बनाता है (जैसे, "हमारे पास होस्ट X के लिए क्रेडेंशियल हैं")।

प्रोजेक्ट संरचना

pentestagent/
  agents/         # Agent implementations
  config/         # Settings and constants
  interface/      # TUI and CLI
  knowledge/      # RAG system and shadow graph
  llm/            # LiteLLM wrapper
  mcp/            # MCP client and server configs
  playbooks/      # Attack playbooks
  runtime/        # Execution environment
  tools/          # Built-in tools

विकास

pip install -e ".[dev]"
pytest                       # Run tests
pytest --cov=pentestagent    # With coverage
black pentestagent           # Format
ruff check pentestagent      # Lint

कानूनी

केवल उन्हीं प्रणालियों के विरुद्ध उपयोग करें जिनके परीक्षण के लिए आपके पास स्पष्ट प्राधिकरण है। अनधिकृत पहुंच अवैध है।

लाइसेंस

MIT

Assist	`/assist <task>`	एक सिंगल शॉट निर्देश, टूल निष्पादन के साथ
Agent	`/agent <task>`	एकल कार्य का स्वायत्त निष्पादन
Crew	`/crew <task>`	मल्टी-एजेंट मोड। ऑर्केस्ट्रेटर विशेष कार्यकर्ताओं को स्पॉन करता है
Interact	`/interact <task>`	इंटरैक्टिव मोड। एजेंट के साथ चैट करें, यह पेनेट्रेशन टेस्टिंग प्रक्रिया के दौरान आपकी मदद करेगा और मार्गदर्शन करेगा

`target`	string	—	चाइल्ड को पास करने के लिए पेनेट्रेशन टेस्टिंग लक्ष्य
`scope`	string[]	—	चाइल्ड के लिए इन-स्कोप लक्ष्य/CIDR
`model`	string	env var	मॉडल पहचानकर्ता, चाइल्ड पर `PENTESTAGENT_MODEL` को ओवरराइड करता है
`no_rag`	boolean	`false`	चाइल्ड पर RAG इंजन आरंभीकरण छोड़ें
`no_mcp`	boolean	`true`	चाइल्ड पर बाहरी MCP सर्वर कनेक्शन छोड़ें (अनुशंसित)

`target`	चाइल्ड को पास करने के लिए पेनेट्रेशन टेस्टिंग लक्ष्य (पोजीशनल या `--target`)
`--scope CIDR`	एक या अधिक इन-स्कोप CIDR (दोहराने योग्य)
`--model MODEL`	चाइल्ड एजेंट के लिए मॉडल ओवरराइड करें
`--no-rag`	चाइल्ड पर RAG इंजन आरंभीकरण छोड़ें
`--no-mcp`	चाइल्ड पर बाहरी MCP सर्वर कनेक्शन छोड़ें

`--type`	(required)	ट्रांसपोर्ट: `stdio` या `sse`
`--host`	`0.0.0.0`	SSE बाइंड होस्ट
`--port`	`8080`	SSE बाइंड पोर्ट
`--target`	none	प्राथमिक पेनेट्रेशन टेस्टिंग लक्ष्य (IP / होस्टनाम)
`--scope`	`[]`	इन-स्कोप लक्ष्य/CIDR (स्पेस-सेपरेटेड)
`--model`	env var	मॉडल पहचानकर्ता, `PENTESTAGENT_MODEL` को ओवरराइड करता है
`--docker`	false	LocalRuntime के बजाय DockerRuntime का उपयोग करें
`--no-rag`	false	RAG इंजन आरंभीकरण छोड़ें
`--no-mcp`	false	बाहरी MCP सर्वर कनेक्शन छोड़ें

सबसे लोकप्रिय

pentestagent