Communitygithub.com

caido-mode (Modo Caido)

CLI de cobertura total para a API do Caido, baseado no pacote oficial `@caido/sdk-client`, permitindo interação completa com o histórico HTTP, sessões, escopos e muito mais.

O que é caido-mode (Modo Caido)?

Esta skill fornece uma interface de linha de comando abrangente para a API do Caido, uma plataforma de proxy e teste de segurança web. Construída sobre o pacote oficial `@caido/sdk-client`, ela permite que agentes de IA e desenvolvedores interajam programaticamente com todos os principais recursos do Caido sem precisar da interface gráfica. As capacidades incluem busca e edição do histórico HTTP usando a linguagem de consulta HTTPQL, gerenciamento de sessões de repetição e coleções, controle de escopos de teste, criação de achados de segurança, monitoramento de tarefas em segundo plano e muito mais. Um recurso chave é a capacidade de `edit` (editar) requisições existentes, preservando cookies e cabeçalhos de autenticação, o que é ideal para testes de IDOR (Insecure Direct Object Reference) e bypass de autenticação. A autenticação é feita através de um Personal Access Token (PAT), que é trocado por um token de acesso via o fluxo device code do SDK, com cache persistente. A skill suporta o Caido como plataforma alvo e requer a instalação do pacote `@caido/sdk-client` para funcionar.

Funciona com✓Claude Code~Codex CLI✓Cursor✓OpenCode
npx skills add Aceproulx/claude-skills

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Habilidade Modo Caido

Visão Geral

CLI de cobertura total para a API do Caido, construída sobre o pacote oficial @caido/sdk-client. Abrange:

  • Histórico HTTP - Pesquisar, recuperar, repetir, editar requisições com HTTPQL
  • Repetição e Sessões - Sessões, coleções, entradas, fuzzing
  • Escopos - Criar e gerenciar escopos de teste (padrões de allowlist/denylist)
  • Filtros Salvos - Salvar e reutilizar presets de filtros HTTPQL
  • Ambientes - Armazenar variáveis de teste (IDs de vítimas, tokens, etc.)
  • Achados - Criar, listar, atualizar achados de segurança
  • Tarefas - Monitorar e cancelar tarefas em segundo plano
  • Projetos - Alternar entre projetos de teste
  • Arquivos Hospedados - Gerenciar arquivos servidos pelo Caido
  • Interceptação - Habilitar/desabilitar interceptação de requisições programaticamente
  • Plugins - Listar plugins instalados
  • Exportar - Converter requisições em comandos curl para PoCs
  • Saúde - Verificar o status da instância do Caido

Todo o tráfego passa pelo Caido, então ele aparece na interface do usuário para análise posterior.

Por que Este Modelo?

Cookies e tokens de autenticação podem ser enormes - cookies de sessão, JWTs, tokens CSRF podem facilmente ter 1-2KB. Em vez de copiar e colar manualmente:

  1. Encontre uma requisição orgânica no histórico HTTP do Caido que já tenha autenticação válida
  2. Use edit para modificar apenas o que você precisa (caminho, método, corpo) mantendo todos os cabeçalhos de autenticação intactos
  3. Envie - a resposta retorna com todo o contexto preservado

Configuração de Autenticação

Configuração (Uma Vez)

  1. Abra Painel → Desenvolvedor → Tokens de Acesso Pessoal
  2. Crie um novo token
  3. Execute:
npx tsx ~/.agents/skills/caido-mode/caido-client.ts setup <seu-pat>

# Instância Caido não padrão
npx tsx ~/.agents/skills/caido-mode/caido-client.ts setup <pat> http://192.168.1.100:8080

# Ou defina a variável de ambiente
CAIDO_PAT=caido_xxxxx

O comando setup valida o PAT através do SDK (que o troca por um token de acesso), então salva tanto o PAT quanto o token de acesso em cache em ~/.agents/config/secrets.json. Execuções subsequentes carregam o token em cache diretamente, e um token em cache válido pode ser usado mesmo quando o PAT estiver ausente.

Verificar Status

npx tsx ~/.agents/skills/caido-mode/caido-client.ts auth-status

Como a Autenticação Funciona

O SDK usa um fluxo de código de dispositivo internamente - o PAT o aprova automaticamente e recebe um token de acesso + token de atualização. Um SecretsTokenCache personalizado (implementando a interface TokenCache do SDK) persiste esses tokens no secrets.json para que sobrevivam entre as invocações da CLI.

