Transaction - Reference Guide - Cortex XDR - Cortex

Abstract

Learn more about the Cortex Query Language transaction stage used to find transactions based on events that meet certain constraints.

Note

This stage is unsupported with Correlation Rules.

Syntax

transaction <field_1, field_2, ...>  [span = <time> [timeshift = <epoch time> [timezone = "<time zone>"]] | startswith = <condition> endswith = <condition> allowunclosed= true|false] maxevents = <number of events per transaction>

Description

The transaction stage is used to find transactions based on events that meet certain constraints. This stage aggregates all fields in a JSON string array by fields defined as transaction fields. For example, using the transaction stage to find transactions based on the user and user_ip fields will make the aggregation of json strings of all fields by the user and user_ip fields. A maximum of 50 fields can be aggregated in a transation stage.

You can also configure whether the transactions falls within a certain timeframe, which is optional to define. You can set one of the following:

span=<time>: Use this command to set a timeframe per transaction, where <time> is a combination of a number and time suffix. Set one time suffix from the list of available options listed in the table below. In addition, you can define a particular start time for grouping the events in your query according to the Unix epoch time by setting timeshift = <epoch time> timezone = "<time zone>", which are both optional. You can configure the <time zone> offset using an hours offset, such as “+08:00”, or using a time zone name from the List of Supported Time Zones, such as "America/Chicago". The query still runs without defining the epoch time or time zone. If no timeshift = <epoch time> timezone = "<time zone>" is set, the query runs according to last time set in the log.
startswith and endswith: Use these commands to set a condition for the beginning or end of the transaction, where the condition can be a logical expression or free text search.

Set the allowunclosed flag to true to include transactions which don't contain an ending event. The last event will be 12 hours after the starting event. By default, this is set to true and transactions without an ending event are included.

Use the maxevents command to define the maximum number of events to include per transaction. If this command is not set, the default value is 100.

When using the transaction stage, 5 additional fields are added to the results displayed:

_start_time: Indicates the initial timestamp of the transaction.
_end_time: Indicates the last timestamp for the transaction.
_duration: Displays the difference in seconds between the timestamps for the first and last events in the transaction.
_num_of_rows: Indicates the number of events in the transaction.
_transaction_id: Displays the unique transaction ID.

Time Suffix	Description
MS	milliseconds
S	seconds
M	minutes
H	hours
D	days
W	weeks
MO	months
Y	years

Example using Span

Return a maximum of 10 events per transaction from the xdr_data records based on the user and agent_id fields, where the transaction timeframe is 1 hour.

dataset=xdr_data
|transaction user, agent_id span=1h timeshift = 1615353499 
timezone = “+08:00” maxevents=10

This query results in the following XQL JSON:

{'TRANSACTION': {'fields': ['user', 'agent_id'], 'maxevents': 10, 'span': {'amount': 1, 'units': 'h', 'timeshift': None}}}

Example using Startswith and Endswith

Return a maximum of 99 events per transaction from the xdr_data records based on the f1 and f2 fields. The starting event of each transaction is an event, where one of the fields contains a string "str_1", and the ending event of each transaction is an event, where one of the fields contains a string "str_2".

dataset=xdr_data
| transaction f1, f2 startswith="str_1" endswith="str2" maxevents=99