Reference Lists User Guide


This document describes how reference lists can be enabled to manage a list of items. A reference list is a generic list of values that customers can create and use within the Chronicle platform. For example, you might have a list of commonly used IP addresses or a list of hostnames that should never appear in your network.

You can add reference lists to rules. This capability provides the following benefits:

  • Simplifies the structure of rules by enabling you to abstract lists of domains, IP addresses, users, assets, etc. from the rule text.
  • Avoids long lists of event filters within rules.
  • Individual reference lists can be used in multiple rules, helping to shorten any rules using that reference list.

Be aware of the following when creating reference lists:

  • Maximum list name size is about 200 characters (256 B).
  • Maximum list description size is about 2000 characters (2 KB).
  • Maximum list size is 6 MB.
  • Maximum size of any single list content line is 512 characters.
  • Maximum number of reference list statements allowed in a rule is 7.
  • Check if a UDM field is present in a list by using the following syntax: `
    • Value for $field must be a valid UDM string (for example, an IP address or hostname).
    • Other types are not supported (for example, integers).
    • List content lines are compared to $field using exact string matching. Regular expressions and CIDR ranges are not supported.
  • For negation, use the not operator: `
  • Double slash // indicates the start of a comment and is ignored by the compiler.

Before you begin

Before you can access the Reference List features in Chronicle, complete the following steps:

  1. Launch Chrome.

    If you do not have Chrome installed, go to

  2. Ensure you have access to your corporate account.

  3. Navigate to your Chronicle account: https://<your-company>

  4. Your screen should appear as follows.

Chronicle landing page Chronicle landing page

Using the Reference List Manager

Use the Reference List Manager for the following tasks:

  • View existing reference lists
  • View the contents of a reference list
  • Create new reference lists
  • Edit existing reference lists
  • Duplicate reference lists

To use the Reference List Manager, complete the following steps:

  1. To open the Reference List Manager, go to the main menu in Chronicle and select List Manager. Select List Manager Select List Manager

  2. The List Manager pop-up window is displayed. List Manager List Manager

  3. To view a reference list, select it in the left panel. You can also search for a reference list using the Search lists field. The List Details includes a description and a list of the reference list items.

  4. To create a new reference list, click NEW. Specify a title and description for the reference list. The title appears in other parts of the user interface and cannot be changed, so be sure to make it meaningful.

  5. Add each item to the reference list on a separate line. Click SAVE when the reference list is complete. New Reference List New Reference List

  6. Click CLOSE when you have finished.

Adding a reference list to a rule

To add a reference list to a rule, complete the following steps:

  1. Navigate to the Rules Editor in Chronicle and open the rule you want to add a reference list to.

  2. In the events section of the rule, add a new line starting with the UDM field you are interested in investigating.

For example, you could investigate hostnames using the following UDM field: $e.principal.hostname 3. The reference list syntax within a rule is as follows:

$e.principal.hostname in %<name-of-reference-list>

For the not in syntax, use the following:

not $e.principal.hostname in %good_hostnames

When you add in and then a % character to a rule, the reference list completion pop-up window opens as shown in the following figure. Select the reference list you want to include in the rule.

Reference list pop-up window Reference list pop-up window

The reference list is now included in the rule. Save and enable the rule to begin receiving detections based on the included reference list.