Build queries or detection rules with watchlists in Microsoft Sentinel

Query data in any table against data from a watchlist by treating the watchlist as a table for joins and lookups. 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 search query, write a Kusto query that uses the _GetWatchlist('watchlist-name') function and uses SearchKey as the key for your join.

1. For Microsoft Sentinel in the Azure portal, under Configuration, select Watchlist.
   For Microsoft Sentinel in the Defender portal, select Microsoft Sentinel > Configuration > 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

To use watchlists in analytics rules, create a rule using the _GetWatchlist('watchlist-name') function in the 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 image shows this last 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 list of watchlist aliases

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.

   

Related content

In this document, you learned how to use watchlists in Microsoft Sentinel to enrich data and improve investigations. To learn more about Microsoft Sentinel, see the following articles:

• Create watchlists
• Learn how to get visibility into your data and potential threats.
• Get started detecting threats with Microsoft Sentinel.
• Use workbooks to monitor your data.