Skill de auditoría de seguridad: una revisión repetible de tu código antes de que se te complique

La revisión de seguridad es ese trabajo que siempre se deja para después, porque la recompensa por hacerlo es que no pase nada. Así que termina haciéndose tarde, de manera inconsistente y distinta cada vez: uno hace grep buscando keys, otro le echa un ojo al middleware de auth, nadie revisa lo mismo dos veces. Un skill de auditoría de seguridad ataca primero el problema de la consistencia: empaqueta una lista de chequeo fija que Claude Code corre igual siempre, y te devuelve una lista priorizada de hallazgos reales con archivo:línea, no un ensayo vago. Al terminar de leer esto vas a saber qué hace un skill así, en qué momento exacto conviene lanzarlo, cómo funciona por dentro y los detalles que deciden si te ayuda o te hunde.

Esto es un skill de Claude Code, así que no es una herramienta aparte que ejecutas: es una capacidad que el agente carga bajo demanda cuando la tarea coincide con su descripción. Ese detalle lo moldea todo: el skill se gana su lugar siendo acotado, determinista en su lista y honesto con la confianza. No reemplaza un pentest ni una herramienta de SAST de verdad. Lo que hace es atrapar las fallas aburridas y comunes que terminan causando incidentes.

01 · Qué hace el skill realmente

Un skill de auditoría de seguridad hace una revisión estructurada del código buscando las fallas aburridas y conocidas que causan la mayoría de las brechas reales, no zero-days exóticos. Tiene criterio propio a propósito: una lista fija para que la salida sea comparable de una corrida a otra, y un reporte priorizado para que leas de arriba hacia abajo y pares cuando se te acabe el riesgo, no la paciencia.

La lista central, corta a propósito:

• Secretos. API keys, tokens y llaves privadas subidas al repo, o metidas en archivos env que git está versionando.
• Autorización. Toda ruta que modifica datos debe verificar quién la está llamando. Un chequeo de authz que falta es el bug serio más común y el más fácil de pasar por alto cuando solo lees el código.
• Inyección. Cualquier query SQL o comando de shell armado con input de usuario a punta de concatenación de strings en lugar de parámetros.
• Cripto. Nada de MD5 ni SHA1 para contraseñas, nada de cifrado hecho a mano, ni IVs o llaves fijas en el código.
• Defaults peligrosos. Endpoints de debug que quedaron prendidos, CORS permisivo, respuestas de error que filtran stack traces, secretos que terminan en el log en texto plano.

La ganancia está en la forma de la salida. No un "deberías considerar revisar tu autenticación", sino una lista priorizada donde cada hallazgo trae una severidad, un archivo:línea, una línea que describe el riesgo y un fix sugerido que puedes aceptar o descartar en segundos.

02 · Cuándo debe dispararse

Un skill se carga cuando su descripción coincide con la tarea, así que acertar con las condiciones del trigger es la mitad del diseño. La idea es que se dispare en los momentos que importan y se quede callado en los demás.

Lánzalo a propósito en estos momentos:

1. Antes de un lanzamiento o un deploy público. La última puerta antes de que el código toque usuarios y datos reales.
2. Después de actualizar dependencias. Los paquetes transitivos nuevos son superficie de ataque nueva; un bump es buen momento para volver a escanear en busca de patrones recién introducidos.
3. Cuando heredas código que no escribiste tú. No tienes idea de dónde están las minas, que es justo cuando una revisión estructurada rinde más.
4. En un pull request que toca seguridad. Cualquier cosa que modifique auth, pagos, subida de archivos o que reciba input de usuario.

Una descripción corta y bien acotada es lo que hace que el skill se dispare a tiempo sin estar fastidiando. Algo así basta para que Claude Code lo cargue cuando la tarea sí es una revisión de seguridad, y lo deje quieto cuando solo estás renombrando una variable:

---
name: security-audit
description: >
  Hace una revisión de seguridad estructurada del código. Úsalo antes de
  un lanzamiento, después de actualizar dependencias, al revisar cambios que
  tocan seguridad, o al heredar código desconocido. Revisa secretos filtrados,
  falta de autorización en rutas que modifican datos, inyección desde input de
  usuario, cripto débil y defaults peligrosos. Produce una lista priorizada de
  hallazgos con archivo:línea y confianza — NO auto-corrige código de seguridad.
---

03 · Cómo funciona por dentro

El skill es un archivo markdown con frontmatter y un cuerpo de instrucciones. Al cargarse, esas instrucciones llevan al agente por las mismas fases cada vez. El mecanismo no tiene nada de glamuroso, y ese es justo el punto: el valor está todo en la previsibilidad.

Una corrida pasa por cuatro fases:

1. Alcance. Define qué escanear: el repo completo, un diff contra main o un directorio puntual. Acotar a un diff es lo que hace al skill lo bastante rápido como para correrlo en cada PR.
2. Barrido. Recorre la lista. Esto es mayormente grep y lectura: busca strings con pinta de secreto, lista las rutas y verifica que cada una tenga un guard de authz, encuentra queries y llamadas de shell armadas con datos del request, y escanea en busca de identificadores de hash y cifrado débiles.
3. Triaje. Le asigna a cada hallazgo una severidad y una confianza. La severidad es "qué tan malo sería si es real"; la confianza es "qué tan seguro estoy de que es real". Son ejes distintos, y mezclarlos es justo como te llenas de ruido.
4. Reporte. Emite una sola lista priorizada, ordenada por severidad y luego por confianza, con cada línea trayendo su archivo:línea y un fix de una línea.

Un buen cuerpo de skill fija el formato de salida para que cada corrida se pueda parsear y comparar:

## Formato de salida
Por cada hallazgo, emite exactamente una fila:

[SEVERIDAD] [CONFIANZA] path/al/archivo.ts:42 — <riesgo en una línea>
  Fix: <una acción concreta>

SEVERIDAD = critical | high | medium | low
CONFIANZA = confirmed | likely | possible

Ordena de critical a low, y dentro de cada una de confirmed a possible.
NO modifiques ningún archivo. Solo reporta.
Cierra con un resumen de un párrafo: el conteo por severidad y el único
ítem más urgente que hay que arreglar primero.

La línea de "no modifiques ningún archivo" es de las que cargan peso, no es decoración: es lo que mantiene a una auditoría como auditoría y no como una sesión de edición sin supervisión sobre tu código de auth.

04 · Una invocación concreta y qué te devuelve

Lo invocas igual que cualquier skill: pidiendo el trabajo con palabras que coincidan con la descripción. En concreto:

"Córreme una auditoría de seguridad sobre los cambios de este branch antes de que abra el PR."

Claude Code carga el skill, lo acota al diff del branch, recorre la lista y te devuelve algo así:

[critical] [confirmed] src/lib/db.ts:88 — SQL armado por concatenación de strings desde req.query.email
  Fix: usa un query parametrizado: db.query("... where email = $1", [email])

[high] [likely] src/app/api/invoices/route.ts:23 — el handler POST modifica datos sin chequeo de authz
  Fix: verifica que quien llama sea dueño del cliente antes de escribir; si no, rechaza

[medium] [possible] config/.env.example:4 — parece una key real de Stripe, no un placeholder
  Fix: confirma que sea un valor de prueba; si es real, rótala y limpia el historial de git

[low] [confirmed] src/lib/auth.ts:31 — contraseña hasheada con SHA1
  Fix: migra a un KDF lento (bcrypt/argon2); re-hashea en el próximo login

Resumen: 1 critical, 1 high, 1 medium, 1 low. Arregla primero la inyección
SQL en db.ts:88 — está confirmada y es explotable directo desde un query param.

Fíjate en lo que lo hace útil: la inyección SQL está confirmed y es critical, así que queda arriba y el resumen apunta directo a ella. La key que parece de Stripe se marca possible, no se da por hecho, porque las configs de ejemplo son justo donde viven los falsos positivos. Te dice dónde mirar, por qué y cómo arreglarlo, en un formato que podrías meter en una checklist o pegar en un comentario de PR.

05 · Configuración y ajuste

Unas pocas perillas deciden si el skill encaja con tu repo o pelea con él. Ponlas en el cuerpo del skill para que apliquen en cada corrida, y sobreescríbelas desde el prompt cuando una auditoría puntual necesite algo distinto.

• Alcance por defecto. Que por defecto sea el diff contra tu branch main, para que corra rápido en cada PR, con un modo "repo completo" para auditorías pre-lanzamiento y de código heredado. Un barrido del repo entero en cada PR es demasiado lento para aguantar el ritmo del día a día.
• Rutas a ignorar. Excluye del barrido de secretos el código generado, las dependencias de terceros y los fixtures, o al menos bájales la prioridad. Los fixtures de prueba llenos de keys falsas son la fuente número uno de ruido.
• Piso de confianza. Deja que quien lo llama pida "solo confirmed y likely" cuando lo que quiere es señal, o "todo, incluyendo possible" para una revisión pre-lanzamiento bien minuciosa.
• Reglas propias del proyecto. Si tu stack tiene una trampa conocida, por ejemplo un framework que deja CORS abierto por defecto o un método de ORM que se salta el escaping, codifícalo como un chequeo explícito para que el skill atrape tu forma particular de meter la pata, no solo las genéricas.

06 · Detalles que deciden si ayuda o estorba

Aquí es donde un skill de seguridad se tuerce, y todos estos puntos tienen que ver con calibrar la confianza más que con la lista en sí.

Va a producir falsos positivos, sobre todo en fixtures de prueba y configs de ejemplo. Eso es inevitable y está bien; lo que no está bien es presentar adivinanzas como hechos. Haz que etiquete la confianza de cada hallazgo para que un "possible" nunca se lea como un "confirmed", y así pongas tu atención donde de verdad hace falta.

Nunca lo dejes auto-corregir código de seguridad. Todo el valor de una revisión de seguridad está en un humano leyendo el diff con intención; un agente que reescribe en silencio tu lógica de autorización para "arreglar" un hallazgo del que solo estaba 60 por ciento seguro es un resultado peor que el bug original. El skill lee y reporta. Tú lees y decides. Por eso la instrucción de "no modifiques archivos" va en el cuerpo.

Dos trampas más que vale la pena nombrar. Primero, un reporte limpio no significa un código limpio: significa que la lista no encontró nada de lo que sabe buscar, que es una afirmación mucho más acotada. Dilo de frente para que una corrida en verde no te genere confianza falsa. Segundo, el skill vale lo que valga su lista; cuando un nuevo tipo de bug te muerda, agrégalo a la lista para que la próxima corrida lo atrape. El skill debería afilarse con el tiempo, moldeado por tus incidentes reales.

Un skill de auditoría de seguridad no es magia ni pretende serlo. Es consistencia en un terreno donde los humanos somos inconsistentes: los mismos chequeos aburridos, corridos igual, en cada lanzamiento y cada PR riesgoso, con resultados que puedes comparar a lo largo del tiempo. Mantenlo acotado, mantenlo honesto con la confianza, nunca lo dejes tocar tu código sin supervisión y aliméntalo con tus errores reales: así se vuelve la puerta que de verdad corres, en vez de la revisión que llevas tiempo posponiendo.