enterprise_ai.soc

Source: sdks/python/src/enterprise_ai/soc/__init__.py. Back to the Python SDK reference index.

note

This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.

Class SocClient

/v1/soc.

Resource

SocClient.add_evidence

add_evidence(incident_id: str, content: object, kind: str | None = None) -> Any

Seal evidence on an incident. Appends a sealed record to the evidence chain of the incident: the content hash and the hash of the previous record, so that a removed, reordered or modified record breaks the chain. Records can never be updated nor deleted. Needs security_officer, soc_analyst or tenant_admin. Writes the audit event soc.evidence.seal and a custody entry. Answers 201 with seq, kind, content_sha256, prev_hash, hash, sealed_by and sealed_at.

Route: /v1/soc/incidents/{incident_id}/evidence (POST).

Name	Type	Default	Required	Description
incident_id	str		yes	Identifier (UUID) of the incident.
content	object		yes	Content of the record, a JSON object; only its hash enters the chain next to it.
kind	str | None	None	no	Kind of record, 1 to 64 characters, note by default.

Returns: Any. Decoded JSON answer of the operation "Seal evidence on an incident".

Raises: the typed errors of the transport (Errors).

SocClient.approve_order

approve_order(order_id: str) -> Any

Approve a containment order. Approves an order waiting for a second person and applies it (kill switch written, adapter run). Needs security_officer or tenant_admin (SOC lead), who is not the requester (409 separation_of_duties). An order that is not pending answers 409 order_not_pending; an unknown one 404.

Route: /v1/soc/orders/{order_id}/approve (POST).

Name	Type	Default	Required	Description
order_id	str		yes	Identifier (UUID) of the containment order.

Returns: Any. Decoded JSON answer of the operation "Approve a containment order".

Raises: the typed errors of the transport (Errors).

SocClient.approve_recovery

approve_recovery(recovery_id: str, reason: str | None = None) -> Any

Approve a recovery. Records one approval of a pending recovery; two distinct SOC leads are required, neither being the requester (409 separation_of_duties), each approving once (409 already_approved). Needs security_officer or tenant_admin (SOC lead). A request that is not pending answers 409 recovery_not_pending.

Route: /v1/soc/recoveries/{recovery_id}/approve (POST).

Name	Type	Default	Required	Description
recovery_id	str		yes	Identifier (UUID) of the recovery request.
reason	str | None	None	no	Reason or note, at most 2000 characters (empty by default). Written to the audit trail.

Returns: Any. Decoded JSON answer of the operation "Approve a recovery".

Raises: the typed errors of the transport (Errors).

SocClient.catalog

catalog() -> Any

Get the SOC catalogue. Returns the allowlists: reactions, the target types allowed per reaction (targets), the detection kinds with their base severity and playbook (detections), the limits of the proportionality guard (response: minimum confidence, maximum automatic blast radius, blast radius needing a manual approval, reactions always needing approval) and the SOC roles. Open to any member of the tenant.

Route: /v1/soc/catalog (GET).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "Get the SOC catalogue".

Raises: the typed errors of the transport (Errors).

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

Report a detection. Ingests a detection. Needs a credential granted the scope soc:detections explicitly (the global * does not count), or security_officer, agent or soc_analyst.

Route: /v1/soc/detections (POST).

Name	Type	Default	Required	Description
kind	str		yes	Detection kind: 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	no	sev1 to sev4. Default: the base severity of the kind.
confidence	float | None	None	no	Confidence of the detector, 0 to 1 (default 0.5). Automatic containment needs at least 0.9.
source	str | None	None	no	Source: guard, dlp, egress, quota, plugins, runtime, authz, policy, audit, knowledge, mcp, falco, tetragon, opensearch or manual (default).
fingerprint	str | None	None	no	Deduplication key of the finding, at most 200 characters.
agent	str | None	None	no	Agent concerned, used for correlation.
user	str | None	None	no	User concerned, used for correlation.
run_id	str | None	None	no	Agent run concerned.
session_id	str | None	None	no	Session concerned.
resource	str | None	None	no	Resource concerned, free object such as {"type": "tool", "id": "..."}.
targets	list[dict[str, Any]] | None	None	no	Targets of the playbook reactions, keyed by session, run, agent, identity, credential, workload, mcp, plugin, tool, connector, knowledge_base, model or application.
data_classification	str | None	None	no	Classification of the data involved: public to secret.
evidence	dict[str, Any] | None	None	no	Evidence of the finding, at most 64000 bytes, sealed with the incident.
occurred_at	str | None	None	no	When it happened (ISO 8601). Default: the reception time.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Report a detection".

