Cómo hacer una auditoría de seguridad con Claude Code

No delegues la seguridad a la IA sin control

Claude Code puede acelerar una auditoría de seguridad. Puede leer rutas, comparar un pull request, revisar dependencias, buscar logs peligrosos, localizar variables de entorno y convertir hábitos de revisión en una lista repetible. Eso ayuda porque los riesgos reales suelen estar repartidos entre autenticación, permisos, jobs de facturación, webhooks, CI y registros.

El error es pedir “revisa la seguridad” y aceptar la respuesta como prueba. Una auditoría no es una opinión general. Es una revisión con alcance, activos, amenazas, controles, evidencias y riesgos pendientes. Claude Code puede investigar y ordenar, pero la responsabilidad de negocio, la publicación de detalles y la decisión de lanzamiento siguen siendo humanas.

Esta guía muestra un flujo práctico y seguro para usar Claude Code en auditorías sin publicar detalles explotables. Cubre alcance, inventario de activos, modelo de amenazas, dependencias, autenticación y sesiones, secretos, validación de entrada, logs y PII, puertas de CI, recibo de evidencias y cuatro casos de uso. Como referencia externa, conviene tener a mano OWASP Top 10, OWASP ASVS, NIST SSDF y la documentación de GitHub sobre secret scanning.

Fija primero el alcance

El primer entregable no es un parche. Es un brief de auditoría. El alcance dice qué debe revisar Claude Code, qué no debe tocar, qué comandos puede ejecutar y qué significa “terminado”. Sin ese límite, la IA tiende a comentar archivos visibles y puede saltarse rutas de administración, billing, tareas en segundo plano, scripts de despliegue o secretos de CI.

Copia esta plantilla y rellénala antes de pedir hallazgos.

# Security Audit Brief

## Goal
- Find serious issues in authentication, authorization, secrets, input validation, logging, and dependencies before release
- Produce evidence and remaining-risk notes, not just suggested fixes

## Scope
- Repository:
- Branch or PR:
- Feature or workflow:
- Directories Claude Code may inspect:
- Directories Claude Code must not change:
- Commands Claude Code may run:

## Priority areas
- Authentication and session handling
- Authorization and roles
- Input validation and output encoding
- Secrets and environment variables
- Dependencies and licenses
- Logs, PII, and audit events
- CI gates that should block release

## Completion criteria
- Record findings in the risk register
- Include only minimal reproduction context
- Do not include live secrets, customer data, or dangerous exploit instructions
- Record commands, results, skipped areas, and human-review items in the evidence receipt

Después del brief, pídele que haga un mapa antes de editar: “Enumera rutas, middleware de autenticación, APIs externas, variables de entorno, puntos de logging, jobs de CI y archivos de alto riesgo. No modifiques código todavía”. Ese paso permite que una persona detecte áreas omitidas antes de que la auditoría se cierre demasiado pronto.

Crea inventario de activos y modelo de amenazas

La seguridad empieza por saber qué se protege. Los activos pueden ser datos de usuarios, estado de facturación, claves API, paneles de administración, logs de auditoría, archivos subidos, mensajes de soporte y analítica. Un modelo de amenazas es un mapa pequeño: quién puede entrar, por qué punto, qué quiere afectar y qué control debe detenerlo.

| Asset | Stored in | Entry point | Likely threat | Required control | Owner |
| --- | --- | --- | --- | --- | --- |
| User email address | users table | signup, admin | unauthorized access, log leakage | authorization, PII masking, audit log | backend |
| Billing status | billing table, Stripe | webhook, admin | tampering, duplicate processing | signature verification, idempotency, role checks | backend |
| API keys | env, secret manager | CI, runtime | repository leak, log exposure | secret scanning, rotation, least privilege | platform |
| Admin console | /admin | browser | privilege escalation | MFA, admin role, operation logs | product |

Entrega esta tabla a Claude Code y pídele que añada límites de confianza y pruebas. Un límite de confianza separa lo que controlas de lo que debes tratar como no confiable. Entradas del navegador, webhooks, CSV subidos, Markdown, nombres de archivo y respuestas de APIs externas deben validarse antes de usarse.

Da carriles de revisión concretos

