Runbook

Runbook opérateur

Procédures pour démarrer, exploiter, et dépanner la plateforme MSSP SnakySec.

Sommaire

• Environnements
• Démarrage pré-prod
• Démarrage production
• Vault (init, unseal, rotation)
• Prisma — sync schéma
• Matrice de rebuild
• Audit local (hors CI)
• Dépannage

---

Environnements

Env	Mode Vault	TLS	Cible
Pré-prod (dev local)	dev mode (root token)	mkcert	Docker Desktop Windows (aujourd’hui) · MacBook Pro (futur)
Production	Shamir seal (5 shares, threshold 3)	Let’s Encrypt	VPS OVH (cible)

Démarrage pré-prod

cp .env.example .env                 # renseigner APP_DOMAIN, VAULT_ADDR
make preprod                         # compose tous les overlays dev

Accès : https://<APP_DOMAIN>. Credentials AppRole injectés automatiquement depuis Vault dev.

Logs par service :

make app-logs     # Next.js
make traefik-logs # Traefik
make vault-logs   # Vault
make postgres-logs

Démarrage production

make prod                            # compose tous les overlays prod
vault operator init -key-shares=5 -key-threshold=3   # SEULEMENT à la 1re init

Conserver les 5 key shares selon la répartition documentée dans dr/01-keyholders.md : 3 chez le DR Owner (YubiKey + KeePass + papier coffre) + 2 en enveloppe scellée chez notaire mandaté. Ne jamais commit.

Vault (init, unseal, rotation)

Unseal après redémarrage

vault operator unseal <share-1>
vault operator unseal <share-2>
vault operator unseal <share-3>      # threshold = 3

Rotation AppRole

Après vault operator init ou ré-init :

vault write -f auth/approle/role/mssp-app/secret-id
vault write -f auth/approle/role/mssp-worker/secret-id

Mettre à jour le volume partagé mssp-approle (les entrypoints lisent les nouveaux credentials au prochain démarrage container).

Paths Vault

• mssp/data/platform — auth_secret, encryption_key, entra_cert_pem, entra_cert_private_key, gitlab_token, postgres_password, redis_password, sentry_dsn, sentry_auth_token
• mssp/data/clients/<slug> — credentials SSO par client (entra_client_id, entra_tenant_id, entra_cert_pem, entra_cert_private_key)

Prisma — sync schéma

Prisma 7 nécessite prisma.config.ts à la racine de platform/.

Après modification de schema.prisma, pousser le schéma via un container éphémère sur le réseau Docker :

docker run --rm --network platform_mssp-net \
  -v "//$PWD/platform://work" -w //work node:22-alpine \
  sh -c "DATABASE_URL='postgresql://mssp:<pw>@postgres:5432/mssp' npx prisma db push"

Puis make app-rebuild pour rebuild l’image avec le nouveau client Prisma.

Matrice de rebuild

Fichier modifié	Commande
platform/src/**/*.ts(x)	make app-rebuild
platform/prisma/schema.prisma	Container éphémère prisma db push + make app-rebuild
platform/package.json	make app-rebuild
platform/docker/**	make preprod-build (ou service ciblé)
.env	make app-restart (recrée le container avec nouveau env)
Contrôles framework (src/frameworks/**/*.json)	Aucun — chargés au runtime côté CI

Audit local (hors CI)

Pour tester un contrôle sans déclencher un pipeline GitLab :

pwsh ./src/runners/Invoke-CISAudit.ps1 `
  -TenantId '<guid>' -TenantName 'Contoso' `
  -ClientId '<app-id>' -AccessToken $token `
  -ProductArea entra

Les artefacts schema v3 sont écrits dans artifacts/audit/.

Dépannage

”No client configured for this domain”

Fallback plateforme actif : vérifier que les secrets Entra sont présents sur mssp/data/platform. Si oui, l’admin MSSP doit voir le bouton SSO. Si non, vérifier que resolveClientFromCookie() retourne les env vars plateforme.

JWT session invalidée après redémarrage

AUTH_SECRET rotated en Vault → toutes les sessions NextAuth sont invalidées. L’utilisateur doit clear ses cookies et re-login.

instrumentation.ts ne voit pas les secrets Vault

instrumentation.ts s’exécute une fois au démarrage serveur, pas à chaque requête. Pour propager une modification, make app-rebuild (pas juste restart).

Cert auth Graph échoue

Les secrets ENTRA_CERT_PEM + ENTRA_CERT_PRIVATE_KEY vivent uniquement dans Vault. Vérifier :

vault kv get -field=entra_cert_pem mssp/platform | head -3

Doit commencer par -----BEGIN CERTIFICATE-----.

Variables NEXT_PUBLIC_* non mises à jour

Bakées au build time dans le JS bundle. make app-rebuild obligatoire (pas juste restart).

Webhook GitLab auto-disabled

GitLab désactive un webhook après N échecs consécutifs. Re-enabler manuellement dans l’UI GitLab + vérifier que /api/webhooks/gitlab répond en <10s (import async via after() configuré).