Playbooks
Structured investigation and response plans, library-authored or AI-composed, attached to cases for analysts and AI agents to work
Attach a playbook to a case to follow a structured investigation and response plan. The versioned document organizes queries, pivots, enrichments, decisions, and actions into phases for analysts and AI agents.
Playbooks exist for two reasons:
- Consistency. Two analysts picking up the same alert follow the same path.
- Automation-readiness. When pivt works a case, it follows the same playbook a human would. One spec, two consumers.
Where playbooks come from
- Library playbooks are written by your team, imported from a playbook repository such as
nano-rs/playbooks, or forked from an imported playbook. They live at Playbooks (/playbooks) and are the reference for "how we respond to X". - Adaptive playbooks are composed by pivt from a case's investigation, capturing the moves it actually made. You can promote a useful one into the library, where it goes through review like any other playbook.
Lifecycle
draft ──► pending_review ──► live ──► archived
▲ │
└── rejected ──┘
adaptive draft ──► promote ──► pending_review ──► live| Status | Meaning |
|---|---|
draft | Being written. Editing the content of a live or pending_review playbook also returns it to draft |
pending_review | Submitted; waiting for an approver |
live | Published; analysts can attach it |
archived | Soft-deleted; history and runs are kept |
DELETE /api/playbooks/{id}/permanent is a separate hard delete. The UI asks you to type to confirm. See Library & lifecycle.
Attaching a playbook to a case
A playbook reaches a case in one of three ways:
- Rule-assigned. The detection rule names a specific library playbook. When the rule's alert creates a case, the playbook attaches automatically with the alert's context.
- Adaptive. pivt composes a playbook from the case's investigation.
- Manual. An analyst attaches a library playbook from the case view.
Attaching creates a run that references the case, the playbook and the playbook version current at attach time. Versions are immutable, so a run always shows the steps as they were when it started, even if the playbook is edited later. See Templating & runs.
Troubleshoot
Need help with these checks? Contact support with the request ID and time with timezone.
A rule's playbook doesn't attach
Check the rule's playbook_selector_mode: only specific, with a playbook_id, attaches a playbook automatically when the rule's alert creates a case. See Library.
What's next
- Authoring: the slash-command grammar, step kinds and parameters,
when:clauses, and the visual builder. - Templating & runs: the
{{...}}tokens, how alert context binds into a run, and what a run executes. - Library & lifecycle: categories, review and approval, access control, adaptive promotion and repository sync.
Troubleshoot hunts
Find out why a hunt didn't run or didn't finish: no_coverage, budget_exhausted, an unavailable server runner, a run waiting for a runner, reasoning effort, and missing reviews.
Authoring Playbooks
Slash-command markdown grammar covering phases, step kinds, per-kind params, when clauses, and the Visual ↔ Source round-trip