enterprise_ai.soc
Source : sdks/python/src/enterprise_ai/soc/__init__.py. Retour à l'index de la référence du SDK Python.
Cette page est générée par tools/docs/gen_sdk_reference.py depuis les sources du SDK et les dossiers de textes OpenAPI. Ne la modifiez pas à la main : changez la source et régénérez.
Classe SocClient
SOC et réponse aux incidents IA. Opérations de sécurité pour l'IA (AI-SDR) : détections, ordres de confinement typés, registre des coupe-circuits (Kill Switch Registry), accusés de confinement, rétablissement à quatre yeux, preuves scellées des incidents et rapprochement des transactions à effet de bord.
Resource
SocClient.add_evidence
add_evidence(incident_id: str, content: object, kind: str | None = None) -> Any
Sceller une preuve sur un incident. Ajoute un enregistrement scellé à la chaîne de preuves de l'incident : l'empreinte du contenu et celle de l'enregistrement précédent, si bien qu'un enregistrement supprimé, réordonné ou modifié rompt la chaîne. Les enregistrements ne peuvent jamais être modifiés ni supprimés. Exige security_officer, soc_analyst ou tenant_admin. Écrit l'événement d'audit soc.evidence.seal et une entrée de traçabilité. Répond 201 avec seq, kind, content_sha256, prev_hash, hash, sealed_by et sealed_at.
Route : /v1/soc/incidents/{incident_id}/evidence (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
incident_id | str | oui | Identifiant (UUID) de l'incident. | |
content | object | oui | Contenu de l'enregistrement, un objet JSON ; seule son empreinte entre dans la chaîne à côté de lui. | |
kind | str | None | None | non | Type d'enregistrement, 1 à 64 caractères, note par défaut. |
Retour : Any. Réponse JSON décodée de l'opération « Sceller une preuve sur un incident ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.approve_order
approve_order(order_id: str) -> Any
Approuver un ordre de confinement. Approuve un ordre en attente d'une seconde personne et l'applique (coupe-circuit écrit, adaptateur lancé). Exige security_officer ou tenant_admin (responsable SOC), qui n'est pas le demandeur (409 separation_of_duties). Un ordre qui n'est pas en attente répond 409 order_not_pending ; un ordre inconnu 404.
Route : /v1/soc/orders/{order_id}/approve (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
order_id | str | oui | Identifiant (UUID) de l'ordre de confinement. |
Retour : Any. Réponse JSON décodée de l'opération « Approuver un ordre de confinement ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.approve_recovery
approve_recovery(recovery_id: str, reason: str | None = None) -> Any
Approuver un rétablissement. Enregistre une approbation d'un rétablissement en attente ; deux responsables SOC distincts sont nécessaires, aucun n'étant le demandeur (409 separation_of_duties), chacun approuvant une seule fois (409 already_approved). Exige security_officer ou tenant_admin (responsable SOC). Une demande qui n'est pas en attente répond 409 recovery_not_pending.
Route : /v1/soc/recoveries/{recovery_id}/approve (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
recovery_id | str | oui | Identifiant (UUID) de la demande de rétablissement. | |
reason | str | None | None | non | Raison ou note, 2000 caractères au plus (vide par défaut). Inscrite dans le journal d'audit. |
Retour : Any. Réponse JSON décodée de l'opération « Approuver un rétablissement ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.catalog
catalog() -> Any
Lire le catalogue SOC. Renvoie les listes autorisées : reactions, les types de cibles admis par réaction (targets), les types de détections avec leur gravité de base et leur playbook (detections), les limites de la garde de proportionnalité (response : confiance minimale, rayon d'impact automatique maximal, rayon d'impact exigeant une validation manuelle, réactions toujours soumises à validation) et les rôles SOC. Ouvert à tout membre du tenant.
Route : /v1/soc/catalog (GET).
Cet élément ne prend aucun paramètre.
Retour : Any. Réponse JSON décodée de l'opération « Lire le catalogue SOC ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.create_detection
create_detection(kind: str, severity: str | None = None, confidence: float | None = None, source: str | None = None, fingerprint: str | None = None, agent: str | None = None, user: str | None = None, run_id: str | None = None, session_id: str | None = None, resource: str | None = None, targets: list[dict[str, Any]] | None = None, data_classification: str | None = None, evidence: dict[str, Any] | None = None, occurred_at: str | None = None, **extra: Any) -> Any
Signaler une détection. Ingère une détection. Exige un identifiant auquel la portée soc:detections a été accordée explicitement (la portée globale * ne compte pas), ou security_officer, agent ou soc_analyst.
Route : /v1/soc/detections (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kind | str | oui | Type de détection : prompt_injection, data_exfiltration, secret_leak, runaway_agent, cost_loop, mcp_compromised, unsigned_plugin, privilege_escalation, rag_poisoning, policy_change_unaudited, policy_change_unauthorized, audit_tampering, runtime_threat, security_finding. | |
severity | str | None | None | non | sev1 à sev4. Par défaut : la gravité de base du type. |
confidence | float | None | None | non | Confiance du détecteur, de 0 à 1 (0,5 par défaut). Le confinement automatique exige au moins 0,9. |
source | str | None | None | non | Source : guard, dlp, egress, quota, plugins, runtime, authz, policy, audit, knowledge, mcp, falco, tetragon, opensearch ou manual (par défaut). |
fingerprint | str | None | None | non | Clé de dédoublonnage du constat, 200 caractères au plus. |
agent | str | None | None | non | Agent concerné, utilisé pour la corrélation. |
user | str | None | None | non | Utilisateur concerné, utilisé pour la corrélation. |
run_id | str | None | None | non | Exécution d'agent concernée. |
session_id | str | None | None | non | Session concernée. |
resource | str | None | None | non | Ressource concernée, objet libre comme {"type": "tool", "id": "..."}. |
targets | list[dict[str, Any]] | None | None | non | Cibles des réactions du playbook, par clé session, run, agent, identity, credential, workload, mcp, plugin, tool, connector, knowledge_base, model ou application. |
data_classification | str | None | None | non | Classification des données en jeu : public à secret. |
evidence | dict[str, Any] | None | None | non | Éléments de preuve du constat, 64000 octets au plus, scellés avec l'incident. |
occurred_at | str | None | None | non | Moment des faits (ISO 8601). Par défaut : l'heure de réception. |
**extra | Any | non | Champs supplémentaires fusionnés dans le corps de la requête. |
Retour : Any. Réponse JSON décodée de l'opération « Signaler une détection ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.create_order
create_order(reaction: str, target: dict[str, Any], reason: str, incident_id: str | None = None, confidence: float | None = None, max_blast_radius: int | None = None, params: dict[str, Any] | None = None, **extra: Any) -> Any
Ordonner un confinement. Crée un ordre de confinement manuel. Exige security_officer, soc_analyst ou tenant_admin.
Route : /v1/soc/orders (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
reaction | str | oui | Réaction typée : BLOCK_REQUEST, RATE_LIMIT, REQUIRE_APPROVAL, CANCEL_RUN, CANCEL_SUBAGENTS, SUSPEND_AGENT, SUSPEND_APPLICATION, DISABLE_TOOL, QUARANTINE_CONNECTOR, REVOKE_CREDENTIAL, DISABLE_MODEL_ROUTE, ISOLATE_NETWORK, TERMINATE_WORKLOAD, SUSPEND_IDENTITY, SUSPEND_TENANT, EMERGENCY_LOCKDOWN. | |
target | dict[str, Any] | oui | Cible typée de la réaction. | |
reason | str | oui | Raison du confinement, 3 à 2000 caractères. | |
incident_id | str | None | None | non | Incident auquel l'ordre se rattache, facultatif (404 s'il est inconnu). |
confidence | float | None | None | non | Confiance de la décision, de 0 à 1 (1 par défaut). |
max_blast_radius | int | None | None | non | Nombre maximal d'objets que l'ordre peut toucher (1 ou plus) ; au-delà, l'ordre est refusé. |
params | dict[str, Any] | None | None | non | Paramètres de la réaction, par exemple un débit pour RATE_LIMIT. |
**extra | Any | non | Champs supplémentaires fusionnés dans le corps de la requête. |
Retour : Any. Réponse JSON décodée de l'opération « Ordonner un confinement ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.create_recovery
create_recovery(kill_switch_id: str, reason: str) -> Any
Demander le rétablissement d'un coupe-circuit. Ouvre une demande de rétablissement à quatre yeux pour un coupe-circuit actif. Exige security_officer, soc_analyst ou tenant_admin. Un coupe-circuit inconnu répond 404, un coupe-circuit qui n'est plus suspendu 409 kill_switch_not_active, un coupe-circuit avec une demande ouverte 409 recovery_already_open. Répond 201 avec la demande.
Route : /v1/soc/recoveries (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
kill_switch_id | str | oui | Coupe-circuit à lever. | |
reason | str | oui | Raison pour laquelle le confinement peut cesser, 3 à 2000 caractères. |
Retour : Any. Réponse JSON décodée de l'opération « Demander le rétablissement d'un coupe-circuit ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.custody
custody(incident_id: str) -> Any
Lire la chaîne de traçabilité. Renvoie le journal de traçabilité des preuves de l'incident (qui a scellé, lu ou exporté quoi, et quand) avec la vérification des deux chaînes de hachage. Exige security_officer, tenant_admin, auditor ou soc_analyst. La lecture elle-même est ajoutée au journal de traçabilité. Répond 404 not_found pour un incident inconnu.
Route : /v1/soc/incidents/{incident_id}/custody (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
incident_id | str | oui | Identifiant (UUID) de l'incident. |
Retour : Any. Réponse JSON décodée de l'opération « Lire la chaîne de traçabilité ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.export_evidence
export_evidence(incident_id: str) -> Any
Exporter les preuves d'un incident. Renvoie l'incident, ses preuves, les deux chaînes vérifiées et le journal de traçabilité. Le paquet est analysé à la recherche d'identifiants secrets avant que le moindre octet ne sorte : si l'un est trouvé, l'export est refusé avec 422 secret_detected, le refus est inscrit dans le journal de traçabilité et une détection secret_leak est levée. Exige security_officer, tenant_admin, auditor ou soc_analyst.
Route : /v1/soc/incidents/{incident_id}/evidence/export (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
incident_id | str | oui | Identifiant (UUID) de l'incident. |
Retour : Any. Réponse JSON décodée de l'opération « Exporter les preuves d'un incident ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.get_order
get_order(order_id: str) -> Any
Lire un ordre de confinement. Renvoie l'ordre avec son dernier coupe-circuit et les accusés reçus pour lui. Exige security_officer, tenant_admin, auditor ou soc_analyst. Répond 404 not_found.
Route : /v1/soc/orders/{order_id} (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
order_id | str | oui | Identifiant (UUID) de l'ordre de confinement. |
Retour : Any. Réponse JSON décodée de l'opération « Lire un ordre de confinement ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.list_detections
list_detections(incident_id: str | None = None, kind: str | None = None, limit: int | None = None) -> Any
Lister les détections. Liste les détections du tenant, les plus récentes d'abord, éventuellement pour un incident ou un type. Exige security_officer, tenant_admin, auditor ou soc_analyst. La lecture est auditée.
Route : /v1/soc/detections (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
incident_id | str | None | None | non | Uniquement les détections corrélées dans cet incident. |
kind | str | None | None | non | Uniquement ce type de détection, par exemple prompt_injection. |
limit | int | None | None | non | Nombre maximal de détections (100 par défaut, 500 au maximum). |
Retour : Any. Réponse JSON décodée de l'opération « Lister les détections ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.list_evidence
list_evidence(incident_id: str) -> Any
Lire les preuves d'un incident. Renvoie les preuves scellées de l'incident (détections, ordres, accusés, notes), la vérification de leur chaîne et custody_seq, l'entrée de traçabilité créée par cette lecture. Exige security_officer, tenant_admin, auditor ou soc_analyst. Répond 404 not_found.
Route : /v1/soc/incidents/{incident_id}/evidence (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
incident_id | str | oui | Identifiant (UUID) de l'incident. |
Retour : Any. Réponse JSON décodée de l'opération « Lire les preuves d'un incident ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.list_kill_switches
list_kill_switches(state: str | None = None) -> Any
Lister les coupe-circuits. Liste les coupe-circuits du tenant, les plus récents d'abord, 500 au plus : par défaut seulement ceux dont l'état voulu est SUSPENDED. Chacun donne réaction, cible, états voulu et observé, dernier accusé et levée. Exige security_officer, tenant_admin, auditor ou soc_analyst. La lecture est auditée.
Route : /v1/soc/kill-switches (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
state | str | None | None | non | active (par défaut, suspendus uniquement) ou all. |
Retour : Any. Réponse JSON décodée de l'opération « Lister les coupe-circuits ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.list_orders
list_orders(incident_id: str | None = None, status: str | None = None, limit: int | None = None) -> Any
Lister les ordres de confinement. Liste les ordres de confinement du tenant, les plus récents d'abord, éventuellement par statut (pending_approval, applied, rejected...) ou par incident. Chacun donne réaction, cible, rayon d'impact, confiance, gravité, mode (manual ou automatique), statut et décision du moteur de politique de réponse. Exige security_officer, tenant_admin, auditor ou soc_analyst.
Route : /v1/soc/orders (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
incident_id | str | None | None | non | Uniquement les ordres de cet incident. |
status | str | None | None | non | Uniquement les ordres dans ce statut, par exemple pending_approval. |
limit | int | None | None | non | Nombre maximal d'ordres (100 par défaut, 500 au maximum). |
Retour : Any. Réponse JSON décodée de l'opération « Lister les ordres de confinement ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.list_recoveries
list_recoveries(status: str | None = None) -> Any
Lister les demandes de rétablissement. Liste les demandes de rétablissement du tenant, les plus récentes d'abord, 500 au plus, éventuellement par statut, avec leurs approbations. Exige security_officer, tenant_admin, auditor ou soc_analyst.
Route : /v1/soc/recoveries (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
status | str | None | None | non | Uniquement les demandes dans ce statut, par exemple pending, approved ou recovered. |
Retour : Any. Réponse JSON décodée de l'opération « Lister les demandes de rétablissement ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.list_transactions
list_transactions(run_id: str | None = None, status: str | None = None) -> Any
Lister les transactions à effet de bord. Liste les appels d'outils et de connecteurs à effet de bord du tenant, les plus récents d'abord, 500 au plus : clé d'idempotence, opération, statut (in_flight, committed, interrupted, reconciled, compensating, compensated...) et rapprochement. Exige security_officer, tenant_admin, auditor ou soc_analyst.
Route : /v1/soc/transactions (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
run_id | str | None | None | non | Uniquement les transactions de cette exécution d'agent. |
status | str | None | None | non | Uniquement les transactions dans ce statut, par exemple interrupted. |
Retour : Any. Réponse JSON décodée de l'opération « Lister les transactions à effet de bord ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.reauthorize_recovery
reauthorize_recovery(recovery_id: str) -> Any
Réautoriser et rétablir. Dernière étape d'un rétablissement, par l'un des approbateurs (403 reauthorization_by_approver sinon) une fois les deux approbations obtenues (409 recovery_not_approved). Le coupe-circuit est levé, la cible est réévaluée par la politique, qui doit l'autoriser (403 reauthorization_denied, tout est annulé), et seulement alors le plan propriétaire est rétabli, par exemple un agent repris. Une clé d'API révoquée le reste : émettez-en une nouvelle. Exige security_officer ou tenant_admin (responsable SOC).
Route : /v1/soc/recoveries/{recovery_id}/reauthorize (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
recovery_id | str | oui | Identifiant (UUID) de la demande de rétablissement. |
Retour : Any. Réponse JSON décodée de l'opération « Réautoriser et rétablir ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.reconcile_transaction
reconcile_transaction(transaction_id: str, outcome: str, note: str | None = None, provider_reference: str | None = None) -> Any
Rapprocher une transaction. Enregistre le résultat réel d'un appel à effet de bord dont l'issue est inconnue (interrompu par un coupe-circuit, une panne ou un délai dépassé) : committed (il a eu lieu chez le fournisseur) ou not_executed. Une nouvelle tentative avec la même clé d'idempotence renvoie alors le résultat enregistré au lieu de rappeler le fournisseur. Exige security_officer ou tenant_admin (responsable SOC). Un résultat inconnu répond 400, une transaction non rapprochable 409 transaction_not_reconcilable, une transaction inconnue 404.
Route : /v1/soc/transactions/{transaction_id}/reconcile (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
transaction_id | str | oui | Identifiant de la transaction à effet de bord. | |
outcome | str | oui | committed (elle a eu lieu chez le fournisseur) ou not_executed. | |
note | str | None | None | non | Note du rapprochement, 2000 caractères au plus. |
provider_reference | str | None | None | non | Référence de l'opération chez le fournisseur, 300 caractères au plus. |
Retour : Any. Réponse JSON décodée de l'opération « Rapprocher une transaction ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.reject_order
reject_order(order_id: str, reason: str | None = None) -> Any
Refuser un ordre de confinement. Refuse un ordre en attente de validation, avec une raison facultative. Exige security_officer ou tenant_admin (responsable SOC). Un ordre qui n'est pas en attente répond 409 order_not_pending ; un ordre inconnu 404.
Route : /v1/soc/orders/{order_id}/reject (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
order_id | str | oui | Identifiant (UUID) de l'ordre de confinement. | |
reason | str | None | None | non | Raison ou note, 2000 caractères au plus (vide par défaut). Inscrite dans le journal d'audit. |
Retour : Any. Réponse JSON décodée de l'opération « Refuser un ordre de confinement ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.submit_receipt
submit_receipt(receipt: bytes, content_type: str = 'application/octet-stream') -> Any
Recevoir un accusé de confinement du cluster. Accusé envoyé depuis le cluster (politique Cilium observée, charge de travail ramenée à zéro) pour une réaction de cluster : JSON {kill_switch_id, verified, adapter, evidence}. Signé comme les webhooks de la plateforme : X-EAI-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>." + corps)>, une fenêtre anti-rejeu de 5 minutes, X-EAI-Delivery pour le dédoublonnage et X-EAI-Tenant (identifiant court du tenant). Sans le secret de webhook SOC configuré, toute livraison est refusée. Chaque livraison, acceptée ou non, est enregistrée et auditée. Un accusé vérifié fait passer l'état observé à SUSPENDED_VERIFIED ; un accusé pour une réaction qui n'en attend pas répond 409 receipt_not_expected. Aucun identifiant d'utilisateur n'est nécessaire : la signature authentifie l'émetteur. Répond 202 avec le coupe-circuit.
Route : /v1/soc/receipts (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
receipt | bytes | oui | Reçu d'application signé, envoyé en octets bruts. | |
content_type | str | 'application/octet-stream' | non | Type de contenu transmis au stockage lors de la signature de l'URL (le type que l'envoi doit transmettre) ; 200 caractères au plus. |
Retour : Any. Réponse JSON décodée de l'opération « Recevoir un accusé de confinement du cluster ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.verify_kill_switch
verify_kill_switch(switch_id: str) -> Any
Vérifier un coupe-circuit. Lance la sonde du vérificateur de confinement pour le coupe-circuit : en cas de succès, l'état observé passe à SUSPENDED_VERIFIED. Les réactions de cluster (ISOLATE_NETWORK, TERMINATE_WORKLOAD) ne sont vérifiées que par un accusé signé depuis le cluster. Exige security_officer, soc_analyst ou tenant_admin. Écrit l'événement d'audit soc.kill_switch.verify. Répond 404 not_found.
Route : /v1/soc/kill-switches/{switch_id}/verify (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
switch_id | str | oui | Identifiant (UUID) du coupe-circuit. |
Retour : Any. Réponse JSON décodée de l'opération « Vérifier un coupe-circuit ».
Erreurs levées : les erreurs typées du transport (Erreurs).
SocClient.webhook
webhook(source: str, payload: bytes, headers: dict[str, str] | None = None) -> Any
Recevoir des constats de sécurité externes. Webhook des détecteurs externes : Falco, Tetragon ou OpenSearch Security Analytics. Le corps est un événement ou une liste (200 au plus traités), normalisés en détections (priorités Falco et étiquettes eai_* associées à des types et des gravités) et ingérés comme POST /v1/soc/detections. Signé comme les webhooks de la plateforme : X-EAI-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>." + corps)>, une fenêtre anti-rejeu de 5 minutes, X-EAI-Delivery pour le dédoublonnage et X-EAI-Tenant (identifiant court du tenant). Sans le secret de webhook SOC configuré, toute livraison est refusée. Chaque livraison, acceptée ou non, est enregistrée et auditée. Une source inconnue répond 404. Répond 202 avec received et les détections.
Route : /v1/soc/webhooks/{source} (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
source | str | oui | Détecteur : falco, tetragon ou opensearch. | |
payload | bytes | oui | Corps JSON brut et signé (application/octet-stream) : un événement ou une liste d'événements du détecteur. | |
headers | dict[str, str] | None | None | non | En-têtes de l'événement, valeurs textuelles. Le contexte de trace y est ajouté. |
Retour : Any. Réponse JSON décodée de l'opération « Recevoir des constats de sécurité externes ».
Erreurs levées : les erreurs typées du transport (Erreurs).