nano SIEM
Playbooks

Library & Lifecycle

Supported in:Self-hosted

Categories, statuses, approvals, adaptive → library promotion, and upstream repository sync

Use the playbook library at /playbooks to find, review, and publish response plans. Manage categories, ownership, approvals, upstream imports, and adaptive playbooks composed by pivt.

Categories

Every library playbook sits under one of six canonical categories:

CategoryScope
identityIAM, user lifecycle, auth, credentials
endpointEDR, process / file / host events
cloudCloudTrail, GCP audit, Azure activity
dataDLP, sensitive-data access
networkNetwork flows, lateral movement, egress
emailMail gateway, phishing, BEC

Categories group the library in the UI, and they are the fallback when nano suggests playbooks for a rule (GET /api/playbooks/suggest-for-rule/{rule_id}).

Status lifecycle

          submit for review
 draft ─────────────────────▶ pending_review
   ▲                               │
   │                     ┌─────────┴─────────┐
   │                  approve              reject
   │                     │                   │
   │                     ▼                   ▼
   └── edit content ── live            back to draft
                         │
                      archive
                         ▼
                     archived
FieldMeaning
statusdraft · pending_review · live · archived
promotedtrue only if the playbook was promoted from an adaptive playbook (see below)
current_versionThe latest immutable version in the playbook's version history
  • Changing the content or metadata of a live or pending_review playbook creates a new version and returns it to draft. Pending approvals for older versions are withdrawn.
  • Setting status to live directly requires the publish permission.
  • Runs always resolve against the version that was current when they started.

Review and approval

  1. The author clicks Submit for review, optionally naming a reviewer. The playbook moves to pending_review and a pending approval is created for the current version. A named reviewer must be an active member who holds playbooks:publish.
  2. A user with playbooks:publish (and, if the playbook has an access list, the publish grant on it) clicks Approve or Reject.
  3. Approve sets the playbook live. Reject returns it to draft and keeps the reviewer's message on the approval.

Approval records stay in the playbook's history (GET /api/playbooks/{id}/approvals); submitting again creates a new one.

Permissions

Two layers control access.

Role permissions (deployment-wide):

PermissionGrants
playbooks:viewRead the library, versions, runs, approvals and analytics
playbooks:runAttach a playbook to a case, run it, and update run steps
playbooks:manageCreate, edit, fork, submit for review, archive, hard-delete, and edit access lists
playbooks:publishApprove or reject a submission, publish directly, and promote adaptive playbooks
playbook_repositories:view / :manage / :sync / :importRepository configuration, sync and import

Per-playbook access lists. Under a playbook's permissions you can grant individual roles can_view, can_run, can_edit and can_publish (PUT /api/playbooks/{id}/permissions/{role}). The rules:

  • A playbook with no access-list entries is governed by the role permissions alone.
  • Once a playbook has any entry, the list is authoritative: you need both the role permission and a matching grant. Entries are grants, not denials.
  • If you hold several roles, a grant on any of them is enough.
  • Run, edit and publish each need a single entry that grants both can_view and that action.
  • API keys are their own principal (api_key); they don't inherit their owner's roles.
  • When you edit an access list yourself, you must keep can_view and can_edit on one of your own roles, so the playbook can't become unmanageable.

Adaptive playbooks

pivt can compose an adaptive playbook from a case's investigation — the queries, pivots, enrichments and decisions recorded in the case notebook. From the case's evidence drawer, use the compose action (POST /api/cases/{case_id}/compose-adaptive-playbook). Adaptive playbooks:

  • Start as draft with adaptive=true, in the library's Adaptive tab.
  • Use the same slash-command format as hand-written playbooks.

Promoting to the library

Reviewing an adaptive playbook, a user with playbooks:publish can click Promote. This clears adaptive, sets promoted=true, creates a new version and moves the playbook to pending_review, so it is approved like any other before going live.

promoted is adaptive-only. Hand-written playbooks that pass review stay promoted=false. The Promoted filter is the track record of which pivt compositions were worth keeping.

Upstream repository sync

The nano-rs/playbooks upstream repo is the canonical source of stock playbooks. Two modes:

ModeBehavior
linkedAuto-pull on sync; local edits are NOT preserved (sync overwrites)
forkedSync imports into a cache; author copies into the library and owns edits

Sync flow:

  1. An admin adds a repository under Playbooks → Repositories (git URL, ref and access token).
  2. Sync pulls the repository into a cache, not into the library itself.
  3. Import (one playbook, or import all) creates library playbooks from the cached entries. Sync and import does both.
  4. When the upstream copy of an imported playbook changes, the repository lists it under upstream updates. Apply one (POST /api/playbooks/{id}/apply-upstream-update) or all of them.

Detection rules and parsers use the same repository pattern.

Archive vs. hard-delete

Two removal actions exist:

ActionEndpointBehavior
ArchiveDELETE /api/playbooks/{id}Soft: status=archived, run history preserved, re-activatable
Hard deleteDELETE /api/playbooks/{id}/permanentRow removed entirely; runs keep their cached doc via playbook_versions

Archive is the default. Hard delete requires type-to-confirm and is intended for accidental creates / test playbooks. Once a playbook has real runs attached, archive is the right move (it keeps the audit trail).

Rule ↔ playbook association

A detection rule's playbook_selector_mode decides what happens when its alert creates a case:

playbook_selector_modeplaybook_idOn case creation
specificsetThe named playbook attaches automatically
adaptivenoneNothing attaches; pivt can compose an adaptive playbook
none (default)noneAnalysts attach playbooks manually from the case

In the rule editor's YAML, playbook: pb_01hz… or playbook: adaptive sets the mode.

GET /api/playbooks/suggest-for-rule/{rule_id} suggests library playbooks for a rule, falling back to the rule's category.

Analytics

GET /api/playbooks/{id}/analytics returns usage for one playbook:

FieldMeaning
attachedRuns attached to cases in the last 30 days
startedRuns started (currently equal to attached)
finishedRuns resolved in the last 30 days
ttr_median_minMedian minutes from attach to resolution, last 90 days
hours_since_last_runHours since the most recent run started
spark_30dDaily attach counts for the last 30 days, oldest first

Troubleshoot

Need help with these checks? Contact support with the request ID and time with timezone.

An approved playbook returns to Draft

Editing live or pending-review content or metadata creates a new version and returns it to draft. Pending approvals for older versions are withdrawn.

Role permission does not grant access

Check the per-playbook access list. Once any entry exists, the action needs both the role permission and a matching grant; run, edit, and publish also need can_view on the same entry.

What's next

On this page