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

Importe informações sobre ameaças para usar 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 uma referência suplementar às instruções em Ligar a sua DICA à API de carregamento. A instalação do conector de dados não é necessária para se conectar à API. A inteligência de ameaças que você pode importar inclui 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 aprimorado para os seguintes objetos de domínio está incluído na API de carregamento:

• indicador
• padrão de ataque
• Agente de ameaça
• 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 da solicitação
2. Cabeçalho da mensagem de solicitação HTTP
3. Corpo da mensagem de solicitação HTTP
4. Opcionalmente, processar o cabeçalho da mensagem de resposta HTTP
5. Opcionalmente, processar o corpo da mensagem de resposta HTTP

Registe a sua aplicação cliente com o Microsoft Entra ID

Para se autenticar no Microsoft Sentinel, a solicitação para a API de carregamento requer um token de acesso válido do Microsoft Entra. Para obter mais informações sobre o registro de aplicativos, consulte Registrar um aplicativo com a plataforma de identidade da Microsoft ou consulte as etapas básicas como parte da configuração Connect threat intelligence with upload API .

Essa API requer que o aplicativo Microsoft Entra chamador receba a função de colaborador do Microsoft Sentinel no nível do espaço de trabalho.

Criar o pedido

Esta seção abrange os três primeiros dos cinco componentes discutidos anteriormente. Primeiro, você precisa adquirir o token de acesso do Microsoft Entra ID, que você usa para montar o cabeçalho da mensagem de solicitação.

Adquirir um token de acesso

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

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

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

Por exemplo, uma solicitação para a API de carregamento usa os seguintes elementos para recuperar um token de acesso e criar o cabeçalho de autorização, que é usado em cada solicitação:

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

Cabeçalhos para usar o aplicativo Microsoft Entra:

• grant_type: "client_credentials"
• client_id: {ID do Cliente do Aplicativo Microsoft Entra}
• client_secret ou client_certificate: {segredos do aplicativo Microsoft Entra}
• Âmbito de aplicação: "https://management.azure.com/.default"

Se accessTokenAcceptedVersion no manifesto do aplicativo estiver definido como 1, seu aplicativo receberá um token de acesso v1.0 mesmo que esteja chamando o ponto de extremidade do token v2.

O valor do recurso/escopo é a audiência do token. Esta API só aceita os seguintes públicos:

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

Montar a mensagem de solicitação

URI do pedido

Controle de versão 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 usando a especificação de formato STIX. Algumas das especificações de propriedade STIX são expandidas aqui para sua conveniência com links para as seções relevantes do documento STIX. Observe também que algumas propriedades, embora válidas para STIX, não têm propriedades de esquema de objeto correspondentes no Microsoft Sentinel.

Exemplo de mensagem de solicitação

Aqui está uma função PowerShell de exemplo que usa um certificado autoassinado carregado em um registro de aplicativo 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 importados com a API de carregamento compartilham essas propriedades comuns.

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

Indicador

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

Padrão de ataque

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

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

Identidade

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

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

Agente de ameaça

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

Para obter mais informações, consulte Agente de ameaças STIX.

Relação

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

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

Processar a mensagem de resposta

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

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

Objeto de erro

Limites de limitação para a API

Todos os limites são aplicados por utilizador:

• 100 objetos por solicitação.
• 100 pedidos por minuto.

Se houver mais solicitações do que o limite, um código de 429 status http no cabeçalho da resposta será retornado 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 é a taxa de transferência máxima antes que um erro de limitação seja recebido.

Corpo da solicitação do indicador de amostra

O exemplo a seguir mostra como representar dois indicadores na especificação STIX. Test Indicator 2 destaca o Protocolo de Semáforo (TLP) definido como branco com a marcação do objeto mapeado, e esclarecendo sua descrição e rótulos estão 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 de resposta da amostra com erro de validação

Se todos os objetos STIX forem validados com êxito, um status HTTP 200 será retornado com um corpo de resposta vazio.

Se a validação falhar para um ou mais objetos, o corpo da resposta será retornado com mais informações. Por exemplo, se você 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), uma resposta de código de status HTTP 200 será gerada junto 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, de modo que o recordIndex começa em 0.

Outras amostras

Indicador de amostra

Neste exemplo, o indicador é marcado com o TLP verde usando marking-definition--089a6ecb-cc15-43cc-9494-767639779123 na object_marking_refs propriedade comum. Mais atributos de extensão de toxicity e rank também estão incluídos. Embora essas propriedades não estejam no esquema do Microsoft Sentinel para indicadores, a ingestão de um objeto com essas propriedades não dispara um erro. As propriedades simplesmente não são referenciadas ou indexadas no espaço 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 da amostra

Esse padrão de ataque e quaisquer outros objetos STIX não indicadores só podem ser visualizados na interface de gerenciamento, a menos que você opte pelas novas tabelas STIX. Para obter mais informações sobre as tabelas necessárias para visualizar objetos como este no KQL, consulte Exibir sua inteligência 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"
          ]
        }
    ]
}

Exemplo de relação com o agente de ameaça e a identidade

{
    "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"
            }
          ]
        }
    ]
}

Próximos passos

Para saber mais sobre como trabalhar com inteligência de ameaças no Microsoft Sentinel, consulte os seguintes artigos:

• Compreender a inteligência de ameaças
• Trabalhar com indicadores de ameaça
• Use análises de correspondência para detetar ameaças
• Utilize o feed de inteligência da Microsoft e habilite o conector de dados MDTI