Introduction
Quick Start
To get started, you can run this simple example search for process
events from the last 24 hours:
FROM process earliest =-24h
Next, you could substitute process
with any of the other event types (see the Build With Me section below). You can even query multiple event types, as in this example:
FROM process, auth earliest =-12h
Query Language Fundamentals
To specify strings in the query language, use single quotes (and note that the WHERE is always optional):
FROM process WHERE image_path CONTAINS 'powershell.exe'
To search for string values that themselves include single quotes, escape with an e
before the first single quote and with a backslash before any single quote(s) in the string:
from process where commandline contains e'echo \'mimikatz\''
Operators and any values specified are case-insensitive. In the examples, we've capitalized the operators only for emphasis.
A search cannot query alerts and events simultaneously and two independent queries must be run.
When running a multi-event search using field names independent to individual event types, individual queries are run and the results returned are a union of those queries.
To see more complex query options and examples, including boolean logic, regex matching, and more, see the Operators section.
Querying Common Fields and Logical Types
It is also possible to make queries without specifying any schema(s) and query all relevant schemas automatically.
Common Fields exist in the schemas for multiple event types. For example, sensor_type = 'ENDPOINT_REDCLOAK'
would return all events that come from the Red Cloak™ Endpoint Agent, for all relevant schemas.
Logical Types can be used if you don’t know which schema(s) or specific field(s) to query. Logical types are preceded by the @
symbol. These automatically query the relevant schemas. For example, you could query:
@ip='8.8.8.8'
@user CONTAINS 'system'
For more information and examples on logical types, see the Logical Types section.
Querying Alerts
Alerts can be queried by fields that are specific to the alert schema as well as fields from the event schemas. Querying by event schemas provides greater flexibility to search, using a much larger set of fields instead of being constrained to the more limited fields within the alert. It also allows for querying fields that have a certain relationship which have been generalized within the alert. An example of this use case is, searching for the fields process.image_path
and process.parent_image_path
, both of which are normalized as the fileName
entity within the alert schema.
To query for alerts, the ’alert’ data type must be specified by using the from alert
clause at the beginning of the query. Specifiying just event fields without explicitly asking for the alert data type will run an events search. When running an alert search using event fields, the event type must be prepended to the field name. E.g. To search alerts using the process image path, you must specify the fields as process.image_path
.
Alert queries can also use logical types as outlined above.
Query for an alert using the title field within the alert schema:
from alert where title contains 'Powershell'
Query for an alert using the commandline field within the event schema:
from alert where process.commandline contains 'powershell.exe'
Query for an alert using logical field types:
from alert where @ip = 10.1.1.10
Build With Me
YOU ENTERED:
sensor_type CONTAINS 'ENDPOINT' EARLIEST=-7d | AGGREGATE COUNT BY sensor_type
Quick Tip: User Shift + Enter to search your query
AVAILABLE FIELDS
The unaltered source data of a normalized event message captured in raw form
An ID of the sensor which generated an event
Event time in microseconds (<C2><B5>s)
Host ID -- unique identifier for the host where the event originated; preferably a uuid
Hostname
Ingest time in microseconds (<C2><B5>s).
Original, unadulterated data prior to any transformation.
Full resource string identifying the record.
An ID for the data supplied by the application that originated it. Ex: redcloak-agent-id, iSensor Dev IP
Type of device that generated this event. Ex: redcloak, iSensor
The ID of the tenant that owns this specific to CTPX ID
FOLLOWED BY AN OPERATOR
AND A VALUE
Operators
The query language supports the operators listed below. All string values must be enclosed in single quotes and are interpreted as literals. All searches are case insensitive (contains, CONTAINS, and ConTAinS are equivalent).
Operator | Description |
---|---|
= <literal> |
case-insensitive exact match |
!= <literal> |
boolean NOT of equality |
> <number> |
numeric greater than |
>= <number> |
numeric greater or equal |
< <number> |
numeric less than |
<= <number> |
numeric less than or equal |
contains <string> |
case-insensitive substring match of string literal in field |
<fieldname> !contains <string exclusion> |
negation of case insensitive substring match of string literal in field |
matches <string> |
case sensitive wildcard match of glob style string pattern in field |
<fieldname> !matches <string exclusion> |
negation of case insensitive wildcard match of glob style string pattern in field |
matches_regex <string> |
case insensitive regex match of string pattern in field |
!matches_regex <string> |
negation of case insensitive regex match of string pattern in field |
in <value list> |
boolean expression evaluates true if field value is contained in value list |
!in <value list> |
boolean expression evaluates true if field value is not contained in value list |
is not null |
tests for the existence of field and that it is not null |
is null |
returns true if specified field does not exist or is null |
contains
The contains
operator tests for a substring match of a quoted string or literal string value and no wildcard expansion/matching occurs. Instead, when you use the contains
operator and specify an asterisk *
, the *
symbol is treated as a literal character.
Example: Query process events where the commandline contains ’netsvc.exe’
from process commandline contains 'netsvc.exe'
matches
The matches
operator must be specified with a supported glob pattern in the value string to execute as a wildcard search. The supported glob characters are the *
and ?
characters. Without the asterisk or question mark symbols, the query runs as a literal equality search. An asterisk matches zero or more characters, including an empty character. A question mark matches any single character.
Example: Query dnsquery events for a domain name ending with the suffix ’.google.com’
from dnsquery @domain matches '*.google.com'
matches_regex
The matches_regex
operator supports regular expressions in the query string. The regex value will need to escape any characters, such as dots, which have a special meaning within regular expression syntax. Events and alerts use different backends and depending on the query being run the regex engine and notation will differ. For events, the regex engine is Java compatible, please see the Java regex documentation for notation help. For alerts, the regex engine is Lucene based, please see the Elastic regex documentation for notation help.
Example: Query process events where commandline field matches a string that is comprised of lower case characters and numbers followed by a file extension of .exe
from process commandline matches_regex '[a-z0-9]*\.exe'
Reserved Words
The following identifiers are reserved words that must be accompanied by single quotes if used in search terms as literal values.
from process where commandline contains 'search'
Note: All operators/reserved words are case insensitive (e.g. AND, and, aNd are equivalent).
AGG, AGGREGATE, AND, AS, ASC,
AVG, BY, CONTAINS, COUNT,
CARDINALITY, DESC, DESCENDANT,
EARLIEST, FALSE, FIELDS, FROM,
HEAD, IN, IS, INDEX,
LATEST, MATCHES, MATCHES_REGEX,
MAX, MIN, NOT, NOW, NULL, OF,
OR, SEARCH, SORT, SUM,
TAIL, TOP, TRUE, WHERE
Logical Types
Common Fields
If you query a field that exists for multiple event types, you will get results from all event types that match your query on this field. The sensor_type
field exists for all event types and can be used to find all events from a particular data source. For example: sensor_type = 'ENDPOINT_REDCLOAK'
would return all events from the Red Cloak™ Endpoint Agent, for all relevant schemas.
Other fields in common to many but not all events include: sensor_id, host_id
Resource ID
Each event in Taegis™ XDR has a unique resource_id
, but this is not a normal common field. If you search for a valid resource_id=<value>
, the one matching event will automatically be returned, regardless of the event type.
CIDR Notation
The query language supports CIDR notation for IP address fields when using the =
(literal), matches
or IN
operators. Negation of these operators is supported with CIDR notation as well (e.g. !=
, !matches
and !IN
).
At this time, CIDR notation is only supported for event queries. Alert queries do not support CIDR notation and a valid IP address must be used.
Example: Query netflow events where the source address is within the IP range ’192.168.2.0/24’:
from netflow where source_address = '192.168.2.0/24'
Note:
The following matches
query will act as textual wildcard match and not a CIDR query:
from netflow where @ip matches '192.168.2*'
The following matches
query will act as CIDR query:
from netflow where @ip matches '192.168.2.*.*'
Logical Types
Logical types are special fields that map to field names under the appropriate data schemas for that particular field category. The logical types are designed to alleviate the need to remember and specify each individual field name for each pertinent schema. Logical types are denoted with the @
prefix. A logical type, specified with @<logical type name>
, will automatically query all the relevant event fields.
Notes: When a negation operator is used with a logical type, the search engine makes sure none of the fields mapped to the logical type in the query match the value provided.
When using the @raw
logical type any backslashes will have to be escaped due to the backend used when searching for raw data. Please see examples at the end of this Logical Types section.
When your query has only a logical type in the search, then you will see results for alerts and events in a tabbed view.
Example: Query all alerts and events that have a username field for the value ’system’:
@user contains 'system'
Logical Type Mappings
The following are the latest logical type mappings:
@command:
An OS command line including the program basename and it's arguments (e.g. 'grep -i “hello” world.txt')
- alert: apicall.commandline, auth.commandline, filemod.commandline, persistence.registry.commandline, process.commandline, process.commandline_decoded, process.host_module.commandline, process.modules.commandline, processmodule.commandline, registry.commandline, threadinjection.commandline
- apicall: commandline
- auth: commandline
- filemod: commandline
- persistence: registry.commandline
- process: commandline, commandline_decoded, host_module.commandline, modules.commandline
- processmodule: commandline
- registry: commandline
- threadinjection: commandline
@domain:
A domain name (e.g. 'secureworks.com')
- alert: auth.extra_targetoutbounddomainname, auth.source_domain_name, auth.target_domain_name, dnsquery.query_name, domain, http.uri_host, netflow.dns_name, thirdparty.domain_name
- auth: extra_targetoutbounddomainname, source_domain_name, target_domain_name
- dnsquery: query_name
- http: uri_host
- netflow: dns_name
- thirdparty: domain_name
@hash:
A digest value of a program or file (e.g. hash of program bytes)
- agentdetection: file_system_context.impacted_file.file_hash.md5, file_system_context.impacted_file.file_hash.sha1, file_system_context.impacted_file.file_hash.sha256, file_system_context.impacted_file.file_hash.sha512
- alert: agentdetection.file_system_context.impacted_file.file_hash.md5, agentdetection.file_system_context.impacted_file.file_hash.sha1, agentdetection.file_system_context.impacted_file.file_hash.sha256, agentdetection.file_system_context.impacted_file.file_hash.sha512, antivirus.file_hash.md5, antivirus.file_hash.sha1, antivirus.file_hash.sha256, antivirus.file_hash.sha512, auth.process_file_hash.md5, auth.process_file_hash.sha1, auth.process_file_hash.sha256, auth.process_file_hash.sha512, email.attachments.file_hash.md5, email.attachments.file_hash.sha1, email.attachments.file_hash.sha256, email.attachments.file_hash.sha512, email.threats.fileinfo.file_hash.md5, email.threats.fileinfo.file_hash.sha1, email.threats.fileinfo.file_hash.sha256, email.threats.fileinfo.file_hash.sha512, encrypt.fingerprint.md5, encrypt.fingerprint.sha1, encrypt.fingerprint.sha256, encrypt.fingerprint.sha512, file.file_hash.md5, file.file_hash.sha1, file.file_hash.sha256, file.file_hash.sha512, file_md5, file_sha1, file_sha256, filemod.file_hash.md5, filemod.file_hash.sha1, filemod.file_hash.sha256, filemod.file_hash.sha512, filemod.parent_process_file_hash.md5, filemod.parent_process_file_hash.sha1, filemod.parent_process_file_hash.sha256, filemod.parent_process_file_hash.sha512, filemod.process_file_hash.md5, filemod.process_file_hash.sha1, filemod.process_file_hash.sha256, filemod.process_file_hash.sha512, persistence.command.host_program.file_hash.md5, persistence.command.host_program.file_hash.sha1, persistence.command.host_program.file_hash.sha256, persistence.command.host_program.file_hash.sha512, persistence.command.program.file_hash.md5, persistence.command.program.file_hash.sha1, persistence.command.program.file_hash.sha256, persistence.command.program.file_hash.sha512, persistence.file.file_hash.md5, persistence.file.file_hash.sha1, persistence.file.file_hash.sha256, persistence.file.file_hash.sha512, persistence.registry.process_file_hash.md5, persistence.registry.process_file_hash.sha1, persistence.registry.process_file_hash.sha256, persistence.registry.process_file_hash.sha512, persistence.shortcut.file.file_hash.md5, persistence.shortcut.file.file_hash.sha1, persistence.shortcut.file.file_hash.sha256, persistence.shortcut.file.file_hash.sha512, process.allocations.file.file_hash.md5, process.allocations.file.file_hash.sha1, process.allocations.file.file_hash.sha256, process.allocations.file.file_hash.sha512, process.host_module.file.file_hash.md5, process.host_module.file.file_hash.sha1, process.host_module.file.file_hash.sha256, process.host_module.file.file_hash.sha512, process.host_module.parent_process_file.file_hash.md5, process.host_module.parent_process_file.file_hash.sha1, process.host_module.parent_process_file.file_hash.sha256, process.host_module.parent_process_file.file_hash.sha512, process.host_module.process_file.file_hash.md5, process.host_module.process_file.file_hash.sha1, process.host_module.process_file.file_hash.sha256, process.host_module.process_file.file_hash.sha512, process.host_program.file_hash.md5, process.host_program.file_hash.sha1, process.host_program.file_hash.sha256, process.host_program.file_hash.sha512, process.modules.file.file_hash.md5, process.modules.file.file_hash.sha1, process.modules.file.file_hash.sha256, process.modules.file.file_hash.sha512, process.modules.parent_process_file.file_hash.md5, process.modules.parent_process_file.file_hash.sha1, process.modules.parent_process_file.file_hash.sha256, process.modules.parent_process_file.file_hash.sha512, process.modules.process_file.file_hash.md5, process.modules.process_file.file_hash.sha1, process.modules.process_file.file_hash.sha256, process.modules.process_file.file_hash.sha512, process.program_hash.md5, process.program_hash.sha1, process.program_hash.sha256, process.program_hash.sha512, process.target_program.file_hash.md5, process.target_program.file_hash.sha1, process.target_program.file_hash.sha256, process.target_program.file_hash.sha512, processmodule.file.file_hash.md5, processmodule.file.file_hash.sha1, processmodule.file.file_hash.sha256, processmodule.file.file_hash.sha512, processmodule.parent_process_file.file_hash.md5, processmodule.parent_process_file.file_hash.sha1, processmodule.parent_process_file.file_hash.sha256, processmodule.parent_process_file.file_hash.sha512, processmodule.process_file.file_hash.md5, processmodule.process_file.file_hash.sha1, processmodule.process_file.file_hash.sha256, processmodule.process_file.file_hash.sha512, program_md5, program_sha1, program_sha256, program_sha512, registry.process_file_hash.md5, registry.process_file_hash.sha1, registry.process_file_hash.sha256, registry.process_file_hash.sha512
- antivirus: file_hash.md5, file_hash.sha1, file_hash.sha256, file_hash.sha512
- auth: process_file_hash.md5, process_file_hash.sha1, process_file_hash.sha256, process_file_hash.sha512
- email: attachments.file_hash.md5, attachments.file_hash.sha1, attachments.file_hash.sha256, attachments.file_hash.sha512, threats.fileinfo.file_hash.md5, threats.fileinfo.file_hash.sha1, threats.fileinfo.file_hash.sha256, threats.fileinfo.file_hash.sha512
- encrypt: fingerprint.md5, fingerprint.sha1, fingerprint.sha256, fingerprint.sha512
- filemod: file_hash.md5, file_hash.sha1, file_hash.sha256, file_hash.sha512, parent_process_file_hash.md5, parent_process_file_hash.sha1, parent_process_file_hash.sha256, parent_process_file_hash.sha512, process_file_hash.md5, process_file_hash.sha1, process_file_hash.sha256, process_file_hash.sha512
- persistence: command.host_program.file_hash.md5, command.host_program.file_hash.sha1, command.host_program.file_hash.sha256, command.host_program.file_hash.sha512, command.program.file_hash.md5, command.program.file_hash.sha1, command.program.file_hash.sha256, command.program.file_hash.sha512, file.file_hash.md5, file.file_hash.sha1, file.file_hash.sha256, file.file_hash.sha512, registry.process_file_hash.md5, registry.process_file_hash.sha1, registry.process_file_hash.sha256, registry.process_file_hash.sha512, shortcut.file.file_hash.md5, shortcut.file.file_hash.sha1, shortcut.file.file_hash.sha256, shortcut.file.file_hash.sha512
- process: allocations.file.file_hash.md5, allocations.file.file_hash.sha1, allocations.file.file_hash.sha256, allocations.file.file_hash.sha512, host_module.file.file_hash.md5, host_module.file.file_hash.sha1, host_module.file.file_hash.sha256, host_module.file.file_hash.sha512, host_module.parent_process_file.file_hash.md5, host_module.parent_process_file.file_hash.sha1, host_module.parent_process_file.file_hash.sha256, host_module.parent_process_file.file_hash.sha512, host_module.process_file.file_hash.md5, host_module.process_file.file_hash.sha1, host_module.process_file.file_hash.sha256, host_module.process_file.file_hash.sha512, host_program.file_hash.md5, host_program.file_hash.sha1, host_program.file_hash.sha256, host_program.file_hash.sha512, modules.file.file_hash.md5, modules.file.file_hash.sha1, modules.file.file_hash.sha256, modules.file.file_hash.sha512, modules.parent_process_file.file_hash.md5, modules.parent_process_file.file_hash.sha1, modules.parent_process_file.file_hash.sha256, modules.parent_process_file.file_hash.sha512, modules.process_file.file_hash.md5, modules.process_file.file_hash.sha1, modules.process_file.file_hash.sha256, modules.process_file.file_hash.sha512, program_hash.md5, program_hash.sha1, program_hash.sha256, program_hash.sha512, target_program.file_hash.md5, target_program.file_hash.sha1, target_program.file_hash.sha256, target_program.file_hash.sha512
- processmodule: file.file_hash.md5, file.file_hash.sha1, file.file_hash.sha256, file.file_hash.sha512, parent_process_file.file_hash.md5, parent_process_file.file_hash.sha1, parent_process_file.file_hash.sha256, parent_process_file.file_hash.sha512, process_file.file_hash.md5, process_file.file_hash.sha1, process_file.file_hash.sha256, process_file.file_hash.sha512
- registry: process_file_hash.md5, process_file_hash.sha1, process_file_hash.sha256, process_file_hash.sha512
@host:
A hostname as captured and normalized from ingested raw events
- alert: antivirus.computer_name, auth.extra_targetservername, auth.extra_workstationname, auth.source_host_name, auth.target_host_name, cloudaudit.source_hostname, cloudaudit.target_hostname, dhcp.client_hostname, dhcp.server_hostname, hostname, managementevent.client_hostname, managementevent.client_hostname_fqdn, managementevent.target_hostname, managementevent.target_hostname_fqdn, process.computer_name, thirdparty.source_host_name, thirdparty.target_host_name
- antivirus: computer_name
- auth: extra_targetservername, extra_workstationname, source_host_name, target_host_name
- cloudaudit: source_hostname, target_hostname
- dhcp: client_hostname, server_hostname
- managementevent: client_hostname, client_hostname_fqdn, target_hostname, target_hostname_fqdn
- process: computer_name
- thirdparty: source_host_name, target_host_name
@ip:
An IPv4 or IPv6 internet address
- alert: antivirus.destination_address, antivirus.source_address, apicall.win_rpc.binding_address, apicall.win_rpc.target_address, auth.source_address, auth.target_address, cloudaudit.source_address, dest_ipaddress, dest_ipgeo, dhcp.client_address, dhcp.server_address, dnsquery.destination_address, dnsquery.responses.records.response_data, dnsquery.source_address, email.sender_ip, encrypt.destination_address, encrypt.source_address, http.destination_address, http.source_address, http.true_source_address, ipaddress, netflow.destination_address, netflow.destination_nat_address, netflow.source_address, netflow.source_nat_address, nids.destination_address, nids.source_address, source_ipaddress, source_ipgeo, thirdparty.additional_destination_addresses, thirdparty.additional_source_addresses, thirdparty.destination_address, thirdparty.source_address
- antivirus: destination_address, source_address
- apicall: win_rpc.binding_address, win_rpc.target_address
- auth: source_address, target_address
- cloudaudit: source_address
- dhcp: client_address, server_address
- dnsquery: destination_address, responses.records.response_data, source_address
- email: sender_ip
- encrypt: destination_address, source_address
- http: destination_address, source_address, true_source_address
- netflow: destination_address, destination_nat_address, source_address, source_nat_address
- nids: destination_address, source_address
- thirdparty: additional_destination_addresses, additional_source_addresses, destination_address, source_address
@mac:
A MAC address
- alert: dhcp.client_mac, dhcp.server_mac, http.destination_mac, http.source_mac, netflow.destination_mac, netflow.source_mac, thirdparty.destination_mac, thirdparty.source_mac
- dhcp: client_mac, server_mac
- http: destination_mac, source_mac
- netflow: destination_mac, source_mac
- thirdparty: destination_mac, source_mac
@path:
Full path to a program or file (e.g. 'C:\Windows\System32\cmd.exe')
- agentdetection: execution_context.target_image_path, file_system_context.impacted_file.native_path, file_system_context.impacted_file.path, image_path
- alert: agentdetection.execution_context.target_image_path, agentdetection.file_system_context.impacted_file.native_path, agentdetection.file_system_context.impacted_file.path, agentdetection.image_path, antivirus.file_path, auth.process_filename, file.native_path, file.path, file_name, filemod.destination_file_name, filemod.file_name, managementevent.script_file_path, persistence.command.host_program.native_path, persistence.command.host_program.path, persistence.command.program.native_path, persistence.command.program.path, persistence.file.native_path, persistence.file.path, persistence.registry.process_image_path, persistence.scheduled_task.action.path, persistence.service.image_path, persistence.shortcut.file.native_path, persistence.shortcut.file.path, persistence.shortcut.relative_path, persistence.shortcut.target_path, persistence.shortcut.working_directory, process.allocations.file.native_path, process.allocations.file.path, process.host_module.file.native_path, process.host_module.file.path, process.host_module.parent_process_file.native_path, process.host_module.parent_process_file.path, process.host_module.process_file.native_path, process.host_module.process_file.path, process.host_program.native_path, process.host_program.path, process.image_path, process.modules.file.native_path, process.modules.file.path, process.modules.parent_process_file.native_path, process.modules.parent_process_file.path, process.modules.process_file.native_path, process.modules.process_file.path, process.parent_image_path, process.target_program.native_path, process.target_program.path, processmodule.file.native_path, processmodule.file.path, processmodule.parent_process_file.native_path, processmodule.parent_process_file.path, processmodule.process_file.native_path, processmodule.process_file.path, registry.process_image_path, scriptblock.interpreter_path, threadinjection.source_process_name, threadinjection.target_process_name
- antivirus: file_path
- auth: process_filename
- filemod: destination_file_name, file_name
- managementevent: script_file_path
- persistence: command.host_program.native_path, command.host_program.path, command.program.native_path, command.program.path, file.native_path, file.path, registry.process_image_path, scheduled_task.action.path, service.image_path, shortcut.file.native_path, shortcut.file.path, shortcut.relative_path, shortcut.target_path, shortcut.working_directory
- process: allocations.file.native_path, allocations.file.path, host_module.file.native_path, host_module.file.path, host_module.parent_process_file.native_path, host_module.parent_process_file.path, host_module.process_file.native_path, host_module.process_file.path, host_program.native_path, host_program.path, image_path, modules.file.native_path, modules.file.path, modules.parent_process_file.native_path, modules.parent_process_file.path, modules.process_file.native_path, modules.process_file.path, parent_image_path, target_program.native_path, target_program.path
- processmodule: file.native_path, file.path, parent_process_file.native_path, parent_process_file.path, process_file.native_path, process_file.path
- registry: process_image_path
- scriptblock: interpreter_path
- threadinjection: source_process_name, target_process_name
@port:
TCP/UDP internet port
- alert: antivirus.destination_port, antivirus.source_port, auth.source_port, auth.target_port, encrypt.destination_port, encrypt.source_port, http.destination_port, http.source_port, netflow.destination_nat_port, netflow.destination_port, netflow.source_nat_port, netflow.source_port, nids.destination_port, nids.source_port, thirdparty.additional_destination_ports, thirdparty.additional_source_ports, thirdparty.destination_port, thirdparty.source_port
- antivirus: destination_port, source_port
- auth: source_port, target_port
- encrypt: destination_port, source_port
- http: destination_port, source_port
- netflow: destination_nat_port, destination_port, source_nat_port, source_port
- nids: destination_port, source_port
- thirdparty: additional_destination_ports, additional_source_ports, destination_port, source_port
@raw:
The unaltered source data of a normalized event message captured in raw form
- agentdetection: file_system_context.impacted_file.original_data, original_data
- alert: agentdetection.file_system_context.impacted_file.original_data, agentdetection.original_data, antivirus.original_data, apicall.original_data, asset.original_data, auth.original_data, cloudaudit.original_data, command.host_program.original_data, command.original_data, command.program.original_data, dhcp.original_data, directory.original_data, dnsquery.original_data, email.original_data, encrypt.original_data, file.original_data, filemod.original_data, generic.original_data, http.original_data, inspector.wmientry.original_data, inspector_process.allocations.file.original_data, inspector_process.allocations.original_data, inspector_process.host_module.file.original_data, inspector_process.host_module.original_data, inspector_process.host_program.original_data, inspector_process.modules.file.original_data, inspector_process.modules.original_data, inspector_process.original_data, inspector_process.target_program.original_data, kernel_object.original_data, managementevent.original_data, memoryallocation.file.original_data, memoryallocation.original_data, netflow.original_data, nids.original_data, persistence.command.host_program.original_data, persistence.command.program.original_data, persistence.file.original_data, persistence.original_data, persistence.registry.original_data, persistence.shortcut.file.original_data, process.allocations.file.original_data, process.allocations.original_data, process.host_module.file.original_data, process.host_module.original_data, process.host_module.parent_process_file.original_data, process.host_module.process_file.original_data, process.modules.file.original_data, process.modules.original_data, process.modules.parent_process_file.original_data, process.modules.process_file.original_data, process.original_data, processmodule.file.original_data, processmodule.original_data, processmodule.parent_process_file.original_data, processmodule.process_file.original_data, registry.original_data, scriptblock.original_data, thirdparty.original_data, threadinjection.original_data, windows_eventrecord.original_data
- antivirus: original_data
- apicall: original_data
- auth: original_data
- cloudaudit: original_data
- dhcp: original_data
- dnsquery: original_data
- email: original_data
- encrypt: original_data
- filemod: original_data
- generic: original_data
- http: original_data
- managementevent: original_data
- netflow: original_data
- nids: original_data
- persistence: command.host_program.original_data, command.program.original_data, file.original_data, original_data, registry.original_data, shortcut.file.original_data
- process: allocations.file.original_data, allocations.original_data, host_module.file.original_data, host_module.original_data, host_module.parent_process_file.original_data, host_module.process_file.original_data, modules.file.original_data, modules.original_data, modules.parent_process_file.original_data, modules.process_file.original_data, original_data
- processmodule: file.original_data, original_data, parent_process_file.original_data, process_file.original_data
- registry: original_data
- scriptblock: original_data
- thirdparty: original_data
- threadinjection: original_data
@sensor_id:
An ID of the sensor which generated an event
- agentdetection: file_system_context.impacted_file.sensor_id, sensor_id
- alert: agentdetection.file_system_context.impacted_file.sensor_id, agentdetection.sensor_id, antivirus.sensor_id, apicall.sensor_id, asset.sensor_id, auth.sensor_id, cloudaudit.sensor_id, dhcp.sensor_id, dnsquery.sensor_id, email.sensor_id, encrypt.sensor_id, file.sensor_id, filemod.sensor_id, generic.sensor_id, http.sensor_id, managementevent.sensor_id, netflow.sensor_id, nids.sensor_id, persistence.command.host_program.sensor_id, persistence.command.program.sensor_id, persistence.file.sensor_id, persistence.registry.sensor_id, persistence.sensor_id, persistence.shortcut.file.sensor_id, process.allocations.file.sensor_id, process.allocations.sensor_id, process.host_module.file.sensor_id, process.host_module.parent_process_file.sensor_id, process.host_module.process_file.sensor_id, process.host_module.sensor_id, process.modules.file.sensor_id, process.modules.parent_process_file.sensor_id, process.modules.process_file.sensor_id, process.modules.sensor_id, process.sensor_id, processmodule.file.sensor_id, processmodule.parent_process_file.sensor_id, processmodule.process_file.sensor_id, processmodule.sensor_id, registry.sensor_id, scriptblock.sensor_id, sensor_hostid, sensor_id, thirdparty.sensor_id, threadinjection.sensor_id
- antivirus: sensor_id
- apicall: sensor_id
- auth: sensor_id
- cloudaudit: sensor_id
- dhcp: sensor_id
- dnsquery: sensor_id
- email: sensor_id
- encrypt: sensor_id
- filemod: sensor_id
- generic: sensor_id
- http: sensor_id
- managementevent: sensor_id
- netflow: sensor_id
- nids: sensor_id
- persistence: command.host_program.sensor_id, command.program.sensor_id, file.sensor_id, registry.sensor_id, sensor_id, shortcut.file.sensor_id
- process: allocations.file.sensor_id, allocations.sensor_id, host_module.file.sensor_id, host_module.parent_process_file.sensor_id, host_module.process_file.sensor_id, host_module.sensor_id, modules.file.sensor_id, modules.parent_process_file.sensor_id, modules.process_file.sensor_id, modules.sensor_id, sensor_id
- processmodule: file.sensor_id, parent_process_file.sensor_id, process_file.sensor_id, sensor_id
- registry: sensor_id
- scriptblock: sensor_id
- thirdparty: sensor_id
- threadinjection: sensor_id
@url:
A full URL (e.g. 'https://www.secureworks.com')
- alert: cloudaudit.resources.resource_id
- cloudaudit: resources.resource_id
@user:
A computer username (e.g. 'bob' or '\\CORP\alice')
- alert: antivirus.user_name, auth.extra_samaccountname, auth.extra_subject_domain_user_id, auth.extra_target_domain_user_id, auth.extra_targetoutboundusername, auth.extra_userprincipalname, auth.extra_virtualaccount, auth.source_user_name, auth.target_user_name, cloudaudit.target_user_name, cloudaudit.user_id, cloudaudit.user_name, http.destination_username, http.source_username, http.uri_userinfo, managementevent.username, nids.destination_username, nids.source_username, process.parent_username, process.parent_windows_sid, process.username, process.windows_sid, thirdparty.additional_source_user_ids, thirdparty.additional_source_user_names, thirdparty.additional_target_user_ids, thirdparty.additional_target_user_names, thirdparty.source_user_id, thirdparty.source_user_name, thirdparty.target_user_id, thirdparty.target_user_name, username
- antivirus: user_name
- auth: extra_samaccountname, extra_subject_domain_user_id, extra_target_domain_user_id, extra_targetoutboundusername, extra_userprincipalname, extra_virtualaccount, source_user_name, target_user_name
- cloudaudit: target_user_name, user_id, user_name
- http: destination_username, source_username, uri_userinfo
- managementevent: username
- nids: destination_username, source_username
- process: parent_username, parent_windows_sid, username, windows_sid
- thirdparty: additional_source_user_ids, additional_source_user_names, additional_target_user_ids, additional_target_user_names, source_user_id, source_user_name, target_user_id, target_user_name
Logical Type Query Examples
@raw contains '192.168.0.1'
returns all events, across all types, where the original_data
text (the raw message) contains ’192.168.0.1’.
from netflow @ip = '10.0.0.1'
is recognized as a query for an IP address matching ’10.0.0.1’ and would be expanded to:
from netflow (source_address='10.0.0.1' OR destination_address='10.0.0.1' OR source_nat_address='10.0.0.1' OR destination_nat_address='10.0.0.1')
Logical type names can be used anywhere that a schema field name would be used:
from auth @user='bob'
This performs a query over all fields tagged as logical type ’user’ for the value ’bob’ and expands to:
from auth (source_user_name='bob' OR extra_subject_domain_user_id='bob' OR extra_target_domain_user_id='bob' OR target_user_name='bob' OR extra_targetoutboundusername='bob' OR extra_userprincipalname='bob' OR extra_virtualaccount='bob')
The query below performs a search for all ’commandline’ fields under the process event type with the value specified:
from process where @command contains 'add HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Run'
If we were to use the @raw
logical type of the query above, we'd have to escape the backslahes due to the backend differences:
from process where @raw contains 'add HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Run'
Search By Hostname
Query Language supports searches for events and alerts by hostname. The hostname field is a special use case where the hostname is first translated to a host_id
from the endpoint databases within Taegis XDR, and the search is then run with the obtained host_id
. Hostname searches do not work with network or cloud events.
The translation is completed using a backend API that only allows lookup for an exact match; therefore, the hostname field only supports literal match operators:
- = (exact match)
- != (negation of an exact match)
- IN (list of exact match values)
- !IN (negation of a list containing exact match values)
The hostname translation is also case sensitive and the value you provide should match against the hostname stored in the endpoint database.
Hostname Search Examples
Example: Query for all authentication events reported by an endpoint agent installed on ‘Demo-PC01’
from auth where hostname = 'Demo-PC01'
Example: Query for all alerts fired for the host ‘Demo-PC01’
from alert where hostname = 'Demo-PC01'
Note: The hostname field is a different use case than the logical type field @host
. The @host
logical type is a mapped to various event fields. These event fields are populated when there is an asset name collected as part of the event original data. The @host
logical type does not map to the actual endpoint hostname. Please review the Logical Type section for the mapping of the @host
type.
Arrays
Queries over array fields are essentially flattened such that you can search for matches across any of the array elements using standard field.subfield
notation:
from http http_response_headers.record.key='Authorization' and http_response_headers.record.value='Bearer 1234'
Note: The above query finds records that have an ’Authorization’ header and have a header with value ’Bearer 1234’, but this does not guarantee that these belong to the same header record. The ability to match on specific array indices is not supported.
String Literals
Single Quotes Usage
'<string value>'
is used to enclose a string literal value.- Any backslashes or escape sequences are interpreted as literals.
- Single quotes cannot be used if the string value itself contains a single quote
'
. Unless escaped (see next section), a'
within a string will result in a syntax error.
Example: Query process events for the directory path 'Windows\system32':
from process where image_path contains 'Windows\system32'
Escape Interpreting Modifier Usage
e'<string value>'
is used to enclose a string value that contains escape sequences.- If a string value itself contains one or more single quote
'
characters, the escape modifier must be used and the single quote(s) must be escaped with a backslash (\'
). - To specify escape sequences:
\n
— new line\r
— carriage return\t
— tab\b
— backspace\f
— formfeed\\
— an escaped \
Example: Query process events that have a new line in the commandline field:
from process where @command contains e'dir\nmkdir test'
Example: Query process events where the value has singles quote and need to be escaped
from process where commandline contains e'echo \'mimikatz\''
Time Ranges
Constrain a query to a limited time range using the following:
earliest=[+-]<delta><unit>[@unit]
latest=[+-]<delta><unit>[@unit]
where delta is an integer and unit is one of the following:
s
— secondm
— minuteh
— hourd
— dayw
— weekmo
— monthy
— year
The optional [@unit]
causes the resulting time value to be truncated to the specified second, minute, hour, day, week, month, or year rather than using the raw time value.
When only the latest
time constraint is specified in the query, a default of the preceding 24 hours is applied for the earliest
time constraint.
An absolute time range can also be specified as a formatted date string:
earliest='2019-06-1T00:00:00' AND latest='2019-06-30T00:00:00'
Note: Dates should be in the ISO 8601 standard, e.g., (2019-07-01, 2019-06-01T00:00:00)
Functions
Searches can be further qualified by “piping“ results into additional functions.
search | functions
When the query searches across multiple data types, the function operates across each data field independently.
Example: Query up to 5 results for the process and the auth data types each. In total, this example returns up to 10 results:
from process, auth where @user contains 'admin' | head 5
sort
sort
sorts results by specified fields/ordering. When only one event type is queried, sorting by any field is supported, but when multiple event types are queried, only sorting by event_time_usec and ingest_time_usec fields are supported. Sorting for alerts is not currently supported.
search | sort field [ASC|DESC] (, field [ASC|DESC)?
from dnsquery query_name MATCHES '*.secureworks.com' earliest=-30d | sort query_name desc
from netflow source_address='10.0.0.1' earliest=-1d@d | sort source_address asc
from auth, process earliest=-1d | sort event_time_usec asc
head
head
returns the first N number of results from each event type in search order.
search | head N
from dnsquery @domain MATCHES '*.secureworks.com' earliest=-30d | head 10
tail
tail
returns the last N number of results from each event type, starting at the end of the result set. Tail reverses the order of the results before returning the last N results.
search | tail N
from dnsquery @domain MATCHES '*.secureworks.com' earliest=-30d | tail 10
Aggregations
aggregate
allows users to group the results of their query and performs the listed operations on the results of their query:
Operator | Description |
---|---|
sum | Calculate the sum of a field for every row returned by the query. |
min | Find the smallest value of a field. |
max | Find the largest value of a field. |
avg | Find the average value of a field for every row returned by the query. |
count | Count the number of rows which have a field. If no field is specified all rows are counted. |
cardinality | Count the number of rows which have a distinct, non-null value for a field. |
(aggregate) by | Group or aggregate the results by the values of the field specified and display a count for each value. |
An aggregate query takes the following form:
search | aggregate [sum|min|max|avg|count|cardinality](field)
by
The by
clause can either specify an optional field list or a time duration where the results will be grouped by the specified field or time unit:
search | aggregate _aggregation (, _aggregation)? by field
search | aggregate _aggregation (, _aggregation)? by int unit
where unit
is
- s — second
- m — minute
- h — hour
- d — day
Examples: Get a list of usernames and their count from process events that had powershell in their commandline:
from process where commandline contains 'powershell' | aggregate count(username) by username
Get the earliest and latest authentication event for the source username ’bob’ in the last 3 days:
from auth where source_user_name = 'bob' and earliest=-3d | aggregate min(event_time_usec), max(event_time_usec)
Get the sum of transfer bytes and the average of transfer bytes for the netflows from the Cisco ASA for the last 24 hours:
from netflow where sensor_type='CISCO_FIREWALL_ASA' | aggregate sum(tx_byte_count) as sum_tx, avg(tx_byte_count)
Query the count of domains matching *.net over the last day:
from dnsquery where query_name MATCHES '*.net' latest=-1d | aggregate count by query_name
Query the count of dnsquery events for each hour of the last 24 hours:
from dnsquery earliest=-1d | aggregate count by 1h
Note: Aggregation is only supported for event queries at this time. When running an aggregation with multiple event type queries aggregation will be performed per event type. Aggregation queries do not currently support aggregating on a logical type. Report creation from an aggregation query is also not supported at this time.
Examples
Query for all generic events from Zeek in the last 2 hours:
from generic where sensor_type = 'zeek' earliest = -2h
Query for all generic events within the last 2 hours with the substring ’secureworks’
from generic where original_data contains 'secureworks' earliest = -2h
or, using the logical type @raw
as an alias for original_data
:
from generic where @raw contains 'secureworks' earliest = -2h
Query for all alerts that have a severity of high or critical:
from alert where severity >= 0.6
Query for all alerts that have a severity of low:
from alert where severity >= 0.2 and severity < 0.4
Query for all alerts where ’Powershell’ appears in the alert title:
from alert where title contains 'Powershell'
Query for all alerts where ’mimikatz’ appears in the commandline event fields:
from alert where @command contains 'mimikatz'
Query for all alerts where the username ’admin’ is the user associated with the event that generated the alert:
from alert where @user contains 'admin'
Query for all alerts that have the detector name of ’TDR Watchlist’:
from alert where metadata.creator.detector.detector_name = 'TDR Watchlist'
Query for all alerts generated by the detector ID ’event-filter’:
from alert where metadata.creator.detector.detector_id contains 'event-filter'
Query for alerts where the process parent image path contains ’cmd.exe’:
from alert where process.parent_image_path contains 'cmd.exe'
Query across all event types that have an IP address field for the IP ’10.0.0.1’:
@ip='10.0.0.1'
Query across all event types that have a domain name field for the name ’redcloak.secureworks.com’:
@domain='redcloak.secureworks.com'
Query only netflow events for the IP address ’10.0.0.1’:
from netflow @ip='10.0.0.1'
Query netflow and auth event types for the IP ’10.0.0.1’:
from netflow, auth @ip='10.0.0.1'
Query only netflow events for IP addresses in the range ’192.168.2.0/24’:
from netflow where @ip='192.168.2.0/24'
Query netflow and auth event types for IP addresses in the range ’192.168.2.0/24’:
from netflow, auth where @ip matches '192.168.2.0/24'
Query only netflow events for IP addresses in the range ’192.168.2.0/24’:
from netflow, auth where @ip matches '192.168.2.*'
Query only netflow events for IP addresses in the range ’192.168.0.0/16’:
from netflow, auth where @ip matches '192.168.*'
Query only netflow events for IP addresses in the range ’192.168.0.0/16’:
from netflow, auth where @ip in ('192.168.0.0/16')
Query auth for the user ’bob’:
from auth where @user='bob'
Query dnsquery events for the last 30 days:
from dnsquery earliest=-30d
Query dnsquery events starting from 30 days in the past till 10 days in the past:
from dnsquery earliest=-30d latest=-10d
Query dnsquery events for the last 2 days starting from the beginning of the day (in this example, 00:00:00 of yesterday):
from dnsquery earliest=-2d@d
Query dnsquery events starting from the specified date/time until current time:
from dnsquery earliest='2021-04-01T00:00:00'
Query process events where commandline field contains the phrase ’exe’:
from process commandline contains 'exe'
Query process events where commandline field does not contain the phrase ’exe’:
from process commandline !contains 'exe'
Query process events where the sensor type field is not equal to ’ENDPOINT_CROWD_STRIKE’:
from process sensor_type != 'ENDPOINT_CROWD_STRIKE'
Query process events where commandline field matches a string that is comprised of lowercase characters and numbers followed by a file extension of ’.exe’:
from process commandline matches_regex '[a-z0-9]*\.exe'
Query process events where the sensor type is one of ’ENDPOINT_REDCLOAK’, ’ENDPOINT_CROWD_STRIKE’:
from process sensor_type IN ('ENDPOINT_REDCLOAK','ENDPOINT_CROWD_STRIKE')
Query dnsquery events for domain name ending with ’.google.com’. It is mandatory to mention field name when using wildcard for equality:
from dnsquery @domain matches '*.google.com'
Query process events where sensor type equals ’ENDPOINT_CROWD_STRIKE’ and process ID equals ’5201’. The fields are AND-ed by default if no operator is specified:
from process where sensor_type='ENDPOINT_CROWD_STRIKE' process_id='5201'
Query process events where sensor_type equals ’ENDPOINT_REDCLOAK’ OR process ID equals ’5201’:
from process sensor_type='ENDPOINT_REDCLOAK' OR process_id='5201'
Query process events for the directory path ’Windows\system32’:
from process where image_path contains 'Windows\system32'
Query process events where the value has single quotes that need to be escaped:
from process where commandline contains e'echo \'mimikatz\''
Query auth events for user accounts being unlocked (Windows Event ID 4767):
from auth where win_event_id='4767'
Query 10 process events in the last 1 day (24 hours from current time) where sensor_type equals ’ENDPOINT_CROWD_STRIKE’, sorted by timestamp descending:
from process sensor_type='ENDPOINT_CROWD_STRIKE' earliest=-1d | head 10
Query 10 process events in the last 1 day (24 hours from current time) where sensor_type equals ’ENDPOINT_REDCLOAK’, sorted by timestamp ascending:
from process sensor_type='ENDPOINT_REDCLOAK' earliest=-1d | tail 10
Query auth events where the target_user_name field is null:
from auth target_user_name is null
Query auth events where the target_user_name field is not null:
from auth target_user_name is not null
Query process events that have a newline in the commandline:
from process where @command contains e'dir\nmkdir test'
Get a list of usernames and their count from process events that had powershell in their commandline:
from process where commandline contains 'powershell' | aggregate count(username) by username
Get the earliest and lastest authentication event for the username ’bob’ in the last 3 days:
from auth where username = 'bob' and earliest=-3d | aggregate min(event_time_usec), max(event_time_usec)
Get the sum of transfer bytes, the average of transfer bytes and the count of destination IP geo-summary for the netflows from the Cisco ASA for the last 24 hours:
from netflow where sensor_type='CISCO_FIREWALL_ASA' | aggregate sum(tx_byte_count) as sum_tx, avg(tx_byte_count), count(dest_ipgeo_summary)
Query the count of domains matching *.net over the last day:
from dnsquery where query_name MATCHES '*.net' latest=-1d | aggregate count by query_name