SOAR handbook

A SOAR case is an incident plus a graph. The case holds the alert, the entities it touches, the evidence you attach and the fields you write. The graph is the automation: a chain of steps the engine executes against the simulated estate, pausing wherever you put a human gate.

Nothing on the screen is narrated. When a step isolates a host, the host is isolated in the emulator, and the rubric beside the case re-scores against that world. Denying an approval costs the same marks it would cost in a real SOC.

Hands-on labs land you on nw-auto01, the persistent Northwind automation runner, through the range console. It has the same layout every time, because that is how a real automation box works — you learn the paths once.

/etc/soc-automation/playbooks/   playbooks, plus README (language reference)
/etc/soc-automation/instances/   connector instances and their vault refs
/var/lib/soc-automation/events/       queued events, one JSON file each
/var/log/soc-automation/events.log      what arrived and how it was enriched
/var/log/soc-automation/runner.log     what ran, what failed, what is unhandled
/var/log/soc-automation/health.log     connector health, stage by stage

Credentials always come from the vault (vault/soc-automation). An inline key in an instance file is a defect, and labs will ask you to find it.

Playbooks are text. The server compiles the text into the graph the engine runs, so what you type is what gets graded — a hand-made graph posted from a browser cannot bypass the language rules.

playbook Contain the finance beacon

step gather_evidence
  action case.attach-evidence
  locator range/hst-nw-auto01/session
  label Queue entry and enrichment for the event

step ask_approval
  action prompt
  label Isolate NW-FIN-014?
  approvers soc-lead, duty-manager

step isolate_host
  action estate.set-attribute
  entity hst-nw-fin-014
  set isolated = true
  risk consequential
  approval required
  on-error stop

step close_case
  action case.update
  field verdict = true-positive
  field closureNote = written

Four actions exist: case.attach-evidence, case.update, estate.set-attribute and prompt. Steps also take retry, timeout, on-error and approvers. Source is capped at 400 lines and 40 steps; the compiler answers with line numbers.

The step list above the editor is the same graph in visual form. You can add a step from the palette, retarget it, toggle its approval gate or remove it, and the text below re-serialises to match. Use whichever you prefer — no-code first, then code as the playbook gets real. Both are locked once the run starts touching the estate, exactly as a production playbook is locked mid-run.

Saving compiles and produces a dry-run review: which steps are reachable, what each one writes, where the run will pause for a person, and the estate and case fields the run would leave behind. The review never touches the estate and never awards marks.

Fix these before you run:

• unreachable steps — nothing after a broken chain will ever execute
• blind actions — you change the estate before attaching any evidence
• ungated consequential steps — containment with no approval in front of it
• retries on non-idempotent actions — a retried isolate is not free

When the review is clean, step the case. Approvals stop the run; approve or deny with the same judgement you would use on shift. When the run settles, the debrief page is written for you.

Rubrics assert state and evidence, never click order. Marks come from what the world looks like at the end: the implicated asset contained, the innocent lookalike untouched, evidence attached before action, a credential resolved from the vault, a verdict and a closure note on the case, and faults survived rather than avoided.

That is why two learners can write very different playbooks and both score full marks — and why pressing Next through someone else's finished graph scores nothing.