vitwit/deploy-security-gate

Porte de sécurité de déploiement

Cette compétence applique une checklist unique : aucune clé n'est jamais exposée, et aucune défaillance unique ne met le produit hors service. Elle s'exécute en trois passes :

1. Un scan automatisé avec scripts/scan.py, rapide, déterministe et en lecture seule.
2. Une revue de code de chaque intégration détectée, guidée par references/integrations.md.
3. Une porte manuelle pour tout ce qui n'est pas visible depuis le dépôt, comme les tableaux de bord fournisseur, la rotation, les sauvegardes et les exercices. Ces éléments proviennent de references/checklist.md.

Le scan seul ne constitue pas un passage. Il couvre environ un tiers de la checklist. La valeur de cette compétence réside dans le parcours des trois passes et l'honnêteté sur ce qui a été vérifié et ce qui nécessite encore une confirmation humaine.

Workflow

1. Périmètre

Déterminez ce qui est expédié :

• la racine du dépôt
• la sortie de build frontend ou mobile, le cas échéant
• la cible de déploiement, comme des conteneurs, serverless ou Kubernetes
• s'il s'agit d'un premier lancement, d'une nouvelle intégration ou d'une maintenance de routine

Si l'utilisateur a nommé un changement spécifique, comme "ajout de Stripe", concentrez la revue sur celui-ci. Exécutez néanmoins le scan complet, car une fuite ailleurs bloque la mise en production de la même manière.

2. Exécution du scanner

python3 <skill-dir>/scripts/scan.py <repo> --history

• Ajoutez --build-dir <dir> pour chaque bundle construit (dist, .next/static, un APK/IPA décompressé). Les bundles expédiés sont l'endroit où les clés "publiques" se révèlent être des clés secrètes. Les répertoires de build courants sont détectés automatiquement ; construisez d'abord l'application s'ils n'existent pas.
• --entropy ajoute une passe de haute entropie qui détecte les secrets personnalisés qu'aucun modèle nommé ne connaît (gravité faible ; vérifiez chacun avant de le signaler).
• --format json ou --format sarif produisent une sortie lisible par machine ; SARIF se télécharge vers l'analyse de code GitHub. --fail-on high|medium|low|never contrôle le code de sortie, utile en CI.
• Les faux positifs confirmés peuvent être supprimés avec un commentaire en ligne # security-gate: allow ou un fichier .security-gate-ignore à la racine du dépôt (voir le README). Préférez supprimer des résultats spécifiques plutôt que d'abaisser --fail-on.
• Le scanner masque les valeurs des secrets. Gardez cela dans tout ce que vous écrivez : ne répétez jamais une clé complète dans un chat, un fichier, un commit ou un texte de PR, car cela crée une seconde fuite.

Le scanner vérifie :

