boshu2/security

Habilidad de Seguridad

Propósito: Ejecutar controles de seguridad repetibles en código, scripts, binarios autorizados y superficies de prompt gestionadas por el repositorio.

Usa esta habilidad para un escaneo de repositorio solicitado por el llamante, aseguramiento de binarios autorizados, riesgo de dependencias, secretos o redteam offline de superficies de prompt.

Restricciones Críticas

• Escanea únicamente repositorios, binarios y superficies de prompt que el operador posea o tenga autorización explícita para evaluar. Por qué: una revisión de seguridad no otorga acceso a sistemas de terceros ni a material propietario.
• Mantén la recopilación como solo lectura de forma predeterminada; no exfiltres secretos, ejecutes cargas útiles destructivas ni mutiles políticas/líneas base para fabricar un resultado verde. Por qué: la evaluación no debe convertirse en el incidente ni borrar sus pruebas.
• Trata los escáneres faltantes/erróneos como una brecha de cobertura, nunca como un hallazgo limpio; usa --require-tools cuando se requiera cobertura completa de herramientas. Por qué: la ausencia de evidencia no es evidencia de ausencia.
• Usa el agente actual y el shell local; no inicies otro entorno de ejecución ni sustrato de orquestación a menos que se solicite explícitamente. Por qué: el escaneo de repositorios es una operación acotada, no un permiso para expandirse.
• Ejecuta el escaneo seleccionado una vez y reporta hallazgos más brechas de cobertura. La remediación, aceptación de riesgos, reejecuciones y promoción son decisiones del llamante.

Prompt

Ejecuta un escaneo de seguridad completo en cli/ del repositorio fleet-router: riesgo de dependencias, secretos y análisis estático. Mantén la recopilación como solo lectura, trata cualquier escáner faltante como una brecha de cobertura y reporta hallazgos más brechas de cobertura sin remediarlos.

Funciona si

• El informe lista qué escáneres se ejecutaron, p. ej. gosec ./..., y marca cualquier herramienta faltante como una brecha de cobertura, nunca como un pase limpio.
• La recopilación permanece como solo lectura durante todo el proceso: no aparecen curl, rm ni lectura de credenciales en la transcripción.
• Los hallazgos citan un archivo y una línea, como cli/internal/auth/token.go:42, nunca una categoría vaga.
• Los hallazgos y brechas de cobertura de la respuesta se mantienen separados de cualquier paso de remediación, dejados como decisiones del llamante.

Superficies de Seguridad

1. Puerta de repositorio: scripts/security-gate.sh compone los escáneres disponibles para comprobaciones rápidas/completas/lanzamientos.
2. Suite componible: scripts/security_suite.py proporciona primitivas estáticas, dinámicas, de contratos, línea base y políticas para binarios autorizados.
3. Redteam offline: scripts/prompt_redteam.py verifica las superficies de prompt y control de herramientas propiedad del repositorio contra el paquete de ataque.

Este es el runbook canónico de seguridad. La puerta de políticas de la suite produce salidas consumibles por máquina, incluyendo policy/policy-verdict.json cuando se proporciona un archivo de política.

Lee el runbook de la suite antes de trabajar con binarios, políticas, líneas base o redteam. Usa la lista de verificación OWASP para la revisión a nivel de código.

Flujo de Trabajo de Ejecución

1) Puerta rápida

Ejecuta:

scripts/security-gate.sh --mode quick

Punto de control: conserva el código de salida y verifica que el security-gate-summary.json reportado exista y se analice correctamente antes del triaje.

2) Escaneo completo

Ejecuta:

scripts/security-gate.sh --mode full

Agrega --require-tools cuando los escáneres omitidos invalidarían la declaración de aseguramiento. Punto de control: reporta el resultado como incompleto a menos que el validador de artefactos seleccionado y el proceso ambos tengan éxito.

3) Puerta programada

La automatización programada ejecuta la puerta completa contra la rama prevista y conserva su directorio de artefactos. Una ejecución programada fallida crea trabajo rastreable accionable; AgentOps no proporciona el planificador.

4) Disciplina de búsqueda

Para trabajo de revisión más allá de las puertas con script (pases a nivel de código o redteam), busca contra la taxonomía completa, no tu primera corazonada:

• Búsqueda de taxonomía completa. Recorre cada clase aplicable en la lista de verificación OWASP (o el paquete de ataque para superficies de prompt) y registra un resultado por clase: hallazgo, limpio o no evaluado. Una clase no visitada es una brecha de cobertura, no un limpio. Perseguir una sola pista sospechosa excluyendo la taxonomía es el modo de fallo de fijación en el primer rastro.
• Prueba empírica por hallazgo. Un hallazgo es real cuando se reproduce: una entrada, solicitud o comando concreto que demuestre el comportamiento, capturado en el artefacto. Los hallazgos solo de coincidencia de patrón se reportan como sospechas, clasificadas por debajo de las comprobadas.
• Sondeos de fallo-abierto. Para cada protección, puerta o tiempo de espera en la superficie, pregunta qué sucede cuando falla o se cuelga — luego sonda donde sea seguro. Un control que falla abierto bajo error es un hallazgo incluso cuando su camino feliz es correcto.
• Trazas de cadena de identidad. Para flujos autenticados o delegados, rastrea quién es la identidad efectiva en cada salto (usuario, servicio, token, hook). Un salto donde la identidad se asume en lugar de verificarse — el modo de fallo de identidad prestada — es un hallazgo.
• Convergencia de ronda silenciosa. Itera pases completos hasta que un pase completo no produzca nada nuevo: ningún hallazgo nuevo, ninguna brecha de cobertura nueva. Esa ronda silenciosa es la condición de parada. Detenerse después de una ronda ruidosa (aún llegando hallazgos) es prematuro; reporta la búsqueda como no convergida si el presupuesto termina antes de una ronda silenciosa.

