Revisión de seguridad en Claude Code: /security-review y GitHub Action

El autor del material original describe su experiencia: «Acabo de ejecutar security-review en mi propio proyecto vibe, y el equipo encontró varios problemas reales en 4 minutos que ya se han corregido». Antes, este mismo trabajo le llevaba un día a un consultor externo.

Encontrarás materiales adicionales sobre la configuración de herramientas en la documentación de Ailoot.

¿Qué es /security-review en Claude Code?#

El comando funciona en dos modos. En local: ejecuta /security-review en el terminal y Claude leerá el repositorio y generará un informe. En el servidor: el mismo motor se instala como una GitHub Action y comenta automáticamente en línea en cada Pull Request.

A diferencia de los escáneres SAST clásicos (Snyk Code, Semgrep, SonarQube), /security-review no se basa en reglas fijas. Lee el código como lo haría un ingeniero en activo: rastrea el flujo de datos, entiende qué framework usas y dónde están los límites de confianza, y detecta vulnerabilidades que ninguna regla describe.

Esto no significa que /security-review sustituya a una prueba de penetración externa o a las pruebas en vivo en un entorno de staging. Puede automatizar parte de la revisión inicial, pero este artículo no mide una fracción de cobertura de auditoría. A continuación, explicaré cómo ejecutarlo correctamente y qué encontrará Claude en tu proyecto.

¿Cómo ejecutar /security-review en 5 pasos?#

Paso 1. Actualiza Claude Code. El comando está disponible a partir de la versión publicada el 20 de febrero de 2026.

claude update

Si instalaste Claude Code mediante npm, también puedes hacer lo siguiente:

npm install -g @anthropic-ai/claude-code@latest

Comprueba que /security-review esté disponible:

claude /help | grep security

Paso 2. Abre el proyecto e inicia sesión en Claude Code.

cd ~/projects/my-vibe-project
claude

Paso 3. Ejecuta el comando. Dentro de Claude Code, escribe simplemente:

/security-review

Claude recorre automáticamente 3 fases de análisis:

1. Investigación del contexto del repositorio - lee la estructura e identifica el stack, las rutas y las consultas a la base de datos.
2. Análisis comparativo - compara el estado actual con patrones habituales de vulnerabilidad para ese stack.
3. Evaluación de vulnerabilidades - enumera cada sospecha con un nivel de confianza en una escala de 1-10. El informe solo incluye hallazgos con un nivel de confianza ≥ 8.

Paso 4. Lee el informe. El resultado tiene formato de tabla Markdown. Para cada problema, Claude proporciona:

• Archivo y número de línea (por ejemplo, src/auth/login.ts:42)
• Gravedad (HIGH / MEDIUM / LOW)
• Categoría (sql_injection, xss, auth_bypass, insecure_storage)
• Descripción - cuál es el problema
• Escenario de explotación - cómo podría aprovecharlo un atacante
• Recomendación - cómo solucionarlo

Paso 5. Pídele que aplique las correcciones. Después, puedes trabajar con Claude como con un agente normal:

«Aplica las correcciones de gravedad HIGH del informe, una a una, con una descripción de PR.»

Claude abrirá cada archivo y propondrá un cambio; tú lo confirmarás. En un proyecto real, cerré 5 hallazgos en 40 minutos, en lugar de las 3 horas previstas.

¿Qué vulnerabilidades detecta /security-review?#

La documentación oficial de Anthropic describe la lista completa de lo que se incluye por defecto en el análisis:

Además, el comando cubre categorías que los escáneres automatizados rara vez detectan:

• Inyección de comandos - ejecución de datos introducidos por el usuario en un shell (child_process.exec(userInput))
• Path traversal - carga de un archivo mediante ../../etc/passwd
• XXE - XML con entidades externas
• Inyección de plantillas - SSTI en Jinja/Handlebars/EJS
• Inyección NoSQL - operadores $ne, $gt en consultas a MongoDB
• Uso incorrecto de criptografía - uso de MD5, modo ECB o un IV estático

Claude asigna un nivel de gravedad a cada hallazgo. La escala es sencilla:

• HIGH - explotación remota sin autenticación, filtración de datos que afecta a todos los usuarios
• MEDIUM - explotación con condiciones adicionales (se necesita una sesión / una entrada específica)
• LOW - un vector potencial, no crítico por ahora, pero conviene solucionarlo

Es útil saber que, en la configuración estándar, Claude no informa sobre DoS, límites de frecuencia, agotamiento de memoria, redirecciones abiertas sin impacto demostrado, inyección mediante expresiones regulares / ReDoS ni falsificación de registros. Es intencionado, para que no te inunde con ruido. Si estas clases son importantes, amplía las reglas (consulta la sección sobre el filtrado de falsos positivos más abajo).

¿Cómo configurar una GitHub Action para la revisión automática?#

Paso 1. Obtén una clave de API. Ve a console.anthropic.com, crea una clave de API y cópiala.

