Threat Detections

How behavioral anomalies are persisted and resolved

Status: schema + API shipped; writes gated by Stage 1. Detections are created once Stage 1 exits shadow mode; today the table schema, ingest path, and REST endpoints exist but are sparsely populated.

Threat Detections

When the behavioral engine classifies an action as ANOMALOUS, the event pipeline creates a threat detection record. Detections are persistent, queryable, and have a resolution workflow.

Detection Flow

Detection Record

Each detection captures the behavioral signals and action context:

Field	Description
detection_type	behavioral, canary, policy, capability_invariant
severity	critical (score >= 0.9), high (>= 0.7), medium (>= 0.4), low
confidence_band	UNCERTAIN or ANOMALOUS
deviation_score	Composite threat score from Gate 2+3 signals
fired_signals	Array of signal names (e.g., bloom:novel_tool, jsd:capability_shift)
gate_reached	Which gate produced the classification
canonical_key	The action’s canonical identity (e.g., mcp:github:delete_repo.delete)
capabilities	Capability tags (e.g., data:delete, net:outbound)

API Endpoints

List Detections

GET /v1/detections?status=open&severity=high&type=behavioral&since=2026-04-01&limit=50

Filterable by status, severity, detection type, date range. Paginated. Ordered by created_at DESC.

Get Detection Detail

GET /v1/detections/{id}

Returns the full detection record including action context and fired signals.

Resolve Detection

PUT /v1/detections/{id}
{
  "status": "resolved",
  "resolution_note": "Confirmed false positive — developer testing new tool",
  "resolved_by": "[e-mail]"
}

Valid statuses: investigating, resolved, false_positive.

Resolution Workflow

Status	Meaning	Next Steps
open	New detection, unreviewed	Triage — investigate or dismiss
investigating	Under review	Analyze action context, check session timeline
resolved	Confirmed threat, addressed	Document resolution, update policies if needed
false_positive	Not a real threat	Feeds back into threshold calibration

Severity Mapping

Severity is computed from the behavioral deviation score:

Score Range	Severity	Typical Cause
>= 0.9	critical	Multiple structural signals + dangerous capability pair
>= 0.7	high	3+ corroborating signals with session escalation
>= 0.4	medium	Corroborated signals without structural evidence
< 0.4	low	Overwhelming statistical signals (5+) without structure