Incidents

An incident is the central unit of work in HLD Sentinel. Every detection, response action, and analyst note is tied to an incident with a full, immutable timeline.

The incident object

json

{
  "id": "inc_01hxyz",
  "tenant_id": "ten_01hxyz",
  "title": "Ransomware staging detected on ACME-WIN-0042",
  "severity": "critical",
  "status": "contained",
  "type": "ransomware",
  "source": "sentinel_autonomous",
  "affected_assets": [
    { "type": "device", "id": "dev_01hxyz", "label": "ACME-WIN-0042" },
    { "type": "user", "id": "idn_01hxyz", "label": "john@acme.com" }
  ],
  "response_actions_taken": ["isolate_device", "revoke_sessions"],
  "response_time_seconds": 38,
  "created_at": "2025-06-01T03:14:00Z",
  "contained_at": "2025-06-01T03:14:38Z",
  "resolved_at": null,
  "timeline_entries": 12
}

List incidents

bash

GET /v1/sentinel/incidents

Name	Type	Required	Description
filter[tenant_id]	string	No	Scope to a tenant.
filter[severity]	string	No	critical \| high \| medium \| low
filter[status]	string	No	open \| investigating \| contained \| resolved \| false_positive
filter[type]	string	No	ransomware \| data_exfil \| lateral_movement \| credential_attack \| insider_threat \| etc.
filter[created_after]	string	No	ISO 8601 timestamp.

Get an incident

bash

GET /v1/sentinel/incidents/:id

Get incident timeline

The timeline is a chronological, immutable log of every event in the incident, detections, actions, analyst notes, and state changes.

bash

GET /v1/sentinel/incidents/:id/timeline

json

{
  "incident_id": "inc_01hxyz",
  "entries": [
    {
      "timestamp": "2025-06-01T03:14:00Z",
      "type": "detection",
      "actor": "sentinel_autonomous",
      "description": "Ransomware staging behaviour detected. Confidence: 97%."
    },
    {
      "timestamp": "2025-06-01T03:14:09Z",
      "type": "action",
      "actor": "sentinel_autonomous",
      "description": "Device ACME-WIN-0042 isolated from network."
    },
    {
      "timestamp": "2025-06-01T03:14:38Z",
      "type": "action",
      "actor": "sentinel_autonomous",
      "description": "All sessions for john@acme.com revoked."
    }
  ]
}

Get incident narrative

After containment, Sentinel generates a plain-language write-up of the already-recorded evidence chain (rule matches, risk factors, policy-gate reasons, action outcomes). The write-up is stored alongside the hash-chained audit log. It is not the system of record for what happened — the deterministic audit trail is. Regenerating appends a new generation; previous write-ups are kept.

bash

GET /v1/sentinel/incidents/:id/narrative
GET /v1/sentinel/incidents/:id/narrative?history=true

json

{
  "incident_id": "inc_01hxyz",
  "system_of_record": false,
  "disclaimer": "This write-up explains the deterministic audit record; it is not itself evidence of what happened, and it is not the system of record.",
  "latest": {
    "id": "nar-1",
    "generation": 1,
    "status": "stub",
    "authored_by": "deterministic-stub",
    "model_id": "stub:deterministic-v1",
    "prompt_version": "sentinel-narrative-v1",
    "evidence_hash": "4b6a0c8e2f1d9a7c5e3b8f0a1c6d2e9b7a4f8c0d1e5b9a3c7f2d6e0b8a4c1f",
    "explained_audit_hashes": ["0c1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d6e7f8"],
    "body": "Incident inc_01hxyz — generated explanation\n\n…",
    "system_of_record": false,
    "generated_at": "2026-08-21T03:14:40Z",
    "generated_by": "system:narrative-pass"
  },
  "generations": []
}

authored_by is deterministic-stub until a live model is approved and injected. A stub write-up is still attributable (model id, prompt version, evidence hash, explained audit hashes) and still not the system of record.

Regenerate incident narrative

Requires sentinel:respond. Appends a new generation against the current evidence chain. Does not take a containment action and does not rewrite the audit log.

bash

POST /v1/sentinel/incidents/:id/narrative

{
  "force": true
}

Add analyst note

bash

POST /v1/sentinel/incidents/:id/notes

{
  "content": "Confirmed ransomware, LockBit variant. Engaged IR team."
}

Resolve an incident

bash

POST /v1/sentinel/incidents/:id/resolve

{
  "outcome": "mitigated",
  "note": "Threat contained. Device re-imaged. No data exfiltration detected."
}

Response actions Webhooks