You are viewing docs on Elastic's new documentation system, currently in technical preview. For all other Elastic docs, visit elastic.co/guide.

Add and manage exceptions

Learn how to create and manage rule exceptions.

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

Important

  • To ensure an exception is successfully applied, ensure that the fields you've defined for its 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"]`
  • Be careful when adding exceptions to indicator match rules. Exceptions are evaluated against source and indicator indices, so if the exception matches events in either index, alerts are not generated.

Add exceptions to a rule

  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 (RulesDetection rules (SIEM)Rule name).

      2. Scroll down the rule details page, select the Rule exceptions tab, then click Add rule exception.

    • 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.
    • To add an exception from the alert details flyout:

      1. Go to Alerts.
      2. Click the View details button from the Alerts table.
      3. In the alert details flyout, click Take action → Add rule exception.
    • To add an exception from the Shared Exception Lists page:

      1. Go to RulesShared exception lists.
      2. Click Create shared exception listCreate exception item.
  2. In the Add rule exception flyout, name the exception.

  3. Add conditions that define the exception. When the exception's query evaluates to true, rules don't generate alerts even when their criteria are met.

    Important

    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.

    Note

    When you create a new exception from an alert, exception conditions are auto-populated with relevant alert data. Data from custom highlighted fields is listed first. A comment that describes the auto-generated exception conditions is also added to the Add comments section.

    1. Field: Select a field to identify the event being filtered.

      A warning displays for fields with conflicts. Using these fields might cause unexpected exceptions behavior. Refer to Troubleshooting type conflicts and unmapped fields for more information.

    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.

        Note

        • 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.

        Note

        Some characters must be escaped with a backslash, such as \\ for a literal backslash, \* for an asterisk, and \? for a question mark. Windows paths must be divided with double backslashes (for example, C:\\Windows\\explorer.exe), and paths that already include double backslashes might require four backslashes for each divider.

        Important

        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.

      Note

      Identical, case-sensitive values are supported for the is one of and is not one of operators. For example, if you want to match the values Windows and windows, add both values to the Value field.

      In the following example, the exception was created from the Rules page and prevents the rule from generating alerts when the svchost.exe process runs on hostname siem-kibana.

  4. Click AND or OR to create multiple conditions and define their relationships.

  5. 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.

  6. Choose to add the exception to a rule or a shared exception list.

    Note

    If you are creating an exception from the Shared Exception Lists page, you can add the exception to multiple rules.

    Tip

    If a shared exception list doesn't exist, you can create one from the Shared Exception Lists page.

  7. (Optional) Enter a comment describing the exception.

  8. (Optional) Enter a future expiration date and time for the exception.

  9. 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.

  10. Click Add rule exception.

Add Elastic Endpoint exceptions

Like detection rule exceptions, you can add Endpoint agent exceptions either by editing the Endpoint Security rule or by adding them as actions 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 the Endpoint Security rule and the Elastic Endpoint on your hosts.

Important

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

Additionally, to add an Endpoint exception to the 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).

Important

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 (RulesDetection rules (SIEM)), 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.
    • To add an Endpoint exception from Shared Exception Lists page:

      1. Go to RulesShared exception lists.
      2. Expand the Endpoint Security Exception List or click the list name to open the list's details page. Next, click Add endpoint exception.

      Note

      The Endpoint Security Exception List is automatically created. By default, it's associated with the Endpoint Security rule and any rules with the Elastic Endpoint exceptions option selected.

    The Add Endpoint Exception flyout opens.

  2. If required, modify the conditions. Refer to Exceptions with nested conditions for more information on when nested conditions are required.

    Important

    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.

    Note

    • Fields with conflicts are marked with a warning icon (). Using these fields might cause unexpected exceptions behavior. For more information, refer to Troubleshooting type conflicts and unmapped fields.
    • Identical, case-sensitive values are supported for the is one of and is not one of operators. For example, if you want to match the values Windows and windows, add both values to the Value field.
  3. (Optional) Add a comment to the exception.

  4. 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.

  5. Click Add Endpoint Exception. An exception is created for both the detection rule and the Elastic Endpoint.

    Note

    It might take longer for exceptions to be applied to hosts within larger deployments.

Exceptions with nested conditions

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"
  }
}

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

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

View and manage exceptions

To view a rule's exceptions, open the rule's details page (RulesDetection rules (SIEM)Rule name), then scroll down and select the Rule exceptions or Endpoint exceptions tab. All exceptions that belong to the rule will display in a list. From the list, you can filter, edit, and delete exceptions. You can also toggle between Active exceptions and Expired exceptions.

Find rules using the same exceptions

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.

Note

Changes that you make to the exception also apply to other rules that use the exception.

On this page