resources/soc.ts

Source : sdks/typescript/packages/sdk/src/resources/soc.ts. Retour à l'index de la référence du SDK TypeScript.

remarque

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.

Interface SocDetection

Corps de SocResource.createDetection (POST /v1/soc/detections) : un événement suspect.

Champs :

Nom	Type	Requis	Description
kind	string	oui	Type de détection, parmi ceux de SocResource.catalog.
agent	string	non	Agent concerné.
confidence	number	non	Niveau de confiance de la détection.
data_classification	string	non	Classification des données concernées.
evidence	Doc	non	Preuves des mesures (journaux, horodatages, références de captures...).
fingerprint	string	non	Empreinte de la détection, pour regrouper les répétitions.
occurred_at	string	non	Date à laquelle le comportement détecté a eu lieu, au format ISO 8601.
resource	string	non	Ressource concernée.
run_id	string	non	Run concerné.
session_id	string	non	Session concernée.
severity	string	non	Gravité de la détection.
source	string	non	Source qui a émis la détection.
targets	Doc[]	non	Cibles des réactions du playbook, par clé session, run, agent, identity, credential, workload, mcp, plugin, tool, connector, knowledge_base, model ou application.
user	string	non	Utilisateur concerné, utilisé pour la corrélation.

Interface SocOrderCreate

Corps de SocResource.createOrder (POST /v1/soc/orders) : un ordre de réaction sur une cible.

Champs :

Nom	Type	Requis	Description
reaction	string	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.
reason	string	oui	Raison de l'action. Inscrite dans le journal d'audit avec l'acteur et l'heure.
target	Doc	oui	Cible de la réaction.
confidence	number	non	Niveau de confiance à l'origine de l'ordre.
incident_id	string	non	Incident auquel l'ordre se rattache, facultatif (404 s'il est inconnu).
max_blast_radius	number	non	Nombre maximal d'objets que l'ordre peut toucher (1 ou plus) ; au-delà, l'ordre est refusé.
params	Doc	non	Paramètres de la réaction.

Classe SocResource

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

SocResource.addEvidence

addEvidence(incidentId: string, body: { content: Doc | string; kind?: string }, opts?: CallOptions)

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
incidentId	string		oui	Identifiant (UUID) de l'incident.
body	{ content: Doc | string; kind?: string }		oui	Type et contenu de la preuve.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.approveOrder

approveOrder(orderId: string, opts?: CallOptions)

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
orderId	string		oui	Identifiant (UUID) de l'ordre de confinement.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.approveRecovery

approveRecovery(recoveryId: string, body: { reason?: string } = {}, opts?: CallOptions)

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
recoveryId	string		oui	Identifiant (UUID) de la demande de rétablissement.
body	{ reason?: string }	{}	non	Note facultative de l'approbation.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.catalog

catalog(opts?: CallOptions)

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).

Nom	Type	Défaut	Requis	Description
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.createDetection

createDetection(body: SocDetection, opts?: CallOptions)

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
body	SocDetection		oui	La détection à ingérer.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.createOrder

createOrder(body: SocOrderCreate, opts?: CallOptions)

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
body	SocOrderCreate		oui	Réaction, cible, incident, raison, paramètres et limites de l'ordre.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.custody

custody(incidentId: string, opts?: CallOptions)

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
incidentId	string		oui	Identifiant (UUID) de l'incident.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.exportEvidence

exportEvidence(incidentId: string, opts?: CallOptions)

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
incidentId	string		oui	Identifiant (UUID) de l'incident.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.getOrder

getOrder(orderId: string, opts?: CallOptions)

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
orderId	string		oui	Identifiant (UUID) de l'ordre de confinement.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.listDetections

listDetections(params?: ListParams & { incident_id?: string; kind?: string }, opts?: CallOptions)

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
params	ListParams & { incident_id?: string; kind?: string }		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.listEvidence

listEvidence(incidentId: string, opts?: CallOptions)

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
incidentId	string		oui	Identifiant (UUID) de l'incident.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.listKillSwitches

listKillSwitches(query: { state?: string } = {}, opts?: CallOptions)

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
query	{ state?: string }	{}	non	Paramètres de la chaîne de requête de la route.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.listOrders

listOrders(params?: ListParams & { incident_id?: string; status?: string }, opts?: CallOptions)

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
params	ListParams & { incident_id?: string; status?: string }		non	Champs supplémentaires fusionnés dans la requête.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.listRecoveries

listRecoveries(query: { status?: string } = {}, opts?: CallOptions)

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
query	{ status?: string }	{}	non	Paramètres de la chaîne de requête de la route.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.listTransactions

listTransactions(query: { run_id?: string; status?: string } = {}, opts?: CallOptions)

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
query	{ run_id?: string; status?: string }	{}	non	Paramètres de la chaîne de requête de la route.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.reauthorizeRecovery

reauthorizeRecovery(recoveryId: string, opts?: CallOptions)

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
recoveryId	string		oui	Identifiant (UUID) de la demande de rétablissement.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.reconcileTransaction

reconcileTransaction(transactionId: string, body: { outcome: string; note?: string; provider_reference?: string }, opts?: CallOptions)

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
transactionId	string		oui	Identifiant de la transaction à effet de bord.
body	{ outcome: string; note?: string; provider_reference?: string }		oui	Résultat, référence du fournisseur et note.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.rejectOrder

rejectOrder(orderId: string, body: { reason?: string } = {}, opts?: CallOptions)

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
orderId	string		oui	Identifiant (UUID) de l'ordre de confinement.
body	{ reason?: string }	{}	non	Raison facultative de la décision.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.requestRecovery

requestRecovery(body: { kill_switch_id: string; reason: string }, opts?: CallOptions)

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
body	{ kill_switch_id: string; reason: string }		oui	Coupe-circuit et raison.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.submitReceipt

submitReceipt(payload: string | Uint8Array, opts?: CallOptions)

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
payload	string | Uint8Array		oui	Corps JSON brut et signé de l'accusé (application/octet-stream), vérifié octet par octet.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.verifyKillSwitch

verifyKillSwitch(switchId: string, opts?: CallOptions)

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
switchId	string		oui	Identifiant (UUID) du coupe-circuit.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).

SocResource.webhook

webhook(source: string, payload: string | Uint8Array, opts?: CallOptions)

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	string		oui	Détecteur : falco, tetragon ou opensearch.
payload	string | Uint8Array		oui	Corps JSON brut et signé (application/octet-stream) : un événement ou une liste d'événements du détecteur.
opts	CallOptions		non	Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes).

Erreurs levées : les erreurs typées du transport (Erreurs).