vuln-hunter — Kit multi-agente de seguridad para Claude Code

El pipeline

Una cadena, un solo comando

Cada agente lee y enriquece el mismo ledger (.vuln-hunter/ledger.json). No se pasan prosa: hablan JSON. Lanza todo con /vuln-hunter:hunt o ejecuta cada etapa por separado.

Recon

reconsuperficie Mapea la superficie de ataque (entradas, sinks, trust boundaries) y modela amenazas. No busca vulnerabilidades concretas.

Análisis∥ paralelo

scanSAST código SAST de tu propio código (Semgrep, Bandit, ESLint-security, Roslyn) con taint/data-flow. No escanea dependencias.

watchSCA deps SCA de dependencias de producción: cruza con OSV/NVD/CISA KEV/EPSS. Único dueño del SCA; solo lee fuentes oficiales.

Ofensiva

red-teamPoC concept. Confirma explotabilidad como atacante. Solo PoCs conceptuales; nada de malware ni exploits desplegables.

Decisión

triageCVSS+EPSS Prioriza con CVSS + EPSS + CISA KEV, deduplica y filtra falsos positivos. KEV es override de prioridad.

planremediación Genera el plan de remediación priorizado (Inmediato / Esta semana / Este mes).

Remediación

fixcausa raíz Aplica el fix de causa raíz (ASVS) en una branch vuln-hunter/*. Nunca commitea sin aprobación humana.

patchaprob. hash Muestra el diff y exige aprobación humana por hash antes de commitear. Sin auto-merge.

verifysin regresión Re-escanea el código parcheado y corre los tests. Verificación honesta: declara PARCIAL si no hay cobertura.

Recon & análisis Ofensiva (PoC) Decisión Remediación

scan ∥ watch corren en paralelo · el resto es secuencial

El escuadrón

7 agentes, 7 profesionales reales

Cada subagente está modelado como un especialista de seguridad con su propia metodología. SAST y SCA no se solapan: uno mira tu código, el otro tus dependencias.

recon-cartographer

Cartógrafo de superficie

Mapea la superficie de ataque: entradas, sinks, confianza y rutas. Construye el contexto inicial del ledger.

PTESSTRIDEPASTAAttack trees

sast-analyst

Análisis estático · código propio

SAST sobre tu código (no dependencias). Taint/data-flow, normaliza a SARIF y mapea a OWASP.

SemgrepBanditRoslynSARIF

threat-intel-scout

CTI · dependencias

SCA: cruza tus deps de producción con fuentes oficiales. Único dueño del SCA y del gate anti-ransomware.

OSV/NVDCISA KEVEPSSATT&CK T1190

redteam-whitehat

Pentester ético (OSCP/OSWE)

Confirma explotabilidad con PoC conceptual. Prohibido malware/exploits — lo refuerzan hooks deterministas.

PTESWSTGPoC conceptual

triage-judge

Analista de triage

Prioriza lo confirmado. Filtra confianza <8 a revisión humana. KEV es override de prioridad.

CVSS v4.0/v3.1EPSSCISA KEV

appsec-fixer

Security architect / AppSec

Fix de causa raíz en branch vuln-hunter/*. Nunca commitea: espera aprobación humana del diff.

OWASP ASVS v5.0.0Cheat Sheets

verify-engineer

Verificación / detección

Re-escaneo + tests. Si no hay tests que cubran la ruta, declara verificación PARCIAL — no finge.

Re-escaneoTestsVerificación honesta

ledger.json

Estado compartido

El pegamento: todos los agentes leen, enriquecen su sub-objeto y reescriben. Unifica severidad, dedup y el informe final.

schema versionadosin prosa entre agentes

Observabilidad

Un panel vivo de la auditoría

Frontend estático (React por CDN con SRI, JSX pre-compilado y CSP estricta) que se sirve solo en 127.0.0.1 (loopback, no se expone a la red) y hace polling del ledger cada 2s. Mira qué agente trabaja y qué se va encontrando, en tiempo real.

Panel vivo de vuln-hunter: pipeline, bitacora y hallazgos — Panel completo: pipeline, bitácora viva y hallazgos por estado

Grafo de pipeline estilo GitHub Actions con fork paralelo SAST/INTEL — Grafo tipo GitHub Actions: el agente activo gira; SAST e INTEL en paralelo

Pipeline en vivo

Grafo con fork paralelo; el nodo activo gira. Hover sobre cada agente para ver qué hace.

Bitácora

Timeline estilo terminal de lo que se va encontrando, con severidad y KEV resaltados.

Hallazgos por estado

Pestañas Encontrados · Mitigando · Arreglados; cada hallazgo se mueve al arreglarse.

Comandos copiables

Copia el comando de Claude Code para atacar uno o varios hallazgos, ver estado o reanudar.

Levántalo con /vuln-hunter:panel y déjalo abierto mientras corre la auditoría.

La consola

15 comandos, flujo guiado

Cada comando termina recomendando el siguiente paso. /vuln-hunter:status muestra un dashboard determinista del ledger en cualquier momento.

/vuln-hunter:hunt

Orquesta el flujo completo: recon → scan ∥ watch → red-team → triage → plan → fix → patch → verify.

/vuln-hunter:detect

Detecta los stacks del monorepo y delimita el scope (scoping por paquete).

/vuln-hunter:scan

SAST del código propio. Delega en sast-analyst y normaliza a SARIF.

/vuln-hunter:watch --gate

Threat-intel de dependencias de producción (OSV/NVD/KEV/EPSS). Gate anti-ransomware.

/vuln-hunter:redteam

Confirma explotabilidad de un hallazgo (o de todos) con PoC conceptual.

/vuln-hunter:triage

Prioriza con CVSS + EPSS + KEV y produce el ledger final.

/vuln-hunter:plan

Plan de remediación. Usa superpowers si está instalado; si no, plan propio por prioridad.

/vuln-hunter:fix

Aplica fixes de causa raíz en branch vuln-hunter/*. No commitea.

/vuln-hunter:patch

Muestra diffs, pide aprobación humana por hash del diff y solo entonces commitea.

/vuln-hunter:verify

Verifica que los fixes cierran las vulnerabilidades sin regresión.

/vuln-hunter:report

Informe HTML reproducible desde el ledger, con mapeo OWASP y Action Plan.

/vuln-hunter:status

Dashboard determinista: progreso, hallazgos por severidad, alerta KEV y siguiente comando.

/vuln-hunter:panel

Levanta el panel administrativo vivo (React+CDN) que lee el ledger y se actualiza por polling.

/vuln-hunter:resume

Reanuda desde donde quedó el run anterior: migra el ledger (retrocompatible) y continúa sin repetir etapas.

/vuln-hunter:rescan

Re-escanea SAST un subárbol y fusiona con el ledger; marca como candidato-resuelto lo que ya no aparece.

Por qué importa

No es teatro de seguridad

Las salvaguardas son hooks deterministas como defensa en profundidad (evadibles, no garantías; la barrera primaria es la revisión humana). La explotabilidad se confirma. Nada se cierra sin evidencia.

Prevención de ransomware

Un CVE en CISA KEV o con EPSS alto en producción hace que deploy-gate.py derive el archivo deploy-blocked del ledger (determinista) y el hook detiene los deploys que pasen por Claude. Señala el Initial Access (ATT&CK T1190).

Ledger compartido

Estado único en .vuln-hunter/ledger.json con schema versionado. Severidad, dedup e informe unificados — cero prosa entre agentes.

Aprobación humana por hash

El patcher commitea solo tras aprobar el índice staged exacto — lo que de verdad se commitea (git diff --cached, vía approve-diff.py). Si re-stageas, la aprobación caduca. Nunca hay auto-merge.

Barrera del red-team

Solo PoCs conceptuales. El allowlist tools: (sin herramientas de escritura ni red) es la barrera principal; disallowedTools + block-exploit-write.py son defensa en profundidad.

Triage que prioriza de verdad

CVSS v4.0/v3.1 + EPSS + KEV. Filtra confianza <8 a revisión humana documentada. KEV es override.

Multi-stack & monorepo

Detecta Python/Django, Next.js/React/TS, Angular y .NET/C#. Scoping por paquete con las herramientas SAST/SCA correctas.

Marco de uso: defensivo y autorizado

Todo el análisis es sobre el código del propio usuario, en auditoría autorizada, con fin de remediar. No se atacan terceros ni se sale del scope del repo. El threat-intel solo lee fuentes oficiales (forzado por el hook guard-webfetch.py).

Empieza en 60 segundos

Instalación & primer escaneo

Dentro de Claude Code, añade el marketplace e instala el plugin. Luego detecta tus stacks y lanza la cacería.

Añade el marketplace e instala

Pega estos comandos en la consola de Claude Code.

/plugin marketplace add JoseAFlores777/vuln-hunter
/plugin install vuln-hunter@vuln-hunter-marketplace

Detecta stacks y lanza la cacería

detect hace el scoping; hunt corre el flujo completo.

/vuln-hunter:detect
/vuln-hunter:hunt
# dashboard en cualquier momento
/vuln-hunter:status

Aprueba el patch (gesto humano)

El fixer no commitea solo. Revisa el diff y aprueba ESE hash.

git add <archivos>                 # stagea lo revisado
git diff --cached HEAD              # revisa el indice staged
python3 scripts/approve-diff.py     # aprueba ESE indice (por hash)

⚠ Si editas más, la aprobación caduca: re-aprueba.

Opcional: superpowers (mejor planning)

Dependencia opcional que mejora la etapa de plan. Instálala solo desde fuentes verificadas.

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Mídelo antes de confiar en él

vuln-hunter incluye un laboratorio con 9 vulnerabilidades plantadas y su ground truth. Corre el flujo en --dry-run y cuenta verdaderos positivos, falsos negativos y falsos positivos. Ese número te dice si el plugin sirve.

/vuln-hunter:detect examples/vulnerable-lab
/vuln-hunter:hunt examples/vulnerable-lab --dry-run

9 vulns conocidas con ground truth verificable
1 control negativo que no debe marcarse
Cuenta TP / FN / FP para medir la tasa de acierto
Sin tocar nada real: corre en --dry-run

Para qué sirve — y qué no reemplaza

vuln-hunter te ayuda a identificar, priorizar y mitigar vulnerabilidades temprano (shift-left): un primer pase disciplinado, reproducible y con trazabilidad. Eso sí, no sustituye una auditoría humana independiente, un pentest profesional ni herramientas SAST/DAST dedicadas — y los hooks son defensa en profundidad, no garantías absolutas. Úsalo como complemento que acelera y enfoca el trabajo, y combínalo siempre con medidas más estrictas antes de confiar en producción.