> ## 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.

# Architecture

# Architecture

Plateforme MSSP SnakySec : moteur d'audit PowerShell + SaaS Next.js multi-tenant pour l'audit M365 (220 contrôles CIS M365 v6.0.1 + CISA SCuBA v1.5.0) et la génération de 8 documents GRC (méthodologie ANSSI).

## Flux audit complet

```
┌──────────────┐   trigger    ┌────────────────┐   pipeline    ┌───────────────┐
│   Dashboard  │─────────────▶│  /api/v1/      │──────────────▶│   GitLab CI   │
│   (Next.js)  │              │  audits/trigger│               │  (OIDC WIF)   │
└──────────────┘              └────────┬───────┘               └───────┬───────┘
                                       │                               │
                                       │                          PS 7 runners
                                       │                     (Invoke-CISAudit /
                                       │                      Invoke-SCuBAAudit)
                                       │                               │
                                       │                               ▼
                                       │                       ┌───────────────┐
                                       │                       │  Graph API +  │
                                       │                       │  EXO/Teams/   │
                                       │                       │  PnP cmdlets  │
                                       │                       └───────┬───────┘
                                       │                               │
                                       │                         artifacts/audit/
                                       │                      <fw>-<area>-<tid>-<ts>.json
                                       │                         (schema v3)
                                       │                               │
                              webhook GitLab                           │
                              HMAC-signed ◀─────────────────────────── │
                                       │
                                       ▼
                               ┌───────────────┐   import    ┌────────────────┐
                               │  BullMQ       │────────────▶│  Prisma →      │
                               │  audit-import │             │  PostgreSQL    │
                               └───────┬───────┘             └───────┬────────┘
                                       │                             │
                                       ▼                             ▼
                               ┌───────────────┐             ┌───────────────┐
                               │   Alerts      │             │  Dashboard +  │
                               │   (BullMQ)    │             │  GRC docs     │
                               └───────────────┘             └───────────────┘
```

## Composants

### Moteur d'audit (PowerShell 7+)

* `src/modules/Mssp.Auth.psm1` — Auth Graph (OIDC WIF, cert X.509, secret) + Exchange Online
* `src/modules/Mssp.Graph.psm1` — Évaluation des contrôles : opérateurs (`eq`, `contains`, `matches`, compound `and`/`or`), retry/backoff, helpers (`Test-MsspTenantHybrid`, `Test-MsspRequiredPermissions`)
* `src/modules/Mssp.Output.psm1` — Assemblage du résultat + export JSON schema v3.0
* `src/runners/Invoke-CISAudit.ps1` — CIS M365 v6.0.1 (accepte `-ProductArea`)
* `src/runners/Invoke-SCuBAAudit.ps1` — CISA SCuBA v1.5.0 (accepte `-ProductArea`)
* `src/frameworks/{cis,scuba}/<product-area>.json` — Catalogue des 220 contrôles évalués

### Plateforme SaaS (Next.js 16 + App Router)

* `platform/src/app/api/v1/audits/trigger/route.ts` — Déclenchement audit (params `framework` × `productArea`)
* `platform/src/app/api/webhooks/gitlab/route.ts` — Réception pipeline complétée (HMAC) → enqueue BullMQ
* `platform/src/lib/import/index.ts` — Import pipeline schema v3 → `ControlResult` + `GapFinding`
* `platform/src/lib/gitlab.ts` — Trigger/cancel pipeline, download artifact
* `platform/src/lib/crypto.ts` — AES-256-GCM pour secrets client en DB
* `platform/src/lib/client-resolver.ts` — Domaine → slug client → secrets Vault → SSO config
* `platform/src/lib/grc/` — 8 générateurs GRC (PSSI, Access Policy, Incident Procedure, Remediation Plan, Data Classification, Breach Notification, IT Charter, Processing Register) — DOCX + PDF
* `platform/src/proxy.ts` — RBAC route protection (remplace `middleware.ts`)
* `platform/src/jobs/` — Workers BullMQ (audit-import, monthly-digest, alerts)

### Base de données (Prisma 7 + PostgreSQL)

13 modèles : `User`, `Client`, `ClientUserAccess`, `ClientSecret`, `ApiKey`, `AuditRun` (framework × productArea), `ControlResult`, `ControlReviewHistory`, `GapFinding`, `Alert`, `Baseline`, `BaselineControl`, `PlatformAuditLog`.

### Infrastructure

* **Vault** (KV v2, Shamir seal en prod) — `mssp/data/platform`, `mssp/data/clients/<slug>`
* **AppRole** — `mssp-app` (read platform + clients), `mssp-worker` (read clients only)
* **Redis 7** — BullMQ queues (audit-import, monthly-digest, alerts)
* **Traefik v3** — mkcert en dev, Let's Encrypt en prod
* **Sentry** — Observabilité full-pipeline (DSN Vault, scrubbing PII, release = commit SHA)

## Sécurité transverse

* **Cadre DICT** (Disponibilité · Intégrité · Confidentialité · Traçabilité — modèle ANSSI) comme référence pour classifier les contrôles et scorer les risques.
* **Zero long-lived secret** : OIDC WIF pour GitLab CI, cert X.509 pour Graph en prod.
* **Chiffrement** : AES-256-GCM en DB, TLS partout.
* **RBAC** : MSSP\_ADMIN · ANALYST · CLIENT\_USER + audit log applicatif (`PlatformAuditLog`).

## Schema artefacts v3.0

```
artifacts/audit/<framework>-<product-area>-<tenantId>-<timestamp>.json
```

Statuts : `compliant | finding | manual | not_applicable | insufficient_perms | not_assessed | error`.

Voir [report-model.md](report-model.md) pour la spec complète.

## Décisions d'architecture

Voir [docs/adr/](adr/) : BullMQ, Vault AppRole, cert X.509, cursor pagination.