Report model

Report Model — Schema v3.0

Spécification du format des artefacts d’audit générés par le moteur PowerShell.

Nomenclature

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

• <framework> : cis | scuba
• <product-area> : entra | exchange | teams | sharepoint | defender | purview
• <tenantId> : GUID tenant Entra
• <timestamp> : ISO 8601 compact (20260414T213045Z)

Exemple : artifacts/audit/cis-entra-12345678-abcd-...-20260414T213045Z.json

Structure de l’artefact

{
  "schemaVersion": "3.0",
  "generatedAt": "2026-04-14T21:30:45Z",
  "runMetadata": {
    "framework": "cis",               // cis | scuba
    "frameworkVersion": "v6.0.1",     // v6.0.1 (CIS) | v1.5.0 (SCuBA)
    "productArea": "entra",
    "runnerVersion": "3.0.0",
    "authMode": "oidc-wif",           // oidc-wif | cert-x509 | secret
    "isHybrid": false                  // Test-MsspTenantHybrid
  },
  "tenant": {
    "tenantId": "<guid>",
    "tenantName": "Contoso",
    "skus": ["ENTERPRISEPREMIUM", "SPE_E5", ...]
  },
  "summary": {
    "total": 60,
    "compliant": 42,
    "finding": 8,
    "manual": 5,
    "not_applicable": 3,
    "insufficient_perms": 1,
    "not_assessed": 1,
    "error": 0
  },
  "controls": [
    {
      "id": "CIS-ENTRA-1.1.1",
      "title": "...",
      "level": 1,                     // CIS L1 | L2  —  SCuBA: absent
      "method": "automated",          // automated | manual
      "status": "compliant",          // voir taxonomie ci-dessous
      "severity": "high",             // critical | high | medium | low
      "evidence": {                   // payload brut (Graph JSON ou cmdlet output)
        "endpoint": "/policies/authorizationPolicy",
        "response": { ... },
        "apiVersion": "v1.0"          // v1.0 | beta (quand renseigné par le contrôle)
      },
      "check": {                      // condition évaluée
        "property": "allowedToSignUpEmailBasedSubscriptions",
        "operator": "eq",
        "expected": false,
        "observed": true
      },
      "remediation": {
        "instructions": "...",
        "graphSetUrl": "https://...",
        "portalUrl": "https://..."
      },
      "mappings": {
        "cis": "CIS-ENTRA-1.1.1",
        "iso27001": "A.5.15",
        "nistCsf2": "PR.AC-01"
      },
      "requiredPermissions": ["Policy.Read.All"],
      "requiredLicense": null,
      "applicability": {
        "hybridOnly": false,
        "cloudOnly": false
      },
      "manualValidation": null         // objet présent quand method=manual
    }
  ]
}

Taxonomie des statuts (v3.0 — 7 valeurs)

Statut	Signification	Conversion GapFinding
compliant	Contrôle évalué, conforme	Non
finding	Contrôle évalué, non conforme	Oui (→ OPEN)
manual	Contrôle non automatisable — nécessite validation humaine	Non (guide dans manualValidation)
not_applicable	Contrôle non applicable (licence manquante, hybrid-only sur cloud-only, etc.)	Non
insufficient_perms	Permissions Graph insuffisantes pour évaluer	Non (audit log)
not_assessed	Évaluation impossible (dépendance externe, endpoint indisponible)	Non
error	Erreur technique (throw dans le check)	Non (audit log + Sentry)

Import pipeline

platform/src/lib/import/index.ts :

1. Télécharge l’artefact depuis GitLab (via API job artifact).
2. Valide le schéma v3 (Zod).
3. Upsert AuditRun avec le summary.
4. Insère/update ControlResult par contrôle.
5. Pour chaque status: "finding", crée un GapFinding en état OPEN (ou update si existant).
6. Génère les alertes (score dégradé, critical finding).

Génération rapports

À partir des ControlResult + GapFinding en DB :

• PDF (/api/v1/audits/:id/report) — Score exécutif + scores domaine + table contrôles + plan remédiation
• Excel (/api/v1/audits/:id/report/excel) — 6 onglets (Summary, Domain Scores, Framework Mapping, All Controls, Failed Controls, Remediation Plan)
• HTML (/api/v1/audits/:id/report/html) — Standalone (CSS/JS inline), search + filtres temps réel

Évolution schéma

• Breaking change sur le schéma → incrémenter schemaVersion majeur et supporter parallèlement l’ancien dans l’import pipeline pendant ≥ 1 release.
• Nouveau champ optionnel → conserver schemaVersion 3.x.