resources/soc.ts

Source: sdks/typescript/packages/sdk/src/resources/soc.ts. Back to the TypeScript 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.

Interface SocDetection

Body of SocResource.createDetection (POST /v1/soc/detections): one suspicious event.

Fields:

Name	Type	Required	Description
kind	string	yes	Kind of detection, one of those of SocResource.catalog.
agent	string	no	Agent involved.
confidence	number	no	Confidence of the detection.
data_classification	string	no	Classification of the data involved.
evidence	Doc	no	Evidence of the measures (logs, timestamps, screenshots references...).
fingerprint	string	no	Fingerprint of the detection, to group repeats.
occurred_at	string	no	Time the detected behaviour happened, ISO 8601.
resource	string	no	Resource involved.
run_id	string	no	Run involved.
session_id	string	no	Session involved.
severity	string	no	Severity of the detection.
source	string	no	Source that raised the detection.
targets	Doc[]	no	Targets of the playbook reactions, keyed by session, run, agent, identity, credential, workload, mcp, plugin, tool, connector, knowledge_base, model or application.
user	string	no	User concerned, used for correlation.

Interface SocOrderCreate

Body of SocResource.createOrder (POST /v1/soc/orders): a reaction order on a target.

Fields:

Name	Type	Required	Description
reaction	string	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.
reason	string	yes	Why the action is taken. Written to the audit trail with the actor and the time.
target	Doc	yes	Target of the reaction.
confidence	number	no	Confidence behind the order.
incident_id	string	no	Incident the order belongs to, optional (404 when unknown).
max_blast_radius	number	no	Largest number of objects the order may affect (1 or more); above it the order is refused.
params	Doc	no	Parameters of the reaction.

Class SocResource

AI-SOC: detections, reaction orders, kill switches verified by receipts and four eyes recovery.

Resource

SocResource.addEvidence

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

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
incidentId	string		yes	Identifier (UUID) of the incident.
body	{ content: Doc | string; kind?: string }		yes	Kind and content of the evidence.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.approveOrder

approveOrder(orderId: string, opts?: CallOptions)

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
orderId	string		yes	Identifier (UUID) of the containment order.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.approveRecovery

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

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
recoveryId	string		yes	Identifier (UUID) of the recovery request.
body	{ reason?: string }	{}	no	Optional note of the approval.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.catalog

catalog(opts?: CallOptions)

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

Name	Type	Default	Required	Description
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.createDetection

createDetection(body: SocDetection, opts?: CallOptions)

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
body	SocDetection		yes	The detection to ingest.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.createOrder

createOrder(body: SocOrderCreate, opts?: CallOptions)

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
body	SocOrderCreate		yes	Reaction, target, incident, reason, parameters and limits of the order.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.custody

custody(incidentId: string, opts?: CallOptions)

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
incidentId	string		yes	Identifier (UUID) of the incident.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.exportEvidence

exportEvidence(incidentId: string, opts?: CallOptions)

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
incidentId	string		yes	Identifier (UUID) of the incident.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.getOrder

getOrder(orderId: string, opts?: CallOptions)

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
orderId	string		yes	Identifier (UUID) of the containment order.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.listDetections

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

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
params	ListParams & { incident_id?: string; kind?: string }		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.listEvidence

listEvidence(incidentId: string, opts?: CallOptions)

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
incidentId	string		yes	Identifier (UUID) of the incident.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.listKillSwitches

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

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
query	{ state?: string }	{}	no	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.listOrders

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

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
params	ListParams & { incident_id?: string; status?: string }		no	Extra fields merged into the request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.listRecoveries

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

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
query	{ status?: string }	{}	no	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.listTransactions

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

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
query	{ run_id?: string; status?: string }	{}	no	Query string parameters of the route.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.reauthorizeRecovery

reauthorizeRecovery(recoveryId: string, opts?: CallOptions)

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
recoveryId	string		yes	Identifier (UUID) of the recovery request.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.reconcileTransaction

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

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
transactionId	string		yes	Identifier of the side effecting transaction.
body	{ outcome: string; note?: string; provider_reference?: string }		yes	Outcome, provider reference and note.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.rejectOrder

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

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
orderId	string		yes	Identifier (UUID) of the containment order.
body	{ reason?: string }	{}	no	Optional reason of the decision.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.requestRecovery

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

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
body	{ kill_switch_id: string; reason: string }		yes	Kill switch and reason.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.submitReceipt

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

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
payload	string | Uint8Array		yes	Raw signed JSON body of the receipt (application/octet-stream), verified byte for byte.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.verifyKillSwitch

verifyKillSwitch(switchId: string, opts?: CallOptions)

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
switchId	string		yes	Identifier (UUID) of the kill switch.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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

SocResource.webhook

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

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	string		yes	Detector: falco, tetragon or opensearch.
payload	string | Uint8Array		yes	Raw signed JSON body (application/octet-stream): one event or a list of events of the detector.
opts	CallOptions		no	Per call options (query, idempotency key, traceparent, headers).

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