xsiam-playbooks

name	xsiam-playbooks
description	This skill should be used when the user asks to "create a playbook", "build a playbook", "design a playbook", "XSIAM playbook", "XSOAR playbook", "incident response workflow", "automation workflow", "playbook YAML", or needs to generate playbook definitions for Cortex XSIAM or XSOAR.

XSIAM Playbook Development

Generate importable unified YAML files for Cortex XSIAM/XSOAR playbooks. Playbooks define automated workflows with tasks, conditions, and sub-playbook calls. The YAML must match the exact structure and field ordering of a real XSIAM export for successful import.

Before Starting

Read the reference file to understand the playbook YAML format:

• references/playbook-format.md — Complete playbook YAML schema: top-level structure, per-task field ordering, task type examples with all boilerplate fields, condition operators, script argument patterns, common flow patterns

What is a Playbook?

Playbooks are automated workflows that orchestrate tasks, integrations, scripts, and sub-playbooks to handle security incidents. They define the sequence of actions, decision points, and data flow for incident response.

When to use which skill:

• Automated incident workflows → playbook (this skill)
• Connecting to external APIs → integration (xsiam-integrations skill)
• Ingesting events into data lake → event collector (xsiam-event-collectors skill)
• Standalone data processing → script (xsiam-scripts skill)

Workflow

1. Gather Requirements

Determine the playbook category:

Category	Trigger	Typical Pattern
Incident Response	Alert/incident type	Enrichment → Triage → Remediation → Close
Enrichment	Sub-playbook call	Parallel lookups → Merge → Output
Remediation	Sub-playbook call	Validate → Act → Verify → Report
Utility	Manual or sub-playbook	Input → Transform → Output

Then gather conditional requirements:

• Uses integration commands? → gather brand names, command names, argument mappings
• Has condition/branching logic? → gather decision criteria, branch labels, inline conditions vs script-based
• Calls sub-playbooks? → gather playbook names, input/output mappings, whether any should iterate per list item (forEach loop), and whether context stays sandboxed (separatecontext: true) or shared
• Needs user input? → gather collection task prompts and options
• Needs error handling? → for each fallible task, choose: stop the playbook (default), continue and ignore the error, or route to an #error# handler branch
• Has parallel execution? → design fork/merge task topology
• What inputs does it accept? → define key, default value, required, description
• What outputs does it produce? → define contextPath, description, type

2. Design the Flow

Map out the task list before generating YAML. Present it as a numbered list for user approval:

"0" (start) → "1"
"1" (title: Enrichment Phase) → "2"
"2" (command: xdr-get-endpoints) → "3"
"3" (condition: Is Malicious?) → yes: "4", #default#: "5"
"4" (command: block-indicator) → "6"
"5" (command: close-incident, close as benign) → "6"
"6" (title: Done)

Each entry shows: task ID, task type, task name, and nexttasks wiring.

Get user approval on the flow before proceeding to YAML generation.

3. Generate the Unified YAML

Build a single .yml file following these ordered sub-steps. The YAML structure must match real XSIAM export format for successful import.

1. Top-level metadata — id (lowercase with hyphens), version: -1, vcShouldKeepItemLegacyProdMachine: false, name, tags (if applicable), starttaskid: "0"
2. Tasks dictionary — each task with ALL boilerplate fields in exact field order per the format spec. Generate real v4 UUIDs for taskid and inner task.id (both must be identical for each task). Position tasks following view layout rules (x: 450 main column, y increments of ~160-180px, branch offsets at x: 730).
3. Top-level view — JSON string with linkLabelsPosition: {} and paper.dimensions computed from task positions
4. inputs and inputSections — define all playbook inputs with key, value, required, description, playbookInputQuery. Wrap in inputSections with all keys listed. If the playbook has no inputs and no outputs, emit inputs: [] and outputs: [] and omit both section blocks entirely.
5. outputSections and outputs — define all playbook outputs with contextPath, description, type. Wrap in outputSections.
6. Verify omissions — confirm no fromversion, no tests, no marketplaces, no timeout

4. File Output

Generate a single file:

• PlaybookName.yml — the unified YAML ready for import into XSIAM

After delivering the file, print a lightweight summary to the conversation:

• Description — 1-2 sentences on what the playbook does
• Trigger — what starts this playbook
• Dependencies — integrations, sub-playbooks, and scripts used
• Inputs — table with name, description, required, default value
• Flow — numbered steps with condition branches noted
• Outputs — table with contextPath, description, type

This summary is conversation-only — not a separate file. For full playbook documentation, use the xsiam-docs-playbooks skill.

5. Validate Structure

Before delivering, run the structural check and confirm it exits 0 (prints OK). If it errors, fix the YAML before delivering:

python3 -c "
import yaml, re
d = yaml.safe_load(open('PlaybookName.yml'))
tasks = d['tasks']
uuid4 = re.compile(r'^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\$', re.I)
for tid, t in tasks.items():
    assert t['id'] == tid, f'id != key at {tid}'
    assert t['taskid'] == t['task']['id'], f'taskid != task.id at {tid}'
    assert uuid4.match(str(t['taskid'])), f'taskid not a v4 UUID at {tid}'
    for targets in (t.get('nexttasks') or {}).values():
        for nt in (targets or []):
            assert nt in tasks, f'{tid} points to missing task {nt}'
    branches = {k.lower() for k in (t.get('nexttasks') or {})}
    for c in (t.get('conditions') or []):
        lbl = str(c.get('label'))
        assert lbl.lower() in branches, f'condition label {lbl} has no nexttasks branch at {tid}'
seen, stack = set(), [d['starttaskid']]
while stack:
    n = stack.pop()
    if n in seen:
        continue
    seen.add(n)
    for targets in (tasks[n].get('nexttasks') or {}).values():
        stack += (targets or [])
assert seen == set(tasks), f'unreachable tasks: {set(tasks) - seen}'
print('OK')
"

This catches taskid/task.id mismatches, nexttasks pointing at ids that do not exist, inline-condition labels with no matching nexttasks branch, orphaned tasks unreachable from starttaskid, and non-v4 UUIDs — linkage errors the eyeball checks below can miss.

Requires PyYAML (pip install pyyaml); if it isn't installed, skip this check and rely on the checklist below.

6. Validation Checklist

Before delivering, verify:

Structure:

• Task "0" exists and is type: start
• All task IDs are unique strings
• All taskid values are valid v4 UUIDs
• taskid matches inner task.id for every task
• All nexttasks reference valid task IDs that exist in the tasks dictionary
• No orphaned tasks — every task is reachable from "0"
• No dead ends — every non-terminal task has nexttasks

Field Ordering:

• Top-level fields follow specified order: id → version → vcShouldKeepItemLegacyProdMachine → name → description (optional) → tags → starttaskid → tasks → view → inputs → inputSections → outputSections → outputs
• Per-task fields follow specified order: id → taskid → type → task → nexttasks → scriptarguments → reputationcalc (if extracting) → results (script conditions) → separatecontext → conditions → continueonerror → continueonerrortype → loop (sub-playbook only) → view → note → timertriggers → ignoreworker → fieldMapping (if mapping) → message (collection only) → form (collection only) → skipunavailable → quietmode → isoversize → isautoswitchedtoquietmode
• Inner task block fields follow specified order: id → version → name → description → playbookName/script/scriptName → type → iscommand → brand → playbooktaskmissingcomponent → istaskmissingcomponenterrordismissed

Boilerplate:

• All tasks have: note: false, timertriggers: [], ignoreworker: false, skipunavailable: false, quietmode: 0, isoversize: false, isautoswitchedtoquietmode: false
• All tasks have continueonerrortype (empty string "" for Stop and Continue modes; errorPath only on tasks with an '#error#' branch)
• All inner task blocks have playbooktaskmissingcomponent: null and istaskmissingcomponenterrordismissed: false

Conditions:

• Every inline condition task (one with a conditions array) has #default# in nexttasks as the fallback branch. Script-based condition tasks route on the script's return values (e.g. yes/no) and may omit #default#.
• Every condition label in nexttasks has a matching entry in conditions (for inline conditions)
• Condition operators are valid (from operator reference table)

Sub-Playbooks:

• separatecontext present on all playbook-type tasks — true (sandboxed) unless the sub-playbook must share context globally (false, deliberate choice; incompatible with generic polling)
• playbookName set in inner task block
• Inputs passed via scriptarguments
• loop block present on every playbook-type task (iscommand: false, exitCondition: "", wait: 1, max: 100; add forEach: true when iterating over list inputs)

Commands:

• Integration command tasks have iscommand: true, script: 'Brand|||command-name', and brand matching the integration
• Automation script tasks use scriptName (not script) with iscommand: false

Inputs/Outputs:

• All ${inputs.X} references in tasks correspond to entries in the inputs array
• inputSections lists all input keys
• inputSections/outputSections present when the playbook defines any inputs or outputs; both omitted when it has neither

Omissions:

• No fromversion field
• No tests field
• No marketplaces field
• No timeout field

Key Conventions

• Playbook ID: lowercase with hyphens (e.g., incident-enrichment-playbook) — a house convention for generated content; IDs only need uniqueness, and real exports usually reuse the display name verbatim (spaces included), so never "correct" the ID of an existing/OOB playbook
• Playbook name: human-readable with spaces (e.g., Incident Enrichment Playbook)
• Task names: verb + noun format (e.g., Get Endpoint Details, Block IP Address)
• UUIDs: real v4 format (e.g., 7c123a77-9e7e-412d-8292-c2a58536723c) — not placeholder patterns
• View positions: main column at x: 450, branches offset at x: 730
• vcShouldKeepItemLegacyProdMachine: false — always present after version
• separatecontext on sub-playbook tasks: true (sandboxed, default choice — outputs must be mapped back explicitly); false shares context globally with the parent (deliberate choice; breaks generic polling)
• Error handling — three modes: Stop (default; no continueonerror), Continue (continueonerror: true + continueonerrortype: "" — ignore the error and proceed), error path (continueonerror: true + continueonerrortype: errorPath + nexttasks.'#error#')