Building a Flow

You build a flow in the flow editor: you set the trigger conditions, drag steps onto a canvas, and draw wires that decide what runs after a step succeeds or fails. This page explains each part of the editor and how UTMStack v12 runs what you draw.

Open the editor

  • To create a flow, click New flow on SOAR > Flows (see Flows Page).

  • To edit a flow, click View in its row. Shipped flows open read-only; copy them to change them.

Editor layout

The flow editor in Visual mode: the palette of step types on the left, the canvas with the Alert match trigger and wired steps in the middle, the When panel with the trigger conditions and Save and close on the right, Edit with AI and the Visual and Code tabs at the top, and Delete and Save at the bottom
PartWhat it does
Visual tabThe canvas. You drag steps from the palette and wire them together.
Code tabThe same flow as YAML text. Changes in one tab show in the other. If the YAML cannot be read, the editor shows "Can't apply the YAML: …".
Palette (left)Ready-made shell steps for Windows, Linux and macOS, plus one entry per step type. Drag an entry onto the canvas.
Trigger (the "When" node)The conditions an alert must match.
Inspector (right)The settings of the selected step or of the trigger.
Flow name (top)Click it to open Flow details: name, description and max depth.
Edit with AIOpens the SOC-AI assistant on this flow (panel "SOAR flow editor"). Shown only when an AI provider is set up.

You can hide the side panels with Hide palette and Hide inspector.

Set the trigger conditions

Select the trigger node ("When — An alert matches all of these conditions") and add conditions with Add condition. Each condition has a field, an operator and a value. The flow runs only when all conditions match ("The flow runs when an alert matches ALL of these conditions."). Click Save and close to keep the conditions.

How matching works:

  • Conditions are checked when a correlation rule raises an alert, before anyone has looked at it.

  • Every matching alert can start its own run. UTMStack does not limit how many runs a flow starts, so a rule that fires often starts the flow often. Narrow conditions matter.

  • After you save a flow or switch it on, the engine picks up the change when the flow file changes, and in any case within about a minute.

The field picker offers these alert fields. They are read from the alert at the moment it is raised, so there is no alert status to match on.

LabelField
Alert namename
Severityseverity (low, medium or high)
Categorycategory
Techniquetechnique
Data typedataType
Data sourcedataSource
RiskimpactScore
Adversary IP, user, hostadversary.ip, adversary.user, adversary.host
Target IP, user, host, porttarget.ip, target.user, target.host, target.port
ProtocollastEvent.protocol
ActionlastEvent.action
Origin IP, user, host, portlastEvent.origin.ip, lastEvent.origin.user, lastEvent.origin.host, lastEvent.origin.port

You can also type another field path. A .keyword ending is ignored.

Operators:

OperatorScreen labelNotes
ISisExact match.
IS_NOTis not
CONTAINScontains
NOT_CONTAINSdoes not contain
START_WITHstarts with
NOT_START_WITHdoes not start with
ENDS_WITHends with
NOT_ENDS_WITHdoes not end with
EXISTSexistsNo value needed.
NOT_EXISTSdoes not existNo value needed.
IS_ONE_OFis one ofTakes a list of values.
IS_NOT_ONE_OFis not one ofTakes a list of values.

Comparisons are case-sensitive: Brute Force does not match brute force.

Match on the alert name of one correlation rule (field name, operator is). The rule decides what is suspicious; the flow decides what to do about it. Broad conditions such as "severity is high" can start a flow on many unrelated alerts.

Changed from UTMStack v11: the operators CONTAIN, DOES_NOT_CONTAIN, EXIST, DOES_NOT_EXIST, IS_BETWEEN, IS_GREATER_THAN and IS_LESS_THAN_OR_EQUALS are not trigger operators any more. A condition with an unknown operator never matches.

Add steps

Drag a step type from the palette onto the canvas, then fill in its settings in the inspector. See Step Types for every type and field.

The palette sections Windows, Linux and MacOS hold ready-made shell steps you can drop in and adjust:

  • Isolate host (block all traffic)

  • Shutdown host

  • Kill process by PID

  • Log user out

  • Disable target user

  • Block adversary IP

  • Restart host

  • Uninstall a package

  • Remove file

Each is written for the platform's default shell (cmd on Windows, bash elsewhere). The same commands are in the Templates menu of every Shell step, written for the shell you chose. Some contain markers you must replace before you save: <PID> in "Kill process by PID", <SESSION_ID> in the Windows "Log user out", <PACKAGE> in "Uninstall a package" and <PATH> in "Remove file". "Isolate host (block all traffic)" also cuts the machine's connection to UTMStack, so you cannot undo it from UTMStack; Worked Examples: Responding Through Other Systems shows an isolation that keeps the agent connected.

