Step Types

A flow is made of steps (the editor calls them nodes). This page lists every step type the flow editor offers in UTMStack v12, its fields and defaults, how it behaves when it runs, and the messages it leaves when it fails.

Two kinds of step

KindWhat it doesOutput for later steps
ExecutorDoes something: runs a command, sends a message, opens an incident, checks a condition.None.
EnrichmentFetches data: an HTTP answer or an AI answer.Yes. Later steps can insert parts of it. See Step Outputs and Variables.

The palette shows the kind under each step type (EXECUTOR or ENRICHMENT).

Every step ends in success or failure. On success the green wires run, on failure the red wires run. See Building a Flow.

Step types at a glance

Palette labelType in YAML (executor)KindUse it to
Shell (endpoint agent)shellExecutorRun a command on a machine through its UTMStack agent.
HTTP callhttpEnrichmentCall a web address (an API of a firewall, ticketing tool, chat service) from the UTMStack server.
LLM enrichmentllm_enrichEnrichmentAsk the SOC-AI assistant a question and use its answer in later steps.
Send notificationnotifyExecutorPost an in-app notification.
Open incidentincidentExecutorOpen an incident linked to the alert.
Send emailmailExecutorSend an email.
Conditional (if/else branch)conditionalExecutorChoose the next steps based on alert values or earlier step outputs.

Fields every step has

When you select a step on the canvas, the inspector on the right shows its settings. Every step has an ID field at the top: the step identifier (for example step_0). Later steps use it to insert this step's output ($(step_0.result)), and Execution history shows it in the Node column. Give enrichment steps short, meaningful IDs such as ticket or ai_check.

At the bottom of the inspector, Save keeps your changes to the step, Cancel drops them and Delete node removes the step. Nothing is stored on the server until you click Save for the whole flow.

Shell (endpoint agent)

Sends a command to a UTMStack agent and waits for the result.

FieldYAML keyNotes
Platformplatformany (default for a new step), or a platform such as windows, linux, ubuntu, centos, darwin and the platforms of your agents. It filters the host list and the shell list.
Shellshellauto (default for a new step), or cmd and powershell for Windows, bash and sh for other platforms. Choosing a platform sets cmd (Windows) or bash (others).
CommandcommandRequired. The buttons above the box are Templates (ready-made commands, available once a platform is chosen: "First select target platform"), Insert field (alert values and outputs of earlier enrichment steps) and Variables (stored variables).
Run onagent, excludedAgentsalert source (default), one host, or all except. See Running Steps on Another Host.

Always choose the shell. With auto, the agent uses cmd.exe on Windows and sh on Linux and macOS, while UTMStack quotes inserted values for sh. On Windows that adds stray single quotes to every inserted value. See Placeholders.

How the agent runs the command:

ShellStarted as
cmd (or auto on Windows)cmd.exe /C <command>
powershellpowershell.exe -Command <command> (Windows PowerShell)
bashbash -c <command>
sh (or auto on Linux and macOS)sh -c <command>
  • The command runs with the agent's own rights: root on Linux, the Local System account on Windows.

  • A command that ends with a non-zero exit code is a failure and takes the red wire. This needs agents from UTMStack v12.0.2 or later; older agents report every finished command as a success.

  • The step keeps the command's output. When the command fails, the output holds what the command printed, its error text and a last line such as exit status 1. Execution history does not show the output; read it through the API (see SOAR API) or run the command in the Interactive Console to see it.

  • Agents from UTMStack v12.0.2 cut output longer than 65,536 bytes and add the line ... output truncated, showing first N of M bytes.

  • If the agent is offline, the step is marked Failed with the cause Agent offline and its red wire runs. If no agent has the host name, the step is marked Failed with the result soar shell: agent not found.

  • An agent installed with remote control disabled answers refused: this agent was installed with no-remote-control, and the step fails.

  • Commands for one agent run one at a time, so a long command delays the next one on the same machine.

  • UTMStack stops waiting after 5 minutes and marks the step Failed. The command itself may still be running on the machine.

The Platform field does not stop a step from running on a machine of another platform. The step runs on whatever host Run on resolves to. If a Windows command reaches a Linux machine, it simply fails. Use trigger conditions (for example Data type) to keep a flow on the right kind of machine.

HTTP call

Sends one web request. The request leaves from the UTMStack server, not from an agent, so the server must be able to reach the address.

FieldYAML key (inside params)Notes
URLurlRequired. Pick https:// or http:// in the list, then type the rest of the address. The full address is shown under the box. "Not a valid http(s) URL." marks a bad address.
MethodmethodGET (default in the editor), POST, PUT, PATCH, DELETE, HEAD or OPTIONS. If the key is missing in YAML: POST when a body is set, otherwise GET.
HTTP headers tabheadersName and value rows (Add header).
Query params tab(added to the URL)Name and value rows (Add param), joined to the address after ?.
Body (JSON) tabbodyShown only for POST, PUT and PATCH. Must be valid JSON ("Invalid JSON" otherwise).
(Code tab only)timeoutSecSeconds to wait for the answer. Default 30.