Raises: the typed errors of the transport (Errors).

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

Order a containment. Creates a manual containment order. Needs security_officer, soc_analyst or tenant_admin.

Route: /v1/soc/orders (POST).

Name	Type	Default	Required	Description
reaction	str		yes	Typed reaction: 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]		yes	Typed target of the reaction.
reason	str		yes	Why the containment is ordered, 3 to 2000 characters.
incident_id	str | None	None	no	Incident the order belongs to, optional (404 when unknown).
confidence	float | None	None	no	Confidence of the decision, 0 to 1 (default 1).
max_blast_radius	int | None	None	no	Largest number of objects the order may affect (1 or more); above it the order is refused.
params	dict[str, Any] | None	None	no	Parameters of the reaction, for example a rate for RATE_LIMIT.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Order a containment".

Raises: the typed errors of the transport (Errors).

SocClient.create_recovery

create_recovery(kill_switch_id: str, reason: str) -> Any

Request the recovery of a kill switch. Opens a four eyes recovery request for one active kill switch. Needs security_officer, soc_analyst or tenant_admin. An unknown switch answers 404, a switch no longer suspended 409 kill_switch_not_active, a switch with an open request 409 recovery_already_open. Answers 201 with the request.

Route: /v1/soc/recoveries (POST).

Name	Type	Default	Required	Description
kill_switch_id	str		yes	Kill switch to lift.
reason	str		yes	Why the containment can end, 3 to 2000 characters.

Returns: Any. Decoded JSON answer of the operation "Request the recovery of a kill switch".

Raises: the typed errors of the transport (Errors).

SocClient.custody

custody(incident_id: str) -> Any

Read the chain of custody. Returns the custody log of the incident evidence (who sealed, read or exported what, and when) with the verification of both hash chains. Needs security_officer, tenant_admin, auditor or soc_analyst. The read itself is added to the custody log. Answers 404 not_found for an unknown incident.

Route: /v1/soc/incidents/{incident_id}/custody (GET).

Name	Type	Default	Required	Description
incident_id	str		yes	Identifier (UUID) of the incident.

Returns: Any. Decoded JSON answer of the operation "Read the chain of custody".

Raises: the typed errors of the transport (Errors).

SocClient.export_evidence

export_evidence(incident_id: str) -> Any

Export the evidence of an incident. Returns the incident, its evidence records, both chains verified and the custody log. The bundle is scanned for credentials before any byte leaves: when one is found the export is refused with 422 secret_detected, the refusal is recorded in the custody log and a secret_leak detection is raised. Needs security_officer, tenant_admin, auditor or soc_analyst.

Route: /v1/soc/incidents/{incident_id}/evidence/export (POST).

Name	Type	Default	Required	Description
incident_id	str		yes	Identifier (UUID) of the incident.

Returns: Any. Decoded JSON answer of the operation "Export the evidence of an incident".

Raises: the typed errors of the transport (Errors).

SocClient.get_order

get_order(order_id: str) -> Any

Get a containment order. Returns the order with its latest kill switch and the receipts received for it. Needs security_officer, tenant_admin, auditor or soc_analyst. Answers 404 not_found.

Route: /v1/soc/orders/{order_id} (GET).

Name	Type	Default	Required	Description
order_id	str		yes	Identifier (UUID) of the containment order.

Returns: Any. Decoded JSON answer of the operation "Get a containment order".

Raises: the typed errors of the transport (Errors).

SocClient.list_detections

list_detections(incident_id: str | None = None, kind: str | None = None, limit: int | None = None) -> Any

List the detections. Lists the detections of the tenant, newest first, optionally for one incident or one kind. Needs security_officer, tenant_admin, auditor or soc_analyst. The read is audited.

Route: /v1/soc/detections (GET).

Name	Type	Default	Required	Description
incident_id	str | None	None	no	Only the detections correlated into this incident.
kind	str | None	None	no	Only this detection kind, for example prompt_injection.
limit	int | None	None	no	Maximum number of detections (default 100, maximum 500).

Returns: Any. Decoded JSON answer of the operation "List the detections".

Raises: the typed errors of the transport (Errors).

SocClient.list_evidence

list_evidence(incident_id: str) -> Any

Read the evidence of an incident. Returns the sealed evidence records of the incident (detections, orders, receipts, notes), the verification of their chain and custody_seq, the custody entry this read created. Needs security_officer, tenant_admin, auditor or soc_analyst. Answers 404 not_found.