La revisión de dependencias debe cubrir package.json, lockfiles, imágenes Docker, GitHub Actions, versiones de runtime y dependencias transitivas. npm audit no es toda la auditoría. Pide a Claude Code que separe riesgo productivo alcanzable de ruido de desarrollo, explique posibles breaking changes y liste las pruebas que demuestran que la actualización no rompió la app.

La revisión de autenticación y sesión debe mirar login, logout, reset de contraseña, MFA, OAuth, flags de cookies, expiración de sesión, CSRF y autorización del lado servidor. “El usuario inició sesión” y “el usuario puede hacer esta acción” son preguntas distintas. APIs de administración, billing, descargas, IDs de usuario en rutas y webhooks repetibles suelen esconder fallos de autorización.

La revisión de secretos debe incluir .env, secrets de CI, configuraciones de ejemplo, README, logs, capturas y fixtures de prueba. Claude Code no debe imprimir secretos reales en el chat. Si encuentra algo sospechoso, el informe debe anotar ruta, tipo, necesidad de rotación y responsable, con el valor redactado. En GitHub, comprueba secret scanning y push protection además de búsquedas locales.

La validación de entrada debe seguir el flujo de datos: dónde entra, dónde se guarda, dónde se renderiza y a quién se envía. No pidas payloads peligrosos. Pide validación en fronteras, normalización, escape, tipos y pruebas. Para equipos principiantes, seguir el flujo de datos es más útil que memorizar nombres de vulnerabilidades.

Los logs y PII requieren revisar emails, nombres, direcciones, tokens, cookies, headers de autenticación, IDs de pago y textos libres. Un console.log de desarrollo puede convertirse en un problema de retención en producción. Los logs deben guardar el mínimo necesario para depurar y auditar, no cuerpos completos de requests.

Cuatro casos de uso

El primer caso es una auditoría SaaS antes del lanzamiento. Antes de publicar billing, invitaciones, administración o ajustes de organización, haz que Claude Code lea el diff del PR, migraciones, rutas, webhooks, pruebas y CI. El objetivo es un registro de riesgos para la reunión de release, no una promesa amplia de seguridad.

El segundo caso es una auditoría de entrega de repositorio en GitHub. Al heredar un repo, el conocimiento más peligroso suele estar en scripts de despliegue, secrets de CI, nombres de entornos, runbooks manuales y carpetas sin owner. Pide a Claude Code una checklist de primera semana: qué rotar, qué documentar, qué puertas de CI faltan y qué zonas necesitan revisión humana.

El tercer caso es una auditoría posterior a incidente. Después de una caída o sospecha de fuga, no basta con corregir la línea que disparó el problema. Pide búsqueda de patrones similares, revisión de PII en logs, pruebas de regresión, nuevas puertas de CI y actualización del runbook. Si hay informe público, debe explicar impacto y mitigación sin enseñar detalles operativos explotables.

El cuarto caso es revisión de seguridad de PR generado por IA. El código generado puede verse limpio y aun así omitir autorización, logs de auditoría, manejo de errores o pruebas. Pide a Claude Code que revise solo el impacto de seguridad del diff: superficie de ataque, permisos, secretos, datos personales, dependencias y cobertura de CI.

Registra riesgos y evidencias

Un hallazgo necesita evidencia. La severidad por sí sola no basta. El registro debe incluir impacto, dónde se observó, acción recomendada, prioridad, estado y dueño.

| ID | Risk | Impact | Evidence | Recommended action | Priority | Status | Owner |
| --- | --- | --- | --- | --- | --- | --- | --- |
| SEC-001 | Missing authorization on admin API | Another user's data may be changed | routes/admin.ts has no role check | Add middleware and regression tests | High | Open | backend |
| SEC-002 | Webhook logs include email | Unnecessary PII retention | logs/webhook-sample.txt | Mask email and reduce retention | Medium | Open | platform |

El recibo de evidencias evita que la auditoría sea solo una conversación difícil de rastrear.

# Security Audit Evidence Receipt

- Target:
- Date:
- Reviewer:
- Scope provided to Claude Code:
- Commands executed:
- Files or directories inspected:
- High-risk findings:
- Fixed items:
- Skipped or out-of-scope areas:
- Decisions requiring human review:
- Release recommendation:

Checklist para revisar PR

Para pull requests, pega una checklist corta en el prompt de revisión. Funciona especialmente bien cuando el cambio lo generó una IA, porque obliga a mirar riesgo y evidencias antes que estilo.

## Security PR Review

- [ ] Scope is clear and no unrelated files are changed
- [ ] Authenticated users cannot access another user's data
- [ ] Admin or billing actions require explicit authorization
- [ ] Inputs are validated at the boundary
- [ ] Outputs are escaped or rendered safely
- [ ] No secrets, tokens, cookies, or PII are printed to logs
- [ ] Dependency changes have a reason and test evidence
- [ ] Errors do not reveal internals
- [ ] CI includes lint, tests, typecheck, and security-relevant checks
- [ ] Risk register and evidence receipt are updated

Checklist de comandos

Los comandos exactos dependen del stack, pero en un proyecto Node o TypeScript se puede empezar por aquí. Pide a Claude Code que explique el objetivo de cada comando antes de ejecutarlo y que se detenga si un fallo cambia el riesgo.

git status --short
npm ci
npm audit --audit-level=moderate
npm run lint
npm run typecheck
npm test
rg -n "TODO|FIXME|console\\.log|process\\.env|localStorage|innerHTML|dangerouslySetInnerHTML" src
git diff --check

Los resultados de rg son pistas, no veredictos. process.env puede ser correcto, e innerHTML puede estar permitido si se sanea. Pide a Claude Code separar evidencia, suposición y pasos de confirmación.

Fallos y trampas habituales

El fallo más común es un prompt vago. “Revisa seguridad” produce respuestas superficiales. Un buen prompt nombra alcance, activos, fecha de release, comandos permitidos, flujos críticos y formato de salida. Un informe que diga claramente “no revisado” vale más que una conclusión segura sin pruebas.

El segundo fallo es no dejar evidencia. Si nadie sabe qué comandos se ejecutaron, qué archivos se inspeccionaron y qué quedó fuera, la auditoría no sirve para decidir un lanzamiento. Hay que confirmar las afirmaciones de Claude Code con CI, pruebas, diffs, logs y configuración.

Otro fallo peligroso es publicar demasiado detalle. No pongas URLs reales, tokens, datos de clientes ni instrucciones paso a paso en issues o artículos públicos. El lenguaje público debe centrarse en impacto y remediación. La reproducción sensible pertenece a un tracker restringido.

Tampoco ignores secretos y logs. Una aplicación puede tener código razonable y aun así filtrar datos por logs de CI, capturas de depuración, .env de ejemplo o errores verbosos. En cambios de autenticación, pagos, datos personales o administración, la revisión humana debe ser obligatoria.

Llévalo a CI y hábitos de equipo

Una auditoría puntual se deteriora rápido. Añade gates de CI para lint, typecheck, tests, dependency audit, secret scanning, búsqueda de APIs peligrosas y reglas de logging. No todo warning debe bloquear. Una regla práctica es bloquear High, crear tickets con fecha para Medium y agrupar Low en mantenimiento.

También revisa permisos y herramientas de Claude Code con la guía de permisos. Complementa con gestión de secretos, casos de fallo de seguridad y code review con Claude Code. Si tu equipo quiere convertir esto en política de revisión, gates de CI y brief específico del repositorio, empieza por formación y consultoría de Claude Code.

Resumen

Claude Code aporta más valor cuando una persona define el sistema de auditoría: alcance, activos, amenazas, carriles de revisión, registro de riesgos, recibo de evidencias, CI y aprobación humana para decisiones críticas. Sin esa estructura, el informe puede sonar bien y aun así no explicar el riesgo real.

Cuando Masa aplicó este flujo a revisiones previas al release de ClaudeCodeLab, lo más útil fue el registro de riesgos y el recibo de evidencias. Hacer que Claude Code inventariara rutas, logs, variables de entorno y CI antes de la revisión humana hizo visibles las preguntas pendientes. El resultado no fue una garantía de seguridad perfecta, sino una decisión de lanzamiento más clara.