refacil-security-skills

Slash commands de Claude Code para auditorías de seguridad en backends Node.js. Genera un reporte consolidado de vulnerabilidades con Risk Score, tickets de remediación P0/P1/P2, y PoC de verificación por cada hallazgo.

Probado en Express, NestJS/Fastify, y Koa. El flujo es agnóstico al framework — funciona sobre cualquier backend que tenga archivos de rutas o controladores legibles.

Prerrequisitos

• Claude Code instalado y con sesión activa
• Node.js 18 o superior

Instalación

Ejecutar desde el directorio raíz del proyecto a auditar.

Opción A — npm (como dev dependency):

cd tu-proyecto-backend/
npm install --save-dev refacil-security-skills
# Las skills se copian automáticamente a .claude/commands/

Opción B — tarball local (sin registro):

cd tu-proyecto-backend/
npx /ruta/al/refacil-security-skills-1.1.0.tgz install

Opción C — npx desde registro:

cd tu-proyecto-backend/
npx refacil-security-skills install

Verifica la instalación:

ls .claude/commands/
# audit-diff.md  audit-init.md  audit-lite.md  audit-status.md
# audit-wave.md  synthesize.md  triage.md

Flujo de auditoría

Cada skill recomienda el siguiente comando al terminar. No necesitas recordar la secuencia — el output de cada paso te dice exactamente qué correr después, con los nombres reales de los archivos de tu proyecto.

/audit-init
    └─▶ audit/PROJECT_CONTEXT.md

/triage
    └─▶ audit/TRIAGE_RESULTS.md
        └─▶ /audit-wave orders payments auth   ← comandos exactos generados por el triage
            └─▶ audit/reports/*/full/*.md
        └─▶ /audit-lite users notifications
            └─▶ audit/reports/*/lite/*.md

/synthesize
    └─▶ audit/FINDINGS_MASTER.md

Comandos principales

| Skill | Qué hace | |---|---| | /audit-init | Detecta stack, ORM, auth middleware y estructura de carpetas. Escribe audit/PROJECT_CONTEXT.md | | /triage | Clasifica todos los endpoints por riesgo (CRITICAL / SENSITIVE / STATE_MUTATION / READ_ONLY) y genera los comandos de siguiente paso | | /audit-wave <archivos> | Auditoría FULL — reporte de 12 secciones por endpoint: middlewares, flujo, contrato, análisis de seguridad, hipótesis forense | | /audit-lite <archivos> | Auditoría LITE — reporte de 6 secciones para endpoints de menor riesgo | | /synthesize | Consolida todos los reportes en audit/FINDINGS_MASTER.md |

Comandos de soporte

| Skill | Qué hace | |---|---| | /audit-status | Dashboard de progreso con barra visual — qué olas corrieron, cuántas vulns encontradas, qué falta | | /audit-diff | Audita solo los archivos modificados en el branch actual — útil para revisiones de PR |

Qué produce FINDINGS_MASTER.md

Un documento consolidado con:

Tabla maestra de endpoints — ordenada por Risk Score descendente:

| Endpoint | Método | Vulns 🔴 | Vulns 🟠 | Audit Trail | Veredicto | Risk Score | |---|---|---|---|---|---|---| | /shifts/:id/close | POST | 2 | 2 | Parcial | 🔴 Probable | 🔴 90 | | /shifts/open | POST | 1 | 2 | Parcial | 🔴 Probable | 🔴 90 | | /sync/sheet-change | POST | 0 | 3 | Parcial | 🟠 Posible | 🟠 75 |

Por cada vulnerabilidad:

• Confianza — 🔵 ALTA (código lo demuestra) / 🟡 MEDIA (patrón probable) / ⚪ BAJA (ausencia de protección visible)
• Verificación rápida — curl o query SQL para confirmar o descartar en menos de 5 minutos
• Posible falso positivo — qué condición haría que el hallazgo sea incorrecto

Tickets de remediación — listos para copiar a Linear, Jira o GitHub Issues:

[P0-001] VULN-C-001 — POST /shifts/:id/close · src/shifts/shifts.service.ts:362
Confianza: 🔵 ALTA
Descripción: r.price del body del cliente se usa directamente en el cálculo financiero
Fix: Eliminar price del DTO y obtener el precio desde DailyPrice por station_id y date
Verificación: curl -X POST /shifts/<id>/close -d '{"readings":[{"price":0.01,...}]}'
Esfuerzo: S

Fórmula Risk Score (0–100):

• Base por severidad máxima: Crítica=40 · Alta=30 · Media=15 · Baja=5
• +20 si no tiene audit trail
• +20 si veredicto forense es Probable
• +10 si veredicto forense es Posible
• +10 si es CRITICAL o AUTH sin segundo factor

Compartir skills con el equipo

Las skills viven en .claude/commands/ del proyecto. Dos opciones para que todo el equipo las tenga:

Opción 1 — via git (más simple):

git add .claude/commands/ -f
git commit -m "chore: add security audit skills"

Cada dev que clone el repo tendrá las skills disponibles inmediatamente en Claude Code.

Opción 2 — via npm install:

Cada dev corre npm install normalmente y el postinstall las instala automáticamente.

Si .claude/ está en el .gitignore del proyecto, el CLI lo detecta y avisa con instrucciones de fix.

Archivos generados

audit/ contiene hallazgos de seguridad reales — tratar como información sensible.

Configuración recomendada de .gitignore:

# Reportes individuales — sensibles, pueden ser voluminosos
audit/reports/

# Mantener en git: el resumen ejecutivo y el triage
# audit/FINDINGS_MASTER.md
# audit/TRIAGE_RESULTS.md

Proyectos grandes (15+ archivos de rutas)

/triage procesa todos los archivos en paralelo. Con proyectos muy grandes puede saturar el contexto de Claude. Solución: pasar los archivos en olas de 5–8 por vez:

/audit-wave orders payments auth webhooks
# al terminar:
/audit-wave users notifications reports exports

Limitaciones

• No es un pentest. Los hallazgos son puntos de partida, no conclusiones. Un pentest real incluye pruebas dinámicas, encadenamiento de vulnerabilidades y análisis de infraestructura.
• Hay falsos positivos. Código que parece vulnerable puede estar protegido por un middleware global no analizado. El nivel de confianza (🔵/🟡/⚪) indica qué verificar primero.
• Hay falsos negativos. Vulnerabilidades en lógica de negocio compleja, condiciones de carrera sutiles o configuraciones de infraestructura no aparecen en análisis estático.
• Los P0 requieren revisión humana antes de cerrarlos, independientemente de la confianza reportada.

Desarrollo y validación

# Validar coherencia estructural de los skills
npm test

# Generar tarball para distribución
npm run pack

El validador verifica que cada skill contenga las secciones contractuales requeridas, que no haya referencias hardcodeadas a proyectos internos, y que el flujo de cascada esté correctamente enlazado.