Playbooks

A playbook is a structured plan an analyst (human or AI) follows when investigating or responding to a detection. Each playbook is a short, opinionated document with phases, steps, decisions, and actions — the SOC equivalent of a runbook, but first-class and version-controlled inside nano.

Playbooks exist for two reasons:

1. Consistency — two analysts picking up the same alert should follow the same path. The playbook codifies that path.
2. Automation-readiness — when an AI agent (PIVT) auto-works an alert, it follows the same playbook a human would. One shared spec, two consumers.

Where playbooks come from

Every playbook belongs to one of two origins:

• Library playbooks — hand-authored by the SOC team, sync-imported from the nanos-sh/playbooks upstream repo, or forked locally for customization. These live in the /playbooks route and are the canonical "how we respond to X" reference.
• Adaptive playbooks — auto-composed by the Shadow Investigator (PIVT) when it finishes investigating a case. Each adaptive playbook captures the actual moves the agent made. Promising ones can be promoted to the library with one click, at which point they become first-class library entries.

Lifecycle

draft ──► in_review ──► live ──► archived
                   └──► rejected

adaptive ──► (promote) ──► live

Every playbook carries a status field. draft and in_review are author-only; live is the published state an analyst sees in the library; archived is a soft delete that preserves history. DELETE /api/playbooks/{id}/permanent is a separate hard-delete action that removes the row entirely (requires typed confirmation in the UI).

Attaching a playbook to a case

When a detection rule fires and a case is created, one of three things happens:

1. Rule-pinned — the firing rule has a specific library playbook assigned (playbook_selector_mode = 'specific', playbook_id = <uuid>). The playbook attaches to the case automatically.
2. Adaptive mode — the rule is set to adaptive. No playbook attaches at case creation; when the Shadow Investigator later wraps its investigation, it composes a new adaptive playbook and attaches that.
3. None — the rule has no playbook preference. Analysts can manually attach library playbooks from the case view.

Attachment creates a row in playbook_runs that references the case, the playbook, and the playbook version in effect at attach time (versions are immutable, so the run always renders the step list as it existed when the run started, even if the playbook is later edited).

Architecture

┌─────────────────────┐      ┌─────────────────────┐
│ nanos-sh/playbooks  │ sync │ repository_playbooks│
│ (markdown + YAML    ├─────▶│ (cache of upstream) │
│  upstream repo)     │      └──────────┬──────────┘
└─────────────────────┘                 │ import
                                        ▼
┌─────────────────────┐      ┌─────────────────────┐
│ PIVT shadow         │ auto │      playbooks      │
│ investigation       ├─────▶│  (library entries)  │
│ (auto-composes      │      │                     │
│  adaptive)          │      │  + versions         │
└─────────────────────┘      │  + permissions      │
                             │  + approvals        │
                             └──────────┬──────────┘
                                        │ attach
                                        ▼
┌──────────────────┐          ┌─────────────────────┐
│ detection rule   │ creates  │    playbook_runs    │
│ fires → case     ├─────────▶│  + run_context      │
│                  │          │   snapshot          │
└──────────────────┘          └─────────────────────┘

Where to go next

• Authoring — the slash-command markdown grammar, phases, per-kind params, when: clauses, and the visual builder.
• Templating & runs — the {{...}} token grammar, how alert context binds into a run, what resolves where (and what doesn't yet).
• Library & lifecycle — categories, status transitions, approvals, adaptive → library promotion, and syncing from upstream.