# Modifying Detections with Rule Filters (Beta)

## Overview

{% hint style="info" %}
Rule filters are in open beta as of Panther version 1.54. Please share any bug reports and feature requests with your account team.
{% endhint %}

In the Panther Console, you can easily tune existing [rules](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/detections/writing-and-editing-detections/rules), including [Panther-managed rules](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/detections/panther-managed), by adding Rule Filters. Because Rule Filters are code-free, they expand who, on your security team, can contribute to detection fidelity. Note that Rule Filters are available only on rules, not scheduled rules nor policies.

Based on a detection's log type, you can select a `field` to filter on. From there, you will specify the `operator` and, if applicable, input a `value`. You can add filters while editing a rule, or directly from an associated alert. This quick tuning from alerts is particularly useful if the alert is a false positive, and you would like similar events in the future to not trigger the rule.

A common use case for filters is to add an allowlist or denylist.

### How filters work

Filter statements are evaluated before a detection's rule function. A filter must return `true` (i.e., match the event) for the rule function, which is written in code, to then be run. 

When multiple filters are included on one rule, they run using `AND` logic. `OR` statements are not supported.

If an event does not contain the field the filter is evaluating, the filter will pass. If the field the filter is evaluating has a value of `none`, the filter will return `false` on positive comparators or on comparators that don't apply, and `true` for inverse comparators.

Note that filters are not available during new rule creation. When you export a rule from the Panther Console, filters are not included.

## How to add filters to a rule

You can add filters to a rule [from its edit page](#add-filters-from-a-rules-edit-page), or [within an alert triggered by that rule](#add-filters-from-an-alert-event).

### Add filters from an alert event

You can add Rule Filters to a rule directly from an event in an associated alert. This is particularly helpful if you've received a false positive alert, and want to tune the triggered detection so it won't match on similar events in the future.

1. Log in to the Panther Console.
2. In the left sidebar, click **Alerts**.
3. Locate the alert whose associated rule you'd like to tune, and click its name.
4. On the alert's detail page, scroll down to the **Event** section. 
5. In the event's JSON, hover over the indicator you'd like the new filter to target, and click the target icon. \
   ![While viewing an alert, the event JSON is shown. One event field is hovered over, and three icons have appeared. The third is a target, and the tooltip reads "Add to Rule Filter"](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fp99tsZ85sVytcGBXqJZE%2FScreenshot%202023-03-29%20at%202.46.34%20PM.png?alt=media\&token=8a01df10-7e76-457f-b8f3-7fae6da34168)
   * The **Add Rule Filter** panel will open on the righthand side of the window.
6. In the **Add Rule Filter** panel, a new filter will be pre-populated in the following way:
   * **Field**: defaults to the field on which you clicked the target icon in the event JSON.
   * **Operator**: defaults to **is not**, assuming you would *not* like to receive alerts for events like this in the future.
   * **String**: defaults to the value of the selected field in the event JSON.\
     ![The Add Rule Filter panel is shown. It displays a Target Rule, Filters section (with a new filter pre-populated with "actor.alternateId is not james.sirius.potter@hogwarts.uk", a read-only Rule Function section, and a Unit Test section. at the bottom there are buttons for Close, Discard Changes, and Save & Run Test](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2F2NyxA6AyOH9A97lDzUN3%2FScreenshot%202023-03-29%20at%203.31.17%20PM.png?alt=media\&token=dc6b00ef-ead9-47a2-a42d-0ab79a2d11ca)
7. Make any desired changes to the filter. All pre-populated fields (i.e., **Field**, **Operator** and **String**) are editable.
8. (Optional) Add more filters.
   1. At the bottom of the **Add Rule Filter** panel, click **Close** (or click outside of the panel).\
      ![The lower portion of the panel displays a Close button, which is circled.](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2FfsjhsSzP4xo9110s2rMP%2FScreenshot%202023-03-29%20at%203.25.59%20PM.png?alt=media\&token=f0e336d8-37f0-4c06-8d5c-ca18036ed445)
   2. Repeat steps 5–7 above to add additional filters.
      * In the **Filters** section of the **Add Rule Filter** panel, previously added filters will be shown in addition to the new one you're adding.
      * You can continue adding filters to your rule in this fashion, but they are not saved until step 10, when you click **Save & Run Test**. (You can think of this like an online shopping cart.)
9. Locate the **Unit Test** section near the bottom of the panel. If the rule is not [Panther-managed](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/detections/panther-managed) and you'd like to create a new unit test for the rule using the current event, click the checkbox labeled **Add the current alert event as a unit test**. 
   * The toggle labeled **The detection should trigger based on the example event** is editable. It defaults to **No**, as you are likely trying to prevent alerts like this in the future.\
     ![The Unit Test section of the panel is shown. A checkbox labeled "Add the current alert event as a unit test" is checked. There is a toggle below with the label "The detection should trigger based on the example event:"](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2FApSBkHMSLcTehSc14VZ6%2FScreenshot%202023-03-29%20at%203.46.30%20PM.png?alt=media\&token=a9d6b29d-ab0a-4d1b-9395-ded8abfc1ba0)
   * If the rule is [Panther-managed](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/detections/panther-managed), this option will be greyed out.\
     ![The Unit Test section is greyed out. The informational tooltip says "Unit Test is created and managed by the Panther team."](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2F4UpulUtX67bwkzcYRbZ8%2FScreenshot%202023-03-29%20at%204.35.25%20PM.png?alt=media\&token=a3cd8f44-5ed7-4fd2-a3a6-563fe384df48)
10. Click **Save & Run Test**.
    * This runs all of the target rule's unit tests. If you created a new unit test in step 9, it is also run.
    * In order for the new filter(s) to be saved, all of the rule's unit tests must pass. If any of the unit tests fail:
      * If the rule is not [Panther-managed](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/detections/panther-managed), click **View Detection** to be taken to the rule's detail page to edit unit tests. From there, you can click **Update** to save your changes to the rule.\
        ![An error message reads "There were errors trying to save the rule with additional filter(s). Changes have not been saved to your detection." A button reads "View Detection"](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2FY3kp0iVtWGl9c7Z1jFW5%2Fimage.png?alt=media\&token=5b4502b7-fbe6-4c95-8879-20cb0efb392f)
      * If the rule is [Panther-managed](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/detections/panther-managed), its unit tests are read-only, meaning you can't alter failing tests to make them pass. To be able to add the filter successfully, instead follow the [Working with failed unit tests with filters](#working-with-failed-unit-tests-with-filters) workflow.

### Add filters from a rule's edit page

{% hint style="info" %}
This consolidated user interface for viewing and editing detections is in open beta starting with Panther version 1.74. Please share any bug reports and feature requests with your Panther support team.
{% endhint %}

1. In the left-hand navigation bar of your Panther Console, click **Build > Detections**.
2. In the list of detections, click a rule's name to view its details page.
3. In the **Detect** section, find the **Filters** tile, and on its right-hand side, click **Add New**.\
   ![On the Cloudflare Bot High Volume detection page, there is a section titled "Detect." Within it, there is a Filters tile, and to its right an "Add New" button. Below the Filters tile is a "Rule Function" tile.](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fz2hG1w3hfQ9eaMY5zslX%2Fimage.png?alt=media\&token=c4ce91b9-dd4e-433c-b7d8-1567f5710d69)
4. In the Filters form, provide values for the **Field**, **Operator**, and if applicable, value(s).
   * Run the unit tests to ensure they pass with the added filter(s).
   * If the values(s) field takes in an array, see the [Inputting array values](#inputting-array-values) instructions below.\
     ![Above the "Filters" section is the text "When the following conditions are true:" — the filter in progress has a Field value of "p\_any\_aws\_account\_ids," an Operator value of "contains" and an empty String field.](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2FG0ieUXnbEBWoXjY7kgoS%2Fimage.png?alt=media\&token=93045c23-236d-4fb2-b8eb-086b9ae4f933)
5. In the upper-right corner of the page, click **Update** to save your changes.

### Inputting array values

If the Rule Filter operator you've selected requires the value field to take in an array (such as the `is in` operator), you'll input the array values in a modal that pops up when you click into the value field.

To add values to an array:

1. After selecting a **Field** and **Operator** for your Filter, click into the values field.

   <figure><img src="https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2FW6mJ5v5Rc9XzB1258qfs%2FScreenshot%202023-03-21%20at%203.09.29%20PM.png?alt=media&#x26;token=23e5826f-bc32-4158-8d43-f57551218f82" alt="In the Filters section, Field, Operator and List inputs are shown. Field has an &#x22;id&#x22; value, Operator has an &#x22;is in&#x22; value, and List doesn&#x27;t yet have a value, but the field is circled."><figcaption></figcaption></figure>

   * This will open the array input modal.
2. In the modal, enter the array value(s) in the input field.
   * If your input is comma-delimited, check the **Values entered above are comma-delimited** checkbox.
     * When this field is checked, the text inputted into the values field will be separated (using a comma delimiter) into multiple values.  For example, entering "User 1,User 2,User 3" will result in three values added.

       <img src="https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2FrHZAV5mTzEY6FYeT4yvb%2Fimage.png?alt=media&#x26;token=05213608-9c3d-4658-8c73-4f35b514a662" alt="The array input modal says &#x22;Enter a list of strings...&#x22; at the top. It has an input textfield, and a checkbox that says &#x22;Values entered above are comma-delimited,&#x22; which is checked. Three values have been entered: User 3, User 2, and User 1." data-size="original">
   * If your input is not comma-delimited, leave **Values entered above are comma-delimited** unchecked.
     * When this field is unchecked, you can add values that contain commas one at a time. For example, entering "1,000" will add just one value.\
       ![The array input modal says "Enter a list of strings..." at the top. It has an input textfield, and a checkbox that says "Values entered above are comma-delimited," which is unchecked. One value has been entered: 1,000](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2FSj1eJBeUwFo9wjtnYx59%2Fimage.png?alt=media\&token=ee92d584-668f-494a-bf4a-38dde0cfe331)
3. Click **Add**.
4. Repeat steps 2-3 as needed, until all values have been added to the array.
5. Click **Apply**.

### Working with failed unit tests with filters

For [Panther-managed](https://docs.panther.com/~/changes/15ann7vKLltCCAGHtdQr/detections/panther-managed) rules with filters, you currently cannot add or edit unit tests. You cannot save a rule if the unit test does not pass.&#x20;

If a unit test fails, take the following steps:

1. Clone the Panther-managed rule.
2. Add your filter(s) to the cloned rule.
3. Edit the unit tests for the cloned rule so that they pass.

## Rule filter reference

Refer to the below operators and value types when building out your filters.

### Supported operators

<table><thead><tr><th width="154">Operation</th><th>Usage guidelines</th><th width="210">Supported field types</th><th>Examples</th></tr></thead><tbody><tr><td>is / is not</td><td>Valid for a single value. Results include only events where the field matches/ does not match the value in the filter.</td><td>string, ip, bool, int</td><td>username is “root”</td></tr><tr><td>is in / is not in</td><td>Valid for multiple values. Results include only events where the field matches/does not match an entry in the list of values in the filter.</td><td>string, int</td><td><p>username is in [ “root”, “admin” ]<br></p><p>port is in [25, 553]</p></td></tr><tr><td>is empty</td><td>Valid for an event where the field's value is not specified. The operator tests only for the absence of data.</td><td>string, int array, ip array, float array, bool array, string array</td><td>errors_list is empty</td></tr><tr><td>is not empty</td><td>Valid for an event where the field's value is specified. The operator tests only for the presence of data.</td><td>string, int array, ip array, float array, bool array, string array</td><td>errors_list is not empty</td></tr><tr><td>contains</td><td>Valid for an event that contains a specific single value or multiple values. Results include only events where at least one of the values is in the filter.</td><td>string, int array, ip array, bool array, string array</td><td><p>domain contains “.google.com”<br></p><p>p_any_port contains 22</p></td></tr><tr><td>does not contain</td><td>Valid for events that contain a specific single value or multiple values. Results include only events that do not contain any of the values in the filter.</td><td>string, int array, ip array, bool array, string array</td><td><p>domain !contains “.google.com”<br></p><p>p_any_port !contains 22</p></td></tr><tr><td>starts with</td><td>Valid for events that begin with a value.</td><td>string</td><td>role starts with “admin_”</td></tr><tr><td>ends with</td><td>Valid for events that end with a value.</td><td>string</td><td>domain ends with “.cc”</td></tr><tr><td>is greater than</td><td>Valid for a single value. Results include only events where the field is greater than the value in the filter.</td><td>int, float</td><td>port > 1023</td></tr><tr><td>is less than</td><td>Valid for a single value. Results include only events where the field is less than the value in the filter.</td><td>int, float</td><td>port &#x3C; 1024</td></tr><tr><td>is greater than or equal</td><td>Valid for a single value. Results include only events where the field is greater than or equal to the value in the filter.</td><td>int</td><td>count ≥ 1</td></tr><tr><td>is less than or equal</td><td>Valid for a single value. Results include only events where the field is less than or equal to the value in the filter.</td><td>int</td><td>count ≤ 100</td></tr><tr><td>is private</td><td>Valid for private IPs</td><td>IP</td><td>dst_ip is_private</td></tr><tr><td>is public</td><td>Valid for public IPs</td><td>IP</td><td>src_ip is_public</td></tr><tr><td>is in CIDR / is not in CIDR</td><td>Valid for addresses within a CIDR (Classless Inter-Domain Routing) block. Results include only events where the field is/is not in the CIDR block in the filter.</td><td>IP</td><td>src_ip in_cidr 192.168.0.0/16</td></tr><tr><td>does not contain IP in CIDR</td><td>Valid for an array of IPs that does not contain any IP address within a CIDR block. Results include only events where the field does not contain any IP address within the CIDR block in the filter.</td><td>ip array</td><td><p>p_any_ip_address !contains_ip 8.8.0.0/16<br></p><p>p_any_ip_address !contains_ip 1.1.1.1/32</p></td></tr><tr><td>contains IP in CIDR</td><td>Valid for an array of IPs containing any IP address within a CIDR block. Results include only events where the field contains at least one IP address within the CIDR block in the filter.</td><td>ip array</td><td><p>p_any_ip_address contains_ip 8.8.0.0/16<br></p><p>p_any_ip_address contains_ip 1.1.1.1/32</p></td></tr></tbody></table>

### Supported value types

<table><thead><tr><th width="153">Value types</th><th>Description</th></tr></thead><tbody><tr><td><code>string</code></td><td>A string value</td></tr><tr><td><code>int</code></td><td>A 32-bit integer number in the range <code>-2147483648</code>, <code>2147483647</code></td></tr><tr><td><code>float</code></td><td>A 64-bit floating point number</td></tr><tr><td><code>boolean</code></td><td>A boolean value <code>true</code> / <code>false</code></td></tr><tr><td><code>array</code></td><td>A JSON array where each element is of the same type</td></tr><tr><td><code>ip</code></td><td>A single valid IPv4 or IPv6 address</td></tr><tr><td><code>CIDR</code></td><td>A classless inter-domain routing block</td></tr></tbody></table>