Guía práctica de deepsec
Guía completa para usar deepsec — el security harness de Vercel — entendiendo qué hace cada comando, cómo configurarlo correctamente para usar tu suscripción de Claude Code (en vez del AI Gateway de Vercel), y cómo triar los findings que produce.
Contexto: deepsec es una herramienta de análisis de seguridad que usa coding agents (Claude o Codex) para investigar vulnerabilidades en tu codebase. Usa Opus 4.7 a thinking máximo por defecto, lo que la hace cara — pero también muy capaz.
Esta guía cubre deepsec ≥ 2.0.2. Versiones anteriores tenían un bug crítico de billing que se resolvió en PR #43. Si estás en versión previa, actualiza con pnpm update deepsec antes de seguir.
TL;DR del flujo correcto
# 1. Setup limpio
claude login # tu suscripción Pro/Max
# 2. Init y bootstrap
cd ~/proyectos/mi-app
npx deepsec init
cd .deepsec
pnpm install
# 3. Pipeline (en orden)
pnpm deepsec scan # gratis, sin IA
pnpm deepsec process --project-id mi-app # CARO, usa IA
pnpm deepsec revalidate # CARO, usa IA
pnpm deepsec export --format md-dir --out ./findings # gratis, sin IA
📝 Requiere deepsec ≥ 2.0.2. Versiones anteriores tenían un bug que ruteaba el tráfico al Vercel AI Gateway aunque el usuario no lo hubiera elegido. Si estás en una versión previa, actualiza con pnpm update deepsec.
Contexto histórico: cambio de comportamiento en v2.0.2
✅ Si tu versión de deepsec es ≥ 2.0.2, puedes saltarte esta sección. Se documenta solo para usuarios que vengan de versiones previas y para explicar por qué algunos repos pueden tener residuos como un .vercel/ stub dentro de .deepsec/.
En versiones pre-2.0.2, la lógica de autenticación local tenía un comportamiento poco intuitivo. El README indicaba que deepsec usaría las suscripciones locales de claude o codex automáticamente, pero en la práctica el orden de prioridad hacía que la presencia del Vercel CLI logueado (común en proyectos Next.js) dirigiera todo el tráfico al AI Gateway de Vercel, cobrando contra la cuenta del usuario sin opt-in explícito.
El flujo interno era aproximadamente:
Deepsec llamaba a getVercelOidcToken() durante preflight
Esa función caminaba hacia arriba desde .deepsec/ buscando un .vercel/project.json
Si lo encontraba, leía la auth del CLI de Vercel
Solicitaba un OIDC token fresco
Lo expandía a ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL=https://ai-gateway.vercel.sh
Resultado típico para usuarios sin crédito en Vercel AI Gateway:
Agent SDK error: Claude Code returned an error result:
API Error: 402 Insufficient funds. Please add credits to your account...
Visit https://vercel.com/d?to=...
Adicionalmente, intentar evitar el Gateway poniendo ANTHROPIC_BASE_URL=https://api.anthropic.com sin token producía un modo de falla silenciosa: cada archivo terminaba en ~5 segundos con 0 tokens, 0 turns, 0 findings, marcado como analyzed. La herramienta reportaba el escaneo como exitoso sin haber llamado a la IA.
Ambos comportamientos cambiaron en PR #43 ("Use the vercel OIDC token for the gateway if no primary API token is present"), mergeado el 5 de mayo de 2026 y publicado en deepsec 2.0.2.
A partir de v2.0.2, el OIDC token solo se usa como fallback explícito cuando ninguna otra credencial está presente, y la suscripción local de claude CLI tiene precedencia. Esto significa que puedes tener Vercel CLI logueado y deepsec correctamente usará tu suscripción de Claude Code sin desviar tráfico al Gateway.
Cómo configurar para usar tu suscripción de Claude Code
Paso 1: Setup limpio del entorno
# Verifica que no haya variables de entorno conflictivas
env | grep -iE "anthropic|openai|gateway"
# No debería retornar nada relevante
# Verifica que claude CLI esté autenticado con tu suscripción
claude --version
claude --print "test"
# Debería responder normalmente
Paso 2: Borrar instalaciones previas si las hay
Si ya intentaste correr deepsec antes y falló, hay residuos que pueden contaminar el setup:
cd tu-proyecto
rm -rf .deepsec
Paso 3: Init desde cero
npx deepsec init
cd .deepsec
pnpm install
No hagas cp .env.example .env ni edites .env.local. El init te dirá:
# Set AI_GATEWAY_API_KEY in .env.local (or skip if claude/codex CLI is logged in)
Saltea ese paso. Tu claude CLI logueado debería ser suficiente.
Paso 4: Verificar que está usando tu suscripción
Antes de correr el pipeline completo, haz una prueba pequeña:
pnpm deepsec process --project-id mi-app --filter apps/api/src/middleware --limit 2
Espera ver algo como:
Investigating 2 file(s) with Claude Agent SDK (claude-opus-4-7)
Turn 1 (15s, 4 tool calls)
Turn 2 (22s, 3 tool calls)
Lo que NO quieres ver:
Turn 1 (4s, 0 tool calls) repetido (silent failure — indicaría versión antigua)
402 Insufficient funds con link a Vercel (Gateway activo — indicaría versión antigua)
Si ves uno de esos dos, probablemente estás en una versión vieja de deepsec. Actualiza con pnpm update deepsec y verifica con cat node_modules/deepsec/package.json | grep version.
Pipeline de comandos: qué hace cada uno
scan — Análisis estático con regex
pnpm deepsec scan
| Aspecto |
Detalle |
| ¿Usa IA? |
❌ No |
| Costo |
Gratis |
| Tiempo |
~15s para 2k archivos |
| Output |
Archivos marcados como pending con candidates |
Qué hace: Recorre tu codebase con ~110 patrones regex predefinidos y marca archivos sospechosos. No produce findings finales — solo "candidatos" que merecen investigación con IA.
Qué esperar: Lista de archivos con candidatos (ej: "este archivo tiene template literals en HTML, posible XSS"). Sin veredicto, sin severidad.
process — Investigación con IA
pnpm deepsec process --project-id mi-app
| Aspecto |
Detalle |
| ¿Usa IA? |
✅ Sí (Opus 4.7 a thinking máximo) |
| Costo |
$$$ — quemas tokens de tu suscripción |
| Tiempo |
Minutos a horas según tamaño |
| Output |
Archivos con findings[] y status analyzed |
Qué hace: Por cada archivo candidato del scan, lanza un agente de IA que lee el código, traza el flujo de datos, busca mitigaciones, considera el contexto y produce findings con severidad (CRITICAL, HIGH, MEDIUM, LOW, BUG).
Qué esperar: Lista de hallazgos por archivo, cada uno con:
Flags útiles:
# Solo procesar archivos en una ruta específica (útil para testing)
pnpm deepsec process --project-id mi-app --filter apps/api/src
# Procesar máximo N archivos
pnpm deepsec process --project-id mi-app --limit 10
# Re-analizar todo desde cero (BORRA findings previos, usar con cuidado)
pnpm deepsec process --project-id mi-app --reinvestigate
# Cambiar concurrencia (default suele estar bien)
pnpm deepsec process --project-id mi-app --concurrency 5 --batch-size 5
Idempotencia: process sin --reinvestigate solo procesa archivos en estado pending. Si se interrumpe (rate limit, sesión muerta), simplemente vuelves a correr el comando y reanuda donde quedó.
revalidate — Reduce falsos positivos
pnpm deepsec revalidate --project-id mi-app
| Aspecto |
Detalle |
| ¿Usa IA? |
✅ Sí (mismo modelo, similar costo a process) |
| Costo |
$$$ — comparable a process |
| Tiempo |
Similar a process |
| Output |
Findings etiquetados con veredicto |
Qué hace: Por cada finding generado, lanza al agente a re-evaluarlo: ¿es realmente explotable? ¿Está mitigado upstream? ¿Se arregló en commits recientes? Asigna un veredicto:
TP (True Positive) — bug real, vale la pena arreglar
FP (False Positive) — el agente del process se equivocó
Fixed — ya fue arreglado en algún commit
Uncertain — no se puede determinar sin más contexto
Qué esperar:
Revalidation complete. Run: 20260506180136-...
TP: 116 FP: 4 Fixed: 0 Uncertain: 0
Flags útiles:
# Re-revalidar findings específicos (por path)
pnpm deepsec revalidate --filter apps/api/src/routes/auth
# Forzar re-revalidación de findings ya revalidados
pnpm deepsec revalidate --force
Idempotencia: revalidate sin --force solo procesa findings que aún no tienen veredicto. Si terminó con "120/122 revalidated", correrlo de nuevo procesa solo los 2 faltantes.
export — Exportar findings a archivos legibles
pnpm deepsec export --format md-dir --out ./findings
| Aspecto |
Detalle |
| ¿Usa IA? |
❌ No |
| Costo |
Gratis |
| Tiempo |
Segundos |
| Output |
Carpeta con un .md por finding |
Qué hace: Lee los findings + veredictos del data/<id>/files/ y los exporta a un formato leíble para humanos. Sin IA, sin costo.
Formatos disponibles:
status — Ver estado del proyecto
pnpm deepsec status --project-id mi-app
| Aspecto |
Detalle |
| ¿Usa IA? |
❌ No |
| Costo |
Gratis |
Muestra:
Cuántos archivos hay en cada status (analyzed, pending, processing)
Conteo de findings por severidad
Resultados de revalidation
Runs recientes con su costo equivalente
Output esperado al terminar pipeline:
Project: mi-app
Files tracked: 650
Status
analyzed: 650 ← 100%
pending: 0
Findings
CRITICAL: 1 | HIGH: 11 | MEDIUM: 41 | BUG: 64
Revalidated: 122/122 TP: 116 FP: 4 Fixed: 0 Uncertain: 0
Importante: Los costos en USD que muestra (\(24.10, \)10.93) son valor equivalente si pagaras la API directa, no lo que te cobró Anthropic. Si usas tu suscripción, todo sale de tu cuota — $0 reales.
Verificar que el análisis fue real (no zombi del bug del Gateway)
Después de process, especialmente si tuviste problemas previos con el Gateway, verifica que los archivos hayan sido analizados de verdad:
# Cuenta archivos "analyzed" pero con 0 tokens (zombis del bug)
find data/<project-id>/files -name "*.json" -type f -exec python3 -c "
import json, sys
try:
d = json.load(open(sys.argv[1]))
h = d.get('analysisHistory', [])
if h and d.get('status') == 'analyzed':
last = h[-1]
if last.get('usage', {}).get('inputTokens', 0) == 0:
print(sys.argv[1])
except: pass
" {} \; 2>/dev/null | wc -l
Si este conteo es > 0, esos archivos fueron marcados como analizados sin haber pasado por la IA. Re-procesa el proyecto:
pnpm deepsec process --project-id mi-app --reinvestigate
Costo estimado
Para una codebase mediana (~650 archivos):
| Stage |
Tokens (aprox) |
$ equivalente |
scan |
0 |
$0 |
process |
300k - 500k |
$20 - $30 |
revalidate |
100k - 200k |
$8 - $15 |
export |
0 |
$0 |
| Total |
~500k - 700k |
~$30 - $45 |
Si usas tu suscripción de Claude Max (\(100/mes), este pipeline cabe cómodamente y te deja margen para uso normal el resto del mes. Plan Pro (\)20/mes) probablemente se sature en mitad de un proyecto grande.
Triaje de findings: qué hacer después de exportar
Con 116 TPs (true positives) confirmados, necesitas un plan de revisión sistemático:
Prioriza por severidad
CRITICAL → revísalo hoy, no espera
HIGH → esta semana
MEDIUM → próximas 2 semanas
BUG / HIGH_BUG → backlog de calidad de código (no bloquean seguridad)
Agrupa por categoría, no por archivo
Muchos findings son el mismo bug repetido en múltiples archivos. Agrupar por vulnSlug (ej: todos los xss juntos) te permite arreglar 5 findings con un solo cambio (ej: agregar sanitización en el helper compartido).
Filtra por superficie de ataque real
Un finding en apps/api/src/routes/public.ts (recibe input de internet) pesa muchísimo más que uno en apps/web/src/components/InternalDashboard.tsx. Pregunta crítica para cada finding: ¿el input que llega aquí viene de un atacante?
Para cada TP, tres preguntas
¿Es realmente explotable, no teórico?
¿Hay mitigación upstream que el agente no vio? (validación en middleware, rate limiting, auth)
¿El arreglo introduce regresiones? (¿hay tests que cubran el camino?)
Errores comunes y soluciones
"402 Insufficient funds" con link a vercel.com
Causa: Estás en una versión vieja de deepsec (pre-2.0.2) donde el OIDC token fallback estaba activo por defecto.
Solución: Actualiza deepsec:
pnpm update deepsec
cat node_modules/deepsec/package.json | grep version
# Debe ser >= 2.0.2
Causa: El SDK no tiene credenciales válidas y está fallando en silencio. Suele pasar en versiones pre-2.0.2 cuando se intentaba evitar el Gateway con ANTHROPIC_BASE_URL=https://api.anthropic.com sin token.
Solución:
Actualiza a deepsec ≥ 2.0.2 (pnpm update deepsec)
Verifica claude --print "test" responde normalmente
Asegúrate de NO tener ANTHROPIC_BASE_URL ni ANTHROPIC_AUTH_TOKEN en .env.local ni en el shell (a menos que sí quieras usar el Gateway o una API key directa)
Rate limit de Claude durante process
Causa: Tu plan se topó con el límite de uso (5h Pro, ventanas más largas Max).
Solución: Espera a que se resetee la ventana y vuelve a correr pnpm deepsec process. Es idempotente y reanuda donde quedó.
Archivos quedan en processing para siempre
Causa: Run anterior murió sin liberar locks.
Solución:
# Limpia los runs zombi
rm -rf data/<project-id>/runs/*
# Re-corre process — los archivos en "processing" se re-procesarán
pnpm deepsec process --project-id mi-app
Qué commitear y qué no
.deepsec/ contiene una mezcla de archivos de configuración (que sí van a git) y output de runs (que NO debe ir a git por seguridad). El init ya genera un .gitignore razonable, pero hay que verificar que cubra los exports también.
Lo que SÍ se commitea
Estos archivos son la "receta" del escaneo y permiten que cualquier persona del equipo replique el setup:
deepsec.config.ts — config del proyecto (matchers, paths, plugins)
package.json + pnpm-lock.yaml — para reproducibilidad
pnpm-workspace.yaml
AGENTS.md — instrucciones para coding agents
README.md
.gitignore
data/<id>/INFO.md — contexto del proyecto inyectado a los prompts (¡el archivo más valioso!)
data/<id>/SETUP.md — instrucciones por proyecto
data/<id>/config.json (si existe) — priorityPaths, promptAppend, ignorePaths
Lo que NO se commitea
# .deepsec/.gitignore
node_modules/
.env*.local
.vercel/
# Scan output — regenerated by `deepsec scan` / `process`. INFO.md
# and SETUP.md (manually edited) stay tracked.
data/*/files/
data/*/runs/
data/*/reports/
data/*/project.json
# Auto-detected metadata (regenerated each run, contains absolute paths)
data/*/tech.json
# Exported findings (regenerated by `deepsec export`)
findings/
exports/
El init genera las primeras secciones automáticamente, pero NO incluye tech.json, findings/ ni exports/. Agrégalos tú:
cat >> .deepsec/.gitignore << 'EOF'
# Auto-detected metadata (regenerated each run, contains absolute paths)
data/*/tech.json
# Exported findings (regenerated by `deepsec export`)
findings/
exports/
EOF
💡 Por qué ignorar tech.json: Contiene el rootPath absoluto de la máquina donde se corrió el scan (ej: /Users/jdoe/proyectos/mi-app), lo cual revela el username y estructura local del desarrollador. Además se regenera en cada run, así que versionarlo solo crea ruido en diffs.
Por qué los findings y exports NO van a git
Los archivos en data/<id>/files/ y la carpeta de export contienen:
Si tu repo es público, eso es básicamente una guía paso a paso para atacar tu app. Incluso en repos privados, considera que el historial de git es para siempre — un finding puede estar fixeado hoy pero el commit sigue mostrando cómo era el bug.
Verifica que no haya residuos en tracking
Si ya commiteaste algo antes de configurar el gitignore correctamente:
git ls-files .deepsec/ | grep -E "findings/|/files/|/runs/|/reports/"
Si retorna algo, sácalos del trackeo:
git rm -r --cached .deepsec/findings/ 2>/dev/null
git rm -r --cached .deepsec/data/*/files/ 2>/dev/null
git rm -r --cached .deepsec/data/*/runs/ 2>/dev/null
git rm -r --cached .deepsec/data/*/reports/ 2>/dev/null
git commit -m "chore: untrack deepsec output files"
⚠️ git rm --cached solo los saca del trackeo futuro, no los borra del historial. Si los findings exponen vulns aún sin arreglar y el repo tiene muchos colaboradores, considera limpiar el historial con git filter-repo o BFG.
Dónde viven los findings entonces
Los findings exportados son locales y temporales. Tres patrones comunes para gestionarlos:
Locales sin persistir — para escaneos puntuales, cada quien revisa los suyos
Repo privado separado — mi-proyecto-security/ con acceso restringido
Sistema de tickets (recomendado) — los findings TP relevantes se convierten en issues de Linear/Jira/GitHub con responsable y deadline; los FPs se descartan
Para equipos serios, la opción 3 es la estándar: deepsec genera la lista, humanos triamos, y los hallazgos importantes pasan al flujo normal de trabajo.
Recursos
Buenas prácticas para equipos
Recomendaciones generales basadas en la experiencia de implementar deepsec en un proyecto real.
Designar un responsable
Aunque cualquier persona del equipo puede correr deepsec siguiendo esta guía (los archivos en .deepsec/ están versionados y el setup es reproducible con pnpm install), conviene designar a alguien como responsable del proceso para evitar duplicaciones y mantener consistencia en el triaje.
Cuándo escanear
Casos típicos donde tiene sentido correr un escaneo completo:
Después de mergear una feature grande que toca auth, manejo de inputs, o flujos de pago/datos sensibles
Antes de un release a producción que incluya cambios significativos
Cuando se reporta una vuln en alguna de las dependencias críticas del stack
Periódicamente (cada 3-6 meses) como higiene general
Cuando se decida re-evaluar findings previos después de aplicar fixes
Para cambios pequeños o aislados, basta con escanear el directorio modificado:
pnpm deepsec process --project-id mi-app --filter apps/api/src/routes/<modulo>
Gestión de findings
Recomendamos integrar los findings críticos y altos al sistema de tickets que use el equipo (Linear, Jira, GitHub Issues privados, sistema interno, etc). Después de cada escaneo, el responsable triagea los TPs y crea entradas para los que requieren acción, asignándolos a los devs correspondientes.
Los findings exportados (./findings/) deben mantenerse solo localmente en la máquina de quien escaneó — no se commitean al repo (ver sección "Qué commitear y qué no").
Costos esperados
Para una codebase mediana (~650 archivos), un pipeline completo (process + revalidate) consume entre $30-50 de equivalente API y toma 15-30 minutos de wall-clock.
Opciones para cubrir el costo:
Suscripción personal de Claude Max (\(100/mes) — viable para escaneos ad-hoc del equipo. \)0 reales si cabe en la cuota.
AI Gateway de Vercel con AI_GATEWAY_API_KEY — recomendado para CI/CD o escaneos frecuentes. Permite cap de gasto y atribución a la cuenta corporativa.
API key directa de Anthropic — si el equipo ya paga API directa para otros propósitos.
Política de escalación
Para findings de severidad CRITICAL o HIGH, conviene tener un canal directo de escalación al responsable de seguridad antes de cualquier release. Los MEDIUM y BUG pueden seguir el flujo normal del sistema de tickets.
Notas finales
Si encuentras secretos en findings, rótalos inmediatamente. La presencia de un secreto en un finding implica que estaba en el código fuente.
El reporte de costos en USD que muestra deepsec es siempre el equivalente API, no lo cargado a tu cuenta. Si usas suscripción, los $ son referenciales.
--reinvestigate borra trabajo previo. Solo úsalo cuando realmente quieras re-empezar.
Esta guía cubre deepsec ≥ 2.0.2 — última actualización: mayo 2026.
