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 enscripts/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 defectosecurity/scandentro del repo KDD (coincide con el default devalidate_security_findings.py); si estas gobernando un repo EXTERNO, cualquier directorio disponible sirve, con tal de que se lo pases explicito afinalize_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
highen un findingcriticales una afirmacion fuerte; si tenes dudas reales, la confianza va enmedium/low(ver la regla de politica mas abajo, que exigehighpara todocritical). - 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", yscanconid,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 +revisionsi es git_revision),scope,coverageRef: "coverage.json",findingsRef: "findings.json". Dejalo SINsealedAtniscan.artifacts-- eso lo llena el finalizer.findings.json:documentType,schemaVersion,scanId(igual ascan.iddel manifest), yfindings[]confindingId/occurrenceIden"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 condispositionreal),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
criticalde 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 elcode_onlydesecurity-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.jsontal como esta.
04 同仓库更多 Skills
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.
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.
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.
pkb-agent-first
暂无简介
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.
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).