Importar informações sobre ameaças para Microsoft Sentinel com a API de carregamento (Pré-visualização)

Importe informações sobre ameaças para utilizar no Microsoft Sentinel com a API de carregamento. Quer esteja a utilizar uma plataforma de informações sobre ameaças ou uma aplicação personalizada, utilize este documento como referência suplementar às instruções em Ligar o TIP à API de carregamento. A instalação do conector de dados não é necessária para ligar à API. As informações sobre ameaças que pode importar incluem indicadores de comprometimento e outros objetos de domínio STIX.

Structured Threat Information Expression (STIX) é uma linguagem para expressar ameaças cibernéticas e informações observáveis. O suporte melhorado para os seguintes objetos de domínio está incluído na API de carregamento:

• indicador
• padrão de ataque
• ator de ameaças
• identidade
• relação

Para obter mais informações, consulte Introdução ao STIX.

Chamar a API

Uma chamada para a API de carregamento tem cinco componentes:

1. O URI do pedido
2. Cabeçalho da mensagem de pedido HTTP
3. Corpo da mensagem de pedido HTTP
4. Opcionalmente, processe o cabeçalho da mensagem de resposta HTTP
5. Opcionalmente, processe o corpo da mensagem de resposta HTTP

Registar a aplicação cliente no Microsoft Entra ID

Para se autenticar no Microsoft Sentinel, o pedido à API de carregamento requer um token de acesso Microsoft Entra válido. Para obter mais informações sobre o registo de aplicações, veja Registar uma aplicação com o plataforma de identidades da Microsoft ou veja os passos básicos como parte da configuração da API de ligação de informações sobre ameaças com carregamento.

Esta API requer que a aplicação Microsoft Entra de chamadas seja concedida a função de contribuidor Microsoft Sentinel ao nível da área de trabalho.

Criar o pedido

Esta secção abrange os três primeiros dos cinco componentes abordados anteriormente. Primeiro, tem de adquirir o token de acesso do Microsoft Entra ID, que utiliza para montar o cabeçalho da mensagem de pedido.

Adquirir um token de acesso

Adquirir um token de acesso Microsoft Entra com a autenticação OAuth 2.0. V1.0 e V2.0 são tokens válidos aceites pela API.

A versão do token (v1.0 ou v2.0) recebida é determinada pela accessTokenAcceptedVersion propriedade no manifesto da aplicação da API que a sua aplicação está a chamar. Se accessTokenAcceptedVersion estiver definido como 1, a aplicação receberá um token v1.0.

Utilize a Biblioteca de Autenticação da Microsoft (MSAL) para adquirir um token de acesso v1.0 ou v2.0. Utilize o token de acesso para criar o cabeçalho de autorização que contém o token de portador.

Por exemplo, um pedido para a API de carregamento utiliza os seguintes elementos para obter um token de acesso e criar o cabeçalho de autorização, que é utilizado em cada pedido:

• PUBLICAR https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token

Cabeçalhos para utilizar a Aplicação Microsoft Entra:

• grant_type: "client_credentials"
• client_id: {Client ID of Microsoft Entra App}
• client_secret ou client_certificate: {secrets of the Microsoft Entra App}
• âmbito: "https://management.azure.com/.default"

Se accessTokenAcceptedVersion no manifesto da aplicação estiver definido como 1, a aplicação recebe um token de acesso v1.0, apesar de estar a chamar o ponto final do token v2.

O valor de recurso/âmbito é a audiência do token. Esta API só aceita as seguintes audiências:

• https://management.core.windows.net/
• https://management.core.windows.net
• https://management.azure.com/
• https://management.azure.com

Reunir a mensagem de pedido

URI do Pedido

Controlo de versões da API: api-version=2024-02-01-preview
Ponto final: https://api.ti.sentinel.azure.com/workspaces/{workspaceId}/threat-intelligence-stix-objects:upload?api-version={apiVersion}
Método: POST

Cabeçalho do pedido

Authorization: contém o token de portador OAuth2
Content-Type: application/json

Corpo do pedido

O objeto JSON para o corpo contém os seguintes campos:

Crie a matriz de objetos STIX com a especificação de formato STIX. Algumas das especificações da propriedade STIX são expandidas aqui para sua comodidade com ligações para as secções relevantes do documento STIX. Tenha também em atenção que algumas propriedades, embora válidas para STIX, não têm propriedades de esquema de objeto correspondentes no Microsoft Sentinel.

Mensagem de pedido de exemplo

Eis um exemplo de função do PowerShell que utiliza um certificado autoassinado carregado para um registo de aplicações Entra para gerar o token de acesso e o cabeçalho de autorização:

function Test-UploadApi {
<#
.SYNOPSIS
    requires Powershell module MSAL.PS version 4.37 or higher
    https://www.powershellgallery.com/packages/MSAL.PS/
.EXAMPLE
    Test-Api -API UploadApi -WorkspaceName "workspacename" -ResourceGroupName "rgname" -AppId "00001111-aaaa-2222-bbbb-3333cccc4444" -TenantName "contoso.onmicrosoft.com" -FilePath "C:\Users\user\Documents\stixobjects.json"
#>
[CmdletBinding()]
param (
    [Parameter(Mandatory = $true)]
    [string]$TenantName,
    [Parameter(Mandatory = $true)]
    [string]$CertThumbprint,
    [Parameter(Mandatory = $true)]
    [string]$AppId,
    [Parameter(Mandatory = $true)]
    [string]$WorkspaceId,
    [Parameter(Mandatory = $true)]
    [string]$FilePath
)
$Scope = "https://management.azure.com/.default"
# Connection details for getting initial token with self-signed certificate from local store
$connectionDetails = @{
    'TenantId'          = $TenantName
    'ClientId'          = $AppId
    'ClientCertificate' = Get-Item -Path "Cert:\CurrentUser\My\$CertThumbprint"
    scope               = $Scope
}
# Request the token
#  Using Powershell module MSAL.PS https://www.powershellgallery.com/packages/MSAL.PS/
#  Get-MsalToken is automatically using OAuth 2.0 token endpoint https://login.microsoftonline.com/$TenantName/oauth2/v2.0/token
#  and sets auth flow to grant_type = 'client_credentials'
$token = Get-MsalToken @connectionDetails

# Create header
#  Again relying on MSAL.PS which has method CreateAuthorizationHeader() getting us the bearer token
$Header = @{
    'Authorization' = $token.CreateAuthorizationHeader()
}
$Uri = "https://api.ti.sentinel.azure.com/workspaces/$workspaceId/threat-intelligence-stix-objects:upload?api-version=$apiVersion"
$stixobjects = get-content -path $FilePath
if(-not $stixobjects) { Write-Host "No file found at $FilePath"; break }
$results = Invoke-RestMethod -Uri $Uri -Headers $Header -Body $stixobjects -Method POST -ContentType "application/json"

$results | ConvertTo-Json -Depth 4
}

Propriedades comuns

Todos os objetos que importar com a API de carregamento partilham estas propriedades comuns.

Para obter mais informações, veja Propriedades comuns do STIX.

Indicador

Para obter mais informações, veja Indicador STIX.

Padrão de ataque

Siga as especificações STIX para criar um objeto STIX de padrão de ataque. Utilize este exemplo como uma referência extra.

Para obter mais informações, veja Padrão de ataque STIX.

Identidade

Siga as especificações STIX para criar um objeto STIX de identidade. Utilize este exemplo como uma referência extra.

Para obter mais informações, veja Identidade STIX.

Ator de ameaças

Siga as especificações STIX para criar um objeto STIX do ator de ameaças. Utilize este exemplo como uma referência extra.

Para obter mais informações, veja Ator de ameaças STIX.

Relação

Siga as especificações STIX para criar um objeto STIX de relação. Utilize este exemplo como uma referência extra.

Para obter mais informações, veja Relação STIX.

Processar a mensagem de resposta

O cabeçalho de resposta contém um código de estado HTTP. Veja esta tabela para obter mais informações sobre como interpretar o resultado da chamada à API.

O corpo da resposta é uma matriz de mensagens de erro no formato JSON:

Objeto de erro

Limites de limitação da API

Todos os limites são aplicados por utilizador:

• 100 objetos por pedido.
• 100 pedidos por minuto.

Se existirem mais pedidos do que o limite, é devolvido um 429 código de estado http no cabeçalho de resposta com o seguinte corpo de resposta:

{
    "statusCode": 429,
    "message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
}

Aproximadamente 10 000 objetos por minuto é o débito máximo antes de ser recebido um erro de limitação.

Corpo do pedido do indicador de exemplo

O exemplo seguinte mostra como representar dois indicadores na especificação STIX. Test Indicator 2 realça o protocolo TLP (Traffic Light Protocol) definido como branco com a marcação de objeto mapeado e esclarece a descrição e as etiquetas em inglês.

