Build queries or detection rules with watchlists in Microsoft Sentinel

Correlate your watchlist data against any Microsoft Sentinel data with Kusto tabular operators such as join and lookup. 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 optimal query performance, use SearchKey as the key for joins in your queries.

Build queries with watchlists

To use a watchlist in a search query, write a Kusto Query Language (KQL) query that uses the _GetWatchlist('watchlist-name') function and uses SearchKey as the key for your join.

1. For Microsoft Sentinel in the Defender portal, select Microsoft Sentinel > Configuration > Watchlist. For Microsoft Sentinel in the Azure portal, under Configuration, select Watchlist.

2. Select the watchlist you want to use.

3. Select View in Logs.

   

4. Review the Results tab. The items in your watchlist are automatically extracted for your query.

   The example below shows the results of the extraction of the Name and IP Address fields. The SearchKey is shown as its own column.

   

   The timestamp on your queries will be ignored in both the query UI and in scheduled alerts.

5. Write a query that uses the _GetWatchlist('watchlist-name') function and uses SearchKey as the key for your join.

   For example, the following example query joins the RemoteIPCountry column in the Heartbeat table with the search key defined for the watchlist named mywatchlist.

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

   The following image shows the results of this example query in Log Analytics.

   

Create an analytics rule with a watchlist

The _GetWatchlist('watchlist-name') function returns the contents of a specified watchlist so you can reference watchlist data directly in a query. To use watchlists in analytics rules, create a rule that includes this function in the rule query.

1. Under Configuration, select Analytics.

2. Select Create and the type of rule you want to create.

3. On the General tab, enter the appropriate information.

4. On the Set rule logic tab, under Rule query use the _GetWatchlist('<watchlist>') function in the query.

   For example, let's say you have a watchlist named ipwatchlist that you created from a CSV file with the following values:

   IPAddress,Location
   10.0.100.11,Home
   172.16.107.23,Work
   10.0.150.39,Home
   172.20.32.117,Work

   The CSV file looks something like the following image.

   To use the _GetWatchlist function for this example, your query would be _GetWatchlist('ipwatchlist').

   

   In this example, we only include events from IP addresses in the watchlist:

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

   The following 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)
   )
   

   The following screenshot shows the inline _GetWatchlist('ipwatchlist') query used in the rule query.

   

5. Complete the rest of the tabs in the Analytics rule wizard.

Watchlists are refreshed in your workspace every 12 days, updating the TimeGenerated field. For more information, see Create custom analytics rules to detect threats.

View the list of watchlist aliases

A watchlist alias is the unique identifier used to reference a watchlist in queries and analytics rules. You might need to see a list of watchlist aliases to identify a watchlist to use in a query or analytics rule.

1. For Microsoft Sentinel in the Azure portal, under General, select Logs.
   In the Defender portal, select Investigation & response > Hunting > Advanced hunting.

2. On the New Query page, run the following query: _GetWatchlistAlias.

3. Review the list of aliases in the Results tab.

   

For more information about the Kusto operators and statements used in the examples on this page, see 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

To learn more about watchlists and Microsoft Sentinel, see the following articles:

• Create watchlists
• Visualize collected data.
• Detect threats with built-in analytics rules.
• Use workbooks to monitor your data.