nano SIEM
Playbooks

Authoring Playbooks

Supported in:Self-hosted

Slash-command markdown grammar covering phases, step kinds, per-kind params, when clauses, and the Visual ↔ Source round-trip

Write a playbook in Markdown with slash commands to define investigation phases and steps. You can edit the same structured document in the wizard’s Visual canvas or Source view.

Minimal example

# Credential reuse · offboarded / dormant account

Agent-first identity investigation for the pattern
"account that shouldn't be active is active."

## Triage

/enrichment: HR status for the user
  system: workday
  employee: {{entity.user}}
  fields: status, end_date, manager, team

/query: last 30d of sign-ins for this user
  from:   okta
  window: 30d
  npl:    metadata.log_source="okta" class_uid=3002 user.name="{{entity.user}}"

## Investigate

/decision: is this a live user account?
  options:
    - yes · employed and active
    - no · offboarded
    - partial · on leave / role changed
  note_required_on: no, partial

## Contain

/action: rotate or disable the compromised credential
  kind:    iam.key_rotate
  target:  {{entity.user}}
  danger:  medium
  approval: required
  when:    d1 in [no, partial]

Grammar

Title (#)

The first # Heading becomes the playbook title. Exactly one title per doc.

Phases (##)

## Heading starts a phase. The Build canvas maps headings to the four canonical phase buckets (Triage, Investigate, Contain, Close) using keyword matching:

Heading keywordPhase bucket
triageTriage
investigate, analyze, decideInvestigate
contain, respond, actionContain
close, review, wrapClose

A heading whose keyword matches none of the four buckets becomes an unphased block at the top of the canvas. For example, ## Phase 1 · establish state matches nothing on "establish", so its steps render unphased. Unphased steps always render above any phased steps.

Steps (/kind:)

/kind: label starts a step. The label is the one-line summary shown at the top of the card; per-kind parameters live on indented key/value lines below.

Nine step kinds:

KindWhat it represents
/queryPull data from a source (e.g. okta)
/pivotBranch the investigation on an entity
/enrichmentLook up external context (HR, WHOIS, IPinfo…)
/baselineCompare against an entity's normal behavior
/leadEmit a hunt lead for an entity (entity:)
/decisionAsk the analyst to choose among options
/actionMutate the world (rotate a key, isolate a host)
/reviewHuman confirmation step
/noteFreeform note / instruction

The visual builder's palette offers query, pivot, enrichment, decision, action and review. /baseline, /lead and /note are written in Source view. /baseline and /lead were added for hunts, which share this grammar.

Step parameters

Indented key: value pairs under a step become step.params. Scalars are coerced YAML-style: true/false become booleans, null becomes null, bare integers and decimals become numbers, and everything else stays a string (quotes are stripped). List values use YAML-style dashes:

/decision: is this a live user account?
  options:
    - yes · employed and active
    - no · offboarded

when: clauses

Any step can carry a when: clause that gates its execution on prior decisions:

/action: rotate or disable the compromised credential
  when: d1 in [no, partial]

d1 refers to the first /decision step's answer key (the first word of the chosen option). Supported forms:

  • d1 = yes for equality
  • d1 in [yes, partial] for set membership

When a playbook run queues automation, a mapped action with a when: clause runs only after the approver picks a matching option, and it still waits for its own approval. An action stays manual, with the reason in the automation report, when its decision has its own when: clause, or when the when: value matches none of the decision's options.

Special params

These are lifted out of params into first-class fields on the step:

ParamMoved to
options:step.options
note_required_on:step.note_required_on
id:step.id (overrides the auto-generated id)
when:step.when (parsed)

Per-kind parameters

Queries and fields in playbooks use OCSF 1.9 paths, such as actor.user.name, src_endpoint.ip and device.hostname. See the OCSF field reference.

/query

ParamMeaning
fromLog source the step reads (okta, aws_cloudtrail, …)
windowTime window (90m, 24h, 7d, 2w)
npl (or query)The full nPL query the step runs
where / filterAn nPL filter expression, for the analyst to run
/query: cloud API calls from this user in the last day
  from:   aws_cloudtrail
  window: 24h
  npl:    metadata.log_source="aws_cloudtrail" actor.user.name="{{entity.user}}" | stats count by api.operation

/pivot

ParamMeaning
onField or entity type to fan out on
keysOptional sub-specifier
/pivot: per-source-IP summary
  on: src_endpoint.ip

/enrichment

ParamMeaning
systemExternal system id (workday, ipinfo, virustotal)
field / fieldsWhat to look up (fields takes a comma list)
Any additional keys are passed verbatim to the enrichment call
/enrichment: HR status for the user
  system: workday
  field: employment_status
  employee: {{entity.user}}

/decision

ParamMeaning
options: (list)Answers the analyst chooses from
note_required_onComma-list of answer keys that force a note

The first word of each option is the answer key used by downstream when: clauses.

/action

ParamMeaning
kindDotted action id (iam.key_rotate, edr.isolate_host)
targetEntity / identifier the action hits
dangerlow · medium · high; drives approval routing
approvalauto · required; inline override
reversibleBoolean hint for the operator

/review

ParamMeaning
criteria / hintWhat the analyst is confirming
approverOptional role or user id that must sign off

/note

No params; a freeform instruction block. The parser emits kind: "note" with the label as the body.

Visual ↔ Source round-trip

The authoring wizard's Build phase exposes both views. Switching is lossless:

  • Visual → Source: the draft's flat step list is re-emitted as slash-command markdown, preserving phase headings via the keyword mapping above and only including params with non-empty values.
  • Source → Visual: the textarea is parsed via the same parser the server uses; the resulting step tree is flattened into the canvas, tagging each step with the phase its heading mapped to.

Short hints that describe what to type (format reminders, example values) render inline beneath the field label in the Visual form. Longer explanatory copy lives behind a ? tooltip icon on the label.

Validation

Each kind has a soft validator that surfaces a NEEDS INPUT chip on the step card when a required param is missing:

KindRequired
/queryfrom
/pivoton
/enrichmentsystem + either field or fields
/decisionat least 2 options
/actionkind, target, danger
/reviewcriteria or hint
/notenone (label is the body; not soft-validated)

Validation does not block publishing; it only signals the author. The counter in the Build toolbar rolls up into the Review phase's policy-check section.

Troubleshoot

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

A step appears outside its phase

Check the phase heading against the keyword table. Unmatched headings create unphased steps above the phased steps.

A card shows NEEDS INPUT

Fill the required parameters for that step kind. Soft validation signals missing input but does not block publishing.

An action does not run automatically

Action steps currently render as manual checkboxes regardless of approval. Outbound action connectors are not wired yet.

What's next

On this page