How it behaves:

  • A new HTTP step starts with four headers: Content-Type: application/json, Accept: */*, Accept-Encoding: gzip, deflate, br and Connection: keep-alive. Each header and query row has a tick box; rows you untick are not saved.

  • When a body is set, Content-Type: application/json is sent.

  • Any answer outside the 200 to 299 range is a failure. The result then holds the status line and the answer, for example 401 401 Unauthorized followed by the text the service sent back.

  • The step stores the status line and the first 4,096 characters of the answer.

  • Because the step is an enrichment step, the answer must be JSON (an empty answer counts as {}). Later steps can insert values from it. An answer that is not JSON makes the step fail, even with a 200 status; the result still shows the status line and the answer.

  • Many services answer with plain text (a Slack webhook answers just ok). For those, open the Code tab and change the step's kind from enrichment to executor. The answer is then not read as JSON, and later steps cannot use it.

  • The server checks the certificate of an https address. There is no option to skip that check, so a device with a self-signed certificate is refused. For such devices, run the call from a shell step on a host that can reach them (see Running Steps on Another Host).

  • Redirects are followed.

Remove the Accept-Encoding header from enrichment steps. When that header is set by hand, the server receives the answer compressed and does not unpack it, so a JSON answer from services that compress (many cloud APIs do) fails: the result shows a 200 status line followed by unreadable compressed bytes. Without the header, UTMStack asks for compression itself and unpacks the answer.

Placeholders in the Query params tab are not filled in. The editor encodes the rows into the address, which turns $(alert.adversary.ip) into %24%28alert.adversary.ip%29, and the value is never inserted. Put alert values in the address path or the body instead. In UTMStack v12.0.2 every inserted value also arrives in single quotes; see Placeholders.

LLM enrichment

Sends a prompt to the SOC-AI assistant (LLM stands for large language model, the AI behind the assistant). The assistant may use its own tools to look things up before it answers.

FieldYAML key (inside params)Notes
PromptpromptRequired. You can insert alert values with Insert field.

How it behaves:

  • The editor hint reads: "The model is instructed to always answer with a single JSON object carrying a "result" property. The backend guarantees this shape even if the model deviates." Later steps insert the answer with $(<step id>.result), for example $(step_2.result). If the model answers in plain text, the whole text becomes result.

  • It needs a working AI provider. See AI Providers.

  • Like every step, it is stopped after 5 minutes and marked Failed.

  • When the SOC-AI service cannot be reached or answers with an error, the result starts with soar llm:, for example soar llm: upstream 503: …. When the assistant started answering and then failed, the result holds the assistant's message stream instead, including an event: error entry.

Send notification

Posts an in-app notification for the tenant, shown in the bell menu.

FieldYAML key (inside params)Notes
LeveltypeINFO (default), WARNING or ERROR. Any other value becomes INFO.
MessagemessageRequired. "Notification text. Templates like $(alert.name) are interpolated."

Open incident

Opens an incident and links the alert that started the flow.

FieldYAML key (inside params)Notes
Incident namenameRequired. Example from the editor: Suspicious login on $(alert.dataSource).
DescriptiondescriptionOptional context for responders.

How it behaves:

  • The incident's severity is the alert's severity (low when the alert has none).

  • Incident names must be unique in a tenant. A fixed name works only once: the second run fails because an incident with that name already exists. Put a value that changes per alert into the name, for example $(alert.id).

  • The step fails with soar incident: no alert linked to this execution when the run has no alert, for example a manual run with raw JSON that has no alert id.

Send email

Sends an email through the tenant's mail settings (Configure > Settings > Email Configuration). Set those up and test them first.

FieldYAML key (inside params)Notes
To (comma-separated)toRequired. At least one valid address ("Invalid email address: …" otherwise).
CC (comma-separated, optional)cc
SubjectsubjectRequired. Example from the editor: Alert on $(alert.dataSource).
BodybodyRequired by the server when you save the flow. Sent as HTML.

The email has no attachments. A sending problem fails the step with a result that starts soar mail: send: followed by the mail server's answer.

Conditional (if/else branch)

Checks one or more conditions against the run's data. If all conditions match, the green wire runs; if any condition misses, the red wire runs. The editor hint reads "All conditions must match. Match → success branch (green); miss → error branch (red)."

FieldYAML key (inside params)Notes
ConditionsconditionsField, operator, value; Add condition adds a row. Same 12 operators as the trigger (see Building a Flow). At least one.

What you can check:

  • Alert values, with field paths that start with alert., for example alert.severity or alert.target.host. The field box suggests the common ones.

  • Outputs of earlier enrichment steps, with the step identifier first, for example step_2.result or step_1.data.verdict.

Values are compared as text and are case-sensitive. A number is compared by its digits, so alert.target.port is 22 works.

A conditional step whose conditions do not match is shown as Failed in Execution history, with the result condition failed: <field> <operator> <value>. That only means the red branch was taken.

Enter "is one of" and "is not one of" lists in the Code tab. In UTMStack v12.0.2 the Visual tab saves the comma-separated values of a Conditional step as one piece of text, not as a list. "is one of" then never matches and "is not one of" always matches. Write the values as a YAML list instead:

conditions:
  - field: alert.dataSource
    operator: IS_NOT_ONE_OF
    value:
      - DC01
      - SQL01

Trigger conditions are not affected: the editor splits their lists correctly.

Limits that apply to every step

LimitValue
Steps running at the same time on the server5
Longest time one step may run5 minutes; the step is then marked Failed
HTTP call default timeout30 seconds (timeoutSec in the Code tab)
A step left in Executing after a server restart is closed afterabout 6 minutes (AI and conditional steps are queued again; others are marked Failed)
Check for waiting stepsimmediately when new work arrives, and every 15 seconds
  • Building a Flow

  • Placeholders

  • Step Outputs and Variables

  • Running Steps on Another Host

  • Troubleshooting Flows