• les motifs de secrets (AWS, Anthropic, OpenAI, OpenRouter, Groq, xAI, Perplexity, Replicate, fal, clés API Google et secrets OAuth, clés live Stripe et secrets de webhook, Razorpay, GitHub, GitLab, jetons Slack et jetons d'application, comptes de service GCP, npm, PyPI, SendGrid, Hugging Face, DigitalOcean, New Relic, Shopify, Square, Databricks, Doppler, PlanetScale, Linear, clés de stockage Azure, Mailgun, Telegram, webhooks Discord, JWT, clés privées, URLs de base de données avec mots de passe, affectations codées en dur *_SECRET / *_TOKEN / *_SERVICE_ROLE — entre guillemets (y compris les configurations JSON/MCP) ou non) dans l'arbre de travail, la sortie de build et l'historique git
• avec --entropy, les chaînes de haute entropie qui ne correspondent à aucun format connu (secrets personnalisés ou nouveaux)
• les fichiers .env commités et une entrée .gitignore manquante
• les variables d'apparence secrète derrière des préfixes exposés au client (NEXT_PUBLIC_, VITE_, REACT_APP_, EXPO_PUBLIC_ et similaires), et les appels LLM directs depuis le code client
• les source maps dans la sortie de build
• les workflows GitHub Actions : actions épinglées par tag, pull_request_target, bloc permissions: manquant, secrets affichés, secrets écrits dans des fichiers ou $GITHUB_ENV / $GITHUB_OUTPUT, clés cloud statiques au lieu d'OIDC, et installations qui exécutent des scripts de cycle de vie
• les Dockerfiles : secrets dans ARG/ENV, fichiers .env copiés, et exécution en tant que root
• les gestionnaires de webhook de paiement sans vérification de signature
• l'accès en lecture de l'agent de codage aux fichiers .env
• les intégrations utilisées, ainsi que les indications de fournisseur unique (point unique de défaillance) pour l'IA et les paiements

3. Triage des résultats

Le scanner fonctionne par correspondance de motifs, alors confirmez chaque résultat en lisant le code avant de le signaler.

• Secret actif trouvé (dans l'arbre, l'historique ou un bundle) : traitez-le comme divulgué même si le dépôt est privé. Suivez references/leaked-key-runbook.md, où la révocation vient en premier et le nettoyage plus tard. Révoquer ou faire pivoter une clé modifie la production, alors dites à l'utilisateur exactement quelle clé, où elle a été trouvée et l'étape de révocation. Laissez-le faire, ou confirmez avant de faire quoi que ce soit vous-même.
• Faux positif (un fixture de test, une clé publique documentée) : dites pourquoi c'est sûr et passez à autre chose.
• Résultats heuristiques (vérification de webhook, appel LLM côté client) : ouvrez le fichier et vérifiez le flux de contrôle réel. La vérification peut résider dans un middleware ailleurs.

4. Revue de chaque intégration détectée

Pour chaque intégration listée par le scanner, ou que vous trouvez dans le code, lisez la section correspondante de references/integrations.md et vérifiez le code par rapport à celle-ci. Cette étape capture ce que les motifs ne peuvent pas, comme :

• un proxy backend qui est un relais ouvert
• un nom de modèle pris du corps de la requête
• des montants calculés sur le client
• des appels d'outils exécutés avec des identifiants administrateur
• des PII envoyées à l'analyse
• des requêtes RAG sans filtre de locataire
• une injection de prompt indirecte : des documents, pages web, transcriptions ou résultats d'outils lus par le modèle et traités comme des instructions (checklist 3.17)
• des téléchargements de fichiers analysés sans vérification de type/taille/archive ou un bac à sable (3.18)
• SSRF : une *_url que le modèle ou un outil récupère sans blocage sur des adresses privées ou de métadonnées (3.19)

Les vérifications de webhook, LLM client et secret sont heuristiques : le scanner signale des candidats mais peut manquer un contrôle écrit à la main ou une disposition non standard. Confirmez toujours en lisant le code — un webhook vérifié avec createHmac + timingSafeEqual, ou un backend qui se trouve sous src/, est correct même si un outil le signale ou le manque.

5. Vérification des points uniques de défaillance

Utilisez la section 10 de la checklist et cherchez dans le code et l'IaC :

• un seul fournisseur LLM sans solution de repli
• des clients HTTP vers des fournisseurs sans délai d'attente ou nouvelle tentative
• des appels fournisseur sur le chemin de la requête qui bloquent lorsque l'analyse est indisponible
• une base de données à région unique ou zone unique
• une récupération de secrets sans cache
• une personne qui détient seule l'accès root ou propriétaire, selon ce que l'utilisateur vous dit

6. Porte manuelle

De nombreux éléments de la checklist ne peuvent pas être vérifiés depuis un dépôt, par exemple :

• les plafonds de dépenses sur les tableaux de bord fournisseur
• les calendriers de rotation
• le SSO et l'authentification multifacteur sur les comptes fournisseur
• les tests de restauration de sauvegarde
• les exercices de basculement
• les DPA
• l'inventaire des scripts PCI sur les pages de paiement

Listez-les comme Nécessite confirmation, chacun avec une question d'une ligne pour le propriétaire. Ne les marquez jamais comme réussis par hypothèse. Une porte qui laisse passer silencieusement des éléments non vérifiés est pire que pas de porte du tout.

7. Rapport

Utilisez cette structure pour que les résultats soient comparables entre les versions :

# Porte de sécurité : <produit / changement> — <GO | NO-GO | GO AVEC EXCEPTIONS>

## Bloquants (à corriger avant déploiement)
- [id de vérification] fichier:ligne — ce qui ne va pas — le correctif

## À corriger (ce sprint)
- ...

## Intégrations examinées
| Intégration | Uniquement côté serveur | Clé limitée + plafond de dépenses | Webhooks/sorties vérifiés | Solution de repli | Remarques |

## Nécessite confirmation (manuel)
- [ ] <question pour le propriétaire> (checklist §n)

## Réussi (vérifié)
- <élément> — comment il a été vérifié

Règle de verdict :

• NO-GO : tout résultat ÉLEVÉ confirmé, ce qui inclut un secret actif, une clé secrète exposée au client, un webhook de paiement non vérifié ou un secret dans les journaux CI.
• GO AVEC EXCEPTIONS : seuls des résultats moyens ou faibles subsistent, et l'utilisateur les accepte avec un propriétaire et une date.
• GO : rien d'ouvert, et chaque élément manuel a été confirmé.

Correction des problèmes

Lorsque l'utilisateur vous demande de corriger des résultats, privilégiez ces remèdes, qui traitent la cause racine plutôt que le symptôme :

• Clé dans le code : remplacez-la par une recherche à l'exécution, soit à partir des variables d'environnement injectées par le gestionnaire de secrets, soit via le SDK du fournisseur. Ajoutez un espace réservé à .env.example. N'écrivez jamais la valeur réelle nulle part. Dites à l'utilisateur que la clé doit encore être révoquée, car la supprimer du code ne la rend pas non divulguée.
• Secret atteignant le client : déplacez l'appel derrière une route backend ou une passerelle AI qui authentifie l'utilisateur, limite le débit par utilisateur et locataire, autorise les modèles et opérations, et détient la clé. Ne conservez que les clés publiable dans le client.
• Webhook non vérifié : vérifiez la signature sur le corps brut avec le SDK du fournisseur. Rejetez les horodatages obsolètes, dédupliquez par ID d'événement et récupérez l'objet du fournisseur avant de changer d'état.
• Problèmes CI : épinglez les actions aux SHA de commit (résolvez le SHA avec git ls-remote, conservez le tag dans un commentaire). Ajoutez permissions: contents: read. Remplacez les clés cloud statiques par OIDC. Utilisez npm ci --ignore-scripts.
• Problèmes Docker : utilisez BuildKit RUN --mount=type=secret pour les secrets de build et un USER non root.
• Accès de l'agent : ajoutez des entrées permissions.deny Read(./.env) et Read(./.env.*) à .claude/settings.json. Recommandez l'injection à l'exécution (doppler run, infisical run, op run) afin qu'aucun fichier en clair n'existe du tout.

Utilisation continue

Suggérez de connecter le scanner à la CI afin que la porte s'exécute sur chaque PR, pas seulement au lancement :

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

Suggérez également une revue récurrente à la cadence de la section 12 de la checklist.

Fichiers de référence

• references/checklist.md : la checklist complète (sections 1 à 14), avec chaque élément étiqueté [auto] (scanner), [code] (revue de code) ou [manuel] (le propriétaire confirme). Lisez-la pour les étapes 5 et 6 et chaque fois que vous avez besoin du contrôle exact.
• references/integrations.md : à quoi ressemble un bon état pour les passerelles AI et fournisseurs LLM, les serveurs MCP, les paiements, l'analyse et l'authentification, avec des motifs à rechercher. Lisez les sections pour les intégrations dans le périmètre.
• references/leaked-key-runbook.md : la réponse étape par étape lorsqu'une clé active est trouvée, avec des pointeurs de révocation par fournisseur.