Help CenterTable of Contents
Note: Although this document utilizes Microsoft Sentinel’s API, the bearer token functionality in Threatlocker Detect can be used for any REST API that implements OAuth 2.0.
This document will demonstrate the process for using ThreatLocker Detect to call a rest API for Microsoft Sentinel.
To start, we assume a proper Microsoft Sentinel setup. You can consult the following article from Microsoft for assistance:
Quickstart: Onboard to Microsoft Sentinel | Microsoft Learn
Some Highlights from Microsoft's documentation are:
Prerequisites
-
Active Azure Subscription.
-
Log Analytics workspace.
-
More details on prerequisites can be found here: Prerequisites for deploying Microsoft Sentinel | Microsoft Learn
Permissions
-
To enable Microsoft Sentinel, you need contributor permissions to the subscription in which the Microsoft Sentinel workspace resides.
-
To use Microsoft Sentinel, you need either Microsoft Sentinel Contributor or Microsoft Sentinel Reader permissions on the resource group that the workspace belongs to.
-
To install or manage solutions in the content hub, you need the Microsoft Sentinel Contributor role on the resource group that the workspace belongs to.
Next, consult the Microsoft documentation here to construct the API URL:
Logs Ingestion API in Azure Monitor - Azure Monitor | Microsoft Learn
This Microsoft documentation lists the Header details and format of the JSON Body as shown below:
|
Header |
Required? |
Description |
|
Authorization |
Yes |
Bearer token obtained through the client credentials flow. Use the token audience value for your cloud: |
|
Content-Type |
Yes |
application/json |
|
Content-Encoding |
No |
gzip |
|
x-ms-client-request-id |
No |
String-formatted GUID. This is a request ID that can be used by Microsoft for any troubleshooting purposes. |
An Example Body JSON as provided by Microsoft:
[
{
"TimeGenerated": "2023-11-14 15:10:02",
"Column01": "Value01",
"Column02": "Value02"
}
]
Constructing the API URL for the Detect Policy Action
First, we want to obtain the format for the URL that this api call will use. For example:
{Endpoint}/dataCollectionRules/{DCR Immutable ID}/streams/{Stream Name}?api-version=2023-01-01
-
The endpoint variable is the logs ingestion URL from the Overview page of your Data Collection Endpoint (DCE). For example, in our test tenant, it appeared in the following format:
https://{DCE Name}-xl7k.eastus-1.ingest.monitor.azure.com
- The DCR Immutable ID can be found in your Data Collection Rule (DCR) overview page. Ours followed the format of {dcr-GUID}.
-
The Stream Name variable is also found on the DCR overview page, but you must select 'JSON view' and scroll down to see it. It is called “streams” and is surrounded by square brackets [ ] and quotes.
Obtaining a Bearer Token for Authorization
Additionally, you will need a bearer token for authorization. To obtain this, you will need an entirely new rest API call. For this, please consult the Microsoft documentation below:
The items you will need to make a call for a bearer token successfully are:
-
Tenant: The Tenant ID is found in the overview page of your Tenant's Microsoft Entra Admin Center page. This will be placed in the URL we call:
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
-
Client_id: This is the application ID, which can be found in the Microsoft Entra Admin Center under Applications > App registrations and selecting the overview page for your app registration.
-
Scope: This is the URI of the resource you will call with the token with .default added to the end. For posting logs, it would be the following:
https://monitor.azure.com/.default
For deleting logs, it would be the following:
-
client_secret: This is the client secret that can be added to an app registration from the Certificates and secrets portion of the App registration found in the Microsoft Entra Admin Center. Please note that the secret can only be viewed during creation, so if you forget it, you must recreate it. This process is detailed in step 4 here: Tutorial: Send data to Azure Monitor Logs with Logs ingestion API (Azure portal) - Azure Monitor | Microsoft Learn
-
Grant_type: This must be set to 'client_credentials' for use with an app secret.
At this point, all the information needed to make the two API calls required to post log information to Microsoft Sentinel is collected.
IMPORTANT: It is highly recommended that the calls be tested before using them in ThreatLocker Detect with an API application such as Postman or Talend. To do so, follow the instructions below:
-
Send a post call to https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token with an application/x-www-form-urlencoded body containing the following four variables: client_id, client_secret, scope, and grant_type. This should return a response of 200 with the bearer token in the body.
-
Per the OAuth 2.0 specification, the returned string should be placed in the authorization parameter of the header of our next API POST call, preceded by the work Bearer and a space.
-
The body of this call will be the custom schema of your custom table in the Log Analytics workspace. It must also be surrounded by square brackets [ ]. If all goes well, you should receive a 204 response with no further content.
Unfortunately, this does not mean it worked. You must check the Log Analytic workspace to see if the log was processed. You can either navigate to the Log Analytic workspace or check the entry circled below from the Microsoft Sentinel Overview page.
This should bring up a query showing recent log entries, for example:
Once we are sure our API calls are working as expected, we can build the ThreatLocker Detect Policy. The following is an example:
Note: The text here needs to be exact, including newline characters, or it will fail.
The second action is an alert to assist with debugging. This is especially true if you are passing variables into the bodies of the calls.
Save and deploy your policies, activate the condition, and you should see logs in your Log Analytics workspace. Please note that there may be a slight delay of about 30 seconds.
In addition, if you set up the second action, you will see the alert in the Response Center.