Paso 2. Añade la clave a los secretos del repositorio. En GitHub: Settings → Secrets and variables → Actions → New repository secret. Ponle el nombre CLAUDE_API_KEY; el valor es tu clave.

Paso 3. Crea un archivo de workflow. Guárdalo como .github/workflows/security.yml:

name: Security Review

permissions:
  pull-requests: write
  contents: read

on:
  pull_request:

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
          fetch-depth: 2

      - uses: anthropics/claude-code-security-review@main
        with:
          comment-pr: true
          claude-api-key: ${{ secrets.CLAUDE_API_KEY }}

Paso 4. Fusiona la rama en main. La acción se iniciará automáticamente con la siguiente PR.

Qué hace la acción:

• Se ejecuta al abrir o sincronizar cada Pull Request.
• Obtiene el diff entre la rama de la PR y main.
• Ejecuta el mismo motor que /security-review en local.
• Publica comentarios en línea directamente en las líneas de código donde hay alguna sospecha.
• Duplica el informe completo en el resumen del Job.

Detalles importantes de permissions:

• pull-requests: write - para publicar comentarios en línea.
• contents: read - para leer el código. Sin write. La acción no modifica el código; solo informa.

Este conjunto de permisos basta para un repositorio privado. En uno público, puedes especificar además actions: read si usas workflows reutilizables.

¿Cómo filtrar falsos positivos y cambiar la sensibilidad?#

Tabla completa de entradas de la GitHub Action (fuente: README del repositorio):

Ejemplo de configuración del filtrado de falsos positivos. Crea el archivo .claude/security/false-positives.md:

# Reglas de filtrado de falsos positivos para nuestro proyecto

- Cualquier `dangerouslySetInnerHTML` dentro de `src/lib/email/layout.ts` es seguro:
  el HTML se ensambla a partir de plantillas confiables y pasa por `sanitize-html`
  cuando se escribe en la base de datos, no en el momento de renderizarlo.
- No informes de claves API de prueba codificadas directamente en `__tests__/fixtures/*.ts`.
  Todas las claves empiezan por `sk-test-fake-`.
- La concatenación SQL en `src/lib/admin/migrations.ts` es aceptable: el archivo se ejecuta
  solo como root, y los datos de entrada proceden de variables de entorno.

Conéctalo en el workflow:

- uses: anthropics/claude-code-security-review@main
  with:
    comment-pr: true
    claude-api-key: ${{ secrets.CLAUDE_API_KEY }}
    false-positive-filtering-instructions: .claude/security/false-positives.md

Las instrucciones personalizadas para el análisis de seguridad son similares. Crea un archivo con reglas que sean especialmente importantes para tu proyecto:

# Comprobaciones adicionales para nuestro proyecto

- Cada endpoint bajo `/api/admin/*` debe comprobar el rol de administrador
  mediante un wrapper compartido. Sin este wrapper, la gravedad es HIGH.
- Todos los webhooks de YooKassa / CloudPayments deben verificar la firma antes
  de analizar el cuerpo. Sin esto, la gravedad es HIGH.
- Los tokens de Magic Link deben ser de un solo uso (marcados como utilizados después
  de la primera solicitud válida). Los tokens reutilizables tienen gravedad MEDIUM.

Esto ya no es una configuración predefinida de Anthropic: estás incorporando tus conocimientos del proyecto en reglas que Claude aplica cada vez. Esa es la esencia de «la metodología por encima del modelo».

Para más información sobre la metodología de contexto para Claude, consulta las guías «Cómo configurar CLAUDE.md» y «Second Brain en Claude Code».

Qué NO detecta Claude y por qué: límites explicados con honestidad#

Anthropic indica claramente qué está desactivado por defecto y por qué (fuente: README del repositorio):

• Denegación de servicio - demasiado ruido y casi siempre con poco impacto.
• Problemas de límites de frecuencia - se gestionan en la infraestructura, no en el código.
• Agotamiento de memoria / CPU - lo mismo.
• Validación genérica de entradas sin impacto demostrado - validar cada campo genera una avalancha de falsos positivos.
• Redirección abierta - a menudo es un comportamiento intencionado.

Lo que una revisión de código por sí sola no verifica completamente sin pruebas de ejecución o despliegue:

• Configuración del servidor de producción. Encabezados de NGINX, políticas CORS, ajustes de TLS y puertos a la escucha. Hay que comprobarlos manualmente en un entorno de staging.
• Condiciones de carrera. Por ejemplo, gastar dos veces durante solicitudes de reembolso simultáneas. El análisis estático puede señalar patrones sospechosos, pero hay que probar el comportamiento concurrente.
• Fallos en la lógica de negocio de pagos. Si el total del pedido se calcula en el cliente y simplemente se envía al proveedor de pagos, es un problema de gravedad HIGH. Sin embargo, Claude no siempre detecta este patrón si no tiene contexto explícito sobre cómo debería funcionar el pago.
• IDOR a nivel de base de datos. Si la consulta SELECT * FROM orders WHERE id = $1 no comprueba WHERE user_id = $session.userId, Claude suele detectarlo. Pero si la comprobación está implementada mediante middleware del ORM y Claude no puede ver el flujo de datos completo, puede pasarla por alto.
• Resistencia a la ingeniería social / al phishing. No tiene nada que ver con el código.