Route: /v1/soc/incidents/{incident_id}/evidence (GET).

Name	Type	Default	Required	Description
incident_id	str		yes	Identifier (UUID) of the incident.

Returns: Any. Decoded JSON answer of the operation "Read the evidence of an incident".

Raises: the typed errors of the transport (Errors).

SocClient.list_kill_switches

list_kill_switches(state: str | None = None) -> Any

List the kill switches. Lists the kill switches of the tenant, newest first, at most 500: by default only those whose desired state is SUSPENDED. Each gives reaction, target, desired and observed state, last receipt and release. Needs security_officer, tenant_admin, auditor or soc_analyst. The read is audited.

Route: /v1/soc/kill-switches (GET).

Name	Type	Default	Required	Description
state	str | None	None	no	active (default, suspended only) or all.

Returns: Any. Decoded JSON answer of the operation "List the kill switches".

Raises: the typed errors of the transport (Errors).

SocClient.list_orders

list_orders(incident_id: str | None = None, status: str | None = None, limit: int | None = None) -> Any

List the containment orders. Lists the containment orders of the tenant, newest first, optionally by status (pending_approval, applied, rejected...) or incident. Each gives reaction, target, blast radius, confidence, severity, mode (manual or automatic), status and the decision of the Response Policy Engine. Needs security_officer, tenant_admin, auditor or soc_analyst.

Route: /v1/soc/orders (GET).

Name	Type	Default	Required	Description
incident_id	str | None	None	no	Only the orders of this incident.
status	str | None	None	no	Only the orders in this status, for example pending_approval.
limit	int | None	None	no	Maximum number of orders (default 100, maximum 500).

Returns: Any. Decoded JSON answer of the operation "List the containment orders".

Raises: the typed errors of the transport (Errors).

SocClient.list_recoveries

list_recoveries(status: str | None = None) -> Any

List the recovery requests. Lists the recovery requests of the tenant, newest first, at most 500, optionally by status, with their approvals. Needs security_officer, tenant_admin, auditor or soc_analyst.

Route: /v1/soc/recoveries (GET).

Name	Type	Default	Required	Description
status	str | None	None	no	Only the requests in this status, for example pending, approved or recovered.

Returns: Any. Decoded JSON answer of the operation "List the recovery requests".

Raises: the typed errors of the transport (Errors).

SocClient.list_transactions

list_transactions(run_id: str | None = None, status: str | None = None) -> Any

List the side effecting transactions. Lists the side effecting tool and connector calls of the tenant, newest first, at most 500: idempotency key, operation, status (in_flight, committed, interrupted, reconciled, compensating, compensated...) and reconciliation. Needs security_officer, tenant_admin, auditor or soc_analyst.

Route: /v1/soc/transactions (GET).

Name	Type	Default	Required	Description
run_id	str | None	None	no	Only the transactions of this agent run.
status	str | None	None	no	Only the transactions in this status, for example interrupted.

Returns: Any. Decoded JSON answer of the operation "List the side effecting transactions".

Raises: the typed errors of the transport (Errors).

SocClient.reauthorize_recovery

reauthorize_recovery(recovery_id: str) -> Any

Re-authorize and recover. Final step of a recovery, by one of the approvers (403 reauthorization_by_approver otherwise) once both approvals are in (409 recovery_not_approved). The switch is released, the target is re-evaluated by the policy, which must allow it (403 reauthorization_denied, everything rolled back), and only then the owning plane is restored, for example an agent resumed. A revoked API key stays revoked: issue a new one. Needs security_officer or tenant_admin (SOC lead).

Route: /v1/soc/recoveries/{recovery_id}/reauthorize (POST).

Name	Type	Default	Required	Description
recovery_id	str		yes	Identifier (UUID) of the recovery request.

Returns: Any. Decoded JSON answer of the operation "Re-authorize and recover".

Raises: the typed errors of the transport (Errors).

SocClient.reconcile_transaction

reconcile_transaction(transaction_id: str, outcome: str, note: str | None = None, provider_reference: str | None = None) -> Any

Reconcile a transaction. Records the real outcome of a side effecting call whose result is unknown (interrupted by a kill, a crash or a timeout): committed (it happened at the provider) or not_executed. A retry with the same idempotency key then returns the stored result instead of calling the provider again. Needs security_officer or tenant_admin (SOC lead). An unknown outcome answers 400, a transaction that cannot be reconciled 409 transaction_not_reconcilable, an unknown one 404.

