Referencie a API de indicadores de upload (versão prévia) para importar inteligência contra ameaças para o Microsoft Sentinel
A API de indicadores de upload do Microsoft Sentinel permite que plataformas de inteligência contra ameaças ou aplicativos personalizados importem indicadores de comprometimento no formato STIX para um workspace do Microsoft Sentinel. Se você usar a API com o conector de dados da API de indicadores de upload do Microsoft Sentinel ou como parte de uma solução personalizada, este documento serve como referência.
Importante
Esta API está atualmente em VERSÃO PRÉVIA. Os termos suplementares de versão prévia do Azure incluem termos legais adicionais que se aplicam aos recursos do Azure que estão em versão beta, versão prévia ou que, de outra forma, ainda não foram lançados em disponibilidade geral.
Uma chamada à 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, processe o cabeçalho da mensagem de resposta HTTP
- Opcionalmente, processe o corpo da mensagem de resposta HTTP
Registrar seu aplicativo cliente com o Microsoft Entra ID
Para se autenticar no Microsoft Sentinel, a solicitação para a API de indicadores de upload requer um token de acesso válido do Microsoft Entra. Para obter mais informações sobre o registro de aplicativo, confira Registrar um aplicativo com a plataforma de identidade da Microsoft ou veja as etapas básicas como parte da configuração do conector de dados da API de indicadores de upload.
Permissões
Essa API exige que o aplicativo de chamada do Microsoft Entra receba a função de colaborador do Microsoft Sentinel no nível do workspace.
Criar a solicitação
Esta seção aborda 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 propriedade accessTokenAcceptedVersion no manifesto do aplicativo da API que seu aplicativo está chamando. Se accessTokenAcceptedVersion for definido como 1, o aplicativo receberá um token v1.0.
Use a MSAL da Biblioteca de Autenticação da Microsoft para adquirir um token de acesso v1.0 ou v2.0. Ou envie solicitações para a API REST no seguinte formato:
- POST
https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token - Cabeçalhos para usar o aplicativo do Microsoft Entra:
- grant_type: "client_credentials"
- client_id: {ID do cliente do aplicativo do Microsoft Entra}
- client_secret: {segredo do aplicativo do Microsoft Entra}
- escopo:
"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 de recurso/escopo é o público-alvo do token. Essa API aceita apenas os seguintes públicos:
https://management.core.windows.net/https://management.core.windows.nethttps://management.azure.com/https://management.azure.com
Montar a mensagem de solicitação
Há 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: Inteligência contra Ameaças – Carregar Indicadores de Comprometimento (Preterido)
- Ponto de extremidade:
https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators - Nome da matriz de indicadores:
value{ "sourcesystem":"TIsource-example", "value":[] }
- Ponto de extremidade:
Nome da ação do conector: Inteligência contra Ameaças – Carregar Indicadores de Comprometimento (V2) (Versão Prévia)
- Ponto de extremidade:
https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload - Nome da matriz de indicadores:
indicators{ "sourcesystem":"TIsource-example", "indicators":[] }
- Ponto de extremidade:
URI da solicitação
Controle de versão de API: api-version=2022-07-01
Ponto de extremidade: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload?api-version=2022-07-01
Método: POST
Cabeçalho da solicitação
Authorization: contém o token de portador OAuth2
Content-Type: application/json
Corpo da solicitação
O objeto JSON do corpo contém os seguintes campos:
| Nome do campo | Tipo de Dados | Descrição |
|---|---|---|
| SourceSystem (obrigatório) | string | Identifique o nome do sistema de origem. O valor Microsoft Sentinel é restrito. |
| Indicadores (obrigatórios) | 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 da propriedade | Type | Descrição |
|---|---|---|
id (obrigatório) |
string | Uma ID usada para identificar o indicador. Confira a seção 2.9 para obter especificações sobre como criar um id. A saída se parece com: indicator--<UUID> |
spec_version (opcional) |
string | Versão do indicador STIX. Esse valor é necessário na especificação STIX, mas como essa API só dá suporte a STIX 2.0 e 2.1, quando esse campo não estiver definido, a API usará 2.1 como padrão |
type (obrigatório) |
string | O valor dessa propriedade deve ser indicator. |
created (obrigatório) |
timestamp | Consulte a seção 3.2 para ver especificações dessa propriedade comum. |
modified (obrigatório) |
timestamp | Consulte a seção 3.2 para ver especificações dessa 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 esse indicador. Os valores dessa propriedade devem vir do indicador-type-ov |
pattern (obrigatório) |
string | O padrão de detecção para esse indicador pode ser expresso como uma Padronização STIX ou outra linguagem apropriada, como SNORT, YARA etc. |
pattern_type (obrigatório) |
string | A linguagem padrão usada neste indicador. O valor dessa 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 de padrão, que deve corresponder ao tipo de dados de padrão incluídos na propriedade de padrão. 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 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 do idioma de padronização no momento da criação desse objeto. |
valid_from (obrigatório) |
timestamp | O tempo a partir do qual esse indicador é considerado um indicador válido dos comportamentos aos quais ele está relacionado ou que ele representa. |
valid_until (opcional) |
timestamp | O momento em que esse indicador não deve mais ser considerado um indicador válido dos comportamentos relacionados ou representados. Se a propriedade valid_until for omitida, não haverá restrição na hora mais recente para a qual o indicador é válido. Esse carimbo de data/hora deve ser maior que o carimbo de data/hora valid_from. |
kill_chain_phases (opcional) |
lista de cadeias de caracteres | As fases de cadeia de eliminação às quais esse indicador corresponde. O valor dessa propriedade deve vir da Fase de Cadeia de Eliminação. |
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 origem dessas informações será indefinida. Para criadores de objetos que desejam permanecer anônimos, mantenha esse valor indefinido. |
revoked (opcional) |
booleano | Objetos revogados não são mais considerados válidos pelo criador de objeto. A revogação de um objeto é permanente; versões futuras do objeto com this id não devem ser criadas.O valor padrão dessa propriedade é falso. |
labels (opcional) |
lista de cadeias de caracteres | A propriedade labels especifica um conjunto de termos usados para descrever esse objeto. Os termos são definidos pelo usuário ou pelo grupo de confiança definidos. Esses rótulos serão exibidos como Marcas no Microsoft Sentinel. |
confidence (opcional) |
inteiro | A propriedade confidence identifica a confiança que o criador tem na exatidão de seus dados. O valor de confiança deve ser um número no intervalo de 0 a 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 de confiança não estiver presente, a confiança do conteúdo não será especificada. |
lang (opcional) |
string | A propriedade lang identifica o idioma do conteúdo do texto neste objeto. Quando presente, ela deve ser um código de idioma compatível com RFC5646. Se a propriedade não estiver presente, o idioma do conteúdo será en (inglês).Essa propriedade deverá estar presente se o tipo de objeto contiver propriedades de texto traduzíveis (por exemplo, nome, descrição). A linguagem de campos individuais neste objeto pode substituir a propriedade lang em marcações granulares (confira a seção 7.2.3). |
object_marking_refs (opcional, incluindo TLP) |
lista de cadeias de caracteres | A propriedade object_marking_refs especifica uma lista de propriedades de ID de objetos de definição de marcação que se aplicam a esse objeto. Por exemplo, use a ID de definição de marcação do protocolo TLP para designar a confidencialidade da origem do indicador. Para obter detalhes sobre quais IDs de definição de marcação usar para conteúdo TLP, confira a seção 7.2.1.4Embora incomum em alguns casos, as definições de marcação em si podem ser marcadas com diretrizes de compartilhamento ou manipulação. Nesse caso, essa propriedade não deve conter nenhuma referência ao mesmo objeto de definição de marcação (ou seja, não pode conter referências circulares). Confira a seção 7.2.2 para obter mais definições de marcações de dados. |
external_references (opcional) |
lista de objetos | A propriedade external_references especifica uma lista de referências externas que se referem 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 propriedade granular_markings ajuda a definir partes do indicador de maneira diferente. Por exemplo, o idioma do indicador é inglês, en mas a descrição está em alemão, de.Embora incomum em alguns casos, as definições de marcação em si podem ser marcadas com diretrizes de compartilhamento ou manipulação. Nesse caso, essa propriedade não deve conter nenhuma referência ao mesmo objeto de definição de marcação (ou seja, ela não pode conter nenhuma referência circular). Confira a seção 7.2.3 para obter 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. Confira esta tabela para obter mais informações sobre como interpretar o resultado da chamada à API.
| Código de status | Descrição |
|---|---|
| 200 | Êxito. A API retorna 200 quando um ou mais indicadores são validados e publicados com êxito. |
| 400 | Formato inválido. Algo na solicitação não está formatado corretamente. |
| 401 | Não autorizado. |
| 404 | Arquivo não localizado. Normalmente, esse erro ocorre quando a ID do workspace não é encontrada. |
| 429 | O número de solicitações em um minuto foi excedido. |
| 500 | Erro de servidor. Geralmente, um erro nos serviços da API ou do Microsoft Sentinel. |
O corpo da resposta é uma matriz de mensagens de erro no formato JSON:
| Nome do campo | Tipo de Dados | Descrição |
|---|---|---|
| erros | Matriz de objetos de erro | Lista de erros de validação |
Objeto Error
| Nome do campo | Tipo de Dados | Descrição |
|---|---|---|
| recordIndex | INT | Índice dos indicadores na solicitação |
| errorMessages | Matriz de cadeias de caracteres | Mensagens de erro |
Limites da API
Todos os limites são aplicados por usuário:
- 100 indicadores por solicitação.
- 100 solicitações por minuto.
Se houver mais solicitações do que o limite, um código de status HTTP 429 no cabeçalho de 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.
Exemplo de corpo da solicitação
{
"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 da resposta de exemplo 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 com o 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, portanto, recordIndex começa em 0.
Próximas etapas
Para saber mais sobre como trabalhar com inteligência contra ameaças no Microsoft Sentinel, confira os seguintes artigos:
- Entenda a inteligência contra ameaças
- Trabalhar com indicadores de ameaça
- Usar a análise de correspondência para detectar ameaças
- Utilize o feed de inteligência da Microsoft e habilite o conector de dados MDTI