Rule exceptions and value lists

edit

To prevent the creation of unwanted alerts, you can add exceptions to any rule. Exceptions contain the source event conditions that determine when alerts are not generated. They provide a convenient way of allowing trusted processes and network activity to function without producing unnecessary noise.

You can add multiple exceptions to a single rule. An exception can also apply to multiple rules.

In addition to defining exception queries for source event values, you can use rule exceptions with value lists. Value lists are lists of items with the same Elasticsearch data type. You can create value lists with these types:

  • Keywords (many ECS fields are keywords)
  • IP Addresses
  • IP Ranges
  • Text

After creating value lists, you can use is in list and is not in list operators to define exceptions.

You can also use value lists as the indicator match index when creating an indicator match rule.

Create value lists

edit

When creating a value list for a rule exception, be mindful of the list’s size and data type. In general, all rule types support value list exceptions, but there are some limitations for especially large lists or certain data types. The following value list types can only be used with custom query, machine learning, and indicator match rule types:

  • Keyword or IP address lists with more than 65,536 values
  • IP range lists with more than 200 dash notation values (for example, 127.0.0.1-127.0.0.4 is one value) or more than 65,536 CIDR notation values
  • Text data type lists of any size

To create a value list:

  1. Prepare a txt or csv file with all the values you want to use for determining exceptions from a single list. If you use a txt file, new lines act as value delimiters.

    • All values in the file must be of the same Elasticsearch type.
    • Wildcards are not supported in value lists. Values must be literal values.
  2. Go to ManageRules.
  3. Click Import value lists. The Import value lists window opens.

    Import value lists flyout
  4. Select the list type (Keywords, IP addresses, IP ranges, or Text) from the Type of value list drop-down.
  5. Drag or select the csv or txt file that contains the values.
  6. Click Import list.

When the name of the file you are importing already exists, the values in the new file are appended to the previously imported values.

Manage value lists

edit

To view, delete, or export existing value lists:

  1. Go to ManageRules.
  2. Click Import value lists. The Import value lists window opens.
  3. In the Value lists table, click the required action button.

    Import value list flyout with action buttons highlighted

Add exceptions to a rule

edit

You can add exceptions to a rule from the rule details page or the Alerts table. When you add an exception, you can also close all alerts that meet the exception’s criteria.

  • To ensure an exception is successfully applied, make sure that the fields you’ve defined for the exception query are correctly and consistently mapped in their respective indices. Refer to ECS to learn more about supported mappings.
  • Be careful when adding exceptions to event correlation rules. Exceptions are evaluated against every event in the sequence, and if an exception matches any events that are necessary to complete the sequence, alerts are not created.

    To exclude values from a specific event in the sequence, update the rule’s EQL statement. For example:

    `sequence
      [file where file.extension == "exe"
      and file.name != "app-name.exe"]
      [process where true
      and process.name != "process-name.exe"]`
  1. Do one of the following:

    • To add an exception from the rule details page:

      1. Go to the rule details page of the rule to which you want to add an exception (ManageRules<Rule name>).
      2. Scroll down the rule details page, select the Rule exceptions tab, then click Add rule exception.

        Detail of rule exceptions tab
    • To add an exception from the Alerts table:

      1. Go to Alerts.
      2. Scroll down to the Alerts table, go to the alert you want to create an exception for, click the More Actions menu (…​), then select Add rule exception.

    The Add Rule Exception flyout opens (the example below was opened from the Alerts table):

    add exception ui
  2. Use the following settings to add conditions that define when the exception prevents alerts. In the example above, the exception prevents the rule from generating alerts when the svchost.exe process runs on agent hostname siem-kibana.

    Rule exceptions are case-sensitive, which means that any character that’s entered as an uppercase or lowercase letter will be treated as such. In the event you don’t want a field evaluated as case-sensitive, some ECS fields have a .caseless version that you can use.

    1. Field: Select a field to identify the event being filtered.
    2. Operator: Select an operator to define the condition:

      • is | is not — Must be an exact match of the defined value.
      • is one of | is not one of — Matches any of the defined values.
      • exists | does not exist — The field exists.
      • is in list | is not in list — Matches values in a value list.

        • An exception defined by a value list must use is in list or is not in list in all conditions.
        • Wildcards are not supported in value lists.
        • If a value list can’t be used due to size or data type, it’ll be unavailable in the Value menu.
      • matches | does not match — Allows you to use wildcards in Value, such as C:\path\*\app.exe. Available wildcards are ? (match one character) and * (match zero or more characters). The selected Field data type must be keyword, text, or wildcard.

        Using wildcards can impact performance. To create a more efficient exception using wildcards, use multiple conditions and make them as specific as possible. For example, adding conditions using process.name or file.name can help limit the scope of wildcard matching.

    3. Value: Enter the value associated with the Field. To enter multiple values (when using is one of or is not one of), enter each value, then press Return.
  3. Click AND or OR to create multiple conditions and define their relationships.
  4. Click Add nested condition to create conditions using nested fields. This is only required for these nested fields. For all other fields, nested conditions should not be used.
  5. (Optional) Enter a comment describing the exception.
  6. Select one of the following alert actions:

    • Close this alert: Closes the alert when the exception is added. This option is only available when adding exceptions from the Alerts table.
    • Close all alerts that match this exception and were generated by this rule: Closes all alerts that match the exception’s conditions and were generated only by the current rule.
  7. Click Add Rule Exception.

