vitwit/deploy-security-gate

Puerta de seguridad de despliegue

Esta habilidad impone una única lista de verificación: ninguna clave queda expuesta, y ningún fallo único deja el producto fuera de servicio. Se ejecuta en tres fases:

1. Un escaneo automatizado con scripts/scan.py, que es rápido, determinista y de solo lectura.
2. Una revisión de código de cada integración detectada, guiada por references/integrations.md.
3. Una puerta manual para todo lo que no se puede ver desde el repositorio, como paneles de proveedores, rotación, copias de seguridad y simulacros. Estos elementos provienen de references/checklist.md.

El escaneo por sí solo no es suficiente. Cubre aproximadamente un tercio de la lista de verificación. El valor de esta habilidad está en recorrer las tres fases y ser honesto acerca de lo que se verificó y lo que aún necesita confirmación humana.

Flujo de trabajo

1. Alcance

Determine qué se está enviando:

• la raíz del repositorio
• el resultado de compilación frontend o móvil, si lo hay
• el objetivo de despliegue, como contenedores, serverless o Kubernetes
• si se trata de un primer lanzamiento, una nueva integración o mantenimiento rutinario

Si el usuario mencionó un cambio específico, como "añadir Stripe", centre la revisión en él. Aun así, ejecute el escaneo completo, porque una fuga en otro lugar bloquea el lanzamiento de igual manera.

2. Ejecutar el escáner

python3 <directorio-habilidad>/scripts/scan.py <repositorio> --history

• Añada --build-dir <directorio> por cada paquete compilado (dist, .next/static, un APK/IPA descomprimido). Los paquetes enviados son donde las claves "públicas" resultan ser secretas. Los directorios de compilación comunes se detectan automáticamente; compile la aplicación primero si no existen.
• --entropy añade una fase de alta entropía que captura secretos personalizados que ningún patrón nombrado conoce (gravedad baja; verifique cada uno antes de informar).
• --format json o --format sarif proporcionan salida legible por máquina; SARIF se puede subir a GitHub code scanning. --fail-on high|medium|low|never controla el código de salida, lo cual es útil en CI.
• Los falsos positivos confirmados pueden suprimirse con un comentario en línea # security-gate: allow o un archivo .security-gate-ignore en la raíz del repositorio (consulte el README). Prefiera suprimir hallazgos específicos antes que bajar --fail-on.
• El escáner enmascara los valores secretos. Manténgalo así en todo lo que escriba: nunca repita una clave completa en el chat, archivos, commits o texto de PR, porque eso crea una segunda fuga.

El escáner verifica:

• patrones secretos (AWS, Anthropic, OpenAI, OpenRouter, Groq, xAI, Perplexity, Replicate, fal, claves API de Google y secretos OAuth, claves en vivo de Stripe y secretos de webhook, Razorpay, GitHub, GitLab, tokens de Slack y tokens de aplicación, cuentas de servicio de GCP, npm, PyPI, SendGrid, Hugging Face, DigitalOcean, New Relic, Shopify, Square, Databricks, Doppler, PlanetScale, Linear, claves de Azure Storage, Mailgun, Telegram, webhooks de Discord, JWTs, claves privadas, URLs de base de datos con contraseñas, asignaciones de *_SECRET / *_TOKEN / *_SERVICE_ROLE codificadas — entre comillas (incluyendo configuraciones JSON/MCP) o sin comillas) en el árbol de trabajo, la salida de compilación y el historial de git
• con --entropy, cadenas de alta entropía que no coinciden con ningún formato conocido (secretos personalizados o novedosos)
• archivos .env commiteados y una entrada faltante en .gitignore
• variables con aspecto secreto detrás de prefijos expuestos al cliente (NEXT_PUBLIC_, VITE_, REACT_APP_, EXPO_PUBLIC_ y similares), y llamadas directas a LLM desde código de cliente
• mapas de origen en la salida de compilación
• flujos de trabajo de GitHub Actions: acciones ancladas a etiquetas, pull_request_target, un bloque permissions: faltante, secretos impresos en eco, secretos escritos en archivos o en $GITHUB_ENV / $GITHUB_OUTPUT, claves estáticas de nube en lugar de OIDC, e instalaciones que ejecutan scripts de ciclo de vida
• Dockerfiles: secretos en ARG/ENV, archivos .env copiados, y ejecución como root
• manejadores de webhook de pago sin verificación de firma
• acceso de agentes de codificación a archivos .env
• las integraciones en uso, más indicios de proveedor único (punto único de fallo) para IA y pagos

3. Clasificar los hallazgos

El escáner funciona por coincidencia de patrones, así que confirme cada hallazgo leyendo el código antes de informarlo.

• Secreto activo encontrado (en el árbol, el historial o un paquete): trátelo como filtrado incluso si el repositorio es privado. Siga references/leaked-key-runbook.md, donde la revocación es lo primero y la limpieza viene después. Revocar o rotar una clave cambia la producción, así que dígale al usuario exactamente qué clave, dónde se encontró y el paso de revocación. Permítale hacerlo, o confirme antes de hacer algo usted mismo.
• Falso positivo (un fixture de prueba, una clave pública documentada): explique por qué es seguro y continúe.
• Hallazgos heurísticos (verificación de webhook, llamada a LLM desde el cliente): abra el archivo y verifique el flujo de control real. La verificación podría estar en un middleware en otro lugar.

4. Revisar cada integración detectada

Para cada integración que el escáner haya listado, o que encuentre en el código, lea la sección correspondiente de references/integrations.md y verifique el código contra ella. Este paso captura lo que los patrones no pueden, como:

