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

Artigo
10/31/2023

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.

Importante

Esta API está atualmente em pré-visualização. Os Termos Suplementares do Azure Preview incluem termos legais adicionais que se aplicam a funcionalidades do Azure que estão em versão beta, pré-visualização ou ainda não disponibilizadas para disponibilidade geral.

Uma chamada de API de indicadores de upload tem cinco componentes:

O URI da solicitação
Cabeçalho da mensagem de solicitação HTTP
Corpo da mensagem de solicitação HTTP
Opcionalmente, processar o cabeçalho da mensagem de resposta HTTP
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.

Captura de tela dos nomes de ação do conector do aplicativo lógico para a API de indicadores de carregamento do Microsoft Sentinel.

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:

Nome do campo	Tipo de Dados	Description
SourceSystem (obrigatório)	string	Identifique o nome do sistema de origem. O valor `Microsoft Sentinel` é restrito.
indicadores (obrigatório)	matriz	Uma matriz de indicadores no formato STIX 2.0 ou 2.1

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.

Nome de Propriedade	Tipo	Description
`id` (obrigatório)	string	Um ID usado para identificar o indicador. Consulte a secção 2.9 para obter especificações sobre como criar um `id`ficheiro . O formato é algo como `indicator--<UUID>`
`spec_version` (opcional)	string	Versão do indicador STIX. Esse valor é necessário na especificação STIX, mas como essa API suporta apenas STIX 2.0 e 2.1, quando esse campo não estiver definido, a API assumirá como padrão `2.1`
`type` (obrigatório)	string	O valor desta propriedade deve ser `indicator`.
`created` (obrigatório)	carimbo de data/hora	Ver secção 3.2 para as especificações desta propriedade comum.
`modified` (obrigatório)	carimbo de data/hora	Ver secção 3.2 para as especificações desta propriedade comum.
`name` (opcional)	string	Um nome usado para identificar o indicador. Os produtores devem fornecer essa propriedade para ajudar os produtos e analistas a entender o que esse indicador realmente faz.
`description` (opcional)	string	Uma descrição que fornece mais detalhes e contexto sobre o indicador, potencialmente incluindo sua finalidade e suas principais características. Os produtores devem fornecer essa propriedade para ajudar os produtos e analistas a entender o que esse indicador realmente faz.
`indicator_types` (opcional)	Lista de cadeias de caracteres	Um conjunto de categorizações para este indicador. Os valores para esta propriedade devem vir do indicador-type-ov
`pattern` (obrigatório)	string	O padrão de deteção para este indicador pode ser expresso como um padrão STIX ou outra linguagem apropriada, como SNORT, YARA, etc.
`pattern_type` (obrigatório)	string	A linguagem padrão usada neste indicador. O valor para essa propriedade deve vir de tipos de padrão. O valor dessa propriedade deve corresponder ao tipo de dados de padrão incluídos na propriedade pattern.
`pattern_version` (opcional)	string	A versão da linguagem de padrão usada para os dados na propriedade pattern, que deve corresponder ao tipo de dados de padrão incluídos na propriedade pattern. Para padrões que não têm uma especificação formal, a versão de compilação ou código com a qual o padrão é conhecido por trabalhar deve ser usada. Para a linguagem de padrão STIX, a versão de especificação do objeto determina o valor padrão. Para outros idiomas, o valor padrão deve ser a versão mais recente da linguagem de padrão no momento da criação deste objeto.
`valid_from` (obrigatório)	carimbo de data/hora	O momento a partir do qual este indicador é considerado um indicador válido dos comportamentos com que está relacionado ou representa.
`valid_until` (opcional)	carimbo de data/hora	O momento em que este indicador deve deixar de ser considerado um indicador válido dos comportamentos com que está relacionado ou representa. Se a propriedade valid_until for omitida, não haverá restrição sobre a última vez para a qual o indicador é válido. Esse carimbo de data/hora deve ser maior do que o carimbo de data/hora valid_from.
`kill_chain_phases` (opcional)	Lista de string	A(s) fase(s) da cadeia de abate à(s) qual(is) este indicador corresponde. O valor dessa propriedade deve vir da fase Kill Chain.
`created_by_ref` (opcional)	string	A propriedade created_by_ref especifica a propriedade ID da entidade que criou esse objeto. Se esse atributo for omitido, a fonte dessas informações será indefinida. Para criadores de objetos que desejam permanecer anônimos, mantenha esse valor indefinido.
`revoked` (opcional)	boolean	Os objetos revogados não são mais considerados válidos pelo criador do objeto. A revogação de um objeto é permanente; Versões futuras do objeto com isso `id` não devem ser criadas. O valor padrão dessa propriedade é false.
`labels` (opcional)	Lista de cadeias de caracteres	A `labels` propriedade especifica um conjunto de termos usados para descrever esse objeto. Os termos são definidos pelo usuário ou pelo grupo de confiança. Esses rótulos serão exibidos como marcas no Microsoft Sentinel.
`confidence` (opcional)	integer	A `confidence` propriedade identifica a confiança que o criador tem na exatidão dos seus dados. O valor de confiança deve ser um número no intervalo de 0-100. O Apêndice A contém uma tabela de mapeamentos normativos para outras escalas de confiança que devem ser usadas ao apresentar o valor de confiança em uma dessas escalas. Se a propriedade trust não estiver presente, a confiança do conteúdo não será especificada.
`lang` (opcional)	string	A `lang` propriedade identifica o idioma do conteúdo de texto neste objeto. Quando presente, deve ser um código de linguagem compatível com RFC5646. Se a propriedade não estiver presente, o idioma do conteúdo será `en` (inglês). Essa propriedade deve estar presente se o tipo de objeto contiver propriedades de texto traduzíveis (por exemplo, nome, descrição). O idioma de campos individuais neste objeto pode substituir a `lang` propriedade em marcações granulares (ver secção 7.2.3).
`object_marking_refs` (opcional, incluindo TLP)	Lista de cadeias de caracteres	A `object_marking_refs` propriedade especifica uma lista de propriedades de ID de objetos de definição de marcação que se aplicam a esse objeto. Por exemplo, use o ID de definição de marcação TLP (Traffic Light Protocol) para designar a sensibilidade da fonte do indicador. Para obter detalhes sobre quais IDs de definição de marcação usar para conteúdo TLP, consulte a seção 7.2.1.4 Em alguns casos, embora incomuns, as próprias definições de marcação podem ser marcadas com orientações de compartilhamento ou manuseio. Nesse caso, essa propriedade não deve conter referências ao mesmo objeto Marking Definition (ou seja, não pode conter referências circulares). Ver secção 7.2.2 para mais definições de marcações de dados.
`external_references` (opcional)	Lista de objetos	A `external_references` propriedade especifica uma lista de referências externas que se refere a informações não-STIX. Essa propriedade é usada para fornecer uma ou mais URLs, descrições ou IDs para registros em outros sistemas.
`granular_markings` (opcional)	Lista de marcação granular	A `granular_markings` propriedade ajuda a definir partes do indicador de forma diferente. Por exemplo, o idioma do indicador é o inglês, `en` mas a descrição é o alemão, `de`. Em alguns casos, embora incomuns, as próprias definições de marcação podem ser marcadas com orientações de compartilhamento ou manuseio. Nesse caso, essa propriedade não deve conter referências ao mesmo objeto Marking Definition (ou seja, não pode conter referências circulares). Ver secção 7.2.3 para mais definições de marcações de dados.

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.

Código de estado	Description
200	Êxito. A API retorna 200 quando um ou mais indicadores são validados e publicados com êxito.
400	Formato incorreto. Algo na solicitação não está formatado corretamente.
401	Não autorizado.
404	Arquivo não encontrado. Normalmente, esse erro ocorre quando a ID do espaço de trabalho não é encontrada.
429	O número de pedidos num minuto foi excedido.
500	Erro do servidor. Normalmente, um erro nos serviços API ou Microsoft Sentinel.

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

Nome do campo	Tipo de Dados	Description
erros	Matriz de objetos de erro	Lista de erros de validação

Objeto de erro

Nome do campo	Tipo de Dados	Description
recordIndex	número inteiro	Índice dos indicadores no pedido
errorMessages	Matriz de cadeias	Mensagens 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

Partilhar via