¿Qué hace sast-skills?
Convierte a tu asistente de codificación LLM en un escáner SAST completamente funcional. Habilidades (skills) integrables para Claude Code, Codex, Opencode, Cursor y cualquier asistente que cargue carpetas de habilidades CLAUDE.md / AGENTS.md.
Se recomienda Claude Code con Opus para obtener calidad; cualquier modelo capaz funciona.
Aspectos destacados
- 31 habilidades en 28 clases de vulnerabilidades — inyección, control de acceso roto, criptografía débil, manejo de archivos, cadena de suministro, lógica de negocio y riesgos específicos de LLM (inyección de prompts, manejo inseguro de salidas).
- Orquestación en cuatro fases — reconocimiento → detección paralela → informe consolidado → triaje basado en evidencia, impulsado completamente desde
CLAUDE.md/AGENTS.md. - Idempotente y reanudable — cada fase omite el trabajo cuya salida ya existe; vuelve a ejecutar después de corregir problemas para refrescar solo lo obsoleto.
- Salida legible por máquina — cada habilidad emite JSON canónico;
sast-skills exportagrega a JSON, SARIF 2.1.0 o HTML para GitHub Code Scanning y CI. - Multi-asistente — las mismas habilidades se distribuyen para Claude Code (
.claude/skills) y para cada asistenteAGENTS.md(.agents/skills). - CLI sin configuración —
install/update/uninstall/doctor/export, publicado desde GitHub Actions con procedencia npm (atestación SLSA).
Flujo
El orquestador ejecuta cuatro fases: reconocimiento, detección paralela, síntesis y triaje:
flowchart TD
U(["Usuario: Ejecutar escaneo de vulnerabilidades"]) --> R{"Orquestador CLAUDE.md / AGENTS.md"}
R --> S1["Paso 1 — sast-analysis<br/>mapa de código y arquitectura"]
S1 -->|sast/architecture.md| S2["Paso 2 — escaneo paralelo de vulnerabilidades<br/>28 habilidades: reconocimiento, verificación por lotes, fusión"]
S2 -->|sast/*-results.md y *-results.json| S3["Paso 3 — sast-report<br/>consolidar y clasificar"]
S3 -->|sast/final-report.md| S4["Paso 4 — sast-triage<br/>eliminación de falsos positivos,<br/>ajuste de severidad con evidencia"]
S4 -->|sast/final-report-triaged.md y triaged.json| EXP["npx sast-skills export<br/>JSON, SARIF, HTML"]
EXP --> CS(["GitHub Code Scanning, CI, paneles de control"])
Cada paso es idempotente: si su archivo de salida ya existe, el orquestador lo omite. Vuelve a ejecutar el escaneo después de corregir problemas para refrescar solo lo obsoleto.
Lo que detecta
Todas las habilidades siguen el mismo patrón de tres fases: reconocimiento → verificación por lotes (subagentes paralelos, 3 por lote) → fusión. Cada una escribe un informe markdown legible por humanos y un archivo JSON canónico de hallazgos que sast-skills export agrega.
Reconocimiento y Síntesis
| Habilidad | Rol |
|---|---|
sast-analysis | Reconocimiento del código, mapeo de arquitectura, modelo de amenazas |
sast-report | Consolidar hallazgos por clase en un informe clasificado |
sast-triage | Eliminar falsos positivos y ajustar severidades con evidencia del código |
Inyección
| Habilidad | Clase de Vulnerabilidad |
|---|---|
sast-sqli | Inyección SQL |
sast-nosql | Inyección NoSQL (Mongo, Firestore, DynamoDB) |
sast-ldap | Inyección en filtro / DN LDAP |
sast-graphql | Construcción insegura de documentos GraphQL |
sast-xss | Cross-Site Scripting |
sast-ssti | Inyección de Plantillas del Lado del Servidor |
sast-rce | Ejecución Remota de Código (inyección de comandos, eval, deserialización insegura) |
sast-xxe | Entidad Externa XML |
sast-ssrf | Server-Side Request Forgery |
sast-openredirect | Redirección abierta (phishing / robo de tokens OAuth) |
Control de acceso y Autenticación
| Habilidad | Clase de Vulnerabilidad |
|---|---|
sast-idor | Referencia Directa Insegura a Objetos |
sast-missingauth | Autenticación faltante / autorización a nivel de función rota |
sast-jwt | Implementaciones inseguras de JWT |
sast-csrf | Cross-Site Request Forgery |
sast-cors | Configuración incorrecta de CORS |
Archivos, criptografía y tiempo de ejecución
| Habilidad | Clase de Vulnerabilidad |
|---|---|
sast-pathtraversal | Recorrido de rutas / directorios |
sast-fileupload | Carga insegura de archivos |
sast-crypto | Primitivas débiles, modos incorrectos, reutilización de IV, PRNG débil |
sast-prototype | Contaminación de prototipos en JavaScript |
sast-redos | DoS por retroceso catastrófico en regex |
sast-race | Condiciones de carrera y TOCTOU |
Exposición de datos y cadena de suministro
| Habilidad | Clase de Vulnerabilidad |
|---|---|
sast-hardcodedsecrets | Claves API / tokens / credenciales en código orientado al cliente |
sast-pii | Filtración de PII y credenciales a registros / telemetría / páginas de error |
sast-deps | Dependencias con vulnerabilidades conocidas (CVE en archivos de bloqueo) |
sast-iac | IaC inseguro (Dockerfile / Terraform / Kubernetes / GitHub Actions) |
Lógica de negocio y específicas de LLM
| Habilidad | Clase de Vulnerabilidad |
|---|---|
sast-businesslogic | Manipulación de precios, elusión de flujo de trabajo, abuso de recompensas |
sast-promptinjection | Texto no confiable que llega a un prompt de LLM (OWASP LLM #1) |
sast-llmoutput | Salida de LLM no validada que llega a sinks de código / HTML / SQL / shell (OWASP LLM #2) |
Instalación
npx sast-skills install
El instalador pregunta qué asistente se desea (claude / agents / all) y si se debe instalar en el proyecto actual o en el directorio de inicio del usuario (project / global). Para omitir las indicaciones:
npx sast-skills install --yes --assistant claude --scope project
Si tu proyecto ya contiene un
CLAUDE.mdoAGENTS.md, el instalador se niega a sobrescribirlo por defecto — haz una copia de seguridad o pasa--force.
Instalación manual (sin npx / npm)
Usa esta ruta si no puedes ejecutar npx (proxy corporativo, registro npm inalcanzable, entorno sin conexión) o si deseas fijar esta bifurcación como fuente en lugar del paquete npm publicado. El instalador CLI solo hace dos cosas — colocar el archivo de entrada del orquestador en la raíz del proyecto y reflejar cada SKILL.md de habilidad en el directorio oculto correspondiente — por lo que un simple cp -R lo reproduce exactamente.
1. Obtén los archivos empaquetados
git clone https://github.com/mstfknn/sast-skills.git
Todo lo que necesitas está en sast-skills/sast-files/:
sast-files/
├── CLAUDE.md # Entrada del orquestador para Claude Code
├── AGENTS.md # Entrada del orquestador para Gemini CLI / Codex / OpenCode / Cursor
├── .claude/skills/sast-*/SKILL.md # 31 habilidades en formato Claude Code
└── .agents/skills/sast-*/SKILL.md # Mismas 31 habilidades reflejadas para asistentes AGENTS.md
Los dos árboles de habilidades se mantienen sincronizados mediante npm run sync — el contenido es idéntico, solo el nombre del directorio difiere.
2a. Instalar para Claude Code
Establece SAST_SRC a la ruta del clon para que los comandos a continuación se puedan copiar y pegar:
export SAST_SRC=/ruta/absoluta/hacia/sast-skills
cd /ruta/hacia/tu-proyecto
Ámbito del proyecto (recomendado — versionado junto con tu repositorio):
cp "$SAST_SRC/sast-files/CLAUDE.md" ./CLAUDE.md
cp -R "$SAST_SRC/sast-files/.claude" ./
Si ya usas un
CLAUDE.mda nivel de proyecto, no lo sobrescribas — Claude Code solo lee unCLAUDE.mdpor proyecto. En su lugar, fusiona el contenido del orquestador (el flujo de cuatro fases) en tu archivo existente.
Ámbito global (habilidades disponibles en cada proyecto; el orquestador aún se copia por proyecto):
mkdir -p ~/.claude/skills
cp -R "$SAST_SRC/sast-files/.claude/skills/." ~/.claude/skills/
# Luego, en cualquier proyecto donde quieras el flujo de escaneo:
cp "$SAST_SRC/sast-files/CLAUDE.md" /ruta/hacia/tu-proyecto/CLAUDE.md
2b. Instalar para Gemini CLI (y otros asistentes AGENTS.md)
export SAST_SRC=/ruta/absoluta/hacia/sast-skills
cd /ruta/hacia/tu-proyecto
cp "$SAST_SRC/sast-files/AGENTS.md" ./AGENTS.md
cp -R "$SAST_SRC/sast-files/.agents" ./
AGENTS.md es la convención entre asistentes respetada por Gemini CLI, Codex CLI, OpenCode y Cursor. Si tu versión de Gemini CLI busca GEMINI.md en su lugar, cámbiale el nombre — el contenido no cambia:
mv AGENTS.md GEMINI.md
3. Verificar la instalación
# Ámbito del proyecto (Claude Code)
ls CLAUDE.md && ls .claude/skills/ | head
# Ámbito del proyecto (Gemini / AGENTS.md)
ls AGENTS.md && ls .agents/skills/ | head
# Ámbito global (Claude Code)
ls ~/.claude/skills/ | head
Deberías ver los 31 directorios de habilidades sast-*. Abre el proyecto en tu asistente y solicita "Run vulnerability scan" — el orquestador dentro de CLAUDE.md / AGENTS.md impulsa las cuatro fases desde ahí.
4. Mantener una instalación manual actualizada
cd "$SAST_SRC" && git pull
# Vuelve a ejecutar los comandos cp del Paso 2a / 2b para actualizar — son idempotentes.
Si mantienes el clon, cd "$SAST_SRC" && git pull && <vuelve a ejecutar cp> es el equivalente manual de npx sast-skills update.
Comandos CLI
| Comando | Qué hace |
|---|---|
npx sast-skills install | Copia CLAUDE.md / AGENTS.md y el árbol de habilidades en tu proyecto o $HOME |
npx sast-skills update | Actualiza una instalación existente con los archivos de habilidades actualmente empaquetados |
npx sast-skills uninstall | Elimina las habilidades instaladas; se niega a eliminar un CLAUDE.md modificado sin --force |
npx sast-skills doctor | Verifica una instalación e informa OK / MISSING / MODIFIED por archivo; sale con código distinto de cero en caso de problemas |
npx sast-skills export --input sast/ --format sarif --output report.sarif | Agrega sast/*-results.json a JSON, SARIF 2.1.0 o HTML |
npx sast-skills export --input sast/ --triaged --format sarif | Prefiere el sast/triaged.json triado sobre los resultados brutos por habilidad |
npx sast-skills --version | Imprime la versión del CLI instalado |
Banderas de instalación
| Bandea | Propósito |
|---|---|
--yes | No interactivo; requerido cuando stdin no es una TTY |
--assistant <claude|agents|all> | Qué árbol de habilidades instalar |
--scope <project|global> | Instalar en ./.claude/skills/ o $HOME/.claude/skills/ |
--target <ruta> | Destino de instalación explícito (anula --scope) |
--force | Sobrescribir un CLAUDE.md / AGENTS.md preexistente |
--dry-run | Imprime el plan de archivos sin escribir |
Ejecutar un escaneo
Después de instalar, abre el proyecto en tu asistente de IA y pregunta:
Run vulnerability scan
o
Find vulnerabilities in this codebase
El orquestador toma el control. Ejecuta las cuatro fases automáticamente, respeta la idempotencia (las reejecuciones solo toman lo que falta) y escribe todo en sast/ en la raíz de tu proyecto.
Archivos de salida
| Archivo | Descripción |
|---|---|
sast/architecture.md | Pila tecnológica, arquitectura, puntos de entrada, flujos de datos |
sast/*-results.md | Hallazgos por clase de vulnerabilidad (legible por humanos) |
sast/*-results.json | Hallazgos canónicos legibles por máquina (alimenta a sast-skills export) |
sast/final-report.md | Informe bruto consolidado clasificado por severidad |
sast/final-report-triaged.md | Informe triado: falsos positivos eliminados, severidades ajustadas con evidencia |
sast/triaged.json | Hallazgos triados canónicos (preferido por sast-skills export --triaged) |
Esquema de hallazgos
Cada habilidad escribe sast/<skill>-results.json como una lista de hallazgos simple:
{
"findings": [
{
"id": "sast-sqli-0001",
"skill": "sast-sqli",
"severity": "critical|high|medium|low|info",
"title": "Inyección SQL en /api/user",
"description": "…",
"location": { "file": "src/api/user.js", "line": 42, "column": 10 },
"remediation": "…"
}
]
}
sast-skills export agrega esos archivos en un documento envuelto en un sobre run — { "run": { "tool": "sast-skills", "version": "<cli-version>" }, "findings": [...] } — sellando la versión del CLI que produjo el informe. El paso de triaje escribe sast/triaged.json en esa misma forma envuelta.
Los hallazgos triados agregan triage_status (confirmed|upgraded|downgraded|false_positive), triage_original_severity (cuando la severidad cambió) y triage_evidence con citas concretas del código.
Integraciones CI
GitHub Code Scanning (SARIF)
Acción compuesta en .github/actions/scan/action.yml:
- uses: mstfknn/sast-skills/.github/actions/scan@main
with:
input: sast/
output: sast-skills.sarif
Esto ejecuta sast-skills export --format sarif y sube el resultado a Code Scanning mediante github/codeql-action/upload-sarif@v3.
Hook de pre-commit
Copia hooks/pre-commit en .git/hooks/pre-commit para que sast-skills doctor proteja cada commit.
Docker
docker build -t sast-skills .
docker run --rm -v "$PWD:/work" sast-skills export --input sast/ --format sarif --output report.sarif
El Dockerfile empaquetado está basado en node:20-alpine con sast-skills configurado como punto de entrada.
Verificar y solucionar problemas
# ¿La instalación tiene la forma esperada?
npx sast-skills doctor --target . --assistant claude
# Verificación de versión
npx sast-skills --version
npm view sast-skills version # última versión en el registro
# Actualización
npx sast-skills update
doctor sale con 0 si cada archivo empaquetado en el destino coincide con la copia de la versión instalada, y con 1 si algún archivo está MISSING o MODIFIED. MODIFIED significa que el archivo divergió de la copia empaquetada — algo esperado si editas el archivo de entrada, de lo contrario, una señal para ejecutar update.
Contribuciones
Consulta CONTRIBUTING.md. Bucle de desarrollo:
npm install
npm test # conjunto vitest (protección TDD habilitada)
npm run sync # reflejar .claude/skills → .agents/skills
node scripts/scaffold-skill.js sast-foo # crear una nueva habilidad en ambos árboles
node scripts/register-skill.js sast-foo foo "Foo" "Descripción de inyección Foo"
npm run lint:md # markdownlint
…
[truncado para la traducción]