• un proxy backend que es un relay abierto
• un nombre de modelo tomado del cuerpo de la solicitud
• cantidades calculadas en el cliente
• llamadas a herramientas que se ejecutan con credenciales de administrador
• PII enviada a analíticas
• consultas RAG sin un filtro de inquilino
• inyección indirecta de prompt: documentos, páginas web, transcripciones o resultados de herramientas que el modelo lee siendo tratados como instrucciones (checklist 3.17)
• archivos subidos analizados sin verificación de tipo/tamaño/archivo o un sandbox (3.18)
• SSRF: una *_url que el modelo o una herramienta obtiene sin bloquear direcciones privadas o de metadatos (3.19)

Las comprobaciones de webhook, LLM de cliente y secretos son heurísticas: el escáner señala candidatos pero puede pasar por alto un control escrito a mano o un diseño no estándar. Siempre confirme leyendo el código — un webhook verificado con createHmac + timingSafeEqual, o un backend que casualmente está en src/, está bien incluso si una herramienta lo señala o lo pasa por alto.

5. Verificar puntos únicos de fallo

Use la sección 10 de la lista de verificación y busque en el código e IaC:

• un solo proveedor de LLM sin respaldo
• clientes HTTP a vendedores sin tiempo de espera ni reintento
• llamadas a vendedores en la ruta de solicitud que se bloquean cuando la analítica está caída
• una base de datos de una sola región o una sola zona
• una obtención de secretos sin caché
• una persona que tiene acceso root o propietario, según lo que el usuario le diga

6. Puerta manual

Muchos elementos de la lista de verificación no se pueden verificar desde un repositorio, por ejemplo:

• topes de gasto en paneles de proveedores
• horarios de rotación
• SSO y MFA en cuentas de vendedores
• pruebas de restauración de copias de seguridad
• simulacros de conmutación por error
• DPAs
• inventario de scripts PCI en páginas de pago

Enumere estos como Necesita confirmación, cada uno con una pregunta de una línea para el propietario. Nunca los marque como aprobados por suposición. Una puerta que aprueba silenciosamente elementos no verificados es peor que ninguna puerta.

7. Informe

Use esta estructura para que los resultados sean comparables entre lanzamientos:

# Puerta de seguridad: <producto / cambio> — <APROBADO | NO APROBADO | APROBADO CON EXCEPCIONES>

## Bloqueantes (deben corregirse antes del despliegue)
- [id de verificación] archivo:línea — qué está mal — la corrección

## Debería corregirse (este sprint)
- ...

## Integraciones revisadas
| Integración | Solo del lado del servidor | Clave con ámbito + tope de gasto | Webhooks/salidas verificados | Respaldo | Notas |

## Necesita confirmación (manual)
- [ ] <pregunta para el propietario> (checklist §n)

## Aprobado (verificado)
- <elemento> — cómo se verificó

Regla de veredicto:

• NO APROBADO: cualquier hallazgo confirmado de gravedad ALTA, que incluye un secreto activo, una clave secreta expuesta al cliente, un webhook de pago no verificado o un secreto en registros de CI.
• APROBADO CON EXCEPCIONES: solo quedan hallazgos de gravedad media o baja, y el usuario los acepta con un propietario y una fecha.
• APROBADO: no hay nada abierto y cada elemento manual ha sido confirmado.

Corrección de problemas

Cuando el usuario le pida corregir hallazgos, prefiera estos remedios, que abordan la causa raíz en lugar del síntoma:

• Clave en código: reemplácela con una búsqueda en tiempo de ejecución, ya sea desde env inyectado por el administrador de secretos o a través del SDK del proveedor. Añada un marcador de posición a .env.example. Nunca escriba el valor real en ningún lado. Dígale al usuario que la clave aún debe revocarse, porque eliminarla del código no la desfiltra.
• Secreto que llega al cliente: mueva la llamada detrás de una ruta backend o AI Gateway que autentique al usuario, límite de velocidad por usuario e inquilino, permita listas blancas de modelos y operaciones, y contenga la clave. Mantenga solo las claves publicables en el cliente.
• Webhook no verificado: verifique la firma en el cuerpo sin procesar con el SDK del proveedor. Rechace marcas de tiempo obsoletas, deduplique por ID de evento y vuelva a obtener el objeto del proveedor antes de cambiar el estado.
• Problemas de CI: fije las acciones a SHAs de commit (resuelva el SHA con git ls-remote, mantenga la etiqueta en un comentario). Añada permissions: contents: read. Reemplace las claves estáticas de nube con OIDC. Use npm ci --ignore-scripts.
• Problemas de Docker: use BuildKit RUN --mount=type=secret para secretos en tiempo de compilación y un USER no root.
• Acceso de agente: añada entradas permissions.deny Read(./.env) y Read(./.env.*) a .claude/settings.json. Recomiende inyección en tiempo de ejecución (doppler run, infisical run, op run) para que no exista ningún archivo de texto plano.

Uso continuo

Sugiera conectar el escáner en CI para que la puerta se ejecute en cada PR, no solo en el lanzamiento:

- run: python3 tools/deploy-security-gate/scripts/scan.py . --fail-on high

También sugiera una revisión recurrente con la cadencia de la sección 12 de la lista de verificación.

Archivos de referencia

• references/checklist.md: la lista de verificación completa (secciones 1–14), con cada elemento etiquetado como [auto] (escáner), [code] (revisión de código) o [manual] (propietario confirma). Léala para los pasos 5–6 y siempre que necesite el control exacto.
• references/integrations.md: cómo se ve una buena práctica para AI Gateways y proveedores de LLM, servidores MCP, pagos, analíticas y autenticación, con patrones a buscar. Lea las secciones para las integraciones en el alcance.
• references/leaked-key-runbook.md: la respuesta paso a paso cuando se encuentra una clave activa, con indicaciones de revocación por proveedor.