PentestAgent

Tests de pénétration par IA

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

Prérequis

• Python 3.10+
• Clé API pour OpenAI, Anthropic, ou autre fournisseur supporté par LiteLLM

Installation

# 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

Configuration

Créez .env à la racine du projet :

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

Ou pour OpenAI :

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

Tout modèle supporté par LiteLLM fonctionne.

Utilisation d'un relais / base API personnalisée

Pointer PentestAgent vers n'importe quel endpoint compatible OpenAI via OPENAI_API_BASE :

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

Pour les endpoints compatibles Anthropic, utilisez ANTHROPIC_API_BASE à la place. Voir .env.example pour les notes complètes sur les fournisseurs et les options d'embedding.

Exécution

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

Docker

Exécutez les outils dans un conteneur Docker pour l'isolation et les outils de pentest préinstallés.

Option 1 : Tirer l'image pré-construite (le plus rapide)

# 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

Option 2 : Construire localement

# 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

Le conteneur exécute PentestAgent avec un accès aux outils de pentest Linux. L'agent peut utiliser nmap, msfconsole, sqlmap, etc. directement via l'outil terminal.

Nécessite que Docker soit installé et en cours d'exécution.

Modes

PentestAgent propose trois modes, accessibles via des commandes dans le TUI :

Commandes 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, /?)

Appuyez sur Esc pour arrêter un agent en cours d'exécution. Ctrl+Q pour quitter.

Playbooks

PentestAgent inclut des playbooks d'attaque préconstruits pour les tests de sécurité en boîte noire. Les playbooks définissent une approche structurée pour des évaluations de sécurité spécifiques.

Exécuter un playbook :

pentestagent run -t example.com --playbook thp3_web

Outils

PentestAgent inclut des outils intégrés et supporte MCP (Model Context Protocol) pour l'extensibilité.

Outils intégrés : terminal, browser, notes, web_search (nécessite TAVILY_API_KEY), spawn_mcp_agent

Auto-génération d'agent (spawn_mcp_agent)

spawn_mcp_agent est un outil intégré qui permet à un agent en cours d'exécution de générer une copie enfant de lui-même en tant que serveur MCP subordonné connecté via stdio. Le processus enfant est totalement isolé — son propre runtime, client LLM, historique de conversation et magasin de notes — et son ensemble complet d'outils est injecté dans les outils disponibles de l'agent parent après la génération.

Cela permet des workflows hiérarchiques multi-agents sans aucune orchestration externe : l'agent s'organise lui-même en déléguant des sous-tâches ciblées à des enfants qu'il génère à la demande.

Après le retour de spawn_mcp_agent, les outils de l'enfant (run_task, run_task_async, await_tasks, etc.) sont disponibles lors du prochain appel d'outil. Le nom du serveur de l'enfant est attribué automatiquement (par exemple child_agent_1) et renvoyé dans le résultat.

Exemple — orchestrateur déléguant une reconnaissance parallèle à deux enfants :

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

Contrôle manuel de l'agent enfant (/spawn et /despawn)

Au-delà de l'outil automatique spawn_mcp_agent, le TUI expose deux commandes qui vous permettent de générer et de terminer des agents enfants manuellement, indépendamment d'une boucle d'agent en cours d'exécution.

/spawn

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

Génère un nouvel agent MCP enfant via stdio et l'attache à la session en cours. L'enfant apparaît comme un panneau de terminal pliable dans la barre latérale du TUI et ses outils deviennent disponibles pour l'agent parent lors du prochain appel d'outil.

Exemples :

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

Termine l'agent enfant identifié par server_name (par exemple child_agent_1), supprime son panneau de terminal du TUI et déconnecte ses outils de la session parente. Utilisez /mcp list pour voir les noms de tous les agents enfants actuellement actifs.

Exemple :

/despawn child_agent_1

Optimiseur d'outil MCP RAG

Lorsqu'un serveur MCP expose plus de 128 outils, PentestAgent remplace automatiquement le catalogue complet par un seul outil mcp_<server>_rag_optimizer. Ce méta-outil utilise la similarité d'embedding (via LiteLLM, par défaut text-embedding-3-small) pour récupérer les outils les plus pertinents pour la tâche en cours et les injecter dans le prochain tour de l'agent — maintenant la fenêtre de contexte gérable sans perdre l'accès à l'ensemble complet des outils.

L'optimiseur est transparent pour l'agent : il appelle l'outil RAG avec des requêtes ciblées en langage naturel décrivant ce dont il a besoin, et les outils correspondants deviennent disponibles au prochain tour pour être appelés directement.

Conseils d'utilisation pour l'agent :

Les embeddings sont calculés une fois au démarrage et mis en cache, donc les requêtes répétées sont rapides. L'optimiseur est construit par serveur, donc chaque serveur MCP avec un grand catalogue obtient son propre index indépendant.

