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-Agentporte la version de l'agent,X-DLPIA-Capabilitiesdéclare ses capacités. - Horodatage : chaque réponse porte
DateRFC 7231 ; l'agent s'en sert pour son repère monotone. - Idempotence : les envois d'événements sont dédoublés par
idcôté serveur.
Authentification mTLS
- À 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.
- Il poste la demande à
POST /api/v1/devices/enrollavec son jeton d'enrôlement. - Le serveur signe un certificat client valable 12 mois et renvoie la chaîne de validation.
- L'agent renouvelle automatiquement aux deux tiers de la validité du certificat, soit après 8 mois environ.
- Le certificat du serveur est validé contre la CA déclarée dans la configuration, pas contre le magasin Windows.
Catalogue des endpoints agent
| Méthode | Chemin | Rôle | Auth |
|---|---|---|---|
| POST | /devices/enroll | Enrôlement initial, délivrance du certificat client. | Jeton |
| POST | /events/batch | Remontée d'événements NDJSON zstd. | mTLS |
| GET | /events/{id}/ack | Vérification d'acquittement d'un événement. | mTLS |
| POST | /anchors | Dé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 | /license | Licence et liste de révocation signées. | mTLS |
| GET | /models?id=<id>&min-version=<v> | Modèle BLOB signé Ed25519. | mTLS |
| GET | /certificate/renew | Renouvellement du certificat client. | mTLS |
| POST | /status | Heartbeat agent, avec métriques internes. | mTLS |
| WS | /notify | Canal push de notifications de longue durée. | mTLS |
| POST | /diagnostics | Paquet 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
| Mode | Comportement | Usage type |
|---|---|---|
| Temps réel | Envoi au fil de l'eau, regroupé au plus 1 s. | Petits parcs, alertes. |
| Lot périodique | Toutes 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 demande | Dé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.
| Type | Charge utile | Action attendue de l'agent |
|---|---|---|
config_available | version | Télécharger /config après délai aléatoire 0-10 min. |
catalog_available | version | Télécharger /catalog. |
model_available | id, version | Télécharger /models. |
license_available | issued_at | Télécharger /license. |
update_available | version, delay_max | Télécharger la mise à jour de l'agent. |
diag_requested | correlation_id | Produire 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 :
kididentifie la clé client,x5cfacultatif 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
| Famille | Préfixe | Durée | Portée | Visibilité |
|---|---|---|---|---|
| Enrôlement de poste | mge_ | 24 à 72 h, usage unique | Un seul enrôlement de poste. | Affiché une seule fois, SHA-256 stocké. |
| API publique | mgs_ | 1 à 366 jours | Portées limitatives : events.read, alerts.read, etc. | Secret affiché une seule fois, SHA-256 stocké. |
| Service de licence | mgls_ | 1 à 366 jours | Portées limitatives : tenants.read, tenants.write. | Secret affiché une seule fois. |
Codes d'erreur HTTP
| Code | Signification | Cas typique |
|---|---|---|
| 200 | Succès. | Opération standard. |
| 201 | Créé. | Enrôlement réussi. |
| 202 | Accepté. | Lot d'événements pris en charge. |
| 304 | Non modifié. | Configuration ou catalogue à jour. |
| 400 | Requête invalide. | Syntaxe JSON ou NDJSON incorrecte. |
| 401 | Non authentifié. | Certificat mTLS absent, jeton invalide. |
| 403 | Interdit. | Portées insuffisantes pour l'action. |
| 404 | Ressource inconnue. | Modèle ou tableau de bord inexistant. |
| 409 | Conflit. | Enrôlement déjà effectué pour ce poste. |
| 413 | Trop volumineux. | Lot supérieur à 1 Mo compressé. |
| 422 | Entité non traitable. | Signature de configuration invalide. |
| 429 | Trop de requêtes. | Quota ou brute-force détecté. |
| 503 | Service 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 deServiceEntrysigné 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.