Resolução de autenticação: variável de ambiente CAIDO_PAT → PAT em ~/.agents/config/secrets.json → token de acesso em cache válido → erro com instruções de configuração

Ferramenta CLI

Localizada em ~/.agents/skills/caido-mode/caido-client.ts. Todos os comandos produzem saída JSON.


Comandos de Histórico HTTP e Teste

search - Pesquisar histórico HTTP com HTTPQL

npx tsx caido-client.ts search 'req.method.eq:"POST" AND resp.code.eq:200'
npx tsx caido-client.ts search 'req.host.cont:"api"' --limit 50
npx tsx caido-client.ts search 'req.host.cont:"api"' --desc --limit 10
npx tsx caido-client.ts search 'req.path.cont:"/admin"' --ids-only
npx tsx caido-client.ts search 'resp.raw.cont:"password"' --after <cursor>

recent - Obter requisições recentes

npx tsx caido-client.ts recent
npx tsx caido-client.ts recent --limit 50

get / get-response - Recuperar detalhes completos

npx tsx caido-client.ts get <request-id>
npx tsx caido-client.ts get <request-id> --headers-only
npx tsx caido-client.ts get-response <request-id>
npx tsx caido-client.ts get-response <request-id> --compact

edit - Editar e repetir (RECURSO PRINCIPAL)

Modifica uma requisição existente preservando todos os cookies/cabeçalhos de autenticação:

# Alterar caminho (teste de IDOR)
npx tsx caido-client.ts edit <id> --path /api/user/999

# Alterar método e adicionar corpo
npx tsx caido-client.ts edit <id> --method POST --body '{"admin":true}'

# Adicionar/remover cabeçalhos
npx tsx caido-client.ts edit <id> --set-header "X-Forwarded-For: 127.0.0.1"
npx tsx caido-client.ts edit <id> --remove-header "X-CSRF-Token"

# Encontrar/substituir texto em qualquer lugar da requisição
npx tsx caido-client.ts edit <id> --replace "user123:::user456"

# Combinar múltiplas edições
npx tsx caido-client.ts edit <id> --method PUT --path /api/admin --body '{"role":"admin"}' --compact

# Reutilizar uma aba/sessão de repetição existente para sondas repetidas
npx tsx caido-client.ts edit <id> --path /api/user/1001 --session <session-id> --compact
OpçãoDescrição
--method <METHOD>Alterar método HTTP
--path <path>Alterar caminho da requisição
--set-header <Name: Valor>Adicionar ou substituir um cabeçalho (repetível)
--remove-header <Name>Remover um cabeçalho (repetível)
--body <content>Definir corpo da requisição (atualiza automaticamente Content-Length)
--replace <de>:::<para>Encontrar/substituir texto em qualquer lugar da requisição (repetível)
--session <id>Reutilizar uma sessão de repetição existente em vez de criar uma nova aba
--collection <id>Colocar uma nova sessão de repetição recém-criada em uma coleção
--sni <host>Substituir o SNI de TLS
--connect-host <host>Conectar a um host diferente preservando a requisição HTTP
--connect-port <port>Conectar a uma porta diferente
--connect-tls / --connect-no-tlsForçar TLS/texto simples para a conexão

replay / send-raw - Enviar requisições

# Repetir como está
npx tsx caido-client.ts replay <request-id>

# Repetir com raw personalizado
npx tsx caido-client.ts replay <id> --raw "GET /modified HTTP/1.1\r\nHost: example.com\r\n\r\n"

# Enviar requisição completamente personalizada
npx tsx caido-client.ts send-raw --host example.com --port 443 --tls --raw "GET / HTTP/1.1\r\nHost: example.com\r\n\r\n"
npx tsx caido-client.ts send-raw --host example.com --raw @request.txt --name "G /"
cat request.txt | npx tsx caido-client.ts send-raw --host example.com --raw -

# Conectar em outro lugar preservando o Host/SNI da requisição necessário
npx tsx caido-client.ts replay <id> --connect-host 10.0.0.5 --connect-port 8443 --sni example.com

--raw aceita uma string com escapes \r\n, @arquivo para ler do disco, ou - para ler da stdin.

export-curl - Converter para curl para PoCs

npx tsx caido-client.ts export-curl <request-id>

Produz um comando curl pronto para uso com todos os cabeçalhos e corpo.


Consulta de Aba de Repetição

