Using tokens

Tokens substitute field values after a search job runs. You can use them in Job Scheduler Active Actions.

The following token types are available:

• local - taken from a search result of a specific job. Written as {{token_name}}. Available in the context of one search result
• global - taken from values entered in Job Scheduler's Global Params section. Written as <global_token_name>. Available in the context of one search job run

The local token syntax is {{_source.field_name}}, where field_name is the name of a field in the search result. For example, use {{_source.host.ip}} for the host.ip field.

The global token syntax is <global_token_name>, where global_token_name is the global token name. For example, use <guid> for the guid value.

Global parameters can use predefined functions, which are computed once at the start of a search job.

List of available predefined functions for global parameters:

Function	Description
guid()	Generates a unique identifier

The <job-meta-field:field_name> token refers to a search job field or one of its _meta fields. An example follows below.

Available search job fields:

Parameter	Syntax	Description
title	<job-meta-field:title>	Search job name
description	<job-meta-field:description>	Search job description
_tag_values	<job-meta-field:_tag_values>	JSON describing all job tags

List of available _meta fields:

Parameter	Syntax	Description
id	<job-meta-field:_meta.id>	Search job ID
type	<job-meta-field:_meta.type>	Object type, shown in Job Scheduler's Object Type field
version	<job-meta-field:_meta.version>	Job Scheduler version
module	<job-meta-field:_meta.module>	Undefined for a job you create, or SAF Cyber Security when imported from that module
created	<job-meta-field:_meta.created>	Search job creation date
update	<job-meta-field:_meta.updated>	Search job update date
tag_ids	<job-meta-field:_meta.tag_ids>	Job tags; multiple tags are allowed

To check how tokens work, create a search job. First, enter its name and description:

• Name - RULE - CS - Sysmon - DetectedTaskList
• Description - triggered when events indicating a task list view on a host are detected

Then enter the search query and time settings:

source sysmon_operational-*
| search event.code=1 AND command_line="C:\\Windows\\system32\\tasklist.exe"
| aggs count, values(winlog.process.pid) as winlog.process.pid, latest(rule_name_technique_id) as rule_name_technique_id, latest(rule_name_technique_name) as rule_name_technique_name, values(event.action) as event.action, values(host.ip) as host.ip by host.name
| eval title=<job-meta-field:title>
| where count > 1
| table host.name, count, winlog.process.pid, rule_name_technique_id, rule_name_technique_name, event.action, host.ip

• Time interval - Last 60 minutes
• Time field - @timestamp
• Lock duration (sec) - 60

In the Schedule section, set:

• Schedule type: Cron Expression
• Cron: 3-59/5 * * * *
• Schedule delay: 0

Suppression is disabled in a new job. Configure an automatic rule:

1. Turn on Suppression
2. Select Automatic suppression
3. Set Suppression window to 5 minutes
4. Enter host.name in the Field field

Throttling is disabled in a new job. Enable it, set the suppression duration to 5 minutes, and select host.name as the throttling field. The query groups results by host.name, so a separate automatic entry is created for each host. Repeated results with the same host.name are not sent to Active Actions while the entry is active. For details, see Throttling in Job Scheduler.

In the Global Params section, add:

• Key: guid
• Value: guid()

The example uses the local token {{_source.host.name}}, the global token <guid>, and the token <job-meta-field:title>:

Job metadata in a query

When local tokens are used, _source is a system object containing all fields of the search result. The general token syntax is {{_source.field_name}}, where field_name is a field name from the search result.

When the search job runs, it creates an incident with the corresponding values substituted for the tokens.