The PowerShell version of "Disable target user" (in the Templates menu of a step whose shell is powershell) puts double quotes around $(alert.target.user). Remove those quotes: UTMStack already quotes the value for PowerShell, and the two sets of quotes together make the account name wrong. The cmd version, which the Windows palette section uses, is correct as it is. See Placeholders.

Wire the steps

Every step has two handles at the bottom:

  • The green handle (bottom left) is the success wire. Steps on it run when this step succeeds.

  • The red handle (bottom right) is the error wire. Steps on it run when this step fails.

Wire the trigger to the steps that should run first. These start steps all run at the same time. Several wires leaving one step also run in parallel.

The wire that is not taken is recorded as Unreachable for the steps on it, so you can see in Execution history which branch ran.

To run the next step whatever happens, wire it to both the green and the red handle. The step then runs once, and Execution history also lists it once as Unreachable for the wire that was not taken. That extra row is expected.

A step with several incoming wires runs once for each wire that fires. The editor hint calls this an "AND-join", but in UTMStack v12.0.2 the step does not wait for all its parents: if two parent steps succeed, the step runs twice. If you need a step to run once, give it a single incoming wire.

Max depth

Max depth is the number of steps one path may chain. The default is 50; you can set 1 to 1000 in Flow details. Steps deeper than the limit are skipped.

Save the flow

Click Save. The editor checks:

  • The flow has a name ("Name is required").

  • At least one condition has a field ("At least one condition with a field is required").

  • At least one step is connected to the trigger ("Add at least one node and connect it to the trigger.").

  • HTTP steps have a valid http or https address and, if set, a valid JSON body.

  • Open incident steps have a name.

  • Send email steps have at least one valid recipient and a subject.

The server checks again: every wire must point to an existing step and not to itself, the step type must be known, and each type's required fields must be filled in. A flow with no conditions is refused, because it would match every alert.

If the server refuses a flow for a content problem, it may answer only "operation failed" without the reason. Check the points above, or open the Code tab to look for the problem.

A flow created from scratch is switched on as soon as it is saved. See Flows Page.

Test before you switch on

Use Trigger flow on the Flows page to run the flow once against a stored alert and on a test machine (Administrators only). Check each step in SOAR > Execution history, then switch the flow on.

The Code tab (YAML)

The Code tab shows the flow as a YAML list with one item. You can paste or edit a whole flow here.

- name: Block brute force source on Linux
  description: Block the attacking address on the host that raised the alert, then notify.
  conditions:
    - operator: IS
      field: name
      value: 'System Linux: Possible Brute Force Attack'
  maxDepth: 50
  roots:
    - step_0
  nodes:
    step_0:
      kind: executor
      executor: shell
      platform: ubuntu
      shell: bash
      command: iptables -I INPUT -s $(alert.adversary.ip) -j DROP
      onSuccess:
        - step_1
    step_1:
      kind: executor
      executor: notify
      params:
        type: WARNING
        message: Blocked $(alert.adversary.ip) on $(alert.dataSource)

Flow keys:

KeyMeaning
nameFlow name, up to 150 characters. Required.
descriptionUp to 512 characters.
conditionsList of field, operator, value. At least one.
maxDepth1 to 1000, default 50.
rootsThe start steps (step identifiers). At least one, no duplicates.
nodesThe steps, keyed by step identifier (for example step_0).

Step keys:

KeyMeaning
kindexecutor (does something) or enrichment (fetches data for later steps).
executorThe step type: shell, http, llm_enrich, notify, incident, mail or conditional.
commandShell steps: the command.
shellShell steps: cmd or powershell on Windows, bash or sh elsewhere.
platformShell steps: the platform the command is written for.
agentShell steps: the host to run on, when you pin the step to one host.
excludedAgentsShell steps: hosts to skip.
paramsSettings of non-shell steps. See Step Types.
onSuccessSteps to run when this step succeeds.
onErrorSteps to run when this step fails.

Create or edit with AI

If an AI provider is set up, Using AI in the New flow dialog and Edit with AI in the editor hand the work to the SOC-AI assistant. Describe what the flow should do; the assistant drafts the flow. Review every step before you save, because the result is a normal flow that acts for real. See SOC-AI Assistant.

  • Step Types

  • Placeholders

  • Step Outputs and Variables

  • Running Steps on Another Host

  • Troubleshooting Flows