pentest-copilot

Agente de teste de penetração orientado por IA que se conecta a uma máquina Kali, executa ferramentas de segurança de forma autónoma, analisa resultados e itera através de fluxos de trabalho baseados no navegador.

Vê-lo no YouTube

Histórico de Estrelas

O Que Faz

• Execução agêntica - a IA executa comandos diretamente na máquina de ataque, lê a saída, decide os próximos passos e repete. Até 25 iterações por turno, sem necessidade de intervenção manual.
• 16 ferramentas de agente - bash, scripts Python, instalação de ferramentas, gestão de shell, pesquisa Google, criação de subagentes, Burp Suite (histórico de proxy, Repeater, Intruder, Collaborator) e automação de browser.
• 100+ capacidades - registo curado de ferramentas de segurança e pacotes Python em 7 categorias (rede, rev, pwn, crypto, forense, stego, core). Seleciona o que precisas, o agente instala o resto.
• Integração com Burp Suite - visualizador de histórico de proxy, envio de pedidos para Repeater/Intruder, Collaborator para testes out-of-band. Tudo acessível ao agente e através da UI.
• Agente de browser - automação de browser real via Magnitude. Testa fluxos de login, preenche formulários, interage com aplicações com muito JavaScript. Opcionalmente encaminha o tráfego através do Burp. Em modo Docker, observa o browser através do stream VNC integrado; em modo de programador, o browser abre no teu desktop local.
• Gestão de VPN - carrega bundles .ovpn/.conf com certificados, chaves ou credenciais referenciados e liga/desliga a partir do browser. Suporta múltiplas ligações simultâneas.
• Paralelismo de subagentes - cria agentes em segundo plano para executar tarefas em simultâneo (por exemplo, brute-force de diretórios + enumeração de subdomínios ao mesmo tempo).
• Verificações de segurança - comandos perigosos (eliminações recursivas, escritas em dispositivos, fork bombs) requerem aprovação explícita, mesmo em modo de execução automática.
• Traz o teu próprio modelo - OpenAI, Anthropic (chave de API ou OAuth), Google, Mistral, ou qualquer endpoint compatível com OpenAI.
• Usa subscrições locais existentes - o Pentest Copilot pode usar um Codex CLI autenticado em modo Docker ou host, e Claude Code em modo host/developer, como fornecedores de inferência normais, mantendo o seu próprio ciclo de ferramentas e consentimento.

Início Rápido

Abre http://localhost:3000, regista-te e inicia uma sessão.

O run.sh aguarda que o frontend, backend, MongoDB e Redis estejam prontos antes de reportar sucesso. Se o arranque falhar, imprime o estado dos contentores afetados e os logs recentes. Configura e atribui um modelo em Settings -> Models após o primeiro arranque.

No Windows, executa o Pentest Copilot dentro do WSL2 com a integração WSL do Docker Desktop ativada. Hosts de trabalho nativos em PowerShell e Windows SSH não são suportados porque os comandos do workspace requerem uma shell POSIX. Para permissões de ficheiros e desempenho fiáveis, clona o repositório para o sistema de ficheiros do WSL, não em /mnt/c.

Inferência por subscrição Codex e Claude

Settings -> Models deteta CLIs Codex e Claude Code autenticados. Autentica uma vez na máquina que executa a CLI:

Depois seleciona Use Codex ou Use Claude Code. A CLI oficial é responsável pelo login, refresh e gestão de direitos de subscrição; o Pentest Copilot não copia nem reproduz tokens OAuth. Os transportes de subscrição recebem o mesmo histórico de conversa e esquemas de funções que os fornecedores de API e devolvem o mesmo contrato de chamada assistant/tool, pelo que o Pentest Copilot continua a executar ferramentas e verificações de consentimento.

O backend Docker inclui a CLI Linux Codex e monta apenas o ~/.codex/auth.json baseado em ficheiro do host, seguindo o fluxo documentado de transferência de login headless/Docker do Codex. Define CODEX_AUTH_FILE antes de docker compose up se o teu ficheiro de credenciais estiver noutro local. A CLI pode atualizar esse ficheiro durante o uso normal; nunca o faças commit nem o partilhes. Credenciais apenas no Keychain do host e Claude Code permanecem disponíveis apenas em modo developer/host até que uma ponte de inferência no host seja configurada. O uso da subscrição Claude é controlo local da CLI e deve cumprir os termos atuais de produtos e subscrições de terceiros da Anthropic.

