Por quê

Agentes de codificação se tornaram testadores genuinamente úteis. Eles têm um shell, eles executam as mesmas ferramentas que você, e cobrem terreno rapidamente. Aponte um para um alvo e ele encontrará coisas.

Então a janela de contexto se enche, e o engajamento desaparece. A próxima sessão reescaneia hosts que já foram limpos, re-testa o que já foi descartado, e não consegue dizer quais partes do escopo foram alguma vez tocadas. Em algum lugar no transcrito está uma injeção SQL confirmada que ninguém anotou.

O Red Clippy resolve isso dando ao agente duas coisas que ele não tem por conta própria.

Um lugar para colocar o trabalho. Cada ativo, observação, verificação e descoberta cai em um banco de dados conforme o teste acontece, não em um buffer de rolagem. A cobertura vira uma consulta em vez de uma memória: quais ativos existem, quais verificações são concluídas em cada um, o que já foi relatado. A sessão de amanhã retoma exatamente de onde a última parou.

Regras para trabalhar. Um documento de Instruções da Equipe Vermelha chega ao agente no handshake do MCP, antes que ele faça qualquer coisa: verifique antes de relatar, comprove cada afirmação, tome o mínimo de acesso necessário para demonstrar impacto, deixe sistemas de terceiros em paz. Substitua-o por organização e por engajamento, porque as regras internas diferem entre equipes e clientes.

Você permanece no controle o tempo todo. Tudo o que o agente escreve é uma linha comum na interface web que você pode revisar, corrigir, reclassificar ou descartar.

[!CAUTION] Somente testes autorizados. O Red Clippy é para testadores de penetração trabalhando sob um engajamento. Teste apenas sistemas que você possui ou para os quais tem permissão escrita explícita para avaliar. A marcação de escopo e as Instruções da Equipe Vermelha existem para manter um agente dentro das regras de engajamento, mas são proteções, não autorização. Um agente age sob sua autoridade, e você permanece responsável por tudo o que ele faz.

Início rápido

Baixe um binário do último lançamento e execute-o. Ele configura o banco de dados e serve o painel em 127.0.0.1:7337.

Linux

Windows

Descompacte o arquivo e, a partir dessa pasta:

Abra http://127.0.0.1:7337 e o assistente de configuração assume a partir daí.

O banco de dados é criado no diretório onde você executa o binário. As evidências enviadas também são armazenadas lá, em red-clippy-storage. Ambos os caminhos podem ser alterados no arquivo de configuração, veja Configuração.

Prefere compilar você mesmo? Veja Compilando a partir do código-fonte.

Como os dados são organizados

O Red Clippy agrupa o trabalho em organizações. Uma organização contém seus pentests, e cada pentest contém os ativos, descobertas e evidências daquele engajamento. Se você testa para uma empresa, uma única organização é tudo o que você precisa. Se você presta consultoria para vários clientes, dê a cada cliente a sua própria: uma organização não vê nada que pertença a outra, então os engajamentos nunca se misturam.

Uma organização tem dois nomes. O nome de exibição ("Acme Corp") é o que você vê no painel e pode ser alterado depois. O slug (acme) é um identificador curto em minúsculas usado na pasta de evidências no disco (red-clippy-storage/org_acme/pentest_PT-2026-08-27/), então é fixo uma vez definido.

Você pode pertencer a várias organizações e alternar entre elas pelo menu do avatar. Em cada uma, você é ou um proprietário, que pode adicionar e remover pessoas e renomear ou excluir a organização, ou um membro, que trabalha nos engajamentos.

Primeira execução

No primeiro lançamento, o banco de dados está vazio, então o navegador mostra um assistente de configuração em vez de um formulário de login. Ele pede:

• um slug e nome de exibição para sua primeira organização
• um nome de usuário e, opcionalmente, um e-mail
• uma senha (mínimo de 8 caracteres)

A conta que ele cria é a proprietária dessa organização. O assistente só aparece enquanto o banco de dados não tem usuários; uma vez que a primeira conta existe, ele é permanentemente desativado, então não pode ser usado para criar contas extras depois.

