Create watchlists in Microsoft Sentinel

• Applies to:

  Microsoft Sentinel in the Azure portal, Microsoft Sentinel in the Microsoft Defender portal

Watchlists in Microsoft Sentinel allow you to correlate data from a data source you provide with the events in your Microsoft Sentinel environment. For example, you might create a watchlist with a list of high value assets, terminated employees, or service accounts in your environment.

Upload a watchlist file from a local folder or from your Azure Storage account. To create a watchlist file, you have the option to download one of the watchlist templates from Microsoft Sentinel to populate with your data. Then upload that file when you create the watchlist in Microsoft Sentinel.

Local file uploads are currently limited to files of up to 3.8 MB in size. A file that's over 3.8 MB in size and up to 500 MB is considered a large watchlist. Upload the file to an Azure Storage account. Before you create a watchlist, review the limitations of watchlists.

Important

The features for watchlist templates and the ability to create a watchlist from a file in Azure Storage are currently in PREVIEW. The Azure Preview Supplemental Terms include additional legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

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.

Upload a watchlist from a local folder

You have two ways to upload a CSV file from your local machine to create a watchlist.

• For a watchlist file you created without a watchlist template: Select Add new and enter the required information.
• For a watchlist file created from a template downloaded from Microsoft Sentinel: Go to the watchlist Templates (Preview) tab. Select the option Create from template. Azure pre-populates the name, description, and watchlist alias for you.

Upload watchlist from a file you created

If you didn't use a watchlist template to create your file,

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 + New.

   Azure portal

   

   Defender portal

   

3. On the General page, provide the name, description, and alias for the watchlist.

   

4. Select Next: Source.

5. Use the information in the following table to upload your watchlist data.

   Field	Description
   Select a type for the dataset	CSV file with a header (.csv)
   Number of lines before row with headings	Enter the number of lines before the header row that's in your data file.
   Upload file	Either drag and drop your data file, or select Browse for files and select the file to upload.
   SearchKey	Enter the name of a column in your watchlist that you expect to use as a join with other data or a frequent object of searches. For example, if your server watchlist contains country names and their respective two-letter country codes, and you expect to use the country codes often for search or joins, use the Code column as the SearchKey.

   Note

   If your CSV file is greater than 3.8 MB, you need to use the instructions for Create a large watchlist from file in Azure Storage.

6. Select Next: Review and Create.

   

7. Review the information, verify that it's correct, wait for the Validation passed message, and then select Create.

   

   A notification appears once the watchlist is created.

It might take several minutes for the watchlist to be created and the new data to be available in queries.

Upload watchlist created from a template (Preview)

To create the watchlist from a template you populated,

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 tab Templates (Preview).

3. Select the appropriate template from the list to view details of the template in the right pane.

4. Select Create from template.

   

5. On the General tab, notice that the Name, Description, and Watchlist Alias fields are all read-only.

6. On the Source tab, select Browse for files and select the file you created from the template.

7. Select Next: Review and Create > Create.

8. Watch for an Azure notification to appear when the watchlist is created.

It might take several minutes for the watchlist to be created and the new data to be available in queries.

Create a large watchlist from file in Azure Storage (preview)

If you have a large watchlist up to 500 MB in size, upload your watchlist file to your Azure Storage account. Then create a shared access signature URL for Microsoft Sentinel to retrieve the watchlist data. A shared access signature URL is an URI that contains both the resource URI and shared access signature token of a resource like a csv file in your storage account. Finally, add the watchlist to your workspace in Microsoft Sentinel.

For more information about shared access signatures, see Azure Storage shared access signature token.

Step 1: Upload a watchlist file to Azure Storage

To upload a large watchlist file to your Azure Storage account, use AzCopy or the Azure portal.

1. If you don't already have an Azure Storage account, create a storage account. The storage account can be in a different resource group or region from your workspace in Microsoft Sentinel.
2. Use either AzCopy or the Azure portal to upload your csv file with your watchlist data into the storage account.

Upload your file with AzCopy