Usa /security-review como revisión estática inicial. Complétala con pruebas dinámicas en staging, roles y permisos, comprobaciones SAST pertinentes y configuración desplegada real. Aquí no se acredita un porcentaje medido de cobertura.

Decide alcance y momento de una evaluación externa según riesgos y cambios del sistema. Ni un comando ni una auditoría externa periódica acreditan seguridad del 100 %.

Cómo realizó el autor del material original una revisión de seguridad en un proyecto vibe#

Qué apareció. Una imagen habitual de un proyecto vibe promedio en la etapa «funciona en producción, pero aún no se ha revisado»: varias sospechas sobre el flujo de autenticación, la lógica de procesamiento de webhooks de la integración de pagos, el manejo de cargas de archivos y un par de observaciones concretas sobre el tratamiento del HTML al renderizarlo. No voy a describir los detalles públicamente; algunas recomendaciones ya se han aplicado y otras siguen en PR. En el proyecto relatado, el análisis inicial fue útil y rápido; no acredita un porcentaje de auditoría ni un tiempo general de finalización.

Lo que descarté como falsos positivos:

• Hallazgos sobre DoS mediante expresiones regulares en la validación de entradas: la carga real no recae sobre esas expresiones.
• Un hallazgo sobre una clave de API codificada directamente: era una clave de prueba con el prefijo explícito fake- en los fixtures.

Cuánto tardó. La ejecución en sí duró 4 minutos. Revisar el informe llevó 25 minutos. Aplicar las correcciones y hacer pruebas llevó alrededor de una hora. En total: aproximadamente una hora y media desde «empezar» hasta «todo está en main». Una prueba de penetración externa del mismo alcance lleva una semana natural y cuesta varias decenas de veces más.

Conclusión principal. /security-review no sustituye a una prueba de penetración externa. Puede detectar hallazgos útiles de código, como en el análisis de cuatro minutos relatado por el autor. Revisa y prueba las correcciones y comprueba aparte ejecución y despliegue; el análisis no elimina el riesgo del proyecto.

¿Cómo integrar /security-review en tu rutina de pre-commit?#

El hook anterior con git_commit, --severity HIGH y --fail-on-find no es una receta documentada y funcional y no debe usarse como barrera de seguridad. Este artículo no aporta un hook local verificado de bloqueo. La GitHub Action oficial anterior automatiza hallazgos de PR; comentar en una PR no demuestra que bloquee commits o merges.

Encontrarás una explicación completa de los hooks en la guía «Hooks en Claude Code».

Como alternativa, puedes usar rutinas para crear una rutina pre-deploy-check que ejecute /security-review + npm run build + npm run test con un solo comando. Encontrarás materiales adicionales en la documentación de Ailoot.

Si usas servidores MCP, puedes integrar los hallazgos de /security-review en un sistema de gestión de incidentes (Sentry, Linear, Notion) para que cada hallazgo de gravedad HIGH se convierta automáticamente en un ticket.

Preguntas frecuentes sobre /security-review#

¿Cuánto cuesta una ejecución? Depende del tamaño del proyecto. En mis 30K líneas, una ejecución consume alrededor de $0.30-0.50 del saldo de API. Un gran repositorio empresarial con un millón de líneas cuesta hasta $5-8 por ejecución. Es varias decenas de veces más barato que cualquier suscripción a un escáner SaaS.

¿Con qué frecuencia debería ejecutarlo en local? Como mínimo, antes de cada lanzamiento a producción. Plantéalo también antes de commits y PR importantes. El artículo no aporta un hook automático de bloqueo de commits verificado.

¿Con qué stacks funciona? Con cualquiera que Claude pueda leer. Según las observaciones del autor, se han comprobado estos: Next.js / Node.js, Python (Django, FastAPI), Go, Rust, PHP (Laravel), Ruby on Rails. La calidad es menor con lenguajes muy exóticos (Erlang, Elixir, Clojure), pero encontrará algo.

¿Qué debería hacer si Claude encuentra cada vez la misma «vulnerabilidad», aunque en realidad no lo sea? Añádela a false-positive-filtering-instructions con una explicación de «por qué es seguro». Claude dejará de informarla en futuras ejecuciones.

¿Puedo ejecutarlo solo en archivos concretos? En local, sí: ejecuta /security-review src/lib/auth/*.ts. En la GitHub Action solo se comprueba el diff de la PR actual, que suele ser lo que se entiende por «archivos concretos».

Fuentes#

Encontrarás materiales adicionales en la documentación de Ailoot.