Após a configuração, gerencie organizações e colegas de equipe no aplicativo em menu do avatar > Organizações.

Se ninguém conseguir entrar, a CLI é o caminho de volta:

Como usar

O fluxo pretendido é orientado por agente. Você configura o engajamento e depois trabalha no alvo com o Claude Code enquanto ele mantém o registro.

Você configura:

1. Crie um pentest. Código, escopo, datas. A lista de verificação de metodologia é preenchida automaticamente.
2. Defina o escopo. Adicione os domínios, hosts e faixas de IP que você está autorizado a testar, e marque qualquer coisa explicitamente fora do escopo. Você pode digitar isso você mesmo, ou colar a lista de escopo do cliente para o agente e fazer com que ele as insira para você.
3. Conecte o agente via MCP, fixado a este engajamento (veja abaixo).

O agente então trabalha e registra conforme avança:

• Executa ferramentas de reconhecimento e teste a partir do próprio shell, da maneira que normalmente faria.
• Entrega a saída bruta do scanner com ingest_tool_output, ou escreve ativos e observações diretamente.
• Promove unidades reais de escopo a ativos, deixando o resto como observações.
• Marca verificações de metodologia conforme as conclui.
• Registra descobertas com CVSS, PoC e evidências anexadas.

Você supervisiona:

• Observe tudo chegar no navegador em tempo real.
• Corrija qualquer coisa: cada linha que o agente escreveu é um registro comum que você pode editar, reclassificar ou excluir.
• Verifique a visão de cobertura para o que ainda não foi tocado.
• Revise no painel entre engajamentos, que mostra cada descoberta na organização junto com o pentest de onde veio.

O agente é opcional. Ele trabalha pela mesma API que o painel usa, então qualquer coisa que ele registra você também pode inserir, corrigir ou excluir você mesmo no navegador. Conduza um engajamento inteiramente manual, inteiramente pelo agente, ou alterne entre os dois conforme avança.

Conectando um agente de IA (MCP)

Esta é a principal forma como o Red Clippy deve ser usado.

red-clippy mcp cobre todo o aplicativo: escopo e ativos, observações, cobertura de metodologia, descobertas, evidências, o grafo de ataque e ingestão de saída de ferramentas. Um agente conectado trabalha no engajamento em vez de apenas responder perguntas sobre ele.

Ao conectar, o servidor entrega ao cliente o documento de Instruções da Equipe Vermelha, a doutrina operacional de como se comportar durante os testes, no handshake do MCP, então ele está no contexto do agente antes da primeira chamada de ferramenta. Ele resolve do mais específico para o mais geral, de uma substituição por engajamento, para um padrão de organização, para o documento embutido. Edite o padrão da organização em Configurações > Instruções da Equipe Vermelha, ou defina uma substituição por engajamento na página de configurações do pentest. get_instructions o relê sob demanda.

Criar uma chave de API

Emita uma em Configurações > Chaves de API. A seção Conectar MCP abaixo dela então fornece configuração pronta para colar para cada cliente, com essa chave, a URL deste servidor e o caminho do próprio binário já preenchidos. Não há nada para substituir manualmente.

Para criar a chave pela CLI em vez disso, e colá-la nos trechos você mesmo:

Claude Code

O nome após add é apenas um rótulo que o Claude Code mostra. O comando após -- é o que ele realmente executa, então use o caminho completo do binário: o Claude Code não encontrará necessariamente red-clippy no seu PATH. Se você copiar o comando da seção Conectar MCP no painel, o caminho correto já está preenchido.

z.ai GLM

A z.ai serve um endpoint compatível com Anthropic, então o Claude Code pode conduzir o Red Clippy com GLM em vez de um modelo Anthropic.

Adicione isso às configurações do Claude Code: .claude/settings.local.json dentro da sua pasta de trabalho para limitá-lo a um engajamento, ou ~/.claude/settings.json para aplicá-lo em todos os lugares.

Duas coisas para substituir:

• sua-chave-de-api-z-ai pela sua própria chave. Prefira o .claude/settings.local.json local do projeto, que o Claude Code mantém fora do git, então a chave não acaba sendo commitada.
• glm-5.3 pelo modelo que a z.ai oferece atualmente. Os nomes dos modelos mudam, então verifique o guia do Claude Code da z.ai para o atual e defina cada entrada para ele.

Depois adicione o servidor MCP exatamente como acima. O Red Clippy não é afetado pela escolha do modelo: o MCP roda no lado do cliente, então as ferramentas se comportam de forma idêntica independentemente do modelo por trás do agente.

OpenAI Codex CLI

Conforme a configuração do Codex CLI, em ~/.codex/config.toml:

Qualquer outro cliente MCP

red-clippy mcp é um servidor stdio JSON-RPC 2.0 simples. Ele precisa de duas coisas no seu ambiente e aceita uma fixação opcional de engajamento:

--pentest vincula a sessão a um engajamento para que o agente não precise nomeá-lo em cada chamada. Execute uma entrada MCP por engajamento ativo e alterne engajamentos alternando os servidores.

Uma vez conectado, você pode simplesmente pedir: "adicione uma descoberta ao PT-2026-Q2-ACME: XSS refletido em /search, severidade alta, aqui está o PoC".

[!NOTE] Seu agente e red-clippy serve rodam na mesma máquina, e é por isso que RED_CLIPPY_URL aponta para 127.0.0.1.

Recursos

Uma superfície MCP completa de ferramentas. Paridade quase total com a interface web, não um subconjunto mínimo. Um agente pode criar e definir escopo de ativos, anexar observações, marcar verificações de metodologia, registrar e atualizar descobertas, enviar evidências, construir arestas de grafo e pesquisar em toda a organização.

Escopo que permanece limpo. Ativos são as unidades que você realmente testa: domínios, hosts, URLs, APIs, pacotes móveis, faixas de IP. Cada um carrega sua própria lista de verificação, marcação de alcançabilidade e sinalizador dentro/fora do escopo. Ruído de reconhecimento (caminhos descobertos, impressões digitais de tecnologia, certificados, URLs do wayback) anexa-se a um ativo como uma observação em vez de entrar na lista de escopo, e é promovido a ativo apenas quando merece. Sem essa divisão, uma única execução de descoberta de conteúdo deixa a lista de ativos inutilizável.

Descobertas até o relatório. Severidade, CVSS 3.1 com uma calculadora embutida no formulário, CWE/CVE, PoC, remediação e evidências em arquivo. Um painel entre engajamentos lista cada descoberta na organização contra seu pentest de origem, que é a visão que um reteste precisa.

Cobertura que você pode consultar. 135 verificações embutidas mapeadas para OWASP WSTG, além de verificações de reconhecimento, rede, nuvem e OSINT. Resumos relatam o que foi testado por ativo e por engajamento, para que o terreno já limpo não seja re-testado.

Doutrina operacional. O documento de Instruções da Equipe Vermelha, servido via MCP e resolvido por engajamento, depois por organização, depois pelo padrão embutido.

Ingestão de saída de ferramentas. A saída bruta do scanner é submetida em uma única chamada, que é como um agente move resultados do próprio shell para o registro. Analisadores para nmap, burp, nessus, openvas, masscan, naabu e subfinder, com detecção automática de formato. Descobertas, reconhecimento e saída bruta chegam juntos em uma única transação.

Um grafo de ataque. Vincule quaisquer dois nós com uma relação de forma livre e depois percorra vizinhos ou calcule caminhos de ataque mais curtos entre eles.

Multi-tenant. Cada registro pertence a uma organização. Um usuário pode pertencer a várias e alternar sem sair, então os dados do cliente permanecem separados.

API REST. Chaves bearer com escopo de organização, mesma superfície de tudo acima.

Opcional: um executor de varredura embutido. Uma conveniência para conduzir subfinder, nmap, masscan e naabu pela página de Varredura, com cobertura retomável por alvo. Ele existe para uso manual do operador e não faz parte do fluxo de trabalho normal orientado por agente, onde o agente executa suas próprias ferramentas e ingere a saída.

