DocumentationRéférence API agent et serveur

Référence API agent et serveur

Référence API agent et serveur

Interfaces entre l'agent et le serveur d'agrégation, authentification mTLS, endpoints /api/v1/*, format NDJSON zstd, catalogue et config signés JWS, modèles BLOB.

L'agent dialogue avec le serveur d'agrégation en HTTPS mTLS pour remonter ses événements, récupérer sa configuration, le catalogue de services d'IA, les modèles de détection, et recevoir des notifications. L'API publique du serveur, elle, s'adresse aux SIEM et outils tiers via un jeton de service.

Base URL et versions

  • Base URL : https://<serveur>/api/v1/ · toutes les ressources sont versionnées dans le chemin.
  • En-têtes d'agent : User-Agent porte la version de l'agent, X-DLPIA-Capabilities déclare ses capacités.
  • Horodatage : chaque réponse porte Date RFC 7231 ; l'agent s'en sert pour son repère monotone.
  • Idempotence : les envois d'événements sont dédoublés par id côté serveur.

Authentification mTLS

  1. À l'enrôlement, l'agent génère une paire de clés non exportable dans le TPM (à défaut, CNG logiciel avec ACL SYSTEM) et une demande de certificat P-256.
  2. Il poste la demande à POST /api/v1/devices/enroll avec son jeton d'enrôlement.
  3. Le serveur signe un certificat client valable 12 mois et renvoie la chaîne de validation.
  4. L'agent renouvelle automatiquement aux deux tiers de la validité du certificat, soit après 8 mois environ.
  5. Le certificat du serveur est validé contre la CA déclarée dans la configuration, pas contre le magasin Windows.

Catalogue des endpoints agent

Endpoints appelés par l'agent sur /api/v1/*.
MéthodeCheminRôleAuth
POST/devices/enrollEnrôlement initial, délivrance du certificat client.Jeton
POST/events/batchRemontée d'événements NDJSON zstd.mTLS
GET/events/{id}/ackVérification d'acquittement d'un événement.mTLS
POST/anchorsDépôt d'un point d'ancrage de la chaîne d'intégrité.mTLS
GET/config?version=<hash>Configuration JWS Ed25519 du poste.mTLS
GET/catalog?version=<hash>Catalogue JWS des services d'IA.mTLS
GET/licenseLicence et liste de révocation signées.mTLS
GET/models?id=<id>&min-version=<v>Modèle BLOB signé Ed25519.mTLS
GET/certificate/renewRenouvellement du certificat client.mTLS
POST/statusHeartbeat agent, avec métriques internes.mTLS
WS/notifyCanal push de notifications de longue durée.mTLS
POST/diagnosticsPaquet de diagnostic, si l'envoi est activé.mTLS

Remontée d'événements

  • Taille d'un lot : au plus 1 000 événements OU 1 Mo compressé, la première limite atteinte.
  • Compression : zstd niveau 3 par défaut.
  • Format : JSON délimité par lignes (NDJSON), un événement par ligne.
  • Garantie : au moins une fois ; les doublons sont éliminés côté serveur par id.
  • Reprise : délai exponentiel avec gigue, de 1 s à 1 h.
POST /api/v1/events/batch HTTP/1.1
Host: aggregator.maelgard.example
Content-Type: application/x-ndjson
Content-Encoding: zstd
X-DLPIA-Capabilities: v=2026.10,models=pii;health;finance
Authorization-Context: mTLS

<corps NDJSON compressé en zstd>
{
  "acked": [
    "018f3b2a-7c6d-7e4a-9f12-0a1b2c3d4e5f",
    "018f3b2b-9d1e-7a21-b304-5f6a7b8c9d0e"
  ],
  "rejected": [],
  "status": "ok"
}

Modes de remontée

Quatre modes d'envoi configurables par type d'événement.
ModeComportementUsage type
Temps réelEnvoi au fil de l'eau, regroupé au plus 1 s.Petits parcs, alertes.
Lot périodiqueToutes les N minutes, défaut 15.Défaut recommandé.
DifféréDans une plage horaire, ou sur réseau non facturé.Postes nomades, faible bande passante.
À la demandeDéclenché par le serveur ou par dlpia-admin.Enquête, support.

Canal de notifications

Le serveur maintient avec chaque agent un canal WebSocket de longue durée, /api/v1/notify, qui signale la disponibilité de nouveaux éléments.

Types de notifications poussés par le serveur.
TypeCharge utileAction attendue de l'agent
config_availableversionTélécharger /config après délai aléatoire 0-10 min.
catalog_availableversionTélécharger /catalog.
model_availableid, versionTélécharger /models.
license_availableissued_atTélécharger /license.
update_availableversion, delay_maxTélécharger la mise à jour de l'agent.
diag_requestedcorrelation_idProduire et envoyer un paquet de diagnostic.

Format du catalogue

Le catalogue des services d'IA est un JWS Ed25519 signé par l'éditeur, enrichi par les ajouts du client. Chaque entrée décrit un service d'IA du point de vue de l'interception.

{
  "service_id": "openai-api",
  "display_name": "OpenAI API",
  "channel": "api",
  "domains": ["api.openai.com"],
  "endpoints": [
    {
      "method": "POST",
      "path": "^/v1/chat/completions$",
      "request_kind": "prompt",
      "extraction": {
        "format": "json",
        "fields": ["$.messages[*].content", "$.system"]
      }
    },
    {
      "method": "POST",
      "path": "^/v1/files$",
      "request_kind": "upload",
      "extraction": { "format": "multipart", "fields": ["file"] }
    }
  ],
  "processes": ["python.exe", "node.exe", "curl.exe"],
  "risk": { "profile": "sanctioned", "default_action": "intercept" }
}

Format de la configuration

  • Enveloppe : JWS compact Ed25519, cty = maelgard-config.
  • En-tête : kid identifie la clé client, x5c facultatif pour les chaînes.
  • Payload : voir la liste des paramètres à la section Déploiement.
  • Versionnage : chaque document porte une empreinte, l'agent passe ?version=<hash> pour ne retélécharger que si nécessaire.
GET /api/v1/config?version=sha256:9f1b…c3a HTTP/1.1
Host: aggregator.maelgard.example

HTTP/1.1 200 OK
Content-Type: application/jwt
X-DLPIA-Version: sha256:a4c0…9bd

eyJhbGciOiJFZERTQSIsImtpZCI6ImNmZy0yMDI2In0...

Modèles BLOB

Les modèles de détection sont des fichiers BLOB signés Ed25519 par l'éditeur, servis par /api/v1/models. Le format du corps est BLOB 0.1.

GET /api/v1/models?id=pii&min-version=1.4.0 HTTP/1.1
Host: aggregator.maelgard.example

HTTP/1.1 200 OK
Content-Type: application/vnd.maelgard.model+blob
X-Model-Id: pii
X-Model-Version: 1.4.2
X-Model-Signature: <base64 Ed25519>

<corps binaire BLOB 0.1>
  • Un modèle n'est ni téléchargé ni chargé si la licence ne l'autorise pas (voir Référence licence).
  • La signature est vérifiée avant tout chargement en mémoire.
  • Les versions suivent SemVer. L'agent demande une version majeure et accepte la plus récente dans cette borne, limitée par la licence.
  • Un modèle corrompu ou mal signé est écarté, le précédent reste chargé.

Jetons d'enrôlement et d'API

Deux familles de jetons, deux usages.
FamillePréfixeDuréePortéeVisibilité
Enrôlement de postemge_24 à 72 h, usage uniqueUn seul enrôlement de poste.Affiché une seule fois, SHA-256 stocké.
API publiquemgs_1 à 366 joursPortées limitatives : events.read, alerts.read, etc.Secret affiché une seule fois, SHA-256 stocké.
Service de licencemgls_1 à 366 joursPortées limitatives : tenants.read, tenants.write.Secret affiché une seule fois.

Codes d'erreur HTTP

Codes HTTP standards utilisés par l'API.
CodeSignificationCas typique
200Succès.Opération standard.
201Créé.Enrôlement réussi.
202Accepté.Lot d'événements pris en charge.
304Non modifié.Configuration ou catalogue à jour.
400Requête invalide.Syntaxe JSON ou NDJSON incorrecte.
401Non authentifié.Certificat mTLS absent, jeton invalide.
403Interdit.Portées insuffisantes pour l'action.
404Ressource inconnue.Modèle ou tableau de bord inexistant.
409Conflit.Enrôlement déjà effectué pour ce poste.
413Trop volumineux.Lot supérieur à 1 Mo compressé.
422Entité non traitable.Signature de configuration invalide.
429Trop de requêtes.Quota ou brute-force détecté.
503Service indisponible.Reprise selon Retry-After.

Modèles de données partagés

  • UsageEvent — voir la référence Événements et audit.
  • License — payload JWS, voir la référence Licence.
  • Catalog — tableau de ServiceEntry signé par l'éditeur, étendu par le client.
  • Config — document JWS Ed25519 à quatre sources fusionnées.
  • Anchor — paire (seq, hash) signée par la clé du poste.
  • Alert — type, criticité, horodatage, dispositif, lien vers l'événement source.