{
    "sourcesystem": "test", 
    "stixobjects":[
        {
            "type": "indicator",
            "spec_version": "2.1",
            "id": "indicator--10000003-71a2-445c-ab86-927291df48f8", 
            "name": "Test Indicator 1",
            "created": "2010-02-26T18:29:07.778Z", 
            "modified": "2011-02-26T18:29:07.778Z",
            "pattern": "[ipv4-addr:value = '172.29.6.7']", 
            "pattern_type": "stix",
            "valid_from": "2015-02-26T18:29:07.778Z"
        },
        {
            "type": "indicator",
            "spec_version": "2.1",
            "id": "indicator--67e62408-e3de-4783-9480-f595d4fdae52", 
            "created": "2023-01-01T18:29:07.778Z",
            "modified": "2025-02-26T18:29:07.778Z",
            "created_by_ref": "identity--19f33886-d196-468e-a14d-f37ff0658ba7", 
            "revoked": false,
            "labels": [
                "label 1",
                "label 2"
            ],
            "confidence": 55, 
            "lang": "en", 
            "external_references": [
                {
                    "source_name": "External Test Source", 
                    "description": "Test Report",
                    "external_id": "e8085f3f-f2b8-4156-a86d-0918c98c498f", 
                    "url": "https://fabrikam.com//testreport.json",
                    "hashes": {
                        "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
                    }
                }
            ],
            "object_marking_refs": [
                "marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9"
            ],
            "granular_markings": [
                {
                    "marking_ref": "marking-definition--beb3ec79-03aa-4594-ad24-09982d399b80", 
                    "selectors": [ "description", "labels" ],
                    "lang": "en"
                }
            ],
            "name": "Test Indicator 2",
            "description": "This is a test indicator to demo valid fields", 
            "indicator_types": [
                "threatstream-severity-low", "threatstream-confidence-80"
            ],
            "pattern": "[ipv4-addr:value = '192.168.1.1']", 
            "pattern_type": "stix",
            "pattern_version": "2.1",
            "valid_from": "2023-01-01T18:29:07.778Z", 
            "valid_until": "2025-02-26T18:29:07.778Z",
            "kill_chain_phases": [
                {
                    "kill_chain_name": "lockheed-martin-cyber-kill-chain", 
                    "phase_name": "reconnaissance"
                }
            ]
        }
    ]
}

Corpo da resposta de exemplo com erro de validação

Se todos os objetos STIX forem validados com êxito, é devolvido um estado HTTP 200 com um corpo de resposta vazio.

Se a validação falhar para um ou mais objetos, o corpo da resposta é devolvido com mais informações. Por exemplo, se enviar uma matriz com quatro indicadores e os três primeiros forem bons, mas o quarto não tiver um id (um campo obrigatório), é gerada uma resposta 200 do código de estado HTTP juntamente com o seguinte corpo:

{
    "errors": [
        {
            "recordIndex":3, 
            "errorMessages": [
                "Error for Property=id: Required property is missing. Actual value: NULL."
            ]
        }
    ]
}

Os objetos são enviados como uma matriz, pelo que começa recordIndex em 0.

Outros exemplos

Indicador de exemplo

Neste exemplo, o indicador é marcado com o TLP verde ao utilizar marking-definition--089a6ecb-cc15-43cc-9494-767639779123 na object_marking_refs propriedade comum. Estão também incluídos mais atributos de extensão de toxicity e rank . Embora estas propriedades não estejam no esquema Microsoft Sentinel para indicadores, ingerir um objeto com estas propriedades não aciona um erro. As propriedades simplesmente não são referenciadas ou indexadas na área de trabalho.

{
    "sourcesystem": "TestStixObjects",
    "stixobjects": [
    {
          "type": "indicator",
          "spec_version": "2.1",
          "id": "indicator--12345678-71a2-445c-ab86-927291df48f8",
          "created": "2010-02-26T18:29:07.778Z",
          "modified": "2011-02-26T18:29:07.778Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ],
          "extensions": {
            "extension-definition--d83fce45-ef58-4c6c-a3f4-1fbc32e98c6e": {
              "extension_type": "property-extension",
              "rank": 5,
              "toxicity": 8
            }
          },
          "name": "Indicator 2.1 Test",
          "description": "TS ID: 35766958; iType: bot_ip; State: active; Org: 52.3667; Source: Emerging Threats - Compromised",
          "indicator_types": [
            "threatstream-severity-low",
            "threatstream-confidence-80"
          ],
          "pattern": "[ipv4-addr:value = '94.102.52.185']",
          "pattern_type": "stix",
          "pattern_version": "2.1",
          "valid_from": "2015-02-26T18:29:07.778Z",
          "valid_until": "2016-02-26T18:29:07.778Z",
          "kill_chain_phases": [
            {
              "kill_chain_name": "lockheed-martin-cyber-kill-chain",
              "phase_name": "reconnaissance"
            }
          ]
        }
    ]
}

Padrão de ataque de exemplo

Este padrão de ataque e quaisquer outros objetos STIX não indicadores só são visíveis na interface de gestão, a menos que opte por participar nas novas tabelas STIX. Para obter mais informações sobre as tabelas necessárias para ver objetos como este no KQL, veja Ver as informações sobre ameaças.

{
    "sourcesystem": "TestStixObjects",
    "stixobjects": [
        {
          "type": "attack-pattern",
          "spec_version": "2.1",
          "id": "attack-pattern--fb6aa549-c94a-4e45-b4fd-7e32602dad85",
          "created": "2015-05-15T09:12:16.432Z",
          "modified": "2015-05-20T09:12:16.432Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": false,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ],
          "extensions": {
            "extension-definition--d83fce45-ef58-4c6c-a3f4-1fbc32e98c6e": {
              "extension_type": "property-extension",
              "rank": 5,
              "toxicity": 8
            }
          },
          "external_references": [
            {
              "source_name": "capec",
              "description": "spear phishing",
              "external_id": "CAPEC-163"
            }
          ],
          "name": "Attack Pattern 2.1",
          "description": "menuPass appears to favor spear phishing to deliver payloads to the intended targets. While the attackers behind menuPass have used other RATs in their campaign, it appears that they use PIVY as their primary persistence mechanism.",
          "kill_chain_phases": [
            {
              "kill_chain_name": "mandiant-attack-lifecycle-model",
              "phase_name": "initial-compromise"
            }
          ],
          "aliases": [
            "alias_1",
            "alias_2"
          ]
        }
    ]
}

Relação de exemplo com o ator e a identidade de ameaças

{
    "sourcesystem": "TestStixObjects",
    "stixobjects": [
    {
          "type": "identity",
          "spec_version": "2.1",
          "id": "identity--733c5838-34d9-4fbf-949c-62aba761184c",
          "created": "2016-08-23T18:05:49.307Z",
          "modified": "2016-08-23T18:05:49.307Z",
          "name": "Identity 2.1",
          "description": "Disco Team is the name of an organized threat actor crime-syndicate.",
          "identity_class": "organization",
          "contact_information": "disco-team@stealthemail.com",
          "roles": [
            "administrators"
          ],
          "sectors": [
            "education"
          ],
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ]
        },
        {
          "type": "threat-actor",
          "spec_version": "2.1",
          "id": "threat-actor--dfaa8d77-07e2-4e28-b2c8-92e9f7b04428",
          "created": "2014-11-19T23:39:03.893Z",
          "modified": "2014-11-19T23:39:03.893Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ],
          "name": "Threat Actor 2.1",
          "description": "This organized threat actor group operates to create profit from all types of crime.",
          "threat_actor_types": [
            "crime-syndicate"
          ],
          "aliases": [
            "Equipo del Discoteca"
          ],
          "first_seen": "2014-01-19T23:39:03.893Z",
          "last_seen": "2014-11-19T23:39:03.893Z",
          "roles": [
            "agent"
          ],
          "goals": [
            "Steal Credit Card Information"
          ],
          "sophistication": "expert",
          "resource_level": "organization",
          "primary_motivation": "personal-gain",
          "secondary_motivations": [
            "dominance"
          ],
          "personal_motivations": [
            "revenge"
          ]
        },
        {
          "type": "relationship",
          "spec_version": "2.1",
          "id": "relationship--a2e3efb5-351d-4d46-97a0-6897ee7c77a0",
          "created": "2020-02-29T18:01:28.577Z",
          "modified": "2020-02-29T18:01:28.577Z",
          "relationship_type": "attributed-to",
          "description": "Description Relationship 2.1",
          "source_ref": "threat-actor--dfaa8d77-07e2-4e28-b2c8-92e9f7b04428",
          "target_ref": "identity--733c5838-34d9-4fbf-949c-62aba761184c",
          "start_time": "2020-02-29T18:01:28.577Z",
          "stop_time": "2020-03-01T18:01:28.577Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ]
        }
    ]
}

Passos seguintes

Para saber mais sobre como trabalhar com informações sobre ameaças no Microsoft Sentinel, consulte os seguintes artigos:

• Compreender as informações sobre ameaças
• Trabalhar com indicadores de ameaças
• Utilizar análises correspondentes para detetar ameaças
• Utilizar o feed de informações da Microsoft e ativar o conector de dados MDTI