---

hackingBuddyGPT est un framework open-source pour construire des agents de test de sécurité pilotés par LLM. Il vous fournit les fondations ennuyeuses mais essentielles — connectivité LLM, connecteurs de cibles (SSH / shell local / psexec de type WinRM), câblage des capacités/outils, limites d'exécution et journalisation structurée — afin que vous puissiez exprimer une nouvelle expérience (un « cas d'usage ») en quelques dizaines de lignes de code. Nous visons à être LE framework de référence pour les chercheurs en sécurité et les pentesters qui souhaitent utiliser les LLM (ou des agents autonomes basés sur LLM) pour les tests de sécurité.

Pour soutenir une recherche reproductible, nous maintenons également un benchmark réutilisable d'élévation de privilèges sous Linux et publions nos résultats sous forme de rapports en accès libre. Si vous avez besoin d'aide pour choisir un LLM pour une tâche, nous avons un article comparant plusieurs LLM.

⚠️ Ce logiciel exécute de vraies commandes sur des systèmes en production. En mode shell local, il les exécute sur votre machine ; en mode SSH/psexec, sur la cible que vous lui indiquez. Ne l'exécutez jamais contre des systèmes que vous ne possédez pas ou que vous n'êtes pas explicitement autorisé à tester, et privilégiez des VM ou des conteneurs isolés. Voir les avertissements.

Démarrage rapide

# 1. clone and install (uv is recommended; a plain venv + pip works too)
git clone https://github.com/ipa-lab/hackingBuddyGPT.git && cd hackingBuddyGPT
uv sync && source .venv/bin/activate

# 2. configure your LLM key + target
cp .env.example .env && $EDITOR .env

# 3. list the available use-cases
wintermute

# 4. run one — e.g. a minimal Linux privilege-escalation against an SSH target
wintermute MinimalPrivEscLinux \
    --conn=ssh --conn.host=192.168.122.151 \
    --conn.username=lowpriv --conn.password=trustno1

L'installation du paquet fournit la commande wintermute. Lancée sans argument, elle liste tous les cas d'usage enregistrés ; wintermute <UseCase> --help affiche les options de ce cas d'usage.

Besoin d'une cible pour vous entraîner ? Récupérez une machine vulnérable depuis notre Linux Privilege-Escalation Benchmark ou une VM délibérément vulnérable telle que Lin.Security de VulnHub.

Cas d'usage

Les expériences sont structurées en cas d'usage. Chacun devient une sous-commande de wintermute. Le framework fournit actuellement les suivants :

Élévation de privilèges

Commande	Description
MinimalPrivEscLinux	Élévation de privilèges Linux minimale d'environ 20 lignes. Injecte tout l'historique dans un seul prompt à chaque tour et extrait une commande brute de la réponse (la boucle classique de hackingBuddyGPT). Excellent point de départ — voir Build your own use-case.
MinimalToolCallPrivEscLinux	Le jumeau avec appel d'outils de ce qui précède : conserve un véritable historique de conversation et pilote la cible via l'appel de fonctions. Son outil task_solved est vérifié par rapport à la vérité terrain, de sorte qu'un « got root » halluciné ou concédé ne peut pas produire un faux succès.
PrivEscLinux	Élévation de privilèges Linux complète basée sur des stratégies, avec génération augmentée par récupération optionnelle (--rag_path), chaîne de pensée (--enable_cot), suivi d'état et guidage structuré.
PrivEscWindows	Élévation de privilèges Windows basée sur des stratégies, pilotant la cible via psexec plutôt que SSH.
ExPrivEscLinuxLSE	Exécute d'abord lse.sh sur la cible, transforme sa sortie en indices, puis orchestre PrivEscLinux pour chaque indice — un exemple de cas d'usage qui appelle un autre cas d'usage.

Web

Commande	Description
WebTestingWithExplanation	Teste de manière autonome une page web via HTTP tout en laissant le LLM « raisonner » à voix haute ; inclut une capacité de playbook de pentest de style OWASP.
WebTestingWithShell	Tests web avec accès shell à une machine attaquante de style Kali.
AdvancedWebTesting	Un agent de haut niveau sans accès direct à la cible qui délègue le travail à des sous-agents bornés via une capacité de sous-agent.

API Web

Commande	Description
WebAPITesting	Détecte la surface de la cible — une spécification OpenAPI ou un sitemap de site web — puis effectue un pentest de l'API REST. S'exécute en --mode document (construire une spécification), test (pentester une surface connue) ou auto (les deux).

Active Directory

Commande	Description
AD	Pentest autonome par LLM d'Active Directory en scénario de compromission présumée, porté depuis l'outil d'attaque cochise. Utilise une conception planificateur/exécuteur : un planificateur stratégique persistant maintient un arbre de tâches et une base de connaissances partagée, déléguant chaque tâche à un exécuteur tactique neuf et sans mémoire.

Fonctionnalités du framework

• Deux styles d'exécution sur une boucle partagée : des agents avec appel d'outils natifs (véritable historique de conversation + appel de fonctions) et de simples stratégies par commandes en texte (template Mako → une seule commande extraite).
• Limites d'exécution unifiées — plafonnez toute exécution par tours, tokens, coût (en dollars) et durée réelle (--limits.max_rounds/max_tokens/max_cost/max_duration).
• Un seul fournisseur LLM en amont : litellm. Tout fournisseur est joignable via la chaîne llm.model — OpenAI, OpenRouter (le point de terminaison par défaut), Anthropic, Azure, un Ollama local, et plus encore. Acheminez le trafic API via un proxy d'interception (Burp/mitmproxy) avec --llm.proxy.
• Journalisation structurée et autonome — chaque exécution est écrite sous forme de trace JSONL OpenTelemetry/GenAI en ajout seul, avec des outils CLI pour rejouer et agréger les exécutions.
• Modèle d'exécution entièrement asynchrone construit sur asyncio.
• Détection de succès vérifiée par la vérité terrain pour l'élévation de privilèges (un « got root » revendiqué est vérifié par rapport à la sortie réelle des commandes).
• Lanceur de benchmark en flotte Docker pour les tests de régression sur de nombreuses cibles à la fois.

Installation & configuration

Prérequis : Python 3.13+. Le projet utilise le backend de build uv ; nous recommandons uv pour gérer l'environnement, mais un simple python -m venv + pip fonctionne également.

git clone https://github.com/ipa-lab/hackingBuddyGPT.git
cd hackingBuddyGPT