Reference Lists

This article explains the overview and configuration steps to add multiple entities like domains, IPs, and so on, to a reference list. 

A reference list is a generic list of values that can be used to analyze your data. The behavior of a list depends on the "List Type" which must be configured at list creation time and cannot be changed. For example, whitelisting the domains from malicious threats using a combination of rules and putting them in a list to use for future detections. These lists can be shared with your tenants and organizations in order to minimize effort and save their time defining the same combination of rules when they encounter similar malicious domains or IP addresses.

The following list of entities is generally used for referencing detection rules.

• Domain
• Email Id
• File Hashes
• File Path
• Host Name
• IP Address
• Network Subnet
• Port 
• URL
• Username

Creating Reference Lists

User Permissions Required: A Creator from these categories such as Domain, Organization and Tenant can configure reference list.

To configure a reference list,

1. Do one of the following to access configurations:

• Click the Configurations icon at the top navigation bar.
• Click the hamburger menu on the left and select CONFIGURATIONS.

2. Click Entities-->Reference Lists. The reference lists page appears. 

3. Click Create New to open the New Reference List page.

4. Enter Title and Description for your reference list.

5. Select the Syntax Type from the drop-down menu.

• • String (Plain text) - Add IPs, domains, and URLs in a plain text format. Examples: IPs: 192.168.1.1, 10.0.0.1, 172.16.0.1, Domains: abc.com, test.org, mywebsite.net 
  • Regex - Add the list of email addresses and URLs in regex format. Example: [a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,}
  • CIDR - Add a range of IP addresses in CIDR notation. Example: 205.148.5.0/24 

6. Add the IPs, domains and URLs in the List editor based on the selected syntax type. 

7. Click Save as Draft to save the reference list as draft.

Note:

• When you add the reference list to a rule, it notifies the users when any signal is detected from the list of IPs, email addresses, and domains you have added. 
• Title and Description are not editable once a reference list is published, and you cannot delete a reference list after publishing it.
• Click Verify List to confirm that the list you provided in the editor is in the correct format and is error-free.

Approval Workflow

Send reference lists for review

Use this procedure to send the reference lists that are saved as draft for review. 

1. Click on the reference lists that are in Draft. 

2. Click Send for review to send the reference lists for review. 

Approve reference lists under review

1. Click on the reference lists that are Under review. 

2. Click Approve to approve the reference list for publishing. The Approve reference list dialog appears. 

3. Add the comment and click Approve. The status of the reference list changes from under review to Approved. 

Publish reference lists

1. Click on a specific reference list that is in approved state and must be published. This opens the reference list page.

2. If you are at domain level, click Add accounts to add the organizations to which the reference lists should be published and then click Done. This adds the selected accounts to the selected accounts section. 

3. Click Publish to publish the list. Only the published reference lists can be added to detection rules. 

Linking reference lists to detection rules

Users can include reference links within the YARA-L rule body. Only published reference lists can be added to rules. Once the rule is verified, users can save the detection rule and view the reference list on the left. The "view" option on the detection rules page allows access to the reference list. 

Note: If a rule is published from the parent account and the reference list is missing in the child account, the reference list linked to the rule is automatically published to the child accounts during rule publication from the parent account. Additionally, all automatic reference list publishing actions associated with rule publication are recorded in the activity logs for traceability.

1. Do one of the following to access configurations:

• Click the Configurations icon at the top of the navigation bar.
• Click the hamburger menu on the left and select CONFIGURATIONS.

2. Click Signals-->Detection Policies. This opens the Signal Detection policies page. 

3. Click Create New drop-down and select Detection Rule. 

4. Enter the rule name and description. 

5. Provide the YARA-L rule in the rule editor adding the name of the reference list within the syntax. 

6. Click Verify rule to check for errors. Once the rule is verified and is sent for review, you can view the populated reference list in the Reference List section on the right. 

7. Click View corresponding to the reference list. This takes you to the respective reference list page to view its details. 

Viewing the reference lists linked to detection rules

Use this procedure to view reference lists associated with detection rules. Only published reference lists can be added to the rule body during the creation of a detection rule. The Referenced By option is displayed only if the reference list is used in detection rules within the specific account.

1. Do one of the following to access configurations:

• Click the Configurations icon at the top navigation bar.
• Click the hamburger menu on the left and select CONFIGURATIONS.

2. Click Entities-->Reference Lists. The reference lists page appears. 

3. Click the Published pill to view only the published reference lists within the account.

4. Select a reference list to view the number of detection rules it is linked to. The Referenced By option will be displayed.

5. Click Referenced By to open a side panel showing the detection rules where the list is used.

6. Review this information:

Field name	Field description
Rule Name	The name of the detection rule using the reference list.
Version	The version of the detection rule linked to the reference list.
Status	The current status of the detection rule.
Modified Date	The date on which the detection rule was last modified.

 

You can also click on any rule to navigate to the respective detection rule's page. 

Managing reference lists

Use this procedure to manage reference lists. 

1. Do one of the following to access configurations:

• Click the Configurations icon at the top of the navigation bar.
• Click the hamburger menu on the left and select CONFIGURATIONS.

2. Click Entities-->Reference Lists. The reference lists page appears. 

3. Review the information:

Field name	Field description
Name	The name of the reference list.
Status	The status of the reference list. Possible values: Draft Under Review Approved Request Changes Published
List type	The type of list created. Possible values: String (Plain Text) Regex CIDR
Referenced by rules	The detection rules, in which the reference list has been added and verified. The count indicates the number of detection rules where the reference list was added.
Modified on	The date on which the reference list was last modified.
Modified by	The user who has last modified the list.

 

You can perform the following actions on the table view of reference list page:

• Click the ellipses icon corresponding to the reference list and select Delete to delete the list. You cannot delete the reference list after it is published and then is moved to draft, approved or other statuses. 
• Click on any of the statues, such as draft, under review, approved, request changes and published to filter the reference list by status. 
• Click the filter icon to open the conditional filters window. Here, you can select the label, operator, and add a value. For example, if you select "List Type" as the label, "Equals" as the operator, and "Regex" as the value, the system will filter and display reference lists with the list type "Regex." You can also add multiple filters using the "Add Filter" option to filter the data.