A complete guide to using deepsec — Vercel's security harness — covering what each command does, how to configure it correctly to use your Claude Code subscription (instead of routing through Vercel AI Gateway), and how to triage the findings it produces.

Context: deepsec is a security analysis tool that uses coding agents (Claude or Codex) to investigate vulnerabilities in your codebase. It uses Opus 4.7 at maximum thinking by default, which makes it expensive — but also remarkably capable.

This guide covers deepsec ≥ 2.0.2. Earlier versions had a critical billing bug fixed in PR #43. If you're on a previous version, update with pnpm update deepsec before continuing.

TL;DR — the correct flow

# 1. Clean setup
claude login                                   # your Pro/Max subscription

# 2. Init and bootstrap
cd ~/projects/my-app
npx deepsec init
cd .deepsec
pnpm install

# 3. Pipeline (in order)
pnpm deepsec scan                              # free, no AI
pnpm deepsec process --project-id my-app       # EXPENSIVE, uses AI
pnpm deepsec revalidate                        # EXPENSIVE, uses AI
pnpm deepsec export --format md-dir --out ./findings   # free, no AI

📝 Requires deepsec ≥ 2.0.2. Earlier versions had a bug that routed traffic through Vercel AI Gateway even when the user hadn't opted in. If you're on an older version, update with pnpm update deepsec.

Historical context: behavior change in v2.0.2

✅ If your deepsec version is ≥ 2.0.2, you can skip this section. It's documented only for users coming from earlier versions and to explain why some repos may have leftover artifacts like a .vercel/ stub inside .deepsec/.

In pre-2.0.2 versions, the local authentication logic had counterintuitive behavior. The README stated that deepsec would automatically use local claude or codex subscriptions, but in practice the priority order meant that having Vercel CLI logged in (common in Next.js projects) directed all traffic to Vercel AI Gateway, billing the user's account without explicit opt-in.

The internal flow was roughly:

1. Deepsec called getVercelOidcToken() during preflight
2. That function walked up from .deepsec/ looking for a .vercel/project.json
3. If found, it read the Vercel CLI auth
4. Requested a fresh OIDC token
5. Expanded it to ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL=https://ai-gateway.vercel.sh

Typical result for users without Vercel AI Gateway credit:

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=...

Additionally, trying to avoid the Gateway by setting ANTHROPIC_BASE_URL=https://api.anthropic.com without a token produced a silent failure mode: each file completed in ~5 seconds with 0 tokens, 0 turns, 0 findings, marked as analyzed. The tool reported the scan as successful without ever calling the AI.

Both behaviors changed in PR #43 ("Use the vercel OIDC token for the gateway if no primary API token is present"), merged on May 5, 2026 and shipped in deepsec 2.0.2.

Starting in v2.0.2, the OIDC token is only used as an explicit fallback when no other credential is present, and the local claude CLI subscription takes precedence. This means you can have Vercel CLI logged in and deepsec will correctly use your Claude Code subscription without diverting traffic to the Gateway.

How to configure deepsec to use your Claude Code subscription

Step 1: Clean environment setup

# Verify there are no conflicting environment variables
env | grep -iE "anthropic|openai|gateway"
# Should return nothing relevant

# Verify claude CLI is authenticated with your subscription
claude --version
claude --print "test"
# Should respond normally

Step 2: Remove previous installations if any

If you've tried running deepsec before and it failed, residual state may contaminate the setup:

cd your-project
rm -rf .deepsec

Step 3: Init from scratch

npx deepsec init
cd .deepsec
pnpm install

Don't run cp .env.example .env or edit .env.local. The init will tell you:

# Set AI_GATEWAY_API_KEY in .env.local (or skip if claude/codex CLI is logged in)

Skip that step. Your logged-in claude CLI should be sufficient.

Step 4: Verify it's using your subscription

Before running the full pipeline, do a small test:

pnpm deepsec process --project-id my-app --filter apps/api/src/middleware --limit 2

