Playbooks

Playbooks are automated response workflows that chain together Sentinel actions. Define them once and trigger them manually via API, or have Sentinel execute them automatically when specific conditions are met.

The playbook object

json

{
  "id": "pbk_01hxyz",
  "tenant_id": "ten_01hxyz",
  "name": "Ransomware containment",
  "description": "Isolate affected device, revoke user sessions, block known C2 IPs.",
  "trigger": "auto",
  "trigger_conditions": {
    "incident_type": "ransomware",
    "severity": ["critical", "high"]
  },
  "steps": [
    {
      "order": 1,
      "action": "isolate_device",
      "target": "incident.primary_device",
      "reason_template": "Ransomware containment playbook, incident {{incident.id}}"
    },
    {
      "order": 2,
      "action": "revoke_sessions",
      "target": "incident.primary_user",
      "reason_template": "Ransomware containment, revoking sessions for {{user.email}}"
    },
    {
      "order": 3,
      "action": "notify_analyst",
      "params": { "channel": "pagerduty", "priority": "P1" }
    }
  ],
  "enabled": true,
  "created_by": "usr_01hxyz",
  "created_at": "2025-03-01T09:00:00Z"
}

Trigger modes

Name	Type	Required	Description
manual	string	No	Playbook only runs when explicitly triggered via the API or UI.
auto	string	No	Sentinel runs the playbook automatically when trigger_conditions match.
semi-auto	string	No	Sentinel alerts the analyst and queues the playbook, runs on analyst approval.

List playbooks

bash

GET /v1/sentinel/playbooks?filter[trigger]=auto

Create a playbook

bash

POST /v1/sentinel/playbooks

Name	Type	Required	Description
name	string	Yes	Descriptive name.
trigger	string	Yes	manual \| auto \| semi-auto
trigger_conditions	object	No	Conditions that trigger auto/semi-auto execution. Supports incident_type, severity, affected_asset_type.
steps	array	Yes	Ordered list of response actions.
enabled	boolean	No	Defaults to true.

Run a playbook manually

bash

POST /v1/sentinel/playbooks/:id/run

{
  "incident_id": "inc_01hxyz",
  "context": {
    "device_id": "dev_01hxyz",
    "user_id": "idn_01hxyz"
  }
}

Returns 202 Accepted with a playbook run object. Steps execute asynchronously, subscribe to the playbook.run.completed webhook event for completion notification.

Approve or reject a gated step

bash

POST /v1/sentinel/playbooks/runs/:run_id/steps/:step_index/approve

POST /v1/sentinel/playbooks/runs/:run_id/steps/:step_index/reject
{
  "reason": "Target is a protected break-glass account."
}

A rejection is a durable negative decision. It cancels the remaining run and the advancer compensates earlier reversible steps in reverse order.

Warning:Each step's order, target, and reason_template fields shown above are accepted and stored, but the current execution engine only reads each step's action field when a run actually executes — steps run in array order (so order is currently redundant with array position, not independently honored), and per-step target/templated reason_template resolution against the incident is not yet implemented. Use context (below) to supply entity IDs the WHOLE run needs (e.g. device_id, user_id) — today this is a run-level context object, not a per-step target lookup.

Built-in playbooks

Compromised Endpoint Lockdown (human-approval tier), isolate, lock local access, evict sessions, suspend the process, disable persistence, quarantine, collect evidence, and notify.
Credential Theft Containment (human-approval tier), isolate device, revoke sessions, force MFA, collect forensics.
Ransomware Early Lockdown (automatic tier), isolate device, kill process, disable account, collect forensics.
IOC Match Response (automatic tier), block IP, block domain, run scan.

Threat intelligence Fleet operations