AGENT SKILL

kdd-security-scan

Guia a cualquier agente (no depende de Codex ni de un modelo puntual) para producir un scan de seguridad de un repositorio en el formato de contrato de Capa 3 de KDD -- scan-manifest.json, findings.json, coverage.json -- que despues sella scripts/vendor/codex-security/finalize_scan_contract.py y gatea scripts/validate_security_findings.py. Usala cuando se pida auditar/escanear un repo por vulnerabilidades bajo gobernanza KDD, o se mencione "security scan", "Capa 3", "findings.json" o "hallazgo de seguridad" en el contexto de este template.

License 许可
MIT
最近更新
2026-09-01
Stars
★ 4
Forks
0

01 前言 Front Matter

name
kdd-security-scan
description
Guia a cualquier agente (no depende de Codex ni de un modelo puntual) para producir un scan de seguridad de un repositorio en el formato de contrato de Capa 3 de KDD -- scan-manifest.json, findings.json, coverage.json -- que despues sella scripts/vendor/codex-security/finalize_scan_contract.py y gatea scripts/validate_security_findings.py. Usala cuando se pida auditar/escanear un repo por vulnerabilidades bajo gobernanza KDD, o se mencione "security scan", "Capa 3", "findings.json" o "hallazgo de seguridad" en el contexto de este template.

03 SKILL.md 正文

Security Scan (Capa 3 de KDD)

Produce hallazgos de seguridad de un repositorio en el formato de contrato que audita la Capa 3 de KDD. Esta skill NO es el gate -- es la parte creativa/no determinista (la hace un LLM, con o sin subagentes) que el gate despues valida. Distincion central: el agente decide QUE es un hallazgo; el gate solo audita que el artefacto sellado cumpla forma y politica. Ningun LLM participa en el gate.

Adaptada del flujo de las skills de openai/codex-security (_bundled_plugin/skills/security-scan/, Apache-2.0), quitando toda dependencia del binario codex y de sus tools MCP especificas de la app de escritorio. Esta version corre con Bash + lectura de archivos nada mas -- cualquier agente sirve.

Cuando usarla

El usuario pide auditar un repo (propio o externo) por vulnerabilidades y quiere el resultado gobernado por KDD (versionable, gateado en CI, con politica declarativa), no un reporte suelto en prosa.

Insumos que necesitas antes de empezar

  • repo_root: raiz del repositorio a escanear (puede ser un clon separado del propio KDD -- ver la nota de portabilidad en scripts/vendor/codex-security/README.md, el finalizer no asume que el target viva dentro del repo KDD).
  • scan_dir: donde vas a escribir los 3 JSON. Por defecto security/scan dentro del repo KDD (coincide con el default de validate_security_findings.py); si estas gobernando un repo EXTERNO, cualquier directorio disponible sirve, con tal de que se lo pases explicito a finalize_scan_contract.py --scan-dir.
  • Los 3 schemas viven en knowledge/data_models/security/ (vendorizados del mismo origen, no los reinventes ni los edites).

Flujo

1. Alcance

Antes de tocar codigo, fija por escrito (2-3 lineas, no hace falta un documento aparte): que directorio/paquete se revisa, que queda explicitamente fuera, y contra que amenaza (codigo de terceros ejecutado localmente, superficie de red expuesta, manejo de secretos, etc.). Esto se vuelca en scan.scope.summary del manifest.

2. Descubrimiento

Recorre el repo_root en el alcance fijado. Por cada archivo relevante, evalua las clases de riesgo que apliquen al lenguaje (inyeccion de comandos/SQL, path traversal, deserializacion insegura, secretos hardcodeados, control de acceso, TOCTOU, etc.). No inventes un hallazgo para llenar un cupo: un scan con cero findings y coverage complete es un resultado valido y se sella igual.

Para cada candidato real, junta ANTES de escribir el JSON:

  • la ubicacion exacta (archivo:linea-linea) del sink y, si aplica, del source:
  • por que es explotable (flujo de datos concreto, no "podria ser inseguro");
  • severidad y confianza honestas -- una confianza high en un finding critical es una afirmacion fuerte; si tenes dudas reales, la confianza va en medium/low (ver la regla de politica mas abajo, que exige high para todo critical).
  • al menos un CWE de la taxonomia estandar.
  • una remediacion CONCRETA y accionable (no "revisar el codigo" -- eso no pasa el gate de politica, que exige remediaciones sustantivas).