As famílias de modelos de primeira linha atuais incluem GPT-5.6 Sol/Terra/Luna, Claude Fable/Opus/Sonnet 5, e Kimi K3 (API direta Moonshot ou OpenRouter).

Perfis SSH com âmbito de workspace

Em modo Docker, o Pentest Copilot monta os diretórios ~/.ssh e ~/keys do host em modo só de leitura. Cada workspace pode selecionar um alias Host concreto de ~/.ssh/config em Connection. Cada sessão nesse workspace usa o mesmo host e pasta de trabalho sem copiar chaves privadas para o MongoDB. Define HOST_SSH_DIR ou HOST_SSH_KEYS_DIR antes de iniciar o Docker quando esses diretórios estiverem noutro local.

Usa aliases nomeados em vez de entradas apenas com wildcard:

O run.sh trata da geração de ficheiros de configuração, builds Docker e orquestração de contentores. Usa ./run.sh start -q para reutilizar o modo de arranque anterior e ignorar prompts em execuções subsequentes.

Para a matriz completa de cenários de SO, Docker, SSH, VPN, proxy, permissões, recuperação e implementação, consulta Setup and Troubleshooting.

Acesso MCP

O Pentest Copilot pode expor o seu plano de controlo local através de MCP para clientes como Claude Code ou Codex. Abre Settings -> MCP Access para copiar o endpoint MCP local e o token bearer.

Trata o token como acesso de administrador local: pode executar comandos na máquina de exploração configurada, operar Burp, automação de browser e fluxos VPN, ler artefactos, escrever descobertas e atualizar a configuração local do Pentest Copilot. As ações MCP ligadas a um engagement são registadas nessa sessão para que permaneçam visíveis na UI do Pentest Copilot.

Depois de copiar o endpoint e o token, podes fazer um smoke test da ligação MCP:

Requisitos de Sistema

O modo Docker liga a sua UI e portas de serviço a 127.0.0.1 por predefinição. Não exponhas a stack a uma LAN ou à internet sem TLS, autenticação e uma configuração deliberada de reverse-proxy. No modo Kali integrado, mantém os ficheiros de workspace duradouros em /kali-data; ficheiros noutros locais do contentor Kali são removidos quando o contentor é recriado.

Documentação

O guia Setup and Troubleshooting no repositório é a fonte autoritativa para instalação, configuração, recuperação e implementação. A Wiki contém referência adicional de funcionalidades e pode estar desatualizada em relação à versão atual:

• Getting Started - visão geral do projeto
• Architecture - design do sistema, ciclo do agente, subagentes
• Usage - fluxo de trabalho, modelo de consentimento, interface de chat
• Features - visão geral completa das funcionalidades
• Settings - modelos, SSH, VNC, Burp, Magnitude
• Capabilities - registo de ferramentas e buckets
• Agent Tools - todas as 16 ferramentas e comportamento de consentimento
• Burp Suite Integration - configuração e utilização
• Browser Agent - configuração do Magnitude
• VPN Management - gestão de perfis
• Slash Commands - utilitários de sessão
• Changelog - novidades

Desenvolvimento Local

Depois, em terminais separados:

Para configuração de desenvolvimento e resolução de problemas, consulta o guia Setup and Troubleshooting.

Autores

• Dhruva Goyal - [email protected] | LinkedIn | GitHub | X
• Aditya Peela - [email protected] | LinkedIn | GitHub | X
• Sitaraman Subramanian - [email protected] | LinkedIn | GitHub | X

Citações

Contribuir

Contribuições são bem-vindas. Consulta o Guia de Contribuição e o Código de Conduta.

Licença

MIT License

Aviso Legal

O Pentest Copilot destina-se apenas a testes de segurança autorizados. Tem sempre permissão explícita antes de testar qualquer sistema.