timeframe - Reference Guide - Cortex XDR - Cortex - Security Operations

Cortex XDR XQL Language Reference

Product
Cortex XDR
Creation date
2023-10-31
Last date published
2024-03-27
Category
Reference Guide
Abstract

Cortex Query Language timeframe configuration enables performing searches within a specific time frame from the query execution.

Syntax
  • Exact Time

    config timeframe between "<Year-Month-Day H:M:S ±Timezone>" and "<Year-Month-Day H:M:S ±Timezone>"
  • Relative Time

    config timeframe = <number><time unit>
    config timeframe between "<+|-><number><time unit>" and "now"
    config timeframe between "begin" and "<+|-><number><time unit>"
    config timeframe between "<+|-><number><time unit>" and "<+|-><number><time unit>"
Description

The timeframe configuration enables you to perform searches within a specific time frame from the query execution. The results for the time frame are based on times listed in the _Time column in the results table.

You can add the timeframe configuration to your queries using different formats depending on whether the time frame you are setting is an exact time or relative time.

When you set an exact time, include the config timeframe details: between "<Year-Month-Day H:M:S ±Timezone>" and "<Year-Month-Day H:M:S ±Timezone>". The ±Timezone format is: ±xxxx. When you do not configure a timezone, the default is UTC. The exact time is based on a static timeframe according to when the query is sent.

When you set a relative time, you have a few options for setting the config timeframe, where the syntax <+|-> indicates whether to go back (-) or forward (+) in time. The default is back (-).

  • <number><time unit>

    Enables setting a static timeframe according to when the query is sent, where you choose the <time unit> from the available time unit options listed in the table below.

  • between "<+|-><number><time unit>" and "now"

    Enables setting a timeframe between a defined start time, where you choose the <time unit> from the available time unit options listed in the table below, and the end time as the time the query is run with the preset keyword "now".

  • between "begin" and "<+|-><number><time unit>"

    Enables setting a timeframe between a preset start time according to the Unix epoch time 00:00:00 UTC on 1 January 1970 with the "begin" keyword, and a defined ending time, where you choose the <time unit> from the available time unit options listed in the table below.

    between "<+|-><number><time unit>" and "<+|-><number><time unit>"

    Enables setting a timeframe between a defined started and ending time, where you choose the <time unit> from the available time unit options listed in the table below.

Available Time Units

Time Unit

Description

S

seconds

M

minutes

H

hours

D

days

W

weeks

MO

months

Y

years

Note

The time unit is not case sensitive.

Examples
  • Example of <number><time unit>

    For the last 10 hours from when the query is sent, return a maximum of 100 xdr_data records.

    config timeframe = 10h
    | dataset = xdr_data
    | limit 100
  • Example of between "<+|-><number><time unit>" and "now"

    Since the last two days until now when the query is run, return a maximum of 100 xdr_data records.

    config timeframe between "2d" and "now"
    | dataset = xdr_data
    | limit 100
  • Example of between "begin" and "<+|-><number><time unit>"

    Since the Unix epoch time 00:00:00 UTC on 1 January 1970 until the past 2 years when the query is run, return a maximum of 100 xdr_data records.

    config timeframe between "begin" and "2y"
    | dataset = xdr_data
    | limit 100
  • Example of between "<+|-><number><time unit>" and "<+|-><number><time unit>"

    Since the last four days until the next 5 days when the query is run, return a maximum of 100 xdr_data records.

    config timeframe between "-4d" and "+5d"
    | dataset = xdr_data
    | limit 100

From April 1, 2021 at 9:00 a.m. UTC -02:00 until April 2, 2021 at 10:00 a.m. UTC -02:00, return a maximum of 100 xdr_data records.

config timeframe between "2021-04-01 09:00:00 -0200" and "2021-04-02 10:00:00 -0200" 
| dataset = xdr_data 
| limit 100