Edge

Ingest bounded runtime telemetry from a trusted sidecar

Changed on

Disabled by default. When CORDUM_EDGE_RUNTIME_INGEST_ENABLED is unset (or set to a non-truthy value), the route returns 503 service_unavailable and persists nothing. When enabled, the endpoint accepts a bounded, redacted runtime event batch (process exec, file read/write, network connect, DNS query) from an authenticated runtime collector holding edge.runtime.ingest; generic job writers are forbidden. A bounded nonce is required by default and is checked against a Redis replay window scoped to (tenant, collector); duplicate nonce submissions return idempotent success without appending another copy. The request source.source_id must match the authenticated collector principal and the referenced session/execution must be bound to that collector before mapped AgentActionEvent records with layer=runtime and decision=RECORDED are persisted through the existing Edge store. Raw argv, file contents, packet payloads, DNS response bodies, request bodies, headers, secrets, and tokens are rejected at the strict-schema decode boundary. All-or-nothing batch acceptance — a single invalid envelope aborts the whole batch. See docs/edge/runtime-ingestion.md for the full contract.

post/api/v1/edge/runtime/events

Request

  • Base URL: http://localhost:8081
  • URL: http://localhost:8081/api/v1/edge/runtime/events
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Headers

X-Tenant-IDstring required

Tenant isolation header (required on all protected routes).

Request body

noncestring required

Required by default replay-protection nonce (UUIDv7 or random 128-bit value). Set CORDUM_EDGE_RUNTIME_REPLAY_REQUIRED=false only for transitional non-production clients that cannot yet send this field.

batch_idstring

Operator correlation identifier only; it is not used for replay protection.

Response

Duplicate nonce detected; replay suppressed idempotently

accepted_countinteger required
dropped_countinteger required
replayedboolean

True when a duplicate nonce was suppressed and no events were appended.

Changes