---

hackingBuddyGPT è un framework open-source per la creazione di agenti di security-testing guidati da LLM. Fornisce le fondamenta noiose ma essenziali — connettività LLM, connettori verso i target (SSH / shell locale / psexec in stile WinRM), cablaggio di capability/tool, limiti di esecuzione e logging strutturato — così puoi esprimere un nuovo esperimento (un "use-case") in poche decine di righe di codice. Il nostro obiettivo è essere IL framework di riferimento per ricercatori di sicurezza e pen-tester che vogliono usare gli LLM (o agenti autonomi basati su LLM) per il security testing.

Per supportare la ricerca riproducibile manteniamo anche un benchmark riutilizzabile per la privilege-escalation su Linux e pubblichiamo i nostri risultati come report ad accesso aperto. Se hai bisogno di aiuto nella scelta di un LLM per un compito, abbiamo un paper che confronta più LLM.

⚠️ Questo software esegue comandi reali su sistemi attivi. In modalità shell locale li esegue sulla tua macchina; in modalità SSH/psexec sul target verso cui lo indirizzi. Eseguilo solo contro sistemi di tua proprietà o che sei esplicitamente autorizzato a testare, e preferisci VM o container isolati. Vedi le avvertenze.

Quickstart

# 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'installazione del pacchetto fornisce il comando wintermute. Eseguendolo senza argomenti elenca tutti i casi d'uso registrati; wintermute <UseCase> --help mostra le opzioni di quel caso d'uso.

Ti serve un bersaglio su cui esercitarti? Prendi una macchina vulnerabile dal nostro Linux Privilege-Escalation Benchmark o una VM deliberatamente vulnerabile come Lin.Security da VulnHub.

Casi d'uso

Gli esperimenti sono strutturati in casi d'uso. Ognuno diventa un sottocomando di wintermute. Il framework attualmente include i seguenti:

Escalation dei privilegi

Comando	Descrizione
MinimalPrivEscLinux	Escalation dei privilegi Linux minimale, di ~20 righe. Inserisce l'intera cronologia in un unico prompt a ogni round ed estrae un comando grezzo dalla risposta (il classico loop di hackingBuddyGPT). Ottimo punto di partenza — vedi Crea il tuo caso d'uso.
MinimalToolCallPrivEscLinux	Il gemello con tool-calling del precedente: mantiene una cronologia di chat reale e guida il bersaglio tramite function calling. Il suo tool task_solved è verificato rispetto alla ground truth, quindi un "got root" allucinato o arrendevole non può ottenere un falso successo.
PrivEscLinux	Escalation dei privilegi Linux basata su strategie, completa di funzionalità, con retrieval-augmented generation opzionale (--rag_path), chain-of-thought (--enable_cot), tracciamento dello stato e guida strutturata.
PrivEscWindows	Escalation dei privilegi Windows basata su strategie, che guida il bersaglio tramite psexec invece di SSH.
ExPrivEscLinuxLSE	Esegue prima lse.sh sul bersaglio, trasforma il suo output in suggerimenti, poi orchestra PrivEscLinux per ogni suggerimento — un esempio di caso d'uso che richiama un altro caso d'uso.

Web

Comando	Descrizione
WebTestingWithExplanation	Testa autonomamente una pagina web via HTTP lasciando che l'LLM "parli" attraverso il suo ragionamento; include una capacità di playbook di pentest in stile OWASP.
WebTestingWithShell	Web testing con accesso shell a una macchina attaccante in stile Kali.
AdvancedWebTesting	Un agente di livello superiore senza accesso diretto al bersaglio che delega il lavoro a sub-agenti delimitati tramite una capacità di sub-agente.

Web API

Comando	Descrizione
WebAPITesting	Rileva la superficie del bersaglio — una specifica OpenAPI oppure una sitemap di un sito web — poi esegue il pentest della REST API. Funziona in --mode document (costruisci una specifica), test (pentest di una superficie nota) o auto (entrambi).

Active Directory

Comando	Descrizione
AD	Pentest autonomo con LLM di Active Directory in scenario di assumed-breach, portato dal tool di attacco cochise. Usa un design planner/executor: un planner strategico persistente mantiene un albero dei task e una knowledge base condivisa, delegando ogni task a un executor tattico nuovo e senza memoria.

Funzionalità del framework

• Due stili di esecuzione su un unico loop condiviso: agenti con tool-calling nativi (cronologia di chat reale + function calling) e semplici strategie a comando testuale (template Mako → singolo comando estratto).
• Limiti di esecuzione unificati — limita qualsiasi esecuzione per round, token, costo (in dollari) e durata in tempo reale (--limits.max_rounds/max_tokens/max_cost/max_duration).
• Un unico upstream LLM: litellm. Qualsiasi provider è raggiungibile tramite la stringa llm.model — OpenAI, OpenRouter (l'endpoint predefinito), Anthropic, Azure, un Ollama locale e altro ancora. Instrada il traffico API attraverso un proxy di intercettazione (Burp/mitmproxy) con --llm.proxy.
• Logging strutturato e autosufficiente — ogni esecuzione viene scritta come traccia JSONL OpenTelemetry/GenAI append-only, con strumenti CLI per riprodurre e aggregare le esecuzioni.
• Modello di esecuzione completamente asincrono basato su asyncio.
• Rilevamento del successo verificato rispetto alla ground truth per l'escalation dei privilegi (un "got root" dichiarato viene confrontato con l'output reale dei comandi).
• Launcher di benchmark con flotta Docker per test di regressione su molti bersagli contemporaneamente.

Installazione e configurazione

Requisiti: Python 3.13+. Il progetto utilizza il backend di build uv; consigliamo uv per gestire l'ambiente, ma anche un semplice python -m venv + pip funziona.

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

# option A (recommended): uv creates .venv and installs the project
uv sync
source .venv/bin/activate

# option B: a plain virtual environment + pip
python -m venv venv && source ./venv/bin/activate
pip install -e .