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.

Important

Microsoft Sentinel is now generally available within the Microsoft unified security operations platform in the Microsoft Defender portal. For more information, see Microsoft Sentinel in the Microsoft Defender portal.

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.

    Screenshot that shows how to use watchlists in queries.

  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.

    Screenshot that shows queries with watchlist fields.

    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.

    Screenshot of queries against watchlist as lookup.

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. Screenshot of four items in a CSV file that's used for the watchlist.

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

    Screenshot that shows the query returns the four items from the watchlist.

    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.

    Screenshot that shows how to use watchlists in analytics rules.

  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.

    Screenshot that shows a list of watchlists.

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: