nano SIEM
Playbooks

Templating & Runs

Supported in:Self-hosted

How {{...}} tokens resolve against the case, alert, rule and entity context captured when a playbook attaches to a case

Use {{...}} tokens to bind playbook steps to the case, alert, rule, and entities. When you attach a playbook, nano creates a run and resolves the tokens against a snapshot of that context.

The same grammar applies to hand-written playbooks, adaptive playbooks that pivt composes, and what an AI agent sees when it works a run.

To see a run with its tokens substituted, call GET /api/playbook-runs/{id}/resolved. The response carries a has_context flag (false for runs attached without context) and the list of paths that did not resolve.

The run-context snapshot

When a playbook attaches to a case, nano stores a run_context JSON snapshot on the run. It is captured once, at attach time, and never recomputed.

{
  "case":  { "id": "case_01hz…", "title": "Root key used outside bastion", "severity": "high" },
  "alert": { "id": "alert_01hz…", "severity": "high" },
  "rule":  { "id": "rule_01hz…", "name": "aws_root_key_outside_bastion", "severity": "high" },
  "top_matched_event": { "...": "the first matched event of the alert, as stored" },
  "entities": {
    "user": ["jsmith"],
    "ip":   ["203.0.113.40"],
    "host": ["ws-jsmith"]
  }
}
  • Alert-driven attach (a rule fires, a case is created and the rule's playbook attaches): case, alert, rule, top_matched_event and entities are filled. The top matched event is the first entry of the alert's matched events. entities comes from the same extraction that fills case entities.
  • Manual attach (an analyst attaches a playbook from the case): only case and entities are filled. entities holds the entities already on the case, primary entities first. {{alert.*}}, {{rule.*}} and {{event.*}} render as empty strings.

Token grammar

TokenResolves to
{{case.id}}, {{case.title}}, {{case.severity}}The case
{{alert.id}}, {{alert.severity}}The alert (empty on manual attach)
{{rule.id}}, {{rule.name}}, {{rule.severity}}The firing rule (empty on manual attach)
{{entity.<type>}}The first extracted entity of that type
{{entity.<type>[N]}}The entity at index N (empty if there isn't one)
{{entities.<type>}}The whole list, for use with join
{{event.<key>}}A top-level key of the top matched event — see the limitation below
{{alert.<key>}}Same as {{event.<key>}} for any key other than id and severity

Entity types

{{entity.*}} uses entity types, not field paths. Extraction folds the source and destination sides of an event into one type: src_endpoint.ip and dst_endpoint.ip both become ip, and actor.user.name and user.name both become user.

TypeTypical OCSF sources
useractor.user.name, user.name
hostdevice.hostname, src_endpoint.hostname, dst_endpoint.hostname, internal domains
ipsrc_endpoint.ip, dst_endpoint.ip
domainhttp_request.url.hostname, url.hostname, query.hostname
hashfile.hashes.value, process.file.hashes.value, actor.process.file.hashes.value
urlhttp_request.url.url_string, url.url_string
filefile.path, file.name, process.file.path, actor.process.file.path
processprocess.name, process.cmd_line, actor.process.name, actor.process.cmd_line
emailemail addresses in event values

So {{entity.ip}} is valid; {{entity.src_endpoint.ip}} is not. See Entities & Entity Graph for how extraction works, and OCSF field reference for the paths.

{{event.*}} reads top-level keys only

Helpers

HelperUsageResult
lower{{lower entity.user}}Lowercased
upper{{upper entity.host}}Uppercased
default{{default entity.user "n/a"}}The value, or the fallback if empty
join{{join entities.ip ","}}A list joined with the separator

Resolution rules

  1. Missing value → empty string. {{entity.hash}} on a case with no hash renders as "". It is not an error and does not stop the run.
  2. Missing list → empty list. {{join entities.hash ","}} renders as "".
  3. Unknown name → flagged. An unknown namespace ({{widget.foo}}), an unknown key under case or rule ({{case.owner}}), or an entity token without a type renders as "" and is listed as unresolved. The step card shows a missing-context indicator. Saving the playbook is never blocked.
  4. Names are case-sensitive. {{entity.User}} is not {{entity.user}}.
  5. You add the quotes. The resolver substitutes the bare value. Write actor.user.name="{{entity.user}}", not actor.user.name={{entity.user}}.

Resolved step example

A query step in the library:

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

Attached to a case whose entities contain user: ["jsmith"], the run shows:

/query: last 7 days of sign-ins for this user
  from:   okta
  window: 7d
  npl:    metadata.log_source="okta" class_uid=3002 user.name="jsmith"

The stored playbook is never changed. Resolution runs each time the run is read, against the frozen run_context.

Why the snapshot is frozen

An investigation can last hours or days. New events join the case, the rule is edited, the alert is reclassified. If tokens resolved against live state, /action: disable {{entity.user}} could point at a different user from one moment to the next. The snapshot pins the run to the moment it started.

Attaching the same playbook again creates a new run with a fresh snapshot, which picks up any entities added since.

AI agents working a run

pivt reads the resolved form of each step: labels and parameters with the tokens substituted, plus the danger and approval settings on /action steps, which decide whether the agent proposes an action or leaves it to the analyst.

Troubleshoot

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

An entity token resolves to an empty string

Check the entity type and case-sensitive token name. Use {{entity.ip}}, rather than an OCSF path such as {{entity.src_endpoint.ip}}.

A nested event token is empty without a warning

Event tokens read top-level keys only. Use entity tokens for nested OCSF entity values.

New case entities do not appear in the run

The run context is frozen at attachment. Attach the playbook again to create a run with a fresh snapshot.

What's next

On this page