A documentação cobre tudo isso tela por tela, com a referência de ferramentas MCP, a API REST e o modelo de dados. Este README cobre como começar e rodar.

Configuração

As configurações vêm de um arquivo TOML. red-clippy serve lê ./red-clippy.toml por padrão. Copie o exemplo e edite:

Cada campo também pode ser definido por sinalizador de CLI ou variável de ambiente. A precedência é sinalizador de CLI > variável de ambiente > TOML > padrão embutido, por campo.

Duas configurações são somente de arquivo:

• frontend_dist substitui o SPA compilado. Os binários de lançamento o incorporam, então isso normalmente não é definido; aponte-o para um diretório para servir um bundle corrigido sem recompilar.
• local_open permite que o botão "revelar no gerenciador de arquivos" da página de Arquivos execute xdg-open / open / explorer.exe na máquina que executa o servidor. Ele vem desativado. Ative-o apenas quando o servidor for seu próprio desktop em uma sessão gráfica com login, nunca sob systemd ou ao servir remotamente.

Uma chave que ele não reconhece interrompe a inicialização com um erro em vez de ser ignorada, então um erro de digitação não pode silenciosamente deixá-lo em um padrão.

A filtragem de logs usa RUST_LOG (padrão info,sqlx=warn).

Execute red-clippy serve --help para a lista completa.

[!WARNING] Execute-o localmente. O Red Clippy vincula-se a 127.0.0.1 e deve ser executado na sua própria máquina, ao lado do agente que o conduz. Ele não foi projetado para ser exposto a uma rede ou à internet.

Referência da CLI

Adicione --help a qualquer subcomando para seus sinalizadores.

A API REST fica em /api/v1 e autentica com Authorization: Bearer rcl_<prefixo>_<segredo>. As chaves têm escopo de organização, então nenhum endpoint recebe uma organização em sua URL. A página Ajuda no aplicativo documenta os endpoints.

Compilando a partir do código-fonte

Linux e macOS

make all compila a interface web primeiro e depois compila o binário com esse bundle incorporado.

[!NOTE] Ordem de compilação. O bundle React é incorporado em tempo de compilação. Executar cargo build --release sozinho funciona, mas se a interface nunca foi compilada, o binário envia uma página de espaço reservado (o cargo imprime um aviso). Execute make frontend primeiro, ou apenas use make all.

Windows

Compile nativamente com rustup, as ferramentas de compilação MSVC e Node instalados:

Ou compile de forma cruzada a partir do Linux usando o toolchain mingw-w64 (apt install gcc-mingw-w64-x86-64):

Copie esse único .exe para o host Windows e execute-o. Nada mais para instalar.

Desenvolvimento

Compilações de debug leem frontend/dist do disco em tempo de execução em vez de incorporá-lo, então você pode recompilar a interface sem recompilar o Rust.

Antes de abrir um pull request, execute o que o CI executa: cargo fmt --all --check, make clippy, make test, make lint e make frontend. make install-hooks conecta os gates de formatação e lint a um hook pré-commit. Veja CONTRIBUTING.md para a versão mais completa, incluindo como adicionar um analisador.

Lançando uma versão

Aumente version em Cargo.toml e depois envie uma tag correspondente:

O CI compila um binário Linux estático e um executável Windows e depois publica ambos como um lançamento do GitHub com somas de verificação. A tag deve corresponder à versão do crate ou a compilação falha. Para ensaiar sem publicar, execute o workflow de Lançamento manualmente na aba Actions: ele compila e envia os arquivos como artefatos do workflow e pula a etapa de lançamento.

Contribuindo

Relatórios de bugs, analisadores para novas ferramentas e cobertura MCP são bem-vindos - veja CONTRIBUTING.md.

Encontrou um problema de segurança? Por favor, relate-o de forma privada via SECURITY.md em vez de abrir uma issue.

Licença

Copyright (C) 2026 Cyber Security & Privacy Foundation

Lançado sob a GNU General Public License v3.0. Este programa vem com ABSOLUTAMENTE NENHUMA GARANTIA; veja a licença para detalhes.