Sign in
Edge

Ingest one redacted shadow-agent finding

Changed on

Persists a single ShadowAgentFinding lifecycle record. Evidence must be either a bounded redacted summary or an artifact pointer; raw payloads are rejected. Observe/warn only — no enforcement, no remediation execution, no Cordum Job creation. Audit event shadow_agent.detected is emitted on success.

post/api/v1/edge/shadow-agents

Request

  • Base URL: http://localhost:8081
  • URL: http://localhost:8081/api/v1/edge/shadow-agents
  • 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

OR

Response

Shadow finding persisted

finding_idstring required

Server-generated id prefixed with edge_shadow_.

tenant_idstring required
owner_principal_idstring required
principal_idstring required

Detector identity (scanner principal); falls back to authenticated caller when omitted.

agent_productstring required
agent_idstring
hostnamestring
risk'low' | 'medium' | 'high' | 'critical' required
status'detected' | 'resolved' | 'suppressed' | 'managed_skip' required
evidence_typestring required
evidence_summarystring

Bounded (≤2 KiB) redacted summary safe to persist and return. Secret-shaped values are stripped at ingest.

redacted_pathstring

Home-prefix-stripped path; never an absolute developer-machine path.

detected_atstring date-time required
created_atstring date-time required
updated_atstring date-time required
resolved_atstring date-time nullable
resolved_bystring
resolution_reasonstring

Bounded (≤512 bytes) human reason supplied at resolve/suppress; secret markers stripped.

suppressed_untilstring date-time nullable

Optional hint for a time-bound suppression. The store does NOT auto-revert when the timestamp lapses.

metadataobject

Small free-form map (≤16 entries, ≤64-byte keys, ≤256-byte values).

source_type'local' | 'kubernetes' | 'ci' | 'network'

EDGE-143.5 §10.1 — detector-family identifier. Defaults to local on read for legacy EDGE-141 records.

source_idstring

Detector instance identifier.

cluster_idstring

Operator-configured K8s cluster name; empty for non-K8s sources.

namespacestring

K8s namespace; empty for non-K8s sources.

workload_kindstring

K8s kind (Deployment, StatefulSet, DaemonSet, ...) or empty.

workload_namestring
pod_uidstring

Optional pod UUID when the finding pins a specific pod.

ci_provider'github_actions' | 'gitlab_ci' | 'jenkins' | 'buildkite' | 'circleci' | 'other'

EDGE-143.5 §10.1 — CI provider; empty for non-CI sources.

repostring

org/repo for CI sources; composite-indexed with ci_provider.

refstring
workflow_idstring
job_idstring
run_idstring
runner_idstring
tenant_sourcestring

Audit trail for tenant-attribution decisions (see §6.1 / §6.3).

principal_sourcestring

Audit trail for principal-attribution decisions (see §6.2 / §6.4).

signal_setstring[]

Bounded enum-shape signal identifiers from §7.1 / §8.x. Supports any-of filtering via the signal query param.

confidencenumber float

Detector self-rated confidence in [0, 1].

first_seenstring date-time nullable

Distinct from observed_at; populated by detectors with longitudinal tracking.

last_seenstring date-time nullable

Updated on every re-observation.

false_positive_reasonstring

Populated when status would be managed_skip per §10.3.

exception_idstring

Joins to operator-defined exception declarations (§10.3).

retention_class'shadow_short' | 'shadow_default' | 'shadow_long'

EDGE-143.5 §10.5 — per-finding terminal-TTL class. Empty falls back to the store's terminalRetention.

Changes