PentestAgent

اختبار الاختراق بالذكاء الاصطناعي

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

المتطلبات

• Python 3.10+
• مفتاح API لـ OpenAI أو Anthropic أو أي مزوّد آخر مدعوم من LiteLLM

التثبيت

# 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 يعمل.

استخدام موزّع (Relay) / قاعدة API مخصصة

وجّه PentestAgent إلى أي نقطة نهاية متوافقة مع OpenAI عبر OPENAI_API_BASE:

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

شغّل الأدوات داخل حاوية 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

تعمل الحاوية على تشغيل PentestAgent مع إمكانية الوصول إلى أدوات اختبار الاختراق لنظام Linux. يمكن للوكيل استخدام 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 للخروج.

قوائم اللعب (Playbooks)

يتضمن 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 هي أداة مدمجة تسمح للوكيل قيد التشغيل بتوليد نسخة فرعية من نفسه كخادم MCP تابع متصل عبر stdio. تكون العملية الفرعية معزولة تمامًا — ببيئة تشغيل خاصة بها، وعميل LLM، وسجل محادثات، ومخزن ملاحظات — ويتم حقن مجموعة أدواتها الكاملة مرة أخرى في أدوات الوكيل الأصلي المتاحة بعد التوليد.

يتيح ذلك سير عمل هرميًا متعدد الوكلاء دون أي تنسيق خارجي: ينظّم الوكيل نفسه بنفسه عبر تفويض مهام فرعية محدودة النطاق إلى أطفال يولّدهم عند الحاجة.

بعد أن يعيد spawn_mcp_agent النتيجة، تصبح أدوات الطفل (run_task, run_task_async, await_tasks, إلخ) متاحة في الاستدعاء التالي للأداة. يتم تعيين اسم خادم الطفل تلقائيًا (مثل child_agent_1) ويُعاد في النتيجة.

مثال — قيام المنسّق بتفويض استطلاع متوازٍ إلى طفلين:

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

يولّد وكيل MCP فرعيًا جديدًا عبر stdio ويربطه بالجلسة الحالية. يظهر الطفل كلوحة طرفية قابلة للطي في الشريط الجانبي لواجهة TUI، وتصبح أدواته متاحة للوكيل الأصلي في استدعاء الأداة التالي.

أمثلة:

/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

محسّن أدوات RAG في MCP

عندما يعرّض خادم MCP أكثر من 128 أداة، يستبدل PentestAgent تلقائيًا الكتالوج الكامل بأداة واحدة باسم mcp_<server>_rag_optimizer. تستخدم هذه الأداة الوصفية تشابه التضمين (عبر LiteLLM، الافتراضي text-embedding-3-small) لاسترجاع الأدوات الأكثر صلة بالمهمة الحالية وحقنها في دورة الوكيل التالية — مما يحافظ على نافذة السياق ضمن الحدود دون فقدان الوصول إلى مجموعة الأدوات الكاملة.

يكون المحسّن شفافًا بالنسبة للوكيل: فهو يستدعي أداة RAG باستعلامات طبيعية مركزة تصف ما يحتاجه، وتصبح الأدوات المطابقة متاحة في الدورة التالية لاستدعائها مباشرةً.

إرشادات الاستخدام للوكيل:

يتم حساب التضمينات مرة واحدة عند بدء التشغيل وتخزينها مؤقتًا، لذا تكون الاستعلامات المتكررة سريعة. يُبنى المحسّن لكل خادم على حدة، لذا يحصل كل خادم 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 الخارجية (وضع العميل)

قم بتهيئة mcp_servers.json لربط PentestAgent بأي خوادم MCP خارجية. مثال على الإعداد:

{
  "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 الأدوات التالية:

حالة الخادم والإعدادات

تنفيذ المهام

فحص المهام

التحكم في المهام

إدارة الأدوات

سجل المحادثات

الذاكرة

المراقبة (Observability)

مثال على سير عمل المهام غير المتزامنة

بالنسبة لمهام الاستطلاع طويلة الأمد، استخدم النمط غير المتزامن:

# 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 في أي رسالة مستخدم لاقتطاع المحادثة إلى ما قبل تلك الرسالة تمامًا — سواء في الواجهة أو في ذاكرة الوكيل الداخلية. استخدمها لإعادة محاولة استعلام من الصفر دون حفظ المسار المهمل.

التفرع (Fork)

انقر على >> fork في أي رسالة مستخدم لتفرع المحادثة من تلك النقطة:

1. يتم حفظ المحادثة الكاملة الحالية في مخزن المحادثات ويظهر معرّف لقطة قصير.
2. يتم بعد ذلك اقتطاع المحادثة إلى ما قبل الرسالة المحددة تمامًا (كما في rewind).

يتيح لك ذلك تجربة نهج بديل من أي نقطة مع إبقاء السلسلة الأصلية قابلة للاسترجاع عبر /conversations.

سجل المحادثات

يحفظ PentestAgent تلقائيًا كل محادثة حتى تتمكن من مراجعة الجلسات السابقة ومقارنتها واستعادتها.

يتم تشغيل الحفظ التلقائي بعد كل مهمة /assist و/agent و/crew و/interact، وقبل /clear. يُحتفظ بما يصل إلى 20 محادثة؛ وتُحذف الأقدم تلقائيًا.

موقع التخزين: workspaces/<active>/memory/conversations/ عند وجود مساحة عمل نشطة، أو conversations/ في جذر المشروع في الحالات الأخرى. كل محادثة عبارة عن ملف JSON.

التصفح والاستعادة عبر /conversations:

يفتح الأمر /conversations نافذة منقسمة داخل واجهة TUI:

• اللوحة اليسرى — قائمة المحادثات المحفوظة مع العنوان والتاريخ.
• اللوحة اليمنى — معاينة البيانات الوصفية بالإضافة إلى أول 5 رسائل (رسائل المستخدم باللون الأزرق، وردود الوكيل باللون الأخضر، واستدعاءات الأدوات باللون الأصفر، ونتائج الأدوات باللون الرمادي). يعرض عداد عدد الرسائل الإضافية الموجودة.

حدد محادثة واضغط Restore لإعادة تحميلها في الجلسة الحالية، أو Close لإغلاق النافذة.

المعرفة

• RAG: ضع المنهجيات أو CVEs أو قوائم الكلمات في pentestagent/knowledge/sources/ للحقن التلقائي في السياق.
• الملاحظات: يحفظ الوكلاء النتائج في loot/notes.json مع فئات (credential, vulnerability, finding, artifact). تستمر الملاحظات عبر الجلسات ويتم حقنها في سياق الوكيل.
• الرسم البياني الظل (Shadow Graph): في وضع Crew، يبني المنسّق رسمًا بيانيًا للمعرفة من الملاحظات لاستخلاص رؤى استراتيجية (مثل "لدينا بيانات اعتماد للمضيف 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