Manage Watchlists

Graylog provides seven built-in watchlists (IP, User, File Hash, Port, Domain, GeoLocation, and File) that flag matching values in your log messages and can be referenced in searches, dashboards, event definitions, and pipeline rules. You manage the entries in each watchlist and control how long they remain on the list. This article explains how to view watchlists, set a default expiry, add and remove entries, and use a watchlist as a query parameter.

Prerequisites

Before proceeding, ensure that the following prerequisites are met:

• You have a valid Graylog Security license.

• You have the watchlist:read permission to view watchlists, the watchlist:edit permission to add entries or change the default TTL, and the watchlist:delete permission to remove entries.

• You are familiar with the watchlist types, accepted values, and matching rules described in Watchlists.

View Watchlists

To view your watchlists and their entries:

1. Navigate to Security > Watchlists. The overview lists each watchlist type, description, current number of entries, and default TTL.

2. Click a watchlist name to open its detail page. The detail page lists the watchlist's entries in a table with a Value column and an Expires column. Entries that never expire show No expiry.

3. (Optional) Enter a value in the Search entries field to filter the list, or click a column heading to sort by value or expiry.

Set a Default TTL

The default TTL determines how long new entries remain on a watchlist when you add them without specifying their own TTL. Changing the default TTL does not change the expiry of existing entries.

To set a watchlist's default TTL, navigate to Security > Watchlists:

1. In the row of the watchlist you want to change, click the More dropdown menu and select Set default TTL.

2. Enter the TTL. Enter 0 if new entries should never expire by default.

3. Click Save.

Add Entries to a Watchlist

You can add one or multiple entries from the watchlist detail page.

To add entries, navigate to Security > Watchlists:

1. Click the name of the watchlist you want to add entries to.

2. Click Add entries.

3. In the Values field, enter the values to add, one per line or separated by commas.

4. (Optional) Change the TTL for this batch of entries. The field is prefilled with the watchlist's default TTL. Leave it unchanged to apply the default, or enter 0 to make these entries permanent.

5. Click Add entries.

Graylog reports how many entries were added and lists any rejected values with the reason for each rejection. Valid values are added even if other values in the batch are rejected.

Remove Entries From a Watchlist

To remove entries, navigate to Security > Watchlists:

1. Click the watchlist you want to remove entries from.

2. Remove the entries in one of the following ways:

   • To remove a single entry, click the More dropdown menu in the entry's row and select Delete.

   • To remove several entries, select their checkboxes, then select Bulk actions > Delete.

3. Confirm the deletion.

Add or Remove Values From Search Results

You can also add or remove individual values while you review search results. This works for the fields that Graylog checks against watchlists, such as source_ip, user_name, and destination_port. For the full list, see Watchlists.

To add or remove a value from a search result:

1. In the Search page, click a field value in a message.

2. Select Add to <Watchlist> or Remove from <Watchlist>, where <Watchlist> is the watchlist that matches the field type.

   The actions you see depend on your permissions and on whether the value is already on the watchlist.

You can also remove a value from the Found on watchlist section of a message's details. If an IP address matched through a CIDR range, removing it from the message details removes the entire range. Graylog asks you to confirm before it removes the range.

Use a Watchlist as a Query Parameter

A watchlist parameter inserts a watchlist's current entries into a query when it runs, so you can include or exclude watched values without updating the query.

If you upgraded from an earlier version, lookup table parameters that referenced the legacy watchlist lookup table with the ip, user, or hash key were converted to Watchlist parameters automatically. You do not need to recreate them.

Add a Watchlist Parameter to a Search or Dashboard

To add a watchlist parameter to a search or dashboard:

1. In the search or dashboard, open the parameter declaration.

2. Add a parameter and select Watchlist as its type.

   

3. Enter a name for the parameter.

4. Select the watchlist the parameter uses.

5. Save the parameter.

6. Reference the parameter on the right-hand side of a field query, in the format field:$parameter_name$.

For example, to find logins by users on the User Watchlist, enter the following query:

user_name:$watched_users$ AND action:login

To exclude watched values instead, negate the field query, for example NOT source_ip:$trusted_ips$.

Add a Watchlist Parameter to an Event Definition

To add a watchlist parameter to an event definition:

1. Navigate to Alerts > Event Definitions, and create or edit an event definition.

2. In the Filter & Aggregation step, add a query parameter and select Watchlist as the parameter type.

3. Select the watchlist the parameter uses.

4. Reference the parameter in the search query, in the format field:$parameter_name$.

5. Complete the remaining event definition steps and save.

Watchlist Parameter Limits

Keep the following limits in mind when you use watchlist parameters:

• A watchlist parameter expands to a maximum of 1,000 entries.

• Your search backend's indices.query.bool.max_clause_count and max_query_string_length limits still apply. A large expansion combined with a complex query can exceed them and cause the search to fail.

• If the watchlist is empty, or the referenced watchlist no longer exists, the parameter's default value is used.

• CIDR entries are inserted as literal text. They match as ranges only if the field is mapped as the ip type in the index set, for example through a custom field mapping or an index field type profile. If the field is mapped as any other type, such as keyword or text, a CIDR entry matches only its exact literal string, for example 10.0.0.0/8, so only exact address entries match individual addresses. For reliable range matching regardless of mapping, use the watchlist_contains() pipeline function instead.

Manage Watchlists With the REST API

You can also manage watchlists through the Graylog REST API. All endpoints require authentication and a valid Graylog Security license, and use the following base path: /api/plugins/org.graylog.plugins.watchlist/v2/watchlists

For example, to add two entries with a one-hour TTL to a watchlist, run the following command:

curl -u <username>:<password> -X POST -H 'Content-Type: application/json' \
  'https://<graylog-host>:9000/api/plugins/org.graylog.plugins.watchlist/v2/watchlists/<watchlist-id>/entries' \
  -d '{"values": ["10.20.30.40", "192.168.1.0/24"], "ttl_seconds": 3600}'

The response reports the number of entries added and lists any rejected values:

When you remove entries through the API, Graylog matches each value by its normalized form, so 10.20.30.40 and 010.020.030.040 remove the same entry. Removing an IP address that is covered only by a CIDR range does not remove the range, so the address continues to match. To clear the match, remove the range itself. This differs from removing a value in the message details view, which removes the entire range.

Troubleshooting and Common Issues

The following section outlines troubleshooting steps for common issues to assist you in resolving potential challenges you may encounter.

Further Reading

Explore the following additional resources and recommended readings to expand your knowledge on related topics:

• Watchlists

• Pipeline Functions

• Search Parameters

• Event Definitions