Faça referência à API de indicadores de carregamento (Visualização) para importar informações sobre ameaças para o Microsoft Sentinel

A API de indicadores de carregamento do Microsoft Sentinel permite que plataformas de inteligência de ameaças ou aplicativos personalizados importem indicadores de comprometimento no formato STIX para um espaço de trabalho do Microsoft Sentinel. Quer utilize a API com o conector de dados da API de indicadores de carregamento do Microsoft Sentinel ou como parte de uma solução personalizada, este documento serve de referência.

Uma chamada de API de indicadores de upload 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 indicadores 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 do conector de dados da API de indicadores de carregamento.

Permissões

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) que seu aplicativo recebe é 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 o Microsoft Authentication Library MSAL para adquirir um token de acesso v1.0 ou v2.0. Ou envie solicitações para a API REST no seguinte formato:

• 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: {segredo do Microsoft Entra App}
• Â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

Existem duas versões da API de indicadores de upload. Dependendo do ponto de extremidade, um nome de matriz diferente é necessário no corpo da solicitação. Isso também é representado por duas versões da ação do conector do aplicativo lógico.

• Nome da ação do conector: Threat Intelligence - Upload Indicators of Compromise (Preterido)

  • Ponto final: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators
  • Nome da matriz de indicadores: value

    {
       "sourcesystem":"TIsource-example",
       "value":[]
    }
    

• Nome da ação do conector: Threat Intelligence - Upload Indicators of Compromise (V2) (Preview)

  • Ponto final: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload
  • Nome da matriz de indicadores: indicators

    {
       "sourcesystem":"TIsource-example",
       "indicators":[]
    }
    

URI do pedido

Controle de versão da API: api-version=2022-07-01
Ponto final: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload?api-version=2022-07-01
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 indicadores usando a especificação de formato de indicador STIX 2.1, que foi condensada aqui para sua conveniência com links para seções importantes. Observe também que algumas propriedades, embora válidas para STIX 2.1, não têm propriedades de indicador correspondentes no Microsoft Sentinel.

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 indicadores 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 indicadores por minuto é a taxa de transferência máxima antes que um erro de limitação seja recebido.

Corpo da solicitação da amostra

{
    "sourcesystem": "test", 
    "indicators":[
        {
            "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 indicadores 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 indicadores, 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 indicadores são enviados como uma matriz, de modo que o recordIndex começa em 0.

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