Cortex API

Plans, kill chains, overrides, fleet sweeps, reasoning chains, and Hive network endpoints.

Plans

An API key with alerts:read can read plans, the summary, context, kill chains and Hive status, and one with actions:write can approve or deny plan steps with POST /api/v1/cortex/plans/:id/approve or /deny. Routes marked dashboard, org admins only need a signed-in admin session; API keys get 403 there.

Analysis and sweeps

Both need a signed-in org admin session in the dashboard; API keys cannot start analysis or sweeps.

Kill chains (MITRE ATT&CK)

A kill chain is opened when Cortex links several stages of an attack (MITRE ATT&CK tactics) on the same server. Each chain lists the stages seen, how long the attacker has been present, and a recommended next step. A chain, abridged:

{
  "id": 42,
  "serverId": "4f2a9c1e8b7d6a50",
  "hostname": "api-prod",
  "currentStage": "privilege_escalation",
  "stageCount": 2,
  "firstDetectedAt": 1792548912456,
  "lastUpdatedAt": 1792551012456,
  "dwellTimeMs": 2100000,
  "tacticsObserved": ["initial_access", "privilege_escalation"],
  "tacticsRemaining": ["defense_evasion", "credential_access", "..."],
  "recommendedNextAction": "...",
  "timeline": [
    { "ts": 1792548912456, "stage": "initial_access", "label": "...", "evidence": "...", "severity": "high" }
  ]
}

Summary and context

Threat sharing

Warnings between your own servers are always on and stay inside your organization. Sharing between organizations is off unless you opt in (Fleet → Threat intel): organizations that opt in share attacker IP addresses and attack types with each other; your servers and data are never shared. Organizations that have not opted in neither share nor receive.

Cortex and webhooks

Cortex has no webhook events of its own. What it finds arrives as alert.* events (see API: Webhooks). Cortex plan steps waiting for approval are not sent as webhooks; poll /api/cortex/plans/active or /api/cortex/summary (pendingApprovals). Plans and kill chains are read with the endpoints above.

Tips

All Vigilhold docs · Start a 14-day free trial