3. Escribir los 3 artefactos (DRAFT, sin sellar)

En <scan_dir>/, escribi:

  • scan-manifest.json: documentType, schemaVersion: "1.0", y scan con id, producer (identificate como el agente real que hizo el analisis, NUNCA como "codex" -- ver la nota de honestidad abajo), status: "completed", timestamps, target (kind/targetId/displayName + revision si es git_revision), scope, coverageRef: "coverage.json", findingsRef: "findings.json". Dejalo SIN sealedAt ni scan.artifacts -- eso lo llena el finalizer.
  • findings.json: documentType, schemaVersion, scanId (igual a scan.id del manifest), y findings[] con findingId/occurrenceId en "draft" (el finalizer los deriva) y el resto de los campos completos: ruleId, identity, title, summary, severity, confidence, taxonomy, locations, remediation, provenance.source.
  • coverage.json: documentType, schemaVersion, scanId, mode, completeness, inventoryStrategy, includePaths, excludePaths, surfaces[] (una entrada por superficie revisada con disposition real), explicitExclusions, deferred.

Los 3 schemas completos estan en knowledge/data_models/security/*.schema.json -- consultalos si dudas de un campo, no adivines la forma.

4. Sellar

python scripts/vendor/codex-security/finalize_scan_contract.py \
  --scan-dir <scan_dir_absoluto_canonico> \
  --schema-dir knowledge/data_models/security \
  --source-root <repo_root_absoluto_canonico>

--scan-dir y --source-root tienen que ser rutas ABSOLUTAS y canonicas (sin .., sin symlinks). El finalizer compara path.absolute() contra path.resolve(strict=True) y rechaza cualquier discrepancia (_require_scan_directory) -- una ruta relativa con .. (p.ej. ../mi-scan) falla con error: scan directory: expected a canonical non-symlink directory (exit 2), aunque el directorio exista y sea perfectamente valido. Resolve la ruta antes de llamarlo (realpath en shells POSIX/Git-Bash, Resolve-Path en PowerShell) en vez de pasarla relativa.

Si falla por JSON Schema invalido, el error dice exactamente que campo -- corregi el draft y reintenta. NO edites el finalizer para que pase; el error es del draft.

5. Gatear

python scripts/validate_security_findings.py <scan_dir>

FAIL con violaciones reales (CWE faltante, remediacion tipo placeholder, critical con confianza no-high) significa que el HALLAZGO esta mal capturado, no que el gate este mal -- volve al paso 2 para ese finding especifico, no debilites la regla en examples/rules/security-findings.rules.json para que pase.

6. Reportar

<scan_dir>/report.md y <scan_dir>/exports/results.sarif ya estan generados por el finalizer -- no los escribas a mano. Devolve al usuario la ruta de report.md y el resumen de severidades.

Honestidad sobre la procedencia (producer / provenance.source)

Nunca declares producer.name como si fuera Codex o cualquier otro agente que no corrio el analisis. Identificate como lo que sos (p.ej. "claude-sonnet-5 (KDD kdd-security-scan skill)", "glm-5.2 via pm-glm-ccdd"). El campo existe justamente para que quien lea el sello sepa que motor de razonamiento genero el hallazgo -- un dato de confianza real, no un detalle cosmetico.

Que NO hace esta skill

  • No reemplaza una auditoria humana para hallazgos critical de alto impacto real -- produce el artefacto gobernable, la decision de remediar/aceptar el riesgo sigue siendo humana (por eso el estado de triage vive fuera del artefacto sellado, ver el code_only de security-findings.rules.json).
  • No escanea binarios ni dependencias de terceros (supply-chain) -- eso es un dominio de politica distinto, no cubierto por security-findings.rules.json tal como esta.

04 同仓库更多 Skills

MauricioPerera
MauricioPerera/mcpwasm

pm-sonnet-opus-haiku

Convierte a Claude Code en un equipo de desarrollo por capas con roles fijos por modelo. PM = Sonnet 5 (sesion principal): planifica, descompone, redacta specs, autora contrato + tests congelados, delega, verifica e integra; no escribe codigo de produccion. Implementador = subagent Opus 4.8 por tarea, en worktree si hay paralelo, implementa contra los tests sin editarlos. QA por defecto = subagent Haiku 4.5 read-only, revisa el diff vs spec + confirma tests congelados, veredicto APROBADO/RECHAZADO; si el repo tiene gate CCDD/KDD determinista (KDD Nivel 1 sin MCP, o el MCP ccdd-complexity, o ambos), el PM puede usarlo en vez de o junto a Haiku, sin GLM ni Ollama. Verificador adversarial opcional = 2-3 subagents Haiku en paralelo, independientes entre si, buscan/refutan bugs y hallazgos de seguridad; sobrevive solo por mayoria. Usala para ejecutar un proyecto/feature/fix con este equipo, o si mencionan equipo sonnet/opus/haiku, gate CCDD, verificacion adversarial. No depende de Ollama ni cuentas externas.

★ 4
MauricioPerera
MauricioPerera/mcpwasm

pm-native-ccdd

Variante NATIVA del PM/orquestador CCDD que usa sub-agentes de la app de Claude (tool Agent con model override) en vez de GLM/Ollama externo. Claude autora contrato + tests congelados (oráculo), delega la IMPLEMENTACIÓN a un sub-agente barato (Haiku 4.5), y verifica por el gate CCDD determinista. Úsala cuando quieras el flujo PM+CCDD sin la fragilidad de ollama, con aislamiento por worktree para paralelismo y reintentos con contexto vía SendMessage. Hermana de pm-glm-ccdd (misma metodología; cambia SOLO el mecanismo de delegación). Deslinde con pm-sonnet-opus-haiku: mismo gate CCDD/KDD como verificador si el repo lo trae, pero tiering de implementador distinto — esta usa Haiku barato con escalado a Sonnet; pm-sonnet-opus-haiku usa Opus fijo (más caro) más QA/verificación adversarial opcional en capas. Elegí ESTA para el flujo 100% CCDD con implementador barato; usá pm-sonnet-opus-haiku si preferís implementador Opus + QA por capas.

★ 4
MauricioPerera
MauricioPerera/mcpwasm

pm-glm-ccdd

Pone a Claude como PM/orquestador de un proyecto donde los desarrolladores son instancias EFÍMERAS de glm-5.2:cloud que implementan usando el CCDD gate. Úsala cuando el usuario quiera ejecutar un proyecto, feature, refactor o conjunto de tareas delegando TODA la implementación a GLM — Claude planifica, descompone en tareas, reparte a devs GLM (en paralelo si conviene), verifica por el veredicto del gate e integra. Claude NO escribe código de producción; dirige.

★ 4
MauricioPerera
MauricioPerera/mcpwasm

pkb-agent-first

暂无简介

★ 4
MauricioPerera
MauricioPerera/mcpwasm

delegar-pool

Cómo lanzar y verificar un dev efímero vía `pool exec` (poolside.ai) en modo headless, agnóstico a la tarea. Cubre el flag no documentado `--unsafe-auto-allow` (obligatorio en no-interactivo), formato de log NLJSON, dónde viven los logs/trayectorias reales para auditar, el riesgo real (bloques de razonamiento largos antes de fallar, no un cuelgue de aprobación) y la doctrina de verificación independiente. Úsala como capa base de mecánica de delegación, análoga a `delegar-ollama` pero para `pool` en vez de Ollama/GLM.

★ 4
MauricioPerera
MauricioPerera/mcpwasm

delegar-pool-ccdd

Delega la IMPLEMENTACIÓN de UNA función/tarea puntual a un dev efímero vía `pool exec` (poolside.ai), verificada por el CCDD gate. Úsala cuando el usuario pida implementar/arreglar/extender algo puntual y quiera que lo haga `pool` — "delega a pool" / "usa el ccdd gate con pool". Para proyectos con VARIAS tareas y devs en paralelo, adaptá `pm-glm-ccdd` con `pool` como mecanismo en vez de esta (esta es la capa de UNA tarea suelta).

★ 4