Habilidad Caido Mode
Resumen
CLI de cobertura completa para la API de Caido, construido sobre el paquete oficial @caido/sdk-client. Cubre:
- Historial HTTP - Buscar, recuperar, reproducir, editar solicitudes con HTTPQL
- Repetición y Sesiones - Sesiones, colecciones, entradas, fuzzing
- Ámbitos - Crear y gestionar ámbitos de prueba (patrones de lista blanca/lista negra)
- Preajustes de Filtro - Guardar y reutilizar preajustes de filtro HTTPQL
- Entornos - Almacenar variables de prueba (IDs de víctima, tokens, etc.)
- Hallazgos - Crear, listar, actualizar hallazgos de seguridad
- Tareas - Monitorear y cancelar tareas en segundo plano
- Proyectos - Cambiar entre proyectos de prueba
- Archivos Alojados - Gestionar archivos servidos por Caido
- Interceptación - Habilitar/deshabilitar la interceptación de solicitudes programáticamente
- Plugins - Listar plugins instalados
- Exportar - Convertir solicitudes a comandos curl para PoCs
- Salud - Verificar el estado de la instancia de Caido
Todo el tráfico pasa a través de Caido, por lo que aparece en la interfaz de usuario para su análisis posterior.
¿Por qué este modelo?
Las cookies y los tokens de autenticación pueden ser enormes - las cookies de sesión, los JWT, los tokens CSRF pueden fácilmente tener 1-2KB. En lugar de copiar y pegar manualmente:
- Encuentra una solicitud orgánica en el historial HTTP de Caido que ya tenga autenticación válida
- Usa
editpara modificar solo lo que necesitas (ruta, método, cuerpo) mientras mantienes todas las cabeceras de autenticación intactas - Envíala - la respuesta regresa con el contexto completo preservado
Configuración de Autenticación
Configuración (Una Sola Vez)
- Abrir Panel de Control → Desarrollador → Tokens de Acceso Personal
- Crear un nuevo token
- Ejecutar:
npx tsx ~/.agents/skills/caido-mode/caido-client.ts setup <tu-pat>
# Instancia de Caido no predeterminada
npx tsx ~/.agents/skills/caido-mode/caido-client.ts setup <pat> http://192.168.1.100:8080
# O establecer variable de entorno en su lugar
export CAIDO_PAT=caido_xxxxx
El comando setup valida el PAT a través del SDK (que lo intercambia por un token de acceso), luego guarda tanto el PAT como el token de acceso en caché en ~/.agents/config/secrets.json. Las ejecuciones posteriores cargan el token en caché directamente, y un token en caché válido se puede usar incluso cuando el PAT está ausente.
Verificar Estado
npx tsx ~/.agents/skills/caido-mode/caido-client.ts auth-status
Cómo Funciona la Autenticación
El SDK utiliza un flujo de código de dispositivo internamente — el PAT lo aprueba automáticamente y recibe un token de acceso + token de actualización. Un SecretsTokenCache personalizado (que implementa la interfaz TokenCache del SDK) persiste estos tokens en secrets.json para que sobrevivan a través de invocaciones del CLI.
Resolución de autenticación: variable de entorno CAIDO_PAT → PAT en ~/.agents/config/secrets.json → token de acceso en caché válido → error con instrucciones de configuración
Herramienta CLI
Ubicada en ~/.agents/skills/caido-mode/caido-client.ts. Todos los comandos generan JSON.
Comandos de Historial y Pruebas HTTP
search - Buscar en el historial HTTP con 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 - Obtener solicitudes recientes
npx tsx caido-client.ts recent
npx tsx caido-client.ts recent --limit 50
get / get-response - Recuperar detalles completos
npx tsx caido-client.ts get <id-solicitud>
npx tsx caido-client.ts get <id-solicitud> --headers-only
npx tsx caido-client.ts get-response <id-solicitud>
npx tsx caido-client.ts get-response <id-solicitud> --compact
edit - Editar y reproducir (CARACTERÍSTICA CLAVE)
Modifica una solicitud existente preservando todas las cookies/cabeceras de autenticación:
# Cambiar ruta (pruebas IDOR)
npx tsx caido-client.ts edit <id> --path /api/user/999
# Cambiar método y agregar cuerpo
npx tsx caido-client.ts edit <id> --method POST --body '{"admin":true}'
# Agregar/eliminar cabeceras
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"
# Buscar/reemplazar texto en cualquier lugar de la solicitud
npx tsx caido-client.ts edit <id> --replace "user123:::user456"
# Combinar múltiples ediciones
npx tsx caido-client.ts edit <id> --method PUT --path /api/admin --body '{"role":"admin"}' --compact
# Reutilizar una pestaña/sesión de repetición existente para sondeos repetidos
npx tsx caido-client.ts edit <id> --path /api/user/1001 --session <id-sesion> --compact
| Opción | Descripción |
|---|---|
--method <MÉTODO> | Cambiar método HTTP |
--path <ruta> | Cambiar ruta de solicitud |
--set-header <Nombre: Valor> | Agregar o reemplazar una cabecera (repetible) |
--remove-header <Nombre> | Eliminar una cabecera (repetible) |
--body <contenido> | Establecer cuerpo de solicitud (actualiza automáticamente Content-Length) |
--replace <de>:::<a> | Buscar/reemplazar texto en cualquier lugar de la solicitud (repetible) |
--session <id> | Reutilizar una sesión de repetición existente en lugar de crear una nueva pestaña |
--collection <id> | Colocar una nueva sesión de repetición creada en una colección |
--sni <host> | Sobrescribir SNI TLS |
--connect-host <host> | Conectar a un host diferente preservando la solicitud HTTP |
--connect-port <puerto> | Conectar a un puerto diferente |
--connect-tls / --connect-no-tls | Forzar TLS/texto plano para la conexión |
replay / send-raw - Enviar solicitudes
# Reproducir tal cual
npx tsx caido-client.ts replay <id-solicitud>
# Reproducir con raw personalizado
npx tsx caido-client.ts replay <id> --raw "GET /modified HTTP/1.1\r\nHost: example.com\r\n\r\n"
# Enviar solicitud 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 a otro lugar mientras se preserva el Host/SNI de la solicitud que necesitas
npx tsx caido-client.ts replay <id> --connect-host 10.0.0.5 --connect-port 8443 --sni example.com
--raw acepta una cadena con escapes \r\n, @archivo para leer desde disco, o - para leer desde stdin.
export-curl - Convertir a curl para PoCs
npx tsx caido-client.ts export-curl <id-solicitud>
Genera un comando curl listo para usar con todas las cabeceras y el cuerpo.
Búsqueda de Pestañas de Repetición
Úsalos cuando una pestaña de repetición de Caido ya esté abierta y quieras trabajar directamente desde su entrada activa.
npx tsx caido-client.ts get-session <id-o-nombre-sesion> --compact
npx tsx caido-client.ts replay-entries <id-o-nombre-sesion> --limit 20
npx tsx caido-client.ts replay-entries <id-o-nombre-sesion> --raw --compact
npx tsx caido-client.ts edit-session <id-o-nombre-sesion> --body '{"test":true}' --compact
session-entries se acepta como un alias para replay-entries.
Sesiones y Colecciones de Repetición
Sesiones
# Crear sesión de repetición desde una solicitud existente
npx tsx caido-client.ts create-session <id-solicitud>
npx tsx caido-client.ts create-session <id-solicitud> --collection <id-coleccion>
# SIEMPRE renombrar sesiones para facilitar la identificación en la interfaz de usuario de Caido
npx tsx caido-client.ts rename-session <id-sesion> "idor-perfil-usuario"
# Listar todas las sesiones de repetición
npx tsx caido-client.ts replay-sessions
npx tsx caido-client.ts replay-sessions --limit 50
# Mover sesiones entre colecciones
npx tsx caido-client.ts move-session <id-sesion> <id-coleccion>
# Eliminar sesiones de repetición
npx tsx caido-client.ts delete-sessions <id-sesion-1>,<id-sesion-2>
Colecciones
Organizar sesiones de repetición en colecciones:
# Listar colecciones de repetición
npx tsx caido-client.ts replay-collections
npx tsx caido-client.ts replay-collections --limit 50
# Crear una colección
npx tsx caido-client.ts create-collection "Pruebas IDOR"
# Renombrar una colección
npx tsx caido-client.ts rename-collection <id-coleccion> "Pruebas de Bypass de Autenticación"
# Eliminar una colección
npx tsx caido-client.ts delete-collection <id-coleccion>
Fuzzing
# Crear sesión de automatización para fuzzing
npx tsx caido-client.ts create-automate-session <id-solicitud>
# Iniciar fuzzing (configurar cargas útiles y marcadores en la interfaz de usuario de Caido primero)
npx tsx caido-client.ts fuzz <id-sesion>
Gestión de Ámbitos
Define lo que está dentro del alcance para tus pruebas. Utiliza patrones glob.
# Listar todos los ámbitos
npx tsx caido-client.ts scopes
# Crear ámbito con lista blanca y lista negra
npx tsx caido-client.ts create-scope "Target Corp" --allow "*.target.com,*.target.io" --deny "*.cdn.target.com"
# Actualizar ámbito
npx tsx caido-client.ts update-scope <id-ambito> --allow "*.target.com,*.api.target.com"
# Eliminar ámbito
npx tsx caido-client.ts delete-scope <id-ambito>
Patrones glob: *.example.com coincide con cualquier subdominio de example.com.
Preajustes de Filtro
Guarda consultas HTTPQL de uso frecuente como preajustes con nombre.
# Listar filtros guardados
npx tsx caido-client.ts filters
# Crear preajuste de filtro
npx tsx caido-client.ts create-filter "Errores API" --query 'req.path.cont:"/api/" AND resp.code.gte:400'
npx tsx caido-client.ts create-filter "Endpoints de Autenticación" --query 'req.path.regex:"/(login|auth|oauth)/"' --alias "auth"
# Actualizar filtro
npx tsx caido-client.ts update-filter <id-filtro> --query 'req.path.cont:"/api/" AND resp.code.gte:500'
# Eliminar filtro
npx tsx caido-client.ts delete-filter <id-filtro>
Variables de Entorno
Almacena variables de prueba que persisten entre sesiones. Excelente para pruebas IDOR con múltiples IDs de usuario.
# Listar entornos
npx tsx caido-client.ts envs
# Crear entorno
npx tsx caido-client.ts create-env "Prueba-IDOR"
# Establecer variables
npx tsx caido-client.ts env-set <id-entorno> victim_user_id "user_456"
npx tsx caido-client.ts env-set <id-entorno> attacker_token "eyJhbG..."
# Seleccionar entorno activo
npx tsx caido-client.ts select-env <id-entorno>
# Deseleccionar entorno
npx tsx caido-client.ts select-env
# Eliminar entorno
npx tsx caido-client.ts delete-env <id-entorno>
Hallazgos
Crear, listar y actualizar hallazgos de seguridad. Aparece en la pestaña de Hallazgos de Caido.
# Listar todos los hallazgos
npx tsx caido-client.ts findings
npx tsx caido-client.ts findings --limit 50
# Obtener un hallazgo específico
npx tsx caido-client.ts get-finding <id-hallazgo>
# Crear hallazgo vinculado a una solicitud
npx tsx caido-client.ts create-finding <id-solicitud> \
--title "IDOR en endpoint de perfil de usuario" \
--description "Se puede acceder a perfiles de otros usuarios cambiando el parámetro ID" \
--reporter "rez0"
# Con clave de deduplicación (evita duplicados)
npx tsx caido-client.ts create-finding <id-solicitud> \
--title "Bypass de autenticación en /admin" \
--dedupe-key "admin-auth-bypass"
# Actualizar hallazgo
npx tsx caido-client.ts update-finding <id-hallazgo> \
--title "Título actualizado" \
--description "Descripción actualizada"
Tareas
Monitorear y cancelar tareas en segundo plano (importaciones, exportaciones, etc.).
# Listar todas las tareas
npx tsx caido-client.ts tasks
# Cancelar una tarea en ejecución
npx tsx caido-client.ts cancel-task <id-tarea>
Gestión de Proyectos
# Listar todos los proyectos
npx tsx caido-client.ts projects
# Cambiar proyecto activo
npx tsx caido-client.ts select-project <id-proyecto>
Archivos Alojados
# Listar archivos alojados
npx tsx caido-client.ts hosted-files
# Eliminar archivo alojado
npx tsx caido-client.ts delete-hosted-file <id-archivo>
Control de Interceptación
# Verificar estado de interceptación
npx tsx caido-client.ts intercept-status
# Habilitar/deshabilitar interceptación
npx tsx caido-client.ts intercept-enable
npx tsx caido-client.ts intercept-disable
Información, Salud y Plugins
# Información del usuario actual
npx tsx caido-client.ts viewer
# Listar plugins instalados
npx tsx caido-client.ts plugins
# Verificar salud de la instancia de Caido (versión, estado de preparación)
npx tsx caido-client.ts health
Control de Salida
Funciona con get, get-response, replay, edit, send-raw:
| Indicador | Descripción |
|---|---|
--max-body <n> | Máximo de líneas del cuerpo de la respuesta (predeterminado: 200, 0=ilimitado) |
--max-body-chars <n> | Máximo de caracteres del cuerpo (predeterminado: 5000, 0=ilimitado) |
--no-request | Omitir raw de solicitud en la salida |
--headers-only | Solo cabeceras HTTP, sin cuerpo |
--compact | Abreviatura: --no-request --max-body 50 --max-body-chars 5000 |
Referencia HTTPQL
Lenguaje de consulta de Caido para buscar en el historial HTTP.
CRÍTICO: Los valores de cadena DEBEN estar entre comillas. Los valores enteros NO se entrecomillan.
CRÍTICO: HTTPQL NO tiene operador NOT. Nunca escribas NOT expr. Usa la variante de operador negada en su lugar:
ncont(no contiene),nlike(no como),nregex(no regex),ne(no igual)- Incorrecto:
NOT req.path.cont:"/admin" - Correcto:
req.path.ncont:"/admin"
Espacios de Nombres y Campos
| Espacio de Nombres | Campo | Tipo | Descripción |
|---|---|---|---|
req | ext | cadena | Extensión de archivo (incluye .) |
req | host | cadena | Nombre de host |
req | method | cadena | Método HTTP (mayúsculas) |
req | path | cadena | Ruta URL |
req | query | cadena | Cadena de consulta |
req | raw | cadena | Solicitud raw completa |
req | port | entero | Número de puerto |
req | len | entero | Longitud del cuerpo de la solicitud |
req | created_at | fecha | Marca de tiempo de creación |
req | tls | booleano | Es HTTPS |
resp | raw | cadena | Respuesta raw completa |
resp | code | entero | Código de estado |
resp | len | entero | Longitud del cuerpo de la respuesta |
resp | roundtrip | entero | Tiempo de ida y vuelta (ms) |
row | id | entero | ID de solicitud |
source | - | especial | "intercept", "replay", "automate", "workflow" |
preset | - | especial | Referencia de preajuste de filtro |
Operadores
Cadena: eq, ne, cont, ncont, like, nlike, regex, nregex
Entero: eq, ne, gt, gte, lt, lte
Booleano: eq, ne
Lógicos: AND, OR, paréntesis para agrupar
Consultas de Ejemplo
# Solicitudes POST con respuestas 200
req.method.eq:"POST" AND resp.code.eq:200
# Solicitudes API
req.host.cont:"api" OR req.path.cont:"/api/"
# No contengan "admin"
req.path.ncont:"admin"
# Método GET, longitud del cuerpo 0, no sean de interceptación
req.method.eq:"GET" AND req.len.eq:0 AND source.ne:"intercept"
# Búsqueda entre fechas (usando marca de tiempo ISO)
req.created_at.gte:"2024-01-01T00:00:00Z" AND req.created_at.lt:"2024-02-01T00:00:00Z"
# Respuestas de error con coincidencia de patrón
resp.code.gte:400 AND resp.raw.regex:"(stack trace|exception|SQL syntax)"
# Búsquedas complejas con anidamiento
(req.method.eq:"POST" OR req.method.eq:"PUT") AND (req.path.cont:"/api" OR req.path.cont:"/graphql")