Custom Lists

The custom lists feature allows you to store and reuse the data from one playbook in other playbooks or batches. Each custom list is a table that is defined at the organization level and automatically made available to all the users in your organization.

As an example, suppose you have a list of suspicious IP addresses. If you create a custom list containing the IP addresses, you can later reopen the custom list in a playbook and check whether you find any of those addresses.

Add a Custom List

1. Select My Library > Custom Lists.

2. Click New.

3. Enter a name to identify the list. The name must be unique across all of the custom lists for your organization.

4. For Overflow, select the action to take if the list exceeds the maximum size of 100000 rows. The options are to delete the oldest entries to make room for new entries or to display an error message.

5. To ignore duplicate rows, select Deduplicate.

6. Enter a name for the first column in the custom list and select a data type for the data to display in the column.

7. To set up additional list columns, click +Add More Columns

1. Click Save.

The list is added to the My Library > Custom Lists page. For a description of actions on this page, see Manage Content in your Library. For information on sharing custom lists with other users and groups, see Share Content from your Library.

Using Custom Lists in Playbooks

The example in this section shows how to use custom lists to identify suspicious IP addresses in a playbook.

Start with a Custom List Definition

First, set up a custom list. Add a string column that can be used for the IP addresses.

Example custom list:
List Name: Suspect IPs
Overflow: Delete Oldest
Deduplication: On
Schema: ColumnA[String] ColumnB[String]
One of the schema columns will be used for the IP address.

Create a Playbook that Uses the Custom List

Next, define a playbook that uses the custom list. The following playbook uses the appendToList operation to extract IP addresses from an input table to populate the custom list. The example is in Advanced Mode.

The ‘pan traffic’ event type brings in traffic from a Palo Alto Networks device. The traffic includes a ‘client_ip’ address column. (It also has an ‘action’ column that we’ll include in the custom list.)

‘parent-node’ performs any initial processing of the input data. In the following example, the ‘client_ip’ and ‘action’ columns from the input data are renamed so they correspond exactly to columns in the custom list schema. The number of rows is limited to 5 for the purposes of the example.

You must rename the columns to match the custom list or an error is returned when you attempt to perform an operation on the custom list.

The ‘appendtolist’ step takes input from ‘parent_node’ to generate output for the Suspect IPs custom list. The input table had 5 rows, but because deduplication was set for the custom list, only two unique entries are shown in the output.

You now have a custom list with entries for two suspicious IP addresses.

Load the Custom List in Another Playbook

To load the custom list in another playbook, use the loadList operator. When you load a list, it becomes the data source for the current step and any child steps, and there is no longer a line connecting the current step with the previous parent step.

You can use a custom list multiple times in a playbook, for example, to load a list and later append to it.

Replace a List

To replace the contents of a custom list with the results of a computation, use the replaceList operator.

For example, the following computation replaces contents of the ‘Suspect IPs’ custom list with the results of the ‘new_output_for_list’ computation, which used this query to change the output of the custom list:

select '172.2.3.4' as ColumnA, 'none' as ColumnB from pan_traffic limit 2

For the replaceList operation to work, the columns in the parent step table must correspond exactly to the columns in ‘Suspect IPs’. The operator takes the parent step and custom list name as arguments.

Selectively Delete Rows from a Custom List

To delete rows from a custom list, use the selectivelyDeleteFromList operator. The operator runs a query on a table and deletes the rows that match the query.

selectivelyDeleteFromList(name, filter, table)

name is the name of the custom list.
filter is an SQL expression that filters the list.
table is the parent step table. The parent table is optional. It is not needed if the filter doesn’t depend on the table.

The following example takes the output from the appendtolist_operation step mentioned earlier and deletes any rows that contain the string ‘none’.

List Definitions are Exported Along with Playbooks

When a playbook is exported, the definitions of the custom lists referenced in the playbook will also be exported alongside the playbook. In this case, the export will be a ZIP file.
When the playbook is imported to another Devo SOAR deployment, the lists referenced in it will be created to the same schema. The lists will initially be empty until some playbooks populate them with data.