Placeholders
Placeholders put values from the alert into a step, for example the attacker's address into a firewall command. UTMStack v12 fills them in when the step runs and, since v12.0.2, quotes every value it inserts. This page explains the syntax, which alert fields you can use, and how the quoting works.
Syntax
Write $(alert.<field path>). Every alert path starts with alert..
iptables -I INPUT -s $(alert.adversary.ip) -j DROPStored variables use a different form, $[variables.NAME]; see Step Outputs and Variables.
You can use placeholders in shell commands and in the fields of HTTP call, LLM enrichment, notification, incident and email steps. In the step editor, the Insert field menu lists the alert fields and puts the placeholder at the cursor.
Changed from UTMStack v11: $(adversary.ip) is now $(alert.adversary.ip), and $(log.message) is now $(alert.lastEvent.log.message). Commands copied from UTMStack v11 must be rewritten.
Common alert fields
| Placeholder | Holds |
|---|---|
$(alert.id) | The alert identifier. |
$(alert.name) | The alert name (the correlation rule name). |
$(alert.severity) | low, medium or high. |
$(alert.category) | The rule category. |
$(alert.technique) | The MITRE ATT&CK technique written in the rule. |
$(alert.dataType) | The kind of data that raised the alert, for example wineventlog or linux. |
$(alert.dataSource) | The host or source that raised the alert. Shell steps run here by default. |
$(alert.adversary.ip), $(alert.adversary.user), $(alert.adversary.host) | The attacking side. |
$(alert.target.ip), $(alert.target.user), $(alert.target.host), $(alert.target.port) | The attacked side. |
$(alert.adversary.process), $(alert.target.file), $(alert.target.path) and similar | Process, file and path names, when the rule fills them in. |
$(alert.lastEvent.<field>) | A field of the last event behind the alert, for example $(alert.lastEvent.origin.ip), $(alert.lastEvent.action) or a raw log field such as $(alert.lastEvent.log.message). |
Which fields an alert carries depends on the rule that raised it. Open a recent alert of the same rule to see what is filled in.
What happens when the value is missing
A placeholder whose field does not exist in the alert is left as written. For example, $(alert.target.user) stays the literal text $(alert.target.user) if the alert has no target user, and the command is sent with that text. In bash, sh and PowerShell, $( … ) is itself shell syntax, so the shell then tries to run a command with that name and the step usually fails. Test a flow with Trigger flow against a real alert of the same rule before you switch it on.
Automatic quoting
Every value UTMStack inserts is quoted for the step's shell:
| Shell | What UTMStack does with the value |
|---|---|
bash, sh | Wraps it in single quotes. A single quote inside the value is escaped. |
powershell | Wraps it in single quotes. A single quote inside the value is doubled. |
cmd | Puts ^ before each special character: ampersand, vertical bar, less-than, greater-than, caret, double quote, percent and exclamation mark. Line breaks become spaces. |
| auto (no shell chosen) | Wraps it in single quotes, as for bash, even when the step runs on Windows, where the agent then uses cmd. Choose the shell explicitly. |
For example, on bash:
# You write
iptables -I INPUT -s $(alert.adversary.ip) -j DROP
# The agent receives
iptables -I INPUT -s '203.0.113.7' -j DROPDo not put your own quotes around a placeholder. Write -s $(alert.adversary.ip), not -s "$(alert.adversary.ip)". Your quotes and UTMStack's quotes combine and the value no longer arrives as intended. Some shipped flows still contain quoted placeholders; fix them in your copy (see Shipped Flows). The editor's own Disable target user template for powershell also puts double quotes around $(alert.target.user): remove them after you insert it. For cmd, UTMStack adds no quotes, so the double quotes in the cmd template are needed and can stay.
Building text from several pieces in bash
Because each value arrives as its own single-quoted piece, you can glue it to fixed text in bash and sh by writing the pieces next to each other, without spaces. The shell joins them into one argument:
# You write
curl -u $[variables.API_USER]:$[variables.API_SECRET] -d '{"address":"'$(alert.adversary.ip)'"}' https://$[variables.FW_HOST]/api/...
# The shell receives the pieces
curl -u 'apiuser':'s3cret' -d '{"address":"''203.0.113.7''"}' https://'fw.example.com'/api/...
# and runs the command with
# -u apiuser:s3cret -d {"address":"203.0.113.7"} https://fw.example.com/api/...This is the reliable way to send alert values and secret variables to another system's API in UTMStack v12.0.2. See Worked Examples: Responding Through Other Systems.
Placeholders outside shell commands
Values placed into HTTP call, LLM enrichment, notification, email and incident fields are quoted too, with single quotes. A notification message written as Blocked $(alert.adversary.ip) arrives as Blocked '203.0.113.7'.
Keep in mind for UTMStack v12.0.2:
An HTTP address, header or body that contains a placeholder receives the value with the single quotes around it. Many APIs will not accept that, so check the request on the receiving side before you rely on it. A header such as
Authorization: Bearer $[variables.TOKEN]arrives asBearer 'token', which most services refuse.A value that contains an apostrophe, a double quote, a backslash (for example
CORP\jdoe) or a line break breaks an HTTP call, LLM enrichment, notification, email or incident step that inserts it: if it is a start step the run does not start, otherwise the step stays Waiting and never runs.Stored variables inserted into these fields are quoted the same way. A variable value with one of those characters makes the step fail with a result that contains
params:(see Step Outputs and Variables).Placeholders typed in the Query params tab of an HTTP call step are never filled in (see Step Types).
Quotes around a value are harmless in text that people read, such as a chat message, a ticket title or an email subject. When another system must receive the exact value (an IP address for a firewall, a token in a header), send the request from a shell step instead, as shown in Worked Examples: Responding Through Other Systems.
Related pages
Step Outputs and Variables
Step Types
Building a Flow
Troubleshooting Flows