---

hackingBuddyGPT é um framework de código aberto para construir agentes de teste de segurança orientados por LLM. Ele fornece a base entediante, porém essencial — conectividade com LLMs, conectores de alvo (SSH / shell local / psexec no estilo WinRM), integração de capacidades/ferramentas, limites de execução e logging estruturado — para que você possa expressar um novo experimento (um "caso de uso") em algumas dezenas de linhas de código. Nosso objetivo é ser O framework de referência para pesquisadores de segurança e pentesters que desejam usar LLMs (ou agentes autônomos baseados em LLM) para testes de segurança.

Para apoiar pesquisas reproduzíveis, também mantemos um benchmark reutilizável de escalação de privilégios no Linux e publicamos nossas descobertas como relatórios de acesso aberto. Se você precisar de ajuda para escolher um LLM para uma tarefa, temos um artigo comparando vários LLMs.

⚠️ Este software executa comandos reais em sistemas ativos. No modo shell local, ele os executa na sua máquina; no modo SSH/psexec, no alvo que você indicar. Execute-o apenas contra sistemas que você possui ou está explicitamente autorizado a testar, e prefira VMs ou containers isolados. Consulte os avisos legais.

Início rápido

# 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

A instalação do pacote fornece o comando wintermute. Executá-lo sem argumentos lista todos os casos de uso registrados; wintermute <UseCase> --help mostra as opções desse caso de uso.

Precisa de um alvo para praticar? Pegue uma máquina vulnerável do nosso Linux Privilege-Escalation Benchmark ou uma VM deliberadamente vulnerável como a Lin.Security do VulnHub.

Casos de uso

Os experimentos são estruturados em casos de uso. Cada um se torna um subcomando do wintermute. O framework atualmente inclui os seguintes:

Escalação de privilégios

Comando	Descrição
MinimalPrivEscLinux	Escalação de privilégios Linux mínima, com ~20 linhas. Modela todo o histórico em um único prompt a cada rodada e extrai um comando puro da resposta (o clássico loop do hackingBuddyGPT). Ótimo ponto de partida — veja Crie seu próprio caso de uso.
MinimalToolCallPrivEscLinux	O gêmeo com chamada de ferramentas do anterior: mantém um histórico de chat real e conduz o alvo por meio de chamada de funções. Sua ferramenta task_solved é verificada contra a verdade fundamental, de modo que um "obtive root" alucinado ou complacente não pode pontuar como um falso sucesso.
PrivEscLinux	Escalação de privilégios Linux completa baseada em estratégias, com geração aumentada por recuperação opcional (--rag_path), cadeia de pensamento (--enable_cot), rastreamento de estado e orientação estruturada.
PrivEscWindows	Escalação de privilégios Windows baseada em estratégias, conduzindo o alvo por meio de psexec em vez de SSH.
ExPrivEscLinuxLSE	Executa o lse.sh no alvo primeiro, transforma sua saída em dicas e então orquestra o PrivEscLinux por dica — um exemplo de caso de uso que chama outro caso de uso.

Web

Comando	Descrição
WebTestingWithExplanation	Testa autonomamente uma página web via HTTP enquanto permite que o LLM "fale" por meio de seu raciocínio; inclui uma capacidade de playbook de pentest no estilo OWASP.
WebTestingWithShell	Teste web com acesso de shell a uma máquina atacante no estilo Kali.
AdvancedWebTesting	Um agente de nível superior sem acesso direto ao alvo que delega trabalho a subagentes limitados por meio de uma capacidade de subagente.

API Web

Comando	Descrição
WebAPITesting	Detecta a superfície do alvo — uma especificação OpenAPI ou um sitemap de site — e então realiza pentest na API REST. Executa em --mode document (construir uma especificação), test (pentest de uma superfície conhecida) ou auto (ambos).

Active Directory

Comando	Descrição
AD	Pentest autônomo de Active Directory com premissa de invasão por LLM, portado da ferramenta de ataque cochise. Usa um design planejador/executor: um planejador estratégico persistente mantém uma árvore de tarefas e uma base de conhecimento compartilhada, delegando cada tarefa a um executor tático novo e sem memória.

Recursos do framework

• Dois estilos de execução em um loop compartilhado: agentes com chamada de ferramentas nativos (histórico de chat real + chamada de funções) e estratégias de comando em texto simples (template Mako → comando único analisado).
• Limites de execução unificados — limite qualquer execução por rodadas, tokens, custo (em dólares) e duração em tempo real (--limits.max_rounds/max_tokens/max_cost/max_duration).
• Um único upstream de LLM: litellm. Qualquer provedor é acessível por meio da string llm.model — OpenAI, OpenRouter (o endpoint padrão), Anthropic, Azure, um Ollama local e mais. Roteie o tráfego de API por um proxy de interceptação (Burp/mitmproxy) com --llm.proxy.
• Logging estruturado e autocontido — cada execução é gravada como um trace JSONL OpenTelemetry/GenAI somente de acréscimo, com ferramentas de CLI para reproduzir e agregar execuções.
• Modelo de execução totalmente assíncrono construído sobre asyncio.
• Detecção de sucesso verificada contra a verdade fundamental para escalação de privilégios (um "obtive root" alegado é verificado contra a saída real do comando).
• Lançador de benchmark em frota Docker para testes de regressão contra muitos alvos ao mesmo tempo.

Instalação e configuração

Requisitos: Python 3.13+. O projeto usa o backend de build uv; recomendamos uv para gerenciar o ambiente, mas um python -m venv simples + pip também funciona.

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 .