G-11 Preuves d'audit (WORM)

Brique G de la plateforme Enterprise AI. Technologie : eai.audit_events chaîné par hachage + stockage objet WORM immuable (S3 Object Lock en mode compliance). Version anglaise : ../../en/bricks/G-11-audit-evidence.md.

Rôle et responsabilités

• Enregistrer chaque mutation et décision de politique avec chaîne prev_hash/hash et séquence par tenant.
• Exporter des périodes signées vers un stockage WORM et vérifier l'intégrité à tout moment.

Position et interactions

• Chemin d'exécution : écriture synchrone à chaque mutation, export batch.
• Écrit dans la même transaction que le changement métier (eai.audit.audit()).

Part open source et part développée

• Open source réutilisé : PostgreSQL, S3 Object Lock (SeaweedFS, Ceph RGW ou cloud).
• Développé dans la plateforme : Chaîne de hachage, endpoint de vérification, export avec manifeste et sha256, correspondance des preuves avec les contrôles.

Modèle de données

Tables du Control Plane (schéma eai) : eai.audit_events, eai.audit_exports.

Chaque table de tenant a tenant_id uuid NOT NULL et une politique de sécurité au niveau des lignes sur current_setting('app.tenant_id', true)::uuid. ClickHouse usage_events est la réplique analytique de eai.usage_events (ReplacingMergeTree par event_id).

Contrat : contracts/v1/audit-event.schema.json (schema_version 1.0). L'usage est toujours remonté avec contracts/v1/usage-event.schema.json, l'audit avec contracts/v1/audit-event.schema.json.

Endpoints d'API

Méthode	Chemin
GET	/v1/audit/events
GET	/v1/audit/events/{id}
GET	/v1/audit/verify
POST	/v1/audit/export

GET /v1/audit/events

Réponse :

{
  "items": [
    {
      "event_id": "aud_901",
      "sequence": 90311,
      "action": "model.invoke",
      "decision": "allow",
      "outcome": "success",
      "hash": "9c1e..."
    }
  ],
  "next_cursor": "c_2"
}

GET /v1/audit/events/{id}

Réponse :

{
  "event_id": "aud_901",
  "actor": {
    "type": "agent",
    "id": "agt_ap"
  },
  "resource": {
    "type": "model",
    "id": "gpt-4o-mini"
  },
  "prev_hash": "77ab...",
  "hash": "9c1e..."
}

GET /v1/audit/verify

Réponse :

{
  "valid": true,
  "checked": 90311,
  "first_sequence": 1,
  "last_sequence": 90311,
  "broken_at": null
}

POST /v1/audit/export

Le champ format choisit ndjson (par défaut) ou csv (une ligne par événement, objets imbriqués en cellules JSON, événement canonique dans la dernière colonne event) ; la signature porte sur le fichier dans le format choisi. Une autre valeur donne un refus 422.

Requête :

{
  "from": "2026-09-01T00:00:00Z",
  "to": "2026-10-01T00:00:00Z",
  "retention_days": 3650
}

Réponse :

{
  "export_id": "aex_3",
  "status": "completed",
  "uri": "s3://eai-audit-worm/tenant/2026-09.jsonl",
  "sha256": "e3b0c442...",
  "object_lock": "COMPLIANCE"
}

Exemples SDK

Python

from enterprise_ai import EnterpriseAI

client = EnterpriseAI(base_url="<control-plane-url>", api_key="eai_live_xxx", tenant="acme", locale="fr")
client.audit.events(action="model.invoke", since="2026-10-01T00:00:00Z")
client.audit.get("aud_901")
client.audit.verify()
client.audit.export(since="2026-09-01T00:00:00Z", until="2026-10-01T00:00:00Z")

TypeScript

import { EnterpriseAI } from "@enterprise-ai/sdk";

const client = new EnterpriseAI({ baseUrl: "<control-plane-url>", apiKey: process.env.EAI_API_KEY, tenant: "acme", locale: "fr" });
await client.audit.list({ action: "model.invoke", from: "2026-10-01T00:00:00Z" });
await client.audit.get("aud_901");
await client.audit.verify();
await client.audit.export({ from: "2026-09-01T00:00:00Z", to: "2026-10-01T00:00:00Z" });

Java

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .tenant("acme")
    .locale(Locale.FRENCH)
    .build();