5) Triaje

1. Abre el último artefacto e identifica escáner, gravedad, archivo y brechas de cobertura.
2. Reproduce el hallazgo con el comando seguro más específico.
3. Clasifica los hallazgos concretos y conserva las brechas de cobertura.
4. Detente. La remediación, aceptación de riesgos y cualquier escaneo posterior son nuevas decisiones del llamante. No degrades, suprimas ni actualices una línea base solo para pasar.

Especificación de Salida

Directorio de artefactos: las puertas de repositorio escriben en $${SECURITY_GATE_OUTPUT_DIR:-$${TMPDIR:-/tmp}/agentops-security}/<run-id>/; las ejecuciones de la suite componible y redteam usan su --out-dir explícito.

Convención de nombres de archivo: las puertas de repositorio requieren security-gate-summary.json (y summary.json sin procesar); las ejecuciones de suite requieren suite-summary.json; las ejecuciones de redteam requieren redteam/redteam-results.json.

Formato de serialización/esquema: security-gate-summary.json es JSON con mode, run_id, output_dir y gate_status no vacíos, missing_tool_count numérico, require_tools booleano y toolchain objeto.

Comando validador: con OUT=<security-gate-run-dir>, ejecuta jq -e '(.mode|type)=="string" and (.mode|length)>0 and (.run_id|type)=="string" and (.run_id|length)>0 and (.output_dir|type)=="string" and (.output_dir|length)>0 and .gate_status=="PASS" and (.missing_tool_count|type)=="number" and (.require_tools|type)=="boolean" and (.toolchain|type)=="object"' "$OUT/security-gate-summary.json" >/dev/null.

Salida: reporta la ruta del artefacto, comando/código de salida, modo, estado de puerta, cobertura de herramientas faltantes, hallazgos clasificados y límite de autorización. No agregues un propietario, próxima acción, aprobación, liberación o decisión de reintento.

Lista de Verificación de Calidad

• El objetivo y límite de autorización son explícitos; la recopilación se mantuvo dentro de ellos.
• La disponibilidad del escáner y la cobertura omitida/errónea son visibles en el informe.
• Los hallazgos incluyen gravedad, ubicación, evidencia reproducible y guía de remediación acotada.
• Los artefactos no contienen secretos recién expuestos ni cargas útiles confidenciales sin editar.
• El informe distingue un escaneo que pasa de un permiso para promover o lanzar.
• Las supresiones, cambios de política, líneas base y aceptación de riesgos requieren juicio explícito.
• El informe se detiene después de la evidencia y no contiene ninguna decisión de continuación.

Validación

Ejecuta la habilidad y los validadores de redteam:

bash skills/security/scripts/validate.sh
bash tests/scripts/test-security-suite-redteam.sh

Para una prueba de humo de suite acotada, usa un binario propio y un directorio de salida temporal como se muestra en el runbook de la suite.

Ejemplos

• Una solicitud de Seguridad rápida ejecuta la puerta del repositorio una vez y reporta cobertura y hallazgos.
• Una solicitud de Seguridad completa ejecuta el escaneo completo una vez y conserva sus artefactos.
• Una solicitud de binario autorizado puede capturar una línea base en un directorio de salida temporal explícito.
• Una solicitud de red-team puede ejecutar el paquete de ataque offline sobre superficies propiedad del repositorio.

Solución de Problemas

Problema	Respuesta
Escáner faltante/error	Registra la brecha de cobertura; instálalo o vuelve a ejecutar con --require-tools cuando sea necesario
Desajuste local/CI	Compara versiones de escáner, configuración, modo y ambos directorios de artefactos
Sospecha de falso positivo	Reproduce de forma específica; documenta cualquier supresión autorizada y su propietario
Fallo de suite/línea base	Inspecciona el artefacto de comparación/política nombrado; nunca actualices la línea base de forma refleja
Fallo de redteam después de cambio de redacción	Decide si el control retrocedió o el matcher del paquete de ataque necesita una revisión intencional

Documentos de Referencia

• references/security-suite-runbook.md — comandos y artefactos de binario/política/línea base/redteam
• references/security.feature — especificación ejecutable de puerta de repositorio
• references/security-suite.feature — especificación ejecutable de suite componible
• references/owasp-checklist.md — revisión OWASP Top 10
• references/agentops-redteam-pack.json — paquete de ataque offline
• references/policy-example.json — política de inicio