You should see something like:

Investigating 2 file(s) with Claude Agent SDK (claude-opus-4-7)
Turn 1 (15s, 4 tool calls)
Turn 2 (22s, 3 tool calls)

What you DON'T want to see:

• Turn 1 (4s, 0 tool calls) repeated (silent failure — would indicate an old version)
• 402 Insufficient funds with a Vercel link (Gateway active — would indicate an old version)

If you see either of those, you're probably on an old deepsec version. Update with pnpm update deepsec and verify with cat node_modules/deepsec/package.json | grep version.

Pipeline commands: what each one does

scan — Static analysis with regex

pnpm deepsec scan

What it does: Runs ~110 predefined regex patterns across your codebase and flags suspicious files. Doesn't produce final findings — just "candidates" worth investigating with AI.

What to expect: A list of files with candidates (e.g., "this file has template literals in HTML, possible XSS"). No verdict, no severity.

process — AI-powered investigation

pnpm deepsec process --project-id my-app

What it does: For each candidate file from scan, it launches an AI agent that reads the code, traces data flows, looks for mitigations, considers context and produces findings with severity (CRITICAL, HIGH, MEDIUM, LOW, BUG).

What to expect: A list of findings per file, each with:

• Vulnerability category (xss, sql-injection, auth-bypass, etc.)
• Severity
• Reasoning
• Affected lines

Useful flags:

# Process only files in a specific path (useful for testing)
pnpm deepsec process --project-id my-app --filter apps/api/src

# Process at most N files
pnpm deepsec process --project-id my-app --limit 10

# Re-analyze everything from scratch (DELETES previous findings, use carefully)
pnpm deepsec process --project-id my-app --reinvestigate

# Change concurrency (default is usually fine)
pnpm deepsec process --project-id my-app --concurrency 5 --batch-size 5

Idempotency: process without --reinvestigate only processes files in pending state. If interrupted (rate limit, dead session), just rerun the command and it resumes where it left off.

revalidate — Reduces false positives

pnpm deepsec revalidate --project-id my-app

What it does: For each finding generated, launches the agent to re-evaluate it: is it actually exploitable? Is it mitigated upstream? Was it fixed in recent commits? Assigns a verdict:

• TP (True Positive) — real bug, worth fixing
• FP (False Positive) — the process agent got it wrong
• Fixed — already fixed in some commit
• Uncertain — can't determine without more context

What to expect:

Revalidation complete. Run: 20260506180136-...
TP: 116  FP: 4  Fixed: 0  Uncertain: 0

Useful flags:

# Re-revalidate specific findings (by path)
pnpm deepsec revalidate --filter apps/api/src/routes/auth

# Force re-validation of already revalidated findings
pnpm deepsec revalidate --force

Idempotency: revalidate without --force only processes findings without a verdict yet. If it ended with "120/122 revalidated", running it again only processes the 2 missing ones.

export — Export findings to readable files

pnpm deepsec export --format md-dir --out ./findings

What it does: Reads findings + verdicts from data/<id>/files/ and exports them in a human-readable format. No AI, no cost.

Available formats:

• md-dir — one Markdown per finding (recommended for human review)
• json — single JSON with all findings (for pipelines / tooling)

status — View project state

pnpm deepsec status --project-id my-app

Shows:

• How many files in each status (analyzed, pending, processing)
• Finding counts by severity
• Revalidation results
• Recent runs with their equivalent cost

Expected output when pipeline finishes:

Project: my-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

Important: The USD costs shown (\(24.10, \)10.93) are the equivalent value if you were paying the API directly, not what Anthropic actually charged you. If you use a subscription, everything comes from your quota — $0 actually billed.

Verifying the analysis was real (not a Gateway bug zombie)

After process, especially if you had previous Gateway issues, verify that files were actually analyzed:

# Count files marked as "analyzed" but with 0 tokens (zombies from the 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

If this count is > 0, those files were marked as analyzed without actually going through the AI. Re-process the project:

pnpm deepsec process --project-id my-app --reinvestigate

Estimated cost

For a medium codebase (~650 files):

If you use a Claude Max (\(100/month) subscription, this pipeline fits comfortably and leaves you headroom for normal use the rest of the month. Pro (\)20/month) will likely max out partway through a large project.

Triaging findings: what to do after exporting

With 116 confirmed TPs (true positives), you need a systematic review plan:

Prioritize by severity

1. CRITICAL → review today, doesn't wait
2. HIGH → this week
3. MEDIUM → next two weeks
4. BUG / HIGH_BUG → code quality backlog (don't block security)

Group by category, not by file

Many findings are the same bug repeated across multiple files. Grouping by vulnSlug (e.g., all xss together) lets you fix 5 findings with one change (e.g., adding sanitization to a shared helper).

Filter by real attack surface

A finding in apps/api/src/routes/public.ts (receives input from the internet) weighs much more than one in apps/web/src/components/InternalDashboard.tsx. Critical question for each finding: is the input arriving here from an attacker?

For each TP, three questions

1. Is it really exploitable, not theoretical?
2. Is there upstream mitigation the agent didn't see? (middleware validation, rate limiting, auth)
3. Does the fix introduce regressions? (are there tests covering the path?)

Common errors and solutions

"402 Insufficient funds" with vercel.com link

Cause: You're on an old deepsec version (pre-2.0.2) where the OIDC token fallback was active by default.

Solution: Update deepsec:

pnpm update deepsec
cat node_modules/deepsec/package.json | grep version
# Should be >= 2.0.2

"0 tool calls, 0 tokens" in every batch

Cause: The SDK has no valid credentials and is failing silently. Common in pre-2.0.2 versions when trying to avoid the Gateway with ANTHROPIC_BASE_URL=https://api.anthropic.com without a token.

Solution:

1. Update to deepsec ≥ 2.0.2 (pnpm update deepsec)
2. Verify claude --print "test" responds normally
3. Make sure you DON'T have ANTHROPIC_BASE_URL or ANTHROPIC_AUTH_TOKEN in .env.local or shell (unless you actually want to use the Gateway or a direct API key)

Claude rate limit during process

Cause: Your plan hit its usage limit (5h on Pro, longer windows on Max).

Solution: Wait for the window to reset and re-run pnpm deepsec process. It's idempotent and resumes where it left off.

Files stuck in processing forever

Cause: A previous run died without releasing locks.

Solution:

# Clean up zombie runs
rm -rf data/<project-id>/runs/*
# Re-run process — files in "processing" will be reprocessed
pnpm deepsec process --project-id my-app

What to commit and what not to

.deepsec/ contains a mix of configuration files (which DO go to git) and run output (which should NOT go to git for security reasons). The init already generates a reasonable .gitignore, but you need to verify it covers exports too.

What DOES get committed

These files are the "scan recipe" and let any team member replicate the setup:

• deepsec.config.ts — project config (matchers, paths, plugins)
• package.json + pnpm-lock.yaml — for reproducibility
• pnpm-workspace.yaml
• AGENTS.md — instructions for coding agents
• README.md
• .gitignore
• data/<id>/INFO.md — project context injected into prompts (the most valuable file!)
• data/<id>/SETUP.md — per-project instructions
• data/<id>/config.json (if it exists) — priorityPaths, promptAppend, ignorePaths

What does NOT get committed

# .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/

init generates the first sections automatically, but does NOT include tech.json, findings/, or exports/. Add them yourself:

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

💡 Why ignore tech.json: It contains the absolute rootPath of the machine where the scan was run (e.g., /Users/jdoe/projects/my-app), which reveals the developer's username and local structure. It also regenerates on every run, so versioning it just creates noise in diffs.

Why findings and exports should NOT go to git

The files in data/<id>/files/ and the export folder contain:

• Exact lines of vulnerable code with snippets
• Detailed agent reasoning about how to exploit each vuln
• Verdicts from revalidate

If your repo is public, that's basically a step-by-step attack guide for your app. Even in private repos, consider that git history is forever — a finding that's fixed today still shows in the commit history how the bug looked.

Verify nothing leaked into tracking

If you committed something before configuring the gitignore properly:

git ls-files .deepsec/ | grep -E "findings/|/files/|/runs/|/reports/"

If it returns anything, untrack them:

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 only removes them from future tracking, not from history. If findings expose unfixed vulns and the repo has many collaborators, consider cleaning history with git filter-repo or BFG.

Where do findings live then?

Exported findings are local and temporary. Three common patterns to manage them:

1. Local without persisting — for one-off scans, each person reviews their own
2. Separate private repo — my-project-security/ with restricted access
3. Ticket system (recommended) — relevant TP findings become Linear/Jira/GitHub issues with assignees and deadlines; FPs are discarded

For serious teams, option 3 is the standard: deepsec generates the list, humans triage, and important findings flow into normal workstreams.

Resources

• Official repo: https://github.com/vercel-labs/deepsec
• Docs: https://github.com/vercel-labs/deepsec/tree/main/docs
• Launch blog post: https://vercel.com/blog/introducing-deepsec-find-and-fix-vulnerabilities-in-your-code-base

Best practices for teams

General recommendations based on the experience of implementing deepsec on a real project.

Designate an owner

Although anyone on the team can run deepsec following this guide (the files in .deepsec/ are versioned and the setup is reproducible with pnpm install), it helps to designate someone as process owner to avoid duplication and keep triaging consistent.

When to scan

Typical cases where running a full scan makes sense:

• After merging a large feature touching auth, input handling, or payment/sensitive data flows
• Before a production release with significant changes
• When a vuln is reported in one of the stack's critical dependencies
• Periodically (every 3-6 months) as general hygiene
• When deciding to re-evaluate previous findings after applying fixes

For small or isolated changes, scanning the modified directory is enough:

pnpm deepsec process --project-id my-app --filter apps/api/src/routes/<module>

Findings management

We recommend integrating critical and high findings into the team's ticket system (Linear, Jira, private GitHub Issues, internal system, etc). After each scan, the owner triages the TPs and creates entries for the ones requiring action, assigning them to the corresponding devs.

Exported findings (./findings/) should stay only local on the machine of whoever scanned — they don't get committed to the repo (see "What to commit and what not to" section).

Expected costs

For a medium codebase (~650 files), a full pipeline (process + revalidate) consumes between $30-50 in API equivalent and takes 15-30 minutes of wall-clock.

Options to cover the cost:

• Personal Claude Max subscription (\(100/month) — viable for ad-hoc team scans. \)0 actually billed if it fits in your quota.
• Vercel AI Gateway with AI_GATEWAY_API_KEY — recommended for CI/CD or frequent scans. Allows spending caps and attribution to the corporate account.
• Direct Anthropic API key — if the team already pays for direct API for other purposes.

Escalation policy

For CRITICAL or HIGH severity findings, it helps to have a direct escalation channel to the security owner before any release. MEDIUM and BUG findings can follow the normal ticket flow.

Final notes

• If you find secrets in findings, rotate them immediately. The presence of a secret in a finding implies it was in the source code.
• The USD cost report that deepsec shows is always the API equivalent, not what was charged to your account. If you use a subscription, the $ are reference values.
• --reinvestigate deletes previous work. Only use it when you really want to start over.

This guide covers deepsec ≥ 2.0.2 — last updated: May 2026.

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:

1. Deepsec llamaba a getVercelOidcToken() durante preflight

2. Esa función caminaba hacia arriba desde .deepsec/ buscando un .vercel/project.json

3. Si lo encontraba, leía la auth del CLI de Vercel

4. Solicitaba un OIDC token fresco

5. 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

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

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:

• Categoría de vuln (xss, sql-injection, auth-bypass, etc.)

• Severidad

• Razonamiento

• Líneas afectadas

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

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

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:

• md-dir — un Markdown por finding (recomendado para revisión humana)

• json — un solo JSON con todos los findings (para pipeline / herramientas)

status — Ver estado del proyecto

pnpm deepsec status --project-id mi-app

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):

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

1. CRITICAL → revísalo hoy, no espera

2. HIGH → esta semana

3. MEDIUM → próximas 2 semanas

4. 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

1. ¿Es realmente explotable, no teórico?

2. ¿Hay mitigación upstream que el agente no vio? (validación en middleware, rate limiting, auth)

3. ¿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

"0 tool calls, 0 tokens" en cada batch

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:

1. Actualiza a deepsec ≥ 2.0.2 (pnpm update deepsec)

2. Verifica claude --print "test" responde normalmente

3. 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:

• Líneas exactas de código vulnerable con snippets

• Razonamiento detallado del agente sobre cómo explotar cada vuln

• Veredictos de revalidate

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:

1. Locales sin persistir — para escaneos puntuales, cada quien revisa los suyos

2. Repo privado separado — mi-proyecto-security/ con acceso restringido

3. 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

• Repo oficial: https://github.com/vercel-labs/deepsec

• Docs: https://github.com/vercel-labs/deepsec/tree/main/docs

• Blog post de lanzamiento: https://vercel.com/blog/introducing-deepsec-find-and-fix-vulnerabilities-in-your-code-base

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.

Components

• Grafana: The analytics and monitoring solution with support for multiple data sources, including Prometheus.

• Prometheus: The monitoring and alerting toolkit, collecting metrics from configured targets at specified intervals.

• Node Exporter: A Prometheus exporter for hardware and OS metrics exposed by *NIX kernels.

• cAdvisor: Analyzes resource usage and performance characteristics of running containers.

• Loki: A horizontally-scalable, highly-available, multi-tenant log aggregation system.

• NGINX: Used as a reverse proxy to expose Grafana on the internet securely.

Prerequisites

• Docker and Docker Compose installed on your host machine.

• Domain name configured to point to the host machine (for NGINX configuration).

Configuration Files Overview

• docker-compose.yml: Defines the services, networks, and volumes for the Docker containers.

• prometheus.yml: Configuration file for Prometheus to define scrape targets and intervals.

• grafana.ini: Configuration file for Grafana's settings, including SMTP for email notifications.

• loki-config.yml: Configuration file for Loki to define the storage backend and other settings.

• domain.conf: NGINX configuration for proxying requests to Grafana and handling WebSocket connections.

Installation Steps

1. Configure Docker Daemon: Enable Docker metrics by adding the following to /etc/docker/daemon.json and restarting Docker:

    {
      "metrics-addr": "127.0.0.1:9323"
    }
    # Then reload Docker configurations:
    sudo systemctl reload docker
   

2. Install Loki plugin for Docker: Install the Loki plugin for Docker to enable log collection:

    docker plugin install grafana/loki-docker-driver:latest --alias loki --grant-all-permissions
   

3. Clone the Repository: Clone the repository to your host machine:

    git clone https://gist.github.com/398e94fb0aebb994b25223d99e7ae769.git monitoring-stack
    cd monitoring-stack
   

4. Start the Services: Start the monitoring stack using Docker Compose:

    docker-compose up -d
   

5. Access Grafana: Access Grafana at http://<your-domain> and log in with the default credentials (username: admin, password: admin).

Important Notes:

• Replace placeholder values in grafana.ini with your SMTP credentials to enable email notifications.

• Adjust the domain.conf to match your domain and specific requirements.

• Review Docker and NGINX logs in case of any issues during setup.

6. How to send container logs to loki:

    docker run --name nginx-loki -d \
    -p 8080:80 \
    --log-driver=loki \
    --log-opt loki-url=http://localhost:3100/loki/api/v1/push \
    nginx:latest