Route: /v1/soc/transactions/{transaction_id}/reconcile (POST).

Name	Type	Default	Required	Description
transaction_id	str		yes	Identifier of the side effecting transaction.
outcome	str		yes	committed (it happened at the provider) or not_executed.
note	str | None	None	no	Note of the reconciliation, at most 2000 characters.
provider_reference	str | None	None	no	Reference of the operation at the provider, at most 300 characters.

Returns: Any. Decoded JSON answer of the operation "Reconcile a transaction".

Raises: the typed errors of the transport (Errors).

SocClient.reject_order

reject_order(order_id: str, reason: str | None = None) -> Any

Reject a containment order. Rejects an order waiting for approval, with an optional reason. Needs security_officer or tenant_admin (SOC lead). An order that is not pending answers 409 order_not_pending; an unknown one 404.

Route: /v1/soc/orders/{order_id}/reject (POST).

Name	Type	Default	Required	Description
order_id	str		yes	Identifier (UUID) of the containment order.
reason	str | None	None	no	Reason or note, at most 2000 characters (empty by default). Written to the audit trail.

Returns: Any. Decoded JSON answer of the operation "Reject a containment order".

Raises: the typed errors of the transport (Errors).

SocClient.submit_receipt

submit_receipt(receipt: bytes, content_type: str = 'application/octet-stream') -> Any

Receive an in-cluster containment receipt. Receipt sent from the cluster (Cilium policy observed, workload scaled to zero) for a cluster reaction: JSON {kill_switch_id, verified, adapter, evidence}. Signed like the platform webhooks: X-EAI-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>." + body)>, a 5 minute replay window, X-EAI-Delivery for deduplication and X-EAI-Tenant (tenant slug). Without the configured SOC webhook secret every delivery is refused. Every delivery, accepted or not, is recorded and audited. A verified receipt moves the observed state to SUSPENDED_VERIFIED; a receipt for a reaction that expects none answers 409 receipt_not_expected. No user credential is needed: the signature authenticates the sender. Answers 202 with the kill switch.

Route: /v1/soc/receipts (POST).

Name	Type	Default	Required	Description
receipt	bytes		yes	Signed enforcement receipt, sent as raw bytes.
content_type	str	'application/octet-stream'	no	Content type passed to the backend when the URL is signed (the type the upload is expected to send); 200 characters at most.

Returns: Any. Decoded JSON answer of the operation "Receive an in-cluster containment receipt".

Raises: the typed errors of the transport (Errors).

SocClient.verify_kill_switch

verify_kill_switch(switch_id: str) -> Any

Verify a kill switch. Runs the Containment Verifier probe of the switch: on success the observed state becomes SUSPENDED_VERIFIED. Cluster reactions (ISOLATE_NETWORK, TERMINATE_WORKLOAD) are verified only by a signed in-cluster receipt. Needs security_officer, soc_analyst or tenant_admin. Writes the audit event soc.kill_switch.verify. Answers 404 not_found.

Route: /v1/soc/kill-switches/{switch_id}/verify (POST).

Name	Type	Default	Required	Description
switch_id	str		yes	Identifier (UUID) of the kill switch.

Returns: Any. Decoded JSON answer of the operation "Verify a kill switch".

Raises: the typed errors of the transport (Errors).

SocClient.webhook

webhook(source: str, payload: bytes, headers: dict[str, str] | None = None) -> Any

Receive external security findings. Webhook of external detectors: Falco, Tetragon or OpenSearch Security Analytics. The body is one event or a list (at most 200 processed), normalized into detections (Falco priorities and eai_* tags mapped to kinds and severities) and ingested like POST /v1/soc/detections. Signed like the platform webhooks: X-EAI-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>." + body)>, a 5 minute replay window, X-EAI-Delivery for deduplication and X-EAI-Tenant (tenant slug). Without the configured SOC webhook secret every delivery is refused. Every delivery, accepted or not, is recorded and audited. An unknown source answers 404. Answers 202 with received and the detections.

Route: /v1/soc/webhooks/{source} (POST).

Name	Type	Default	Required	Description
source	str		yes	Detector: falco, tetragon or opensearch.
payload	bytes		yes	Raw signed JSON body (application/octet-stream): one event or a list of events of the detector.
headers	dict[str, str] | None	None	no	Headers of the event, string values. The trace context is added.

Returns: Any. Decoded JSON answer of the operation "Receive external security findings".

Raises: the typed errors of the transport (Errors).