Library & Lifecycle
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:
| Category | Scope |
|---|---|
identity | IAM, user lifecycle, auth, credentials |
endpoint | EDR, process / file / host events |
cloud | CloudTrail, GCP audit, Azure activity |
data | DLP, sensitive-data access |
network | Network flows, lateral movement, egress |
email | Mail 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| Field | Meaning |
|---|---|
status | draft · pending_review · live · archived |
promoted | true only if the playbook was promoted from an adaptive playbook (see below) |
current_version | The latest immutable version in the playbook's version history |
- Changing the content or metadata of a
liveorpending_reviewplaybook creates a new version and returns it todraft. Pending approvals for older versions are withdrawn. - Setting
statustolivedirectly requires the publish permission. - Runs always resolve against the version that was current when they started.
Review and approval
- The author clicks Submit for review, optionally naming a reviewer. The playbook moves to
pending_reviewand a pending approval is created for the current version. A named reviewer must be an active member who holdsplaybooks:publish. - A user with
playbooks:publish(and, if the playbook has an access list, the publish grant on it) clicks Approve or Reject. - Approve sets the playbook
live. Reject returns it todraftand 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):
| Permission | Grants |
|---|---|
playbooks:view | Read the library, versions, runs, approvals and analytics |
playbooks:run | Attach a playbook to a case, run it, and update run steps |
playbooks:manage | Create, edit, fork, submit for review, archive, hard-delete, and edit access lists |
playbooks:publish | Approve or reject a submission, publish directly, and promote adaptive playbooks |
playbook_repositories:view / :manage / :sync / :import | Repository 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_viewand 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_viewandcan_editon 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
draftwithadaptive=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:
| Mode | Behavior |
|---|---|
linked | Auto-pull on sync; local edits are NOT preserved (sync overwrites) |
forked | Sync imports into a cache; author copies into the library and owns edits |
Sync flow:
- An admin adds a repository under Playbooks → Repositories (git URL, ref and access token).
- Sync pulls the repository into a cache, not into the library itself.
- Import (one playbook, or import all) creates library playbooks from the cached entries. Sync and import does both.
- 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:
| Action | Endpoint | Behavior |
|---|---|---|
| Archive | DELETE /api/playbooks/{id} | Soft: status=archived, run history preserved, re-activatable |
| Hard delete | DELETE /api/playbooks/{id}/permanent | Row 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_mode | playbook_id | On case creation |
|---|---|---|
specific | set | The named playbook attaches automatically |
adaptive | none | Nothing attaches; pivt can compose an adaptive playbook |
none (default) | none | Analysts 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:
| Field | Meaning |
|---|---|
attached | Runs attached to cases in the last 30 days |
started | Runs started (currently equal to attached) |
finished | Runs resolved in the last 30 days |
ttr_median_min | Median minutes from attach to resolution, last 90 days |
hours_since_last_run | Hours since the most recent run started |
spark_30d | Daily 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
- Authoring: writing a playbook.
- Templating & runs:
{{...}}grammar andrun_context.