Add Elastic Endpoint exceptions

edit

Like detection rule exceptions, you can add Endpoint agent exceptions either by editing the Elastic Endpoint Security rule or by adding them as an action on alerts generated by the Endpoint Security rule. Elastic Endpoint alerts have the following fields:

  • kibana.alert.original_event.module determined:endpoint
  • kibana.alert.original_event.kind:alert

You can also add Endpoint exceptions to rules that are associated with Elastic Endpoint rule exceptions. To associate rules, when creating or editing a rule, select the Elastic Endpoint exceptions option.

Endpoint exceptions are added to both the detection rule and the Elastic Endpoint agent on your hosts.

Exceptions added to the Elastic Endpoint Security rule affect all alerts sent from the Endpoint agent. Be careful not to unintentionally prevent some Endpoint alerts.

Additionally, to add an Endpoint exception to the Elastic Endpoint Security rule, there must be at least one Endpoint Security alert generated in the system. For non-production use, if no alerts exist, you can trigger a test alert using malware emulation techniques or tools such as the Anti Malware Testfile from the European Institute for Computer Anti-Virus Research (EICAR).

Binary fields are not supported in detection rule exceptions.

  1. Do one of the following:

    • To add an Endpoint exception from the rule details page:

      1. Go to the rule details page (ManageRules), and then search for and select the Elastic Endpoint Security rule.
      2. Scroll down the rule details page, select the Endpoint exceptions tab, then click Add endpoint exception.
    • To add an Endpoint exception from the Alerts table:

      1. Go to Alerts.
      2. Scroll down to the Alerts table, and from an Elastic Endpoint alert, click the More actions menu (…​), then select Add Endpoint exception.

    The Add Endpoint Exception flyout opens, from either the rule details page or the Alerts table.

    endpoint add exp
  2. If required, modify the conditions.

    Rule exceptions are case-sensitive, which means that any character that’s entered as an uppercase or lowercase letter will be treated as such. In the event you don’t want a field evaluated as case-sensitive, some ECS fields have a .caseless version that you can use.

    Refer to Exceptions with nested conditions for more information on when nested conditions are required.

  3. You can select any of the following:

    • Close this alert: Closes the alert when the exception is added. This option is only available when adding exceptions from the Alerts table.
    • Close all alerts that match this exception and were generated by this rule: Closes all alerts that match the exception’s conditions.
  4. Click Add Endpoint Exception. An exception is created for both the detection rule and the Elastic Endpoint.

Exceptions with nested conditions

edit

Some Endpoint objects contain nested fields, and the only way to ensure you are excluding the correct fields is with nested conditions. One example is the process.Ext object:

{
  "ancestry": [],
  "code_signature": {
    "trusted": true,
    "subject_name": "LFC",
    "exists": true,
    "status": "trusted"
  },
  "user": "WDAGUtilityAccount",
  "token": {
    "elevation": true,
    "integrity_level_name": "high",
    "domain": "27FB305D-3838-4",
    "user": "WDAGUtilityAccount",
    "elevation_type": "default",
    "sid": "S-1-5-21-2047949552-857980807-821054962-504"
  }
}

code_signature.subject_name refers to the process signature not the process name.

Only these objects require nested conditions to ensure the exception functions correctly:

  • Endpoint.policy.applied.artifacts.global.identifiers
  • Endpoint.policy.applied.artifacts.user.identifiers
  • Target.dll.Ext.code_signature
  • Target.process.Ext.code_signature
  • Target.process.Ext.token.privileges
  • Target.process.parent.Ext.code_signature
  • Target.process.thread.Ext.token.privileges
  • dll.Ext.code_signature
  • file.Ext.code_signature
  • file.Ext.macro.errors
  • file.Ext.macro.stream
  • process.Ext.code_signature
  • process.Ext.token.privileges
  • process.parent.Ext.code_signature
  • process.thread.Ext.token.privileges

Nested condition example

edit

Creates an exception that excludes all LFC-signed trusted processes:

nested exp

Find rules using the same exception

edit

To find out if an exception is used by other rules, select the Rule exceptions or Endpoint exceptions tab, navigate to an exception list item, then click Affects X rules.

exception affects multiple rules

View and manage exception lists

edit

The Exception lists table enables you to view and manage all exceptions that have been assigned to rules. To view the Exception lists table, go to ManageException lists.

exceptions page

Exceptions are automatically grouped into exception lists. The table displays each exception list on an individual row, with the most recently created list at the top. Each row contains information such as the name of the rule to which the exception list is assigned, the dates when the list was created and last edited, and options to export or delete it.

To view details of the rule the exception list is assigned to, click the link in the Rules assigned to column.

To filter exception lists by a specific value, enter a query in the Search bar. You can search the following attributes:

  • name
  • list_id
  • created_by
  • type
  • tags

If no attribute is selected, the app searches the list name by default.

To export or delete an exception list, select the required action button on the appropriate list. Note that:

  • Exception lists are exported to .ndjson files.
  • Exception lists are also exported as part of any exported detection rules configured with exceptions. Refer to Export and import rules.
  • If an exception list is linked to any rules, you’ll get a warning asking you to confirm the deletion. If no rules are linked, the list is deleted without confirmation.
Detail of Exception lists table with export and delete buttons highlighted