Watchlists in Microsoft Sentinel

Watchlists in Microsoft Sentinel help security analysts efficiently correlate and enrich event data. They give you a flexible way to manage reference data, like lists of high-value assets or terminated employees. Integrate watchlists into your detection rules, threat hunting, and response workflows to reduce alert fatigue and respond to threats faster. This article explains how to use watchlists in Microsoft Sentinel, outlines key scenarios and limitations, and gives guidance on creating and querying watchlists to enhance your security operations.

Use watchlists in your search, detection rules, threat hunting, and response playbooks. Watchlists are stored in your Microsoft Sentinel workspace in the Watchlist table as name-value pairs. They're cached for optimal query performance and low latency.

When to use watchlists

Use watchlists in these scenarios:

• Investigate threats and respond to incidents quickly by importing IP addresses, file hashes, and other data from CSV files. After you import the data, use watchlist name-value pairs for joins and filters in alert rules, threat hunting, workbooks, notebooks, and queries.

• Import business data as a watchlist. For example, import user lists with privileged system access or lists of terminated employees. Then, use the watchlist to create allowlists and blocklists to detect or prevent those users from signing in to the network.

• Reduce alert fatigue. Create allowlists to suppress alerts from a group of users, like users from authorized IP addresses who perform tasks that would normally trigger the alert. Prevent benign events from becoming alerts.

• Enrich event data. Use watchlists to add name-value combinations from external data sources to your event data.

Watchlist limitations

We recommend reviewing the following limitations before creating watchlists:

Microsoft Sentinel watchlist creation methods

Use one of the following methods to create watchlists in Microsoft Sentinel:

• Uploading a file from a local folder or from your Azure Storage account.

• Download a watchlist template from Microsoft Sentinel, add your data, and then upload the file when you create the watchlist.

To create a watchlist from a large file (up to 500 MB), upload the file to your Azure Storage account. Create a shared access signature (SAS) URL so Microsoft Sentinel can retrieve the watchlist data. A SAS URL includes both the resource URI and the SAS token for a resource, like a CSV file in your storage account. Add the watchlist to your workspace in Microsoft Sentinel.

For more information, see:

• Create watchlists in Microsoft Sentinel
• Built-in watchlist schemas
• Azure Storage SAS token

Watchlists in queries for searches and detection rules

To correlate your watchlist data with other Microsoft Sentinel data, use Kusto tabular operators such as join and lookup with the Watchlist table. Microsoft Sentinel creates the following functions in the workspace to help reference and query your watchlists:

• _GetWatchlistAlias - returns the aliases of all your watchlists
• _GetWatchlist - queries the name-value pairs of the specified watchlist

When you create a watchlist, you define the SearchKey. The search key is the name of a column in your watchlist that you expect to use as a join with other data or as a frequent object of searches. For example, suppose you have a server watchlist that contains country/region names and their respective two-letter country codes. You expect to use the country codes often for searches or joins. So you use the country code column as the search key.

Heartbeat
| lookup kind=leftouter _GetWatchlist('mywatchlist') 
  on $left.RemoteIPCountry == $right.SearchKey

Let's look at some other example queries.

Suppose you want to use a watchlist in an analytics rule. You create a watchlist called ipwatchlist with columns for IPAddress and Location. You set IPAddress as the SearchKey.

To include only events from IP addresses in the watchlist, you might use a query where watchlist is used as a variable or inline.

This example query uses the watchlist as a variable:

  //Watchlist as a variable
  let watchlist = (_GetWatchlist('ipwatchlist') | project IPAddress);
  Heartbeat
  | where ComputerIP in (watchlist)

This example query uses the watchlist inline with the query and the search key defined for the watchlist.

  //Watchlist inline with the query
  //Use SearchKey for the best performance
  Heartbeat
  | where ComputerIP in ( 
      (_GetWatchlist('ipwatchlist')
      | project SearchKey)
  )

For more information, see Build queries and detection rules with watchlists in Microsoft Sentinel and the following articles in the Kusto documentation:

• where operator
• project operator
• lookup operator
• in operator
• let statement

For more information on KQL, see Kusto Query Language (KQL) overview.

Other resources:

• KQL quick reference
• Kusto Query Language learning resources

Related content

For more information, see:

• Create watchlists
• Build queries and detection rules with watchlists
• Manage watchlists