Create an XQL Query

Learn how to create queries using the XDR Query Language (XQL).
Use XQL Search to analyze raw log data stored in Cortex XDR. The following example demonstrates how to create a query that uses the
coalesce
function to derive a single
username
by examining multiple field names.
The XQL Language Reference provides more information about valid commands, such as the ones used in this example, and general XQL syntax.
  1. From Cortex XDR, select
    Investigation
    Query Builder
    XQL Search
    .
  2. (
    Optional
    ) Specify a dataset.
    You only need to specify a dataset if you are running your query against a dataset that you have not set as default. For more information, see how to manage datasets. See the XQL Language Reference for a list of the datasets that are available to you, depending on your configuration.
    From the first letter that you type, the query field provides you with suggestions of commands and their definitions:
    When you select a command, you will see available operators:
    After selecting the operator, the query field presents available values:
  3. Hit the return key and enter a pipe (
    |
    ) followed by the first stage of your query.
    This stage uses the
    fields
    command to declare which fields are returned in the results. If you use this stage, then following stages can only operate on the fields specified in it.
  4. Continue adding stages until your query is complete.
    This stage uses the function
    coalesce
    to return the first value that is not NULL out of the given fields and the
    alter
    stage command to assign that value to the field
    username
    .
  5. Specify the time period against which you want to run your query.
    The options are last
    24H
    (hours), last
    7D
    (days), last
    1M
    (month), or select a
    Custom
    time period.
  6. Choose when to run the query.
    Select the calendar icon to schedule a query to run on or before a specific date,
    Add as BIOC
    to save the query as a BIOC rule (if compatible),
    Run in background
    (that is, as resources are available), or
    Run
    the query immediately.
  7. (
    Optional
    ) After your query is complete, you can save the query as one of the following rules.
    • BIOC Rule
      Save as
      BIOC Rule
      . The XQL query must at a minimum filter on the
      event_type
      field in order for it to be a valid BIOC rule that you can save. For more information, see Working with BIOCs.
    • Correlation Rule
      Save as
      Correlation Rule
      . For more information, see Working with Correlation Rules.
  8. After running your query, review the
    Query Results
    .
    Alternate between the following display options to investigate your query results:
    • Table ( )—Displays results in rows and columns according to the entity fields.
      From the menu, you can change the table layout. You can also change the raw log format (displayed in the
      _Raw_Log
      field) to one of the following log formats:
      • RAW
        —Raw format of the entity in the database.
      • JSON
        —Condensed JSON format with key value distinctions. Null values are not displayed.
      • TREE
        —Dynamic view of the JSON hierarchy with the option to collapse and expand the different hierarchies.
    • Graph ( )—Use the Chart Editor to visualize the query results.
    • Advanced ( )—Displays results in a table format aggregating the entity fields into one column. Similar to the table display, you can change the layout and log format from the menu.
      Select
      Show more
      to pivot an
      Expanded View
      of the event results that include null values. You can toggle between the
      JSON
      and
      Tree
      views, search, and
      Copy to clipboard
      .
    You can also perform the following additional actions on the results displayed.
    • Export to File
      ( )—Exports the results to a TSV (Tab-separated values) file.
    • Refresh
      ( )—Refreshes the query results.
    • Free text search
      ( )—Searches the query results for text that you specify in the free text search. Click the
      Free text search
      icon to reveal the text
      Type your search here
      .
    • Filter
      ( )—Enables you to filter a particular field in the interface that is displayed to specify your filter criteria.
    We recommend for Integer, Boolean, and timestamp, such as
    _Time
    , fields that you use the
    Filter
    as opposed to the
    Free text search
    to retrieve the most accurate query results.
    For Table and Advanced displays, Cortex XDR provides a
    Fields
    menu on the left side of the query results that you use to filter the results. To quickly set a filter, Cortex XDR displays the top 10 results from which you can choose to build your filter. From within the
    Fields
    menu, click on any field (excluding JSON and array fields) to see a histogram of all the values found in the result set for that field. This histogram includes a count of the total number of times a value was found in the result set, the value's frequency as a percentage of the total number of values found for the field, and a bar chart showing the value's frequency. In order for Cortex XDR to provide a histogram for a field, the field must not contain an array or a JSON object.
    You can also manage your queries, which includes viewing query results, from the
    Query Center
    .
  9. (
    Optional
    ) Save the query to your personal query library.
  10. (
    Optional
    ) Continue investigation in the Causality View or Timeline View.
    Right-click the event and select the desired view. This option is available for the following types of events: process (except for those with an event sub type of termination), network, file, registry, injection, load image, system calls, event logs for Windows, and system authentication logs for Linux. For network stories, you can pivot to the Causality View only.
  11. (
    Optional
    ) Add a file path to your exiting Malware Profile allowed list.
    Right-click a
    <path>
    fields, for example,
    target_process_path
    ,
    file_path
    , or
    os_parent_path
    , and select
    Add
    <path type>
    to malware profile allow list
    .

Recommended For You