Authoring Playbooks
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 keyword | Phase bucket |
|---|---|
triage | Triage |
investigate, analyze, decide | Investigate |
contain, respond, action | Contain |
close, review, wrap | Close |
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:
| Kind | What it represents |
|---|---|
/query | Pull data from a source (e.g. okta) |
/pivot | Branch the investigation on an entity |
/enrichment | Look up external context (HR, WHOIS, IPinfo…) |
/baseline | Compare against an entity's normal behavior |
/lead | Emit a hunt lead for an entity (entity:) |
/decision | Ask the analyst to choose among options |
/action | Mutate the world (rotate a key, isolate a host) |
/review | Human confirmation step |
/note | Freeform 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 · offboardedwhen: 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 = yesfor equalityd1 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:
| Param | Moved 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
| Param | Meaning |
|---|---|
from | Log source the step reads (okta, aws_cloudtrail, …) |
window | Time window (90m, 24h, 7d, 2w) |
npl (or query) | The full nPL query the step runs |
where / filter | An 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
| Param | Meaning |
|---|---|
on | Field or entity type to fan out on |
keys | Optional sub-specifier |
/pivot: per-source-IP summary
on: src_endpoint.ip/enrichment
| Param | Meaning |
|---|---|
system | External system id (workday, ipinfo, virustotal) |
field / fields | What 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
| Param | Meaning |
|---|---|
options: (list) | Answers the analyst chooses from |
note_required_on | Comma-list of answer keys that force a note |
The first word of each option is the answer key used by downstream when: clauses.
/action
| Param | Meaning |
|---|---|
kind | Dotted action id (iam.key_rotate, edr.isolate_host) |
target | Entity / identifier the action hits |
danger | low · medium · high; drives approval routing |
approval | auto · required; inline override |
reversible | Boolean hint for the operator |
/review
| Param | Meaning |
|---|---|
criteria / hint | What the analyst is confirming |
approver | Optional 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:
| Kind | Required |
|---|---|
/query | from |
/pivot | on |
/enrichment | system + either field or fields |
/decision | at least 2 options |
/action | kind, target, danger |
/review | criteria or hint |
/note | none (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.