Astuce : Transmettez une requête par capacité distincte plutôt que de tout combiner en une seule requête. ["list open ports on a host", "get process memory usage"] donne de meilleurs résultats que ["list ports and memory and CPU"].

Intégration MCP

PentestAgent supporte MCP dans deux directions : consommer des serveurs MCP externes comme sources d'outils, et s'exposer en tant que serveur MCP afin que des clients externes (Claude Desktop, Cursor, etc.) puissent piloter PentestAgent par programmation.

Consommer des serveurs MCP externes (Mode client)

Configurez mcp_servers.json pour connecter PentestAgent à n'importe quel serveur MCP externe. Exemple de configuration :

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

Exposer PentestAgent en tant que serveur MCP (Mode serveur)

PentestAgent peut s'exécuter en tant que serveur MCP, permettant à tout client compatible MCP de soumettre des tâches, d'inspecter les résultats et de contrôler l'agent à distance. Deux transports sont supportés :

STDIO — pour les clients locaux (par ex. 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) — pour les clients distants ou réseau :

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

Le transport SSE expose un seul endpoint /mcp supportant POST (requêtes), GET (flux SSE persistant pour les push initiés par le serveur) et DELETE (démantèlement de session). Les sessions sont suivies via l'en-tête Mcp-Session-Id.

Tous les drapeaux mcp_server :

Exemple : Configuration de Claude Desktop (claude_desktop_config.json)

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

Référence des outils du serveur MCP

Lorsqu'il agit en tant que serveur MCP, PentestAgent expose les outils suivants :

Statut et configuration du serveur

Exécution des tâches

Inspection des tâches

Contrôle des tâches

Gestion des outils

Historique des conversations

Mémoire

Observabilité

Exemple de workflow de tâche asynchrone

Pour les tâches de reconnaissance de longue durée, utilisez le modèle asynchrone :

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

Gestion des outils en 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

Contrôles de l'historique des conversations

Chaque message utilisateur dans le TUI expose deux boutons d'action en ligne : rewind et fork.

Rewind

Cliquez sur rewind sur n'importe quel message utilisateur pour tronquer la conversation juste avant ce message — à la fois dans l'UI et dans l'historique en mémoire de l'agent. Utilisez-le pour réessayer une requête depuis le début sans sauvegarder le chemin écarté.

Fork

Cliquez sur >> fork sur n'importe quel message utilisateur pour bifurquer la conversation à partir de ce point :

1. La conversation complète actuelle est sauvegardée dans le magasin de conversations et un court ID d'instantané est affiché.
2. La conversation est ensuite tronquée juste avant le message sélectionné (comme pour rewind).

Cela vous permet d'essayer une approche alternative à partir de n'importe quel point tout en gardant le fil original accessible via /conversations.

Historique des conversations

PentestAgent persiste automatiquement chaque conversation afin que vous puissiez consulter, comparer et restaurer les sessions passées.

La sauvegarde automatique se déclenche après chaque tâche /assist, /agent, /crew et /interact, et avant /clear. Jusqu'à 20 conversations sont conservées ; les plus anciennes sont supprimées automatiquement.

Emplacement de stockage : workspaces/<active>/memory/conversations/ lorsqu'un espace de travail est actif, ou conversations/ à la racine du projet sinon. Chaque conversation est un fichier JSON.

Parcourir et restaurer avec /conversations :

La commande /conversations ouvre une modale à deux panneaux dans le TUI :

• Panneau gauche — liste des conversations sauvegardées avec titre et date.
• Panneau droit — aperçu des métadonnées plus les 5 premiers messages (messages utilisateur en bleu, réponses de l'agent en vert, appels d'outils en jaune, résultats d'outils en gris). Un compteur indique combien de messages supplémentaires existent.

Sélectionnez une conversation et appuyez sur Restaurer pour la recharger dans la session actuelle, ou Fermer pour fermer la modale.

Connaissances

• RAG : Placez des méthodologies, des CVE ou des wordlists dans pentestagent/knowledge/sources/ pour une injection automatique de contexte.
• Notes : Les agents sauvegardent les découvertes dans loot/notes.json avec des catégories (credential, vulnerability, finding, artifact). Les notes persistent entre les sessions et sont injectées dans le contexte de l'agent.
• Shadow Graph : En mode Crew, l'orchestrateur construit un graphe de connaissances à partir des notes pour dériver des informations stratégiques (par exemple, « Nous avons des identifiants pour l'hôte X »).

Structure du projet

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

Développement

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

Légal

Utilisez uniquement contre des systèmes pour lesquels vous avez une autorisation explicite de test. L'accès non autorisé est illégal.

Licence

MIT