Upload files and directories to Blob storage by using the AzCopy v10 command-line utility. To learn more, see Upload files to Azure Blob storage by using AzCopy.

1. If you don't already have a storage container, create one by running the following command.

   azcopy make 
   https://<storage-account-name>.<blob or dfs>.core.windows.net/<container-name>
   

2. Next, run the following command to upload the file.

   azcopy copy '<local-file-path>' 'https://<storage-account-name>.<blob or dfs>.core.windows.net/<container-name>/<blob-name>'
   

Upload your file in Azure portal

If you don't use AzCopy, upload your file by using the Azure portal. Go to your storage account in Azure portal to upload the csv file with your watchlist data.

1. If you don't already have an existing storage container, create a container. For the level of public access to the container, we recommend the default which is that the level is set to Private (no anonymous access).
2. Upload your csv file to the storage account by uploading a block blob.

Step 2: Create shared access signature URL

Create a shared access signature URL for Microsoft Sentinel to retrieve the watchlist data.

1. Follow the steps in Create SAS tokens for blobs in the Azure portal.
2. Set the shared access signature token expiry time to be at minimum 6 hours.
3. Keep the default value for Allowed IP addresses as blank.
4. Copy the value for Blob SAS URL.

Step 3: Add Azure to the CORS tab

Before using a SAS URI, add the Azure portal to the Cross Origin Resource Sharing (CORS).

1. Go to the storage account settings, Resource sharing page.
2. Select the Blob service tab.
3. Add https://*.portal.azure.net to the allowed origins table.
4. Select the appropriate Allowed methods of GET and OPTIONS.
5. Save the configuration.

For more information, see CORS support for Azure Storage.

Step 4: Add the watchlist to a workspace

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 + New.

   

3. On the General page, provide the name, description, and alias for the watchlist.

   

4. Select Next: Source.

5. Use the information in the following table to upload your watchlist data.

   Field	Description
   Source type	Azure Storage (preview)
   Select a type for the dataset	CSV file with a header (.csv)
   Number of lines before row with headings	Enter the number of lines before the header row that's in your data file.
   Blob SAS URL (Preview)	Paste in the shared access URL you created.
   SearchKey	Enter the name of a column in your watchlist that you expect to use as a join with other data or a frequent object of searches. For example, if your server watchlist contains country names and their respective two-letter country codes, and you expect to use the country codes often for search or joins, use the Code column as the SearchKey.

   After you enter all the information, your page will look similar to following image.

   

6. Select Next: Review and Create.

7. Review the information, verify that it's correct, wait for the Validation passed message.

8. Select Create.

It might take a while for a large watchlist to be created and the new data to be available in queries.

View watchlist status

View the status by selecting the watchlist in your workspace.

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. On the My Watchlists tab, select the watchlist.

3. On the details page, review the Status (Preview).

   

4. When the status is Succeeded, select View in Log Analytics to use the watchlist in a query. It might take several minutes for the watchlist to show in Log Analytics.

   

Download watchlist template (preview)

Download one of the watchlist templates from Microsoft Sentinel to populate with your data. Then upload that file when you create the watchlist in Microsoft Sentinel.

Each built-in watchlist template has its own set of data listed in the CSV file attached to the template. For more information, see Built-in watchlist schemas.

To download one of the watchlist templates,

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 tab Templates (Preview).

3. Select a template from the list to view details of the template in the right pane.

4. Select the ellipses ... at the end of the row.

5. Select Download Schema.

   

6. Populate your local version of the file and save it locally as a CSV file.

7. Follow the steps to upload watchlist created from a template (Preview).

Deleted and recreated watchlists in Log Analytics view

If you delete and recreate a watchlist, you might see both the deleted and recreated entries in Log Analytics within the five-minute SLA for data ingestion. If you see these entries together in Log Analytics for a longer period of time, submit a support ticket.

Related content

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

• Learn how to get visibility into your data and potential threats
• Get started detecting threats with Microsoft Sentinel
• Use workbooks to monitor your data.
• Manage watchlists
• Build queries and detection rules with watchlists