Microsoft Sentinel (formerly aka Azure Sentinel) has a feature that allows you to create and manage custom Threat Intelligence (TI) indicators (aka IoC – Indicators of Compromise).
There are requests from avid readers asking AzSec to write something about Microsoft Sentinel REST API for Threat Intelligence. To give back to the community as a thanksgiving gift, this article is going to share with you the latest script for creating a new TI indicator in Azure Sentinel.
As of this article, Microsoft hasn’t yet updated this page to add Microsoft Sentinel Threat Intelligence REST API.
Use Case
There are several use cases why you need to understand and work with TI REST API. One of the most common use cases is to integrate with 3rd TI system. Another use case is to create SOAR automation to work with Microsoft Defender for Cloud alert – automatically add source of attack to Microsoft Sentinel TI indicator list (stay tuned for another article of the whole implementation guidance in https://azsec.azurewebsites.net/ in the near future).
Microsoft Sentinel API – Threat Intelligence
Get all indicators
To get all TI indicators in Azure Sentinel you can call the following REST API
$accessToken = Get-AzAccessToken -ResourceTypeName "ResourceManager"
$authHeader = @{
'Content-Type' = 'application/json'
'Authorization' = 'Bearer ' + $accessToken.Token
}
$uri = "https://management.azure.com" + $workspaceId `
+ "/providers/Microsoft.SecurityInsights/ThreatIntelligence/main/indicators" `
+ "?api-version=2021-04-01"
$response = Invoke-RestMethod -Uri $uri `
-Method Get `
-Headers $authHeader
$indicators = $response.value
- WorkspaceId is the Id of the Log Analytics workspace that Microsoft Sentinel connects to.
You can refer to this script to test this API.
Get an indicator by Id
The API to get an indicator by Id (aka GUID name) is slightly different.
$uri = "https://management.azure.com" + $workspaceId `
+ "/providers/Microsoft.SecurityInsights/ThreatIntelligence/" `
+ $IndicatorName `
+ "?api-version=2021-04-01"
- WorkspaceId is the Id of the Log Analytics workspace that Azure Sentinel connects to.
- IndicatorName is the name of the indicator. It is a GUID
You can refer to this script to test this API.
Create an indicator
To create an indicator you need to understand the REST API and what request body the API accepts. Below is the sample request body:
{
"name": "67fc4ca2-9170-4f49-8844-96fd34a3bef4",
"kind": "indicator",
"properties": {
"source": "Azure Sentinel",
"patternType": "ipv4-addr",
"description": "Bad IP from country X",
"validFrom": "2021-11-27T00:00:00Z",
"revoked": "false",
"confidence": 80,
"validUntil": "2022-11-27T00:00:00Z",
"threatTypes": [
"attribution",
"compromised"
],
"pattern": "[ipv4-addr:value = '195.133.20.11']",
"createdByRef": "azsec",
"displayName": "ip-0001-195.133.20.11"
}
}
The Uri supported is as follows:
$uri = "https://management.azure.com" + $workspaceId `
+ "/providers/Microsoft.SecurityInsights/ThreatIntelligence/main/createIndicator" `
+ "?api-version=2021-04-01"
Notice the API name is /main/createIndicator .
You can use this script to create a new custom indicator in Microsoft Sentinel Threat Indicator .
.\New-AzThreatIntelligenceIndicator.ps1 -WorkspaceRg "azsec-corporate-rg" `
-WorkspaceName "azsec-shared-workspace" `
-IndicatorType "ipv4-addr" `
-Pattern "ipv4-addr:value = '195.133.20.11'" `
-IndicatorDisplayName "ip-0001-195.133.20.11" `
-IndicatorDescription "Bad IP from country X" `
-ThreatType "attribution","compromised" `
-IsRevoked "false" `
-Confidence 80 `
-ValidFrom "2021-11-27T00:00:00Z" `
-ValidUntil "2022-11-27T00:00:00Z" `
-CreatedBy "azsec"
The script has well documented by itself to give you the idea of values Threat Indicator API support, for example, the pattern:
| Type | Pattern | Sample |
|---|---|---|
| url | url:value | url:value = 'http://contoso.com' |
| ipv4-addr | ipv4-addr:value | ipv4-addr:value = '195.133.20.78' |
| ipv6-addr | ipv6-addr:value | ipv6-addr:value = 'FE80:0202:B3FF:FE1E:8329' |
| file | file:hashes. | 'SHA-256' = '279D7A3C1CCA7D3C786154ACB40XXXXXXX7' |
| domain-name | domain-name:value | domain-name:value = 'sampledomain.com' |
Delete an indicator
The Deletion API is pretty much similar to the Get one. The only thing you need to change is the request method. Deletion API accepts Delete method.
$uri = "https://management.azure.com" + $workspaceId `
+ "/providers/Microsoft.SecurityInsights/ThreatIntelligence/" `
+ $IndicatorName `
+ "?api-version=2021-04-01"
$response = Invoke-RestMethod -Uri $uri `
-Method Delete `
-Headers $authHeader
You can use this script to test.
If you have any feedback, please feel free to leave a comment in the Comment box or create a new GitHub issue here
Observations:
– API above to list all TI shows only 100 entries. To show more there is need to use $top in the api call. Unfortunately for more than 200k-300k entries api shows timeout
– filtering in TI’s api calls , for instance: $filter=source eq ”xxx” is not working
Thanks Zak very much for your sharing.
I didn’t have an environment to test with thousands of indicators. Very much appreciated your feedback!