Use Azure Sentinel watchlists

Important

The watchlists feature is currently in PREVIEW. See the Supplemental Terms of Use for Microsoft Azure Previews for additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

Azure Sentinel watchlists enable the collection of data from external data sources for correlation with the events in your Azure Sentinel environment. Once created, you can use watchlists in your search, detection rules, threat hunting, and response playbooks. Watchlists are stored in your Azure Sentinel workspace as name-value pairs and are cached for optimal query performance and low latency.

Common scenarios for using watchlists include:

  • Investigating threats and responding to incidents quickly with the rapid import of IP addresses, file hashes, and other data from CSV files. Once imported, you can use watchlist name-value pairs for joins and filters in alert rules, threat hunting, workbooks, notebooks, and general queries.

  • Importing business data as a watchlist. For example, import user lists with privileged system access, or terminated employees, and then use the watchlist to create allow and deny lists used to detect or prevent those users from logging in to the network.

  • Reducing alert fatigue. Create allow lists to suppress alerts from a group of users, such as users from authorized IP addresses that perform tasks that would normally trigger the alert, and prevent benign events from becoming alerts.

  • Enriching event data. Use watchlists to enrich your event data with name-value combinations derived from external data sources.

Create a new watchlist

  1. From the Azure portal, navigate to Azure Sentinel > Configuration > Watchlist and then select Add new.

    new watchlist

  2. On the General page, provide the name, description, and alias for the watchlist, and then select Next.

    watchlist general page

  3. On the Source page, select the dataset type, upload a file, and then select Next.

    watchlist source page

    Note

    File uploads are currently limited to files of up to 3.8 MB in size.

  4. Review the information, verify that it is correct, and then select Create.

    watchlist review page

    A notification appears once the watchlist is created.

    watchlist successful creation notification

Use watchlists in queries

  1. From the Azure portal, navigate to Azure Sentinel > Configuration > Watchlist, select the watchlist you want to use, and then select View in Log Analytics.

    use watchlists in queries

  2. The items in your watchlist are automatically extracted for your query, and will appear on the Results tab. The example below shows the results of the extraction of the ServerName and IpAddress fields.

    Note

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

    queries with watchlist fields

  3. You can query data in any table against data from a watchlist by treating the watchlist as a table for joins and lookups.

    Heartbeat
    | lookup kind=leftouter _GetWatchlist('IPlist') 
     on $left.ComputerIP == $right.IPAddress
    

    queries against watchlist as lookup

Use watchlists in analytics rules

To use watchlists in analytics rules, from the Azure portal, navigate to Azure Sentinel > Configuration > Analytics, and create a rule using the _GetWatchlist('<watchlist>') function in the query.

  1. In this example, create a watchlist called “ipwatchlist” with the following values:

    list of four items for watchlist

    create watchlist with four items

  2. Next, create the analytics rule. 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)
    
    //Watchlist inline with the query
    Heartbeat
    | where ComputerIP in ( 
        (_GetWatchlist('ipwatchlist')
        | project IPAddress)
    )
    

use watchlists in analytics rules

View list of watchlists aliases

To get a list of watchlist aliases, from the Azure portal, navigate to Azure Sentinel > General > Logs, and run the following query: _GetWatchlistAlias. You can see the list of aliases in the Results tab.

list watchlists

Next steps

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