Use estes comandos quando uma aba de repetição do Caido já estiver aberta e você quiser trabalhar a partir de sua entrada ativa diretamente.

npx tsx caido-client.ts get-session <session-id-or-name> --compact
npx tsx caido-client.ts replay-entries <session-id-or-name> --limit 20
npx tsx caido-client.ts replay-entries <session-id-or-name> --raw --compact
npx tsx caido-client.ts edit-session <session-id-or-name> --body '{"test":true}' --compact

session-entries é aceito como um alias para replay-entries.


Sessões e Coleções de Repetição

Sessões

# Criar sessão de repetição a partir de uma requisição existente
npx tsx caido-client.ts create-session <request-id>
npx tsx caido-client.ts create-session <request-id> --collection <collection-id>

# SEMPRE renomeie as sessões para fácil identificação na interface do Caido
npx tsx caido-client.ts rename-session <session-id> "idor-user-profile"

# Listar todas as sessões de repetição
npx tsx caido-client.ts replay-sessions
npx tsx caido-client.ts replay-sessions --limit 50

# Mover sessões entre coleções
npx tsx caido-client.ts move-session <session-id> <collection-id>

# Excluir sessões de repetição
npx tsx caido-client.ts delete-sessions <session-id-1>,<session-id-2>

Coleções

Organize sessões de repetição em coleções:

# Listar coleções de repetição
npx tsx caido-client.ts replay-collections
npx tsx caido-client.ts replay-collections --limit 50

# Criar uma coleção
npx tsx caido-client.ts create-collection "Teste IDOR"

# Renomear uma coleção
npx tsx caido-client.ts rename-collection <collection-id> "Testes de Bypass de Autenticação"

# Excluir uma coleção
npx tsx caido-client.ts delete-collection <collection-id>

Fuzzing

# Criar sessão automatizada para fuzzing
npx tsx caido-client.ts create-automate-session <request-id>

# Iniciar fuzzing (configure payloads e marcadores na interface do Caido primeiro)
npx tsx caido-client.ts fuzz <session-id>

Gerenciamento de Escopo

Defina o que está no escopo para seu teste. Usa padrões glob.

# Listar todos os escopos
npx tsx caido-client.ts scopes

# Criar escopo com allowlist e denylist
npx tsx caido-client.ts create-scope "Target Corp" --allow "*.target.com,*.target.io" --deny "*.cdn.target.com"

# Atualizar escopo
npx tsx caido-client.ts update-scope <scope-id> --allow "*.target.com,*.api.target.com"

# Excluir escopo
npx tsx caido-client.ts delete-scope <scope-id>

Padrões Glob: *.example.com corresponde a qualquer subdomínio de example.com.


Presets de Filtro

Salve consultas HTTPQL usadas com frequência como presets nomeados.

# Listar filtros salvos
npx tsx caido-client.ts filters

# Criar preset de filtro
npx tsx caido-client.ts create-filter "Erros de API" --query 'req.path.cont:"/api/" AND resp.code.gte:400'
npx tsx caido-client.ts create-filter "Endpoints de Autenticação" --query 'req.path.regex:"/(login|auth|oauth)/"' --alias "auth"

# Atualizar filtro
npx tsx caido-client.ts update-filter <filter-id> --query 'req.path.cont:"/api/" AND resp.code.gte:500'

# Excluir filtro
npx tsx caido-client.ts delete-filter <filter-id>

Variáveis de Ambiente

Armazene variáveis de teste que persistem entre sessões. Ótimo para teste de IDOR com múltiplos IDs de usuário.

# Listar ambientes
npx tsx caido-client.ts envs

# Criar ambiente
npx tsx caido-client.ts create-env "Teste-IDOR"

# Definir variáveis
npx tsx caido-client.ts env-set <env-id> victim_user_id "user_456"
npx tsx caido-client.ts env-set <env-id> attacker_token "eyJhbG..."

# Selecionar ambiente ativo
npx tsx caido-client.ts select-env <env-id>

# Desselecionar ambiente
npx tsx caido-client.ts select-env

# Excluir ambiente
npx tsx caido-client.ts delete-env <env-id>

Achados

Crie, liste e atualize achados de segurança. Aparece na aba Findings (Achados) do Caido.

# Listar todos os achados
npx tsx caido-client.ts findings
npx tsx caido-client.ts findings --limit 50

# Obter um achado específico
npx tsx caido-client.ts get-finding <finding-id>

# Criar achado vinculado a uma requisição
npx tsx caido-client.ts create-finding <request-id> \
  --title "IDOR no endpoint de perfil de usuário" \
  --description "Pode acessar perfis de outros usuários alterando o parâmetro de ID" \
  --reporter "rez0"

# Com chave de deduplicação (previne duplicatas)
npx tsx caido-client.ts create-finding <request-id> \
  --title "Bypass de autenticação em /admin" \
  --dedupe-key "admin-auth-bypass"

# Atualizar achado
npx tsx caido-client.ts update-finding <finding-id> \
  --title "Título atualizado" \
  --description "Descrição atualizada"

Tarefas

Monitore e cancele tarefas em segundo plano (importações, exportações, etc.).

# Listar todas as tarefas
npx tsx caido-client.ts tasks

# Cancelar uma tarefa em execução
npx tsx caido-client.ts cancel-task <task-id>

Gerenciamento de Projetos

# Listar todos os projetos
npx tsx caido-client.ts projects

# Alternar projeto ativo
npx tsx caido-client.ts select-project <project-id>

Arquivos Hospedados

# Listar arquivos hospedados
npx tsx caido-client.ts hosted-files

# Excluir arquivo hospedado
npx tsx caido-client.ts delete-hosted-file <file-id>

Controle de Interceptação

# Verificar status da interceptação
npx tsx caido-client.ts intercept-status

# Habilitar/desabilitar interceptação
npx tsx caido-client.ts intercept-enable
npx tsx caido-client.ts intercept-disable

Informações, Saúde e Plugins

# Informações do usuário atual
npx tsx caido-client.ts viewer

# Listar plugins instalados
npx tsx caido-client.ts plugins

# Verificar saúde da instância Caido (versão, estado de prontidão)
npx tsx caido-client.ts health

Controle de Saída

Funciona com get, get-response, replay, edit, send-raw:

FlagDescrição
--max-body <n>Máximo de linhas do corpo da resposta (padrão: 200, 0=ilimitado)
--max-body-chars <n>Máximo de caracteres do corpo (padrão: 5000, 0=ilimitado)
--no-requestPular o raw da requisição na saída
--headers-onlyApenas cabeçalhos HTTP, sem corpo
--compactAbreviação: --no-request --max-body 50 --max-body-chars 5000

Referência HTTPQL

Linguagem de consulta do Caido para pesquisar histórico HTTP.

CRÍTICO: Valores de string DEVEM estar entre aspas. Valores inteiros NÃO estão entre aspas.

CRÍTICO: HTTPQL NÃO tem operador NOT. Nunca escreva NOT expr. Use a variante de operador negado:

  • ncont (não contém), nlike (não é como), nregex (não é regex), ne (não é igual)
  • Errado: NOT req.path.cont:"/admin"
  • Certo: req.path.ncont:"/admin"

Namespaces e Campos

NamespaceCampoTipoDescrição
reqextstringExtensão de arquivo (inclui .)
reqhoststringHostname
reqmethodstringMétodo HTTP (maiúsculo)
reqpathstringCaminho da URL
reqquerystringString de consulta
reqrawstringRequisição raw completa
reqportintNúmero da porta
reqlenintTamanho do corpo da requisição
reqcreated_atdateTimestamp de criação
reqtlsboolÉ HTTPS
resprawstringResposta raw completa
respcodeintCódigo de status
resplenintTamanho do corpo da resposta
resproundtripintTempo de ida e volta (ms)
rowidintID da requisição
source-special"intercept", "replay", "automate", "workflow"
preset-specialReferência de preset de filtro

Operadores

String: eq, ne, cont, ncont, like, nlike, regex, nregex Inteiro: eq, ne, gt, gte, lt, lte Booleano: eq, ne Lógicos: AND, OR, parênteses para agrupamento

Exemplos de Consultas

# Requisições POST com respostas 200
req.method.eq:"POST" AND resp.code.eq:200

# Requisições de API
req.host.cont:"api" OR req.path.cont:"/v1/"

# Erros de servidor
resp.code.gte:500

# Requisições sem corpo, mas com resposta grande
req.len.eq:0 AND resp.len.gte:100000

# Usando fonte (source)
source.eq:"replay" AND req.path.cont:"/admin"

# Negação (use operadores n-*)
req.path.ncont:".css" AND req.path.ncont:".js"

Habilidades Relacionadas