xsiam-scripts

name

xsiam-scripts

description

This skill should be used when the user asks to "create a script", "write an XSIAM script", "build a script", "write an automation", "XSOAR script", "demisto script", "generate script YAML", or needs to develop a standalone Python script with its YAML metadata file for Cortex XSIAM or XSOAR. For connecting to external APIs with multiple commands, use the xsiam-integrations skill instead. For multi-step incident response or automation workflows that orchestrate tasks across integrations, use the xsiam-playbooks skill instead.

XSIAM Script Development

Generate importable unified YAML files for Cortex XSIAM/XSOAR scripts. The Python code MUST be embedded directly inside the YAML file — this is the only format XSIAM accepts for import.

Before Starting

Read the reference files:

• references/script-yaml-spec.md — Script YAML structure, field ordering, and complete example
• ../xsiam-shared/references/common-patterns.md — Python patterns: outputs, error handling, demisto API, arg parsing, indicators

For a specialized script type (transformer, filter, dynamic section, field-change, widget), also read references/script-types-patterns.md — see the Script Types section below.

Guided Mode

If the user asks for guided or standardized mode ("guided", "guided mode", "standardize", "standardized", "walk me through it", "ask me the standard questions"), read ../xsiam-shared/references/guided-mode.md and follow it before step 1 of the workflow. Otherwise skip this — never load guided-mode files on the default path.

What is a Script?

Scripts are standalone automations that process data, orchestrate actions, or transform context — without connecting directly to an external product. The Python code is embedded in a top-level script: |- field.

Use a script when:

• Processing or transforming incident/alert context data
• Chaining multiple integration commands together via execute_command()
• Implementing utility logic (formatting, enrichment, normalization)
• Running calculations or lookups on existing context data

Use the xsiam-integrations skill instead when you need to connect to an external API with authentication and multiple commands.

Script Types

Scripts fall into several categories based on their tags and execution context. Standard scripts (no functional tag) follow the workflow below directly. For specialized types, also read references/script-types-patterns.md for the specific pattern and a complete example.

Type	Tag	When to use
Standard	(none)	General-purpose: data processing, execute_command chaining, utilities
Transformer	transformer	Transform a value inline in playbook task input mappings
Filter	filter	Evaluate a condition in playbook task conditions
Dynamic Section	dynamic-section	Render read-only display content in case/issue layouts
Field-Change Triggered	field-change-triggered	React to a field value change on a layout
Widget	widget	Power a dashboard or report widget

Workflow

1. Gather Requirements

Determine:

• What the script does (input → processing → output)
• Arguments it accepts (names, types, required/optional, defaults)
• Context output it produces (contextPath prefix and fields)
• Whether it operates on incident/alert context, indicators, or standalone data
• Whether it chains to other integrations via execute_command()

2. Generate the Unified YAML

Build a single .yml file. The field order must match the real XSIAM export structure — see the annotated field-order reference under ## Script Structure in references/script-yaml-spec.md, and the single-line ordering in the validation checklist below.

Placements that are easy to get wrong:

• vcShouldKeepItemLegacyProdMachine: false comes immediately after commonfields.
• Each args entry starts with supportedModules: [] as its first key.
• timeout (optional Go duration string, e.g. 30m0s) goes between subtype and pswd — omit it unless the script needs longer than the platform default.
• runas: DBotWeakRole, engineinfo: {}, and mainengineinfo: {} close the file and are all required.

3. Python Code Conventions

The embedded Python follows XSOAR/XSIAM conventions:

• First line: register_module_line('ScriptName', 'start', __line__()) — use the exact script name
• Last line: register_module_line('ScriptName', 'end', __line__()) — use the exact script name
• Do not include from CommonServerPython import *, from CommonServerUserPython import *, or import demistomock as demisto — the platform injects these automatically at runtime. Unified YAML must not contain them.
• Simple main() with try/except and return_error()
• Parse args with argToList(), argToBoolean(), arg_to_number(), arg_to_datetime() — never raw casting
• Return results with CommandResults and return_results()
• Chain to integrations with execute_command('command-name', args) (the platform alias) — it raises automatically on command failure and returns the extracted Contents, so no manual isError() check is needed
• In XSIAM alert-context scripts: use demisto.alert() (not demisto.incident()), and immediately normalize the result to flatten CustomFields:

  issue = demisto.alert()
  cf = issue.pop('CustomFields', {})
  issue.update(cf)
  

4. File Output

Generate a single file:

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

Optionally also generate:

• ScriptName_test.py — pytest test file (separate, not for import)

5. Validate

Before delivering, run the embedded-Python parse check and confirm it exits 0 (prints OK). If it errors, fix the YAML/Python before delivering:

python3 -c "import yaml, ast; d = yaml.safe_load(open('ScriptName.yml')); ast.parse(d['script']); print('OK')"

This catches misindented block scalars, tab characters, and Python syntax errors that 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:

• Python code is embedded using script: |- (top-level string, not nested mapping)
• Python indentation is consistent within the YAML block (2 spaces from key level)
• No CommonServerPython, CommonServerUserPython, or demistomock imports — the platform injects these at runtime
• main() has try/except with return_error()
• Field ordering matches spec: commonfields → vcShouldKeepItemLegacyProdMachine → name → script → type → tags → comment → enabled → args → outputs → scripttarget → subtype → timeout (optional) → pswd → runonce → dockerimage → runas → engineinfo → mainengineinfo
• vcShouldKeepItemLegacyProdMachine: false is present at top level
• enabled: true, scripttarget: 0, pswd: "", runas: DBotWeakRole, engineinfo: {}, mainengineinfo: {} are all present
• Every args entry has supportedModules: [] as its first key
• Arg defaults use defaultValue: key (not default:); list args include isArray: true
• All args have descriptions
• All outputs have contextPath, description, and type
• Docker image is a pinned 3.12.x version (not :latest)
• Do not include fromversion, marketplaces, tests — content-pack CI fields only
• If the script performs bulk work, paginated loops, or other long-running processing, set timeout to a Go duration string (e.g. 30m0s). The platform default for scripts is short (~5m); long-running scripts will be killed without it. Place between subtype and pswd.
• First line of embedded Python is register_module_line('ScriptName', 'start', __line__()) with the correct script name
• Last line of embedded Python is register_module_line('ScriptName', 'end', __line__()) with the correct script name
• No tab characters; consistent YAML indentation throughout
• XSIAM alert-context scripts use demisto.alert() not demisto.incident()
• If demisto.alert() is called, CustomFields is immediately flattened into the alert dict via issue.pop('CustomFields', {}) + issue.update(cf)
• Arg parsing uses helpers (argToList, argToBoolean, arg_to_number, arg_to_datetime), not raw casting

Key Conventions

• Script names: kebab-case (e.g., get-case-url, normalize-timestamp)
• Python functions and variables: snake_case
• Context prefix format: Vendor.Object (e.g., FormattedData.Result)
• Docker image: pinned 3.12.x (e.g., demisto/python3:3.12.12.6947692) — check your tenant for the latest available build
• demisto.alert() for XSIAM alert context; demisto.incident() is the XSOAR equivalent
• Use execute_command() (platform-provided alias) not demisto.executeCommand() directly — it raises on command failure (fail_on_error=True) and returns extracted Contents (extract_contents=True) by default