Azure Sentinel Threat Intelligence API

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:

TypePatternSample
urlurl:value url:value = 'http://contoso.com'
ipv4-addripv4-addr:valueipv4-addr:value = '195.133.20.78'
ipv6-addripv6-addr:value ipv6-addr:value = 'FE80:0202:B3FF:FE1E:8329'
file file:hashes.'SHA-256' = '279D7A3C1CCA7D3C786154ACB40XXXXXXX7'
domain-namedomain-name:valuedomain-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

This entry was posted in Secure Development, Security Automation and tagged , , . Bookmark the permalink.

2 Responses to Azure Sentinel Threat Intelligence API

  1. Zak says:

    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

    • azsec says:

      Thanks Zak very much for your sharing.

      I didn’t have an environment to test with thousands of indicators. Very much appreciated your feedback!

Leave a Reply

Your email address will not be published.