Documentation Index
Fetch the complete documentation index at: https://docs.snakysec.com/llms.txt
Use this file to discover all available pages before exploring further.
Roadmap Q2 2026 — Plan d’amelioration et continuite
1. Evaluation de maturite actuelle — 7.6/10
| Axe | Score | Detail |
|---|
| Couverture controles | 8/10 | 220 controles evalues (CIS M365 v6.0.1 + CISA SCuBA v1.5.0), 6 product areas |
| Fiabilite evaluation | 6.5/10 | 59 checks $count >= 0 placeholder, quelques faux positifs residuels |
| Architecture modules | 8/10 | Separation Core/Graph/PowerShell/Reporting/CISOAssistant, cache par endpoint |
| Pipeline CI | 7.5/10 | Multi-tenant parallel, manifest batch, pas de retry auto ni pre-flight |
| Reporting | 8/10 | HTML+Excel+JSON+Markdown+CISOAssistant, cross-tenant summary |
| Gestion erreurs | 7/10 | Classification 8 types d’erreur Graph, fallback cmdlet, pas de circuit-breaker |
| Tests | 5/10 | Pas de suite de tests unitaires/integration structuree |
| Documentation | 6/10 | CLAUDE.md existe, pas de doc utilisateur/operateur/API |
Points forts : architecture modulaire, double evaluation Graph+Cmdlet, classification d’erreurs riche, multi-tenant natif.
Faiblesses : pas de tests automatises, checks placeholder, pas de validation pre-flight des permissions, pas de monitoring de la qualite des resultats.
2. Plan d’amelioration du framework d’audit
Phase A — Stabilisation (2-3 semaines)
| Action | Impact | Effort |
|---|
Remplacer les 59 checks $count >= 0 par des validations reelles (property exists, value matches expected) | Elimine faux compliant | Moyen |
| Ajouter un pre-flight check : verifier scopes Graph + connexions services AVANT la boucle de controles | Reduit les “permission_blocked” surprises | Faible |
| Creer un test Pester par module : Mssp.Core, Mssp.Graph, Mssp.PowerShell, Mssp.Reporting | Detecte les regressions avant pipeline | Moyen |
| Ajouter un score de qualite dans le manifest : % controles reellement evalues vs manual_review | Visibilite immediate sur les regressions | Faible |
| Circuit-breaker : si >10 erreurs Graph consecutives, pause et retry avec backoff | Resilience face aux throttling Microsoft | Faible |
Phase B — Profondeur (3-4 semaines)
| Action | Impact | Effort |
|---|
| Provider pattern (comme ScubaGear) : 1 fetch par service puis evaluation offline | Reduit les appels API de ~300 a ~30, accelere x10 | Eleve |
OutputType HashTable : migrer Get-MsspGraphControlEvidence vers -AsHashtable | Elimine les crashes ConvertFrom-Json casing | Eleve |
| Validation croisee : pour les controles avec Graph ET Cmdlet, comparer les resultats | Detecte les faux positifs systematiques | Moyen |
| Enrichir les 59 EIDSCA/AAD sans CmdletRegistry avec des Graph checks reels | Reduit manual_review de ~50 controles | Eleve |
| Mock test suite : jeu de donnees de reference (tenant fictif) pour tester toute la chaine | Tests d’integration complets sans tenant reel | Moyen |
Phase C — Excellence (4-6 semaines)
| Action | Impact | Effort |
|---|
| Drift detection : comparer run N vs run N-1, alerter sur les regressions de conformite | Valeur operationnelle forte pour les clients | Moyen |
| Auto-remediation framework : pour les CA policies, generer les scripts de deploiement | Differenciateur commercial fort | Eleve |
| Benchmark scoring : score normalise comparable entre tenants (ponderation par criticite) | Dashboard cross-tenant plus pertinent | Moyen |
| Documentation operateur : guide de deploiement, troubleshooting, ajout de controles | Permet a d’autres operateurs de contribuer | Moyen |
| CI quality gate : pipeline echoue si manual_review > seuil configurable (ex: 15%) | Empeche les regressions | Faible |
Stack technique
| Composant | Choix |
|---|
| Framework | Next.js 16 (App Router, Turbopack, TypeScript) |
| UI | shadcn/ui (Radix + Tailwind) |
| Charts | Recharts |
| Tables | TanStack Table |
| Forms | React Hook Form + Zod |
| API interne | tRPC (type-safe) |
| API externe | REST routes Next.js |
| ORM | Prisma |
| Jobs | BullMQ + Redis |
| Auth | NextAuth.js v5 + Entra ID |
| Stockage fichiers | Volume Docker local (/data/reports/) |
| Containerisation | Docker Compose (4 services) |
Architecture
mssp-admin-platform/
docker/
docker-compose.yml # postgres, redis, app, nginx
nginx/nginx.conf
prisma/
schema.prisma # 13 tables
seed.ts # Import baseline + admin user
src/
app/
(auth)/login, callback # SSO Entra ID
(dashboard)/ # Admin : dashboard, clients, audits
(portal)/ # Portail client isole (white-label)
api/
auth/[...nextauth]/ # NextAuth.js
trpc/[trpc]/ # tRPC endpoint
v1/ # REST API (cles API, webhooks)
webhooks/gitlab/ # Reception pipeline events
components/ # shadcn/ui + composants metier
lib/
auth.ts # NextAuth Entra ID config
prisma.ts # Client Prisma singleton
trpc/routers/ # dashboard, clients, audits, gaps, portal, settings
gitlab/ # API GitLab (trigger, artifacts)
import/ # Parseur results.json/gap.json -> DB
crypto.ts # AES-256-GCM pour secrets client
jobs/ # BullMQ : import, polling, scheduling
types/audit.ts # Types TS alignes sur la sortie PowerShell
Base de donnees (PostgreSQL + Prisma)
| Table | Role |
|---|
users | Comptes SSO, role (MSSP_ADMIN / ANALYST / CLIENT_USER) |
clients | Tenants avec config, features, scheduling, white-label |
client_secrets | Credentials chiffres AES-256-GCM |
client_user_access | Liaison user <-> client pour le portail |
api_keys | Cles API hashees SHA-256, scope optionnel par client |
audit_runs | Historique des runs avec resume, scores, liens pipeline GitLab |
control_results | Resultat par controle par run (220 rows/run) |
gap_findings | Gaps avec suivi remediation (status, assignee, due date) |
alerts | Score degrade, nouveaux findings, audit failed |
baselines | Versions de baseline importees |
baseline_controls | Controles par baseline (reference pour tendances) |
platform_audit_log | Actions admin tracees |
Integration avec le systeme existant
+---------------------+
| MSSP Admin Platform |
| (Next.js + PG) |
+------+------+-------+
trigger pipeline| |webhook + fetch artifacts
v v
+---------------------+
| GitLab CI/CD |
| (pipeline existant) |
+------+--------------+
| produit
v
+---------------------+
| artifacts/audit/ |
| results.json |
| gap.json |
| report.html/xlsx |
+---------------------+
- Le pipeline CI reste inchange — la plateforme est un consommateur additif
- Git reste source de verite pour les baselines, modules PS, et pipeline
- PostgreSQL devient source de verite pour historique, remediation, users, alertes
- Import automatique : webhook GitLab -> BullMQ job -> parse artifacts -> insert DB
Securite
- Auth : NextAuth.js v5 + Microsoft Entra ID (OIDC)
- RBAC : MSSP_ADMIN (full), ANALYST (read + trigger), CLIENT_USER (portail scope)
- Isolation : Row-Level Security PostgreSQL + filtrage applicatif (defense in depth)
- API Keys : hash SHA-256 stocke, cle visible une seule fois, rotation sans downtime
- Secrets : AES-256-GCM avec
ENCRYPTION_KEY env var
- Reports : servis apres verification d’ownership, CSP headers, iframe sandbox
- Audit log : des la Phase 1 (critique pour un MSSP)
Features
Dashboard Multi-Tenant (/(dashboard)/page.tsx)
- KPI cards : tenants actifs, score moyen, findings ouverts, audits recents
- Courbe de tendance : compliance score par tenant sur 30/60/90 jours (Recharts)
- Feed d’alertes : degradation score, nouveaux findings critiques, audit echoue
- Tableau des audit runs : client, statut, score, date, duree, declencheur
- Grille clients : carte par tenant avec jauge de conformite
Gestion des Clients (/(dashboard)/clients/)
- CRUD clients : formulaire multi-tabs (general, features, auth, CISO Assistant, reporting)
- Feature toggles : grille visuelle entra/intune/defender/purview/sharepoint/teams
- Declenchement d’audit : bouton -> appel GitLab API trigger pipeline -> suivi temps reel
- Scheduling : expression cron + preview lisible + job BullMQ repeatable
- Gestion credentials : stockage chiffre, affichage masque, CRUD
- Sync Git : ecriture client.config.json via MR GitLab (jamais push direct sur main)
Portail Client (/(portal)/)
- Isolation tenant : toutes les requetes scoped par
session.clientId
- Dashboard : jauge conformite, repartition statuts, severite, dernier audit
- Viewer gaps : DataTable filtrable (severite, produit, statut remediation) + export CSV
- Viewer rapports : HTML en iframe sandbox, telechargement PDF/Excel/MD
- Suivi remediation : kanban (OPEN -> IN_PROGRESS -> REMEDIATED -> VERIFIED)
- White-label : logo, couleur primaire (CSS vars), domaine custom optionnel
4. Phases de livraison SaaS
Phase 1 — Fondation + Import (Semaines 1-4)
Init Next.js + Prisma + Docker Compose
SSO Entra ID + middleware RBAC + audit log (des le debut)
CRUD Clients (formulaire, config editor)
Import pipeline : parser results.json/gap.json -> DB
Webhook GitLab receiver
Seed DB depuis registry.json + baselines
Phase 2 — Dashboard Admin (Semaines 5-7)
Dashboard KPIs, tendances, alertes
Historique des runs + detail par controle
Trigger audit depuis l'UI (GitLab API)
Cross-tenant comparison view
Quality metrics (% automated, % manual_review, trend)
Phase 3 — Portail Client (Semaines 8-10)
Layout white-label (logo, couleurs, domaine)
Dashboard portail (jauge, stats, dernier audit)
Viewer gaps + export CSV
Viewer rapports (iframe HTML, download PDF/Excel)
Suivi remediation (kanban OPEN -> REMEDIATED -> VERIFIED)
Phase 4 — Operations (Semaines 11-14)
Scheduling audits (cron + BullMQ)
Gestion credentials chiffres
API Keys management + rotation
Alertes automatiques (score degrade, findings critiques)
Documentation (admin guide, API reference, deployment)
5. Lien entre les deux plans
Framework d'audit (PowerShell/CI) Plateforme SaaS (Next.js)
-------------------------------------- -------------------------
Phase A (stabilisation) --------> Phase 1 (fondation + import)
| resultats plus fiables | peut importer et afficher
Phase B (providers, profondeur) --------> Phase 2 (dashboard, KPIs)
| evaluation plus complete | donnees plus riches
Phase C (drift, remediation) --------> Phase 3-4 (portail, alertes)
| actions automatisees | workflow de remediation
Les deux tracks avancent en parallele : le framework produit les donnees, la plateforme les consomme. Le contrat d’interface est results.json + gap.json. Ajouter un champ schemaVersion dans la sortie PowerShell pour versionner le format et decoupler les deux efforts.
6. Verification
- Auth : login via Entra ID, verifier redirection par role (admin -> dashboard, client -> portail)
- Client CRUD : creer un client, verifier que client.config.json est genere en MR GitLab
- Trigger audit : declencher depuis l’UI, verifier pipeline GitLab demarre
- Import : webhook simule ou audit reel, verifier que results/gaps apparaissent dans la DB et le dashboard
- Portail : login en CLIENT_USER, verifier isolation (pas de donnees cross-tenant)
- Reports : verifier que le HTML report s’affiche en iframe, que les downloads fonctionnent
- Docker :
docker compose up depuis une machine vierge, verifier que tout demarre
- Quality gate : verifier que le pipeline echoue si manual_review depasse le seuil
Fichiers critiques existants (contrat d’interface)
src/runners/Invoke-CISAudit.ps1 / src/runners/Invoke-SCuBAAudit.ps1 — orchestrateurs (schema v3 output)
src/modules/Mssp.Output.psm1 — assemblage artefact + JSON export
src/modules/Mssp.Graph.psm1 — moteur d’évaluation (Graph + cmdlets)
clients/<slug>/client.config.json — modele de config client
.gitlab-ci.yml — pipeline FRAMEWORK × PRODUCT_AREA, OIDC WIF
src/frameworks/{cis,scuba}/*.json — 220 controles (CIS M365 v6.0.1 + CISA SCuBA v1.5.0)
7. Q3-Q4 2026 — Post-V1
7.1 Migration Sentry self-hosted
Motivation : souveraineté data (pitch MSSP PME France/EU). V1 utilise Sentry SaaS (DSN via Vault) — fonctionne, mais data hébergée US.
Déclencheur : 1er client payant signé → budget VPS observabilité dédié.
Cible infra :
- VPS dédié observabilité (pas co-locataire du noeud app) — sinon un crash Sentry perturbe la prod
- Specs min : 4 vCPU, 16 GB RAM + 16 GB swap, 40 GB SSD NVMe (haut IOPS)
- Réseau privé entre VPS app et VPS observabilité (Wireguard ou VPC cloud)
Étapes :
- Provisionner VPS observabilité, durcir (SSH key-only, UFW, fail2ban, unattended-upgrades)
git clone https://github.com/getsentry/self-hosted && ./install.sh
- Reverse proxy Traefik avec cert Let’s Encrypt sur
sentry.snakysec.internal
- Créer projet dans Sentry self-hosted → récupérer nouveau DSN
- Rotation du secret
mssp/data/platform/sentry_dsn dans Vault (ancien DSN SaaS → nouveau DSN self-hosted)
- Rebuild app Docker →
instrumentation.ts picke le nouveau DSN automatiquement (pas de code à changer)
- Monitoring du monitoring : alerte externe (UptimeRobot ou Better Uptime) sur
sentry.snakysec.internal/_health
- Décommissionner le projet Sentry SaaS après 30 jours de validation
Dépendances :
- Vault accessible depuis le VPS observabilité (ou duplication du secret DSN sur le VPS app uniquement — préférable, Sentry SaaS ne lit pas Vault)
- Sauvegardes : snapshot quotidien des volumes postgres + clickhouse + kafka (Sentry stocke ses events en clickhouse)
Trade-off assumé :
- +20 containers (postgres dédié, redis dédié, kafka, clickhouse, symbolicator, relay, snuba, web, worker, cron)
- Maintenance upgrades trimestriels (Sentry release cadence ~1 version/trimestre, breaking changes fréquents sur self-hosted)
- Pas d’IA/ML features (issue grouping manuel), pas de billing dashboard — acceptables pour solo MSSP
Effort estimé : 3-5 jours (install + durcissement + migration DSN + validation).
7.2 VulnWatch (différé Q3)
Surveillance vulnérabilités tenants M365 (Defender Secure Score, recommandations Defender for Cloud Apps, alertes SIEM) — intégration différée post-V1.
7.3 Obsidian KB (différé Q4)
Base de connaissance interne MSSP (procédures remédiation, runbooks incidents, veille CVE) — différée post-V1.