nano SIEM
Playbooks

Playbooks

Supported in:Self-hosted

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:

  1. Consistency. Two analysts picking up the same alert follow the same path.
  2. 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
StatusMeaning
draftBeing written. Editing the content of a live or pending_review playbook also returns it to draft
pending_reviewSubmitted; waiting for an approver
livePublished; analysts can attach it
archivedSoft-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:

  1. 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.
  2. Adaptive. pivt composes a playbook from the case's investigation.
  3. 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.

On this page