Use filters in your playbook to specify a subset of artifacts before further processing

Create conditions in a Filter block to gather a subset of artifacts. Only the artifacts matching the specified condition are passed along to downstream blocks for processing. This is useful when you want to remove artifacts that are not needed in the flow if the playbook, or you need to separate artifacts because they require different blocks for processing. For example:

• If an IP address comes from North Korea or Turkey, you can block it.
• If an IP address comes from North America, you can perform an IP reputation lookup.
• If an IP address falls in the 192.168.10.* range, you can to grant access to the user.

Options in a condition aren't related to each other and you can perform multiple actions on an IP address. For example, both the second and third conditions in the example could be true, as an IP address in the 192.168.10.* range could both come from North America and be an internal user who was granted access. The filtered data set is given a named result in the format name="filter_1:condition_1" and passed to the next block for processing.

Create a Filter block in your playbook

To create a filter, perform the following tasks:

1. Drag and drop the half-circle icon attached to any existing block in the editor. Select a Filter block from the menu that appears.
2. Click the Select Parameter field and search for and select the parameter you want to filter on. Parameters are made available to the Filter block by upstream blocks. Click Enter to go to the next result or use the icons to navigate results. You can also expand or collapse the lists by using the icons.
3. (Optional) Create a custom datapath if the datapath you need isn't available. When you add a custom datapath, it is only available for the block you add it to. To see an example of a custom datapath, see Example: Add a custom datapath to a playbook block. To create a custom datapath, follow these steps:
   1. Hover over a datapath field title and click +.
   2. Enter the datapath name.
   3. Select either Key or List from the drop-down menu. Use Key to use one value, and use List to use a list of values. Using List adds a .* value to the datapath and it appears as <list_name [] > with datapaths nested below it in the datapath picker. To add more values to your List, click the + icon under the top value of the list.
   4. Click Save.
4. Click in the == field and select an operator for the filter.
5. Click the Select Value field and search for and select the value you want to match. See Example of creating a filter for an example of how these fields all work together.
6. (Optional) Click + Condition to create another matching condition for the filter. You can have a maximum of five conditions per Filter block. Each condition will have its own downstream path.
7. Click Done.

You can also configure Advanced settings for a Filter block. You can use the Case-sensitive check box to select if you want the conditions evaluation to be case-sensitive, or case-insensitive. The default is case-sensitive. For more information on other Advanced settings, see Advanced settings.

Additionally, you can click the Info tab to create a custom name for the block, add a description for the block, and add a tooltip to the block. See Use custom names.

Example of creating a filter

In the following example, you can create a filter to perform a geolocate ip action on a source IP address and block any IP addresses from North Korea.

1. Configure a geolocate ip Action block in the playbook editor. For more information on configuring an Action block, see Add an action block to your playbook.
2. Drag and drop the half-circle icon attached to the Action block in the editor. Select a Filter block from the menu that appears.
3. Click the Select Parameter field and select geolocate_ip_1.
4. Select geolocate_ip_1:action_result_data.*.country_name. Leave == as the operator, and type North Korea in the Select Value field.

Example of creating a filter with multiple conditions

You can create multiple rows within a condition or multiple conditions.

1. Click + Condition to create a second set of filter conditions, which also adds a second output point on the Filter block.
2. In the Select Parameter field, select artifacts and then label.
3. Select == as the operator, and enter Test in the Select Value field.

Multiple conditions within a filter block are independent of each other. The results of Condition 1 don't play into the set of inputs for Condition 2. In this example, Condition 1 uses the result from the geolocate ip action, while Condition 2 uses a property of the artifact. Each condition has its own color to make it easier to identify the separate downstream actions; green marks the path on Condition 1, and purple marks the path of Condition 2. If you want to edit the Condition 1 and 2 labels, click the pencil icon next to the label names.

Example of filter chaining

You can also chain multiple filter blocks together to obtain a more specific set of data.

For example, to filter out RFC1918 addresses (10.x.x.x, 172.16.x.x-172.31.x.x, and 192.168.x.x), and then perform a geolocate ip action on the remaining addresses, perform the following steps:

1. Drag and drop the half-circle icon attached to any existing block in the editor. Select a Filter block from the menu that appears.
2. In the Select Parameter field, select event > src_ip.
3. Enter 10.0.0.0/8 in the Select Value field.
4. Create a second filter for the 172.16.0.0/12 IP addresses. This filter uses the filtered results from the previous block.
5. Create a third filter for the 192.168.0.0/12 IP addresses. This filter uses the filtered results from the previous block.
6. Create the geolocate ip action block on the remaining IP addresses.

If a filter block eliminates all variables while filtering, the downstream action can't run.

Example of using a custom list in a filter

You can use custom lists in your Filter blocks to simplify checking against a fixed set of items. For example, instead of checking the source country of an IP address to see if it is North Korea, you can define a list of countries in a custom list, then check the IP address against all of the countries in the list. See Create custom lists for use in playbook comparisons for more information about how to create and maintain custom lists.

In this example, use a custom list named Banned Countries in a filter by performing the following tasks:

1. Configure a geolocate ip action in the playbook editor.
2. Add a Filter block.
3. Click the Select Parameter field and select geolocate_ip_1.
4. Select geolocate_ip_1:action_result_data.*.country_name.
5. Use "in" or "not in" as the operator.
6. Click in the Select Value field, select custom lists, then select Banned_Countries.

The country name of the source IP address is checked against the countries defined in the Banned Countries custom list.

The matching that occurs between artifact data and custom list items is exact matching and is case sensitive with no partial matches.