client.audit().events(Map.of("action", "model.invoke", "from", "2026-10-01T00:00:00Z"));
client.audit().event("aud_901");
client.audit().verify();
client.audit().export(Map.of("from", "2026-09-01T00:00:00Z", "to", "2026-10-01T00:00:00Z"));

Go

client, err := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")), eai.WithTenant("acme"), eai.WithLocale("fr"))
if err != nil { log.Fatal(err) }
ctx := context.Background()
_, err = client.Audit.Events(ctx, eai.WithQuery(map[string]string{"action": "model.invoke", "from": "2026-10-01T00:00:00Z"}))
_, err = client.Audit.Event(ctx, "aud_901")
_, err = client.Audit.Verify(ctx)
_, err = client.Audit.Export(ctx, map[string]any{"from": "2026-09-01T00:00:00Z", "to": "2026-10-01T00:00:00Z"})

Configuration

Variables d'environnement : EAI_S3_BUCKET.

Clés de valeurs Helm (deploy/helm/enterprise-ai/values.yaml) : controlPlane.config.EAI_S3_BUCKET.

Sécurité

• Aucun droit UPDATE ou DELETE sur eai.audit_events pour le rôle applicatif.
• Lecteurs : rôles auditor et security_officer.
• Tenant déduit de l'identifiant d'accès, jamais du corps ; sécurité au niveau des lignes PostgreSQL sur chaque table de tenant.
• Chaque mutation et décision de politique écrit un événement d'audit chaîné par hachage (G-11).
• Les erreurs utilisent l'enveloppe standard avec message_i18n en et fr.

Observabilité

• Vérification quotidienne ; alerte si broken_at n'est pas nul.
• traceparent W3C propagé, X-Request-Id renvoyé, les spans portent eai.tenant_id, eai.project, eai.agent_id, eai.run_id.

Unités FinOps

• Coût du stockage WORM imputé par tenant (storage_gb_hours).

Modes de défaillance et résilience

• Échec d'écriture d'audit -> la transaction métier est annulée (aucun changement non audité).

Adoption autonome

Utilisable comme registre de preuves en ajout seul par d'autres systèmes via l'API d'audit.

Tests d'acceptation

1. Altérer une ligne fait renvoyer valid=false avec broken_at par GET /v1/audit/verify.
2. Supprimer un objet exporté avant la fin de rétention échoue au niveau du stockage.

Evidence Service (section 11 du kit)

Le domaine eai.domains.evidence (routes /v1/evidence, migrations V150 à V154) complète la chaîne :

• boîte d'envoi transactionnelle eai.audit_outbox écrite dans la transaction du changement audité, vidée par le job audit_gateway (SIEM HTTP et NATS JetStream, clé d'idempotence = identifiant de l'événement, recul exponentiel, pas d'échantillonnage, détection des trous de séquence) ;
• sceaux signés Ed25519 (eai.audit_seals) sur des plages d'événements : racine de Merkle sha256 des événements canonisés RFC 8785, hachage du sceau précédent, identifiant de clé ; vérification par GET /v1/evidence/seals/{id}/verify et hors ligne par python -m eai.domains.evidence.verify bundle.json ;
• moniteur d'intégrité (job audit_integrity) qui recalcule chaînes, sceaux, signatures et horodatages et ouvre une alerte eai.audit_integrity_alerts et un événement security.audit.integrity_alert ;
• trois horodatages distincts : event_time (fourni par l'appelant, avance limitée par EAI_AUDIT_CLOCK_SKEW_SECONDS), ingested_at (horloge de la base à l'insertion) et sealed_at ;
• charges utiles sensibles chiffrées par enveloppe Tink (clé hors base : OpenBao transit), seule l'empreinte du chiffré est chaînée ; déchiffrement réservé aux rôles auditor et security_officer, avec motif, lui-même audité ;
• conservation légale (locataire, dossier, plage de temps) qui bloque purge et effacement, levée par deux approbateurs distincts, preuve de purge (comptes et empreintes, jamais le contenu) ;
• configuration d'exécution d'un run (modèle, prompt, outil, skill, plugin) reconstructible par GET /v1/evidence/runs/{id}/configuration.

Tests : services/control-plane/tests/test_evidence_gateway.py, services/control-plane/tests/test_evidence_config_redaction.py.

Feuille de route d'implémentation