Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
A API Microsoft Sentinel carregar indicadores permitiu que plataformas de informações sobre ameaças ou aplicações personalizadas importassem indicadores de comprometimento no formato STIX para uma área de trabalho Microsoft Sentinel. Este documento serve como referência à API legada.
Importante
Esta API está em PRÉ-VISUALIZAÇÃO, mas já não é recomendada. Utilize a nova API de objetos STIX em pré-visualização para carregar informações sobre ameaças. Para obter mais informações, veja API de objetos STIX. Os Termos Suplementares de Pré-visualização do Azure incluem termos legais adicionais que se aplicam a funcionalidades Azure que estão em beta, pré-visualização ou que ainda não foram lançadas para disponibilidade geral.
Uma chamada à API de indicadores de carregamento tem cinco componentes:
- O URI do pedido
- Cabeçalho da mensagem de pedido HTTP
- Corpo da mensagem de pedido HTTP
- Opcionalmente, processe o cabeçalho da mensagem de resposta HTTP
- 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 para a API de indicadores 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 identidade da Microsoft ou veja os passos básicos como parte da configuração do conector de dados da API de indicadores de carregamento.
Permissões
Esta API requer que a aplicação Microsoft Entra de chamadas seja concedida a função de Microsoft Sentinel contribuidor 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) que a aplicação recebe é 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 MSAL da Biblioteca de Autenticação da Microsoft para adquirir um token de acesso v1.0 ou v2.0. Em alternativa, envie pedidos para a API REST no seguinte formato:
- POST
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: {secret of Microsoft Entra App}
- âmbito:
"https://management.azure.com/.default"
Se accessTokenAcceptedVersion no manifesto da aplicação estiver definido como 1, a aplicação receberá 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.nethttps://management.azure.com/https://management.azure.com
Reunir a mensagem de pedido
Havia duas versões da API legada. Consoante o ponto final, era necessário um nome de matriz diferente no corpo do pedido. Isto também foi representado por duas versões da ação do conector da aplicação lógica.
- Nome da ação do conector: Informações sobre Ameaças – Indicadores de Carregamento de Compromisso (Preterido)
- Ponto final:
https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators - Nome da matriz de indicadores:
value
- Ponto final:
- Nome da ação do conector: Informações sobre Ameaças – Indicadores de Carregamento de Compromisso (V2) (Pré-visualização)
- Ponto final:
https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload - Nome da matriz de indicadores:
indicators{ "sourcesystem":"TIsource-example", "indicators":[] }
- Ponto final:
URI do Pedido
Controlo de versões 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 da solicitação
O objeto JSON para o 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ório) | array | Uma matriz de indicadores no formato STIX 2.0 ou 2.1 |
Crie a matriz de indicadores com a especificação de formato de indicador STIX 2.1, que foi condensada aqui para sua comodidade com ligações para secções importantes. Tenha também em atenção que algumas propriedades, embora válidas para STIX 2.1, não têm propriedades de indicador correspondentes no Microsoft Sentinel.
| Nome da propriedade | Tipo | Descrição |
|---|---|---|
id (obrigatório) |
string | Um ID utilizado para identificar o indicador. Consulte a secção 2.9 para obter especificações sobre como criar um id. O formato tem um aspeto semelhante a indicator--<UUID> |
spec_version (opcional) |
string | Versão do indicador STIX. Este valor é necessário na especificação STIX, mas como esta API só suporta STIX 2.0 e 2.1, quando este campo não estiver definido, a API será predefinida como 2.1 |
type (obrigatório) |
string | O valor desta propriedade tem de ser indicator. |
created (obrigatório) |
carimbo de data/hora | Veja a secção 3.2 para obter especificações desta propriedade comum. |
modified (obrigatório) |
carimbo de data/hora | Veja a secção 3.2 para obter especificações desta propriedade comum. |
name (opcional) |
string | Um nome utilizado para identificar o indicador. Os produtores devem fornecer esta propriedade para ajudar os produtos e analistas a compreender o que este indicador realmente faz. |
description (opcional) |
string | Uma descrição que fornece mais detalhes e contexto sobre o indicador, incluindo potencialmente a sua finalidade e as suas principais características. Os produtores devem fornecer esta propriedade para ajudar os produtos e analistas a compreender o que este indicador realmente faz. |
indicator_types (opcional) |
lista de cadeias | Um conjunto de categorizações para este indicador. Os valores para esta propriedade devem ser provenientes de indicator-type-ov |
pattern (obrigatório) |
string | O padrão de deteção para este indicador pode ser expresso como um Padrão STIX ou outro idioma adequado, como SNORT, YARA, etc. |
pattern_type (obrigatório) |
string | A linguagem padrão utilizada neste indicador. O valor desta propriedade deve ser proveniente de tipos de padrão. O valor desta propriedade tem de corresponder ao tipo de dados de padrão incluídos na propriedade do padrão. |
pattern_version (opcional) |
string | A versão da linguagem padrão utilizada para os dados na propriedade do padrão, que tem de corresponder ao tipo de dados padrão incluídos na propriedade do padrão. Para padrões que não têm uma especificação formal, deve ser utilizada a versão de criação ou código com a qual o padrão funciona. Para a linguagem de padrão STIX, a versão de especificação do objeto determina o valor predefinido. Para outros idiomas, o valor predefinido deve ser a versão mais recente do idioma de padrão no momento da criação deste objeto. |
valid_from (obrigatório) |
carimbo de data/hora | O tempo a partir do qual este indicador é considerado um indicador válido dos comportamentos a que está relacionado ou representa. |
valid_until (opcional) |
carimbo de data/hora | O momento em que este indicador já não deve ser considerado um indicador válido dos comportamentos que está relacionado ou representa. Se a propriedade valid_until for omitida, não haverá qualquer restrição na hora mais recente para a qual o indicador é válido. Este carimbo de data/hora tem de ser maior do que o carimbo de data/hora valid_from. |
kill_chain_phases (opcional) |
lista de cadeia | As fases da cadeia de eliminação às quais este indicador corresponde. O valor desta propriedade deve ser proveniente 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 este objeto. Se este atributo for omitido, a origem destas informações será indefinida. Para os criadores de objetos que pretendam permanecer anónimos, mantenha este valor indefinido. |
revoked (opcional) |
booliano | Os objetos revogados já não são considerados válidos pelo criador do objeto. Revogar um objeto é permanente; as versões futuras do objeto com este idnão podem ser criadas.O valor predefinido desta propriedade é falso. |
labels (opcional) |
lista de cadeias | A labels propriedade especifica um conjunto de termos utilizados para descrever este objeto. Os termos são definidos pelo utilizador ou pelo grupo de confiança definidos. Estas etiquetas serão apresentadas como Etiquetas no Microsoft Sentinel. |
confidence (opcional) |
inteiro | A confidence propriedade identifica a confiança que o criador tem na correção dos seus dados. O valor de confiança tem de 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 têm de ser utilizadas ao apresentar o valor de confiança numa dessas escalas. Se a propriedade de confiança não estiver presente, significa que a confiança do conteúdo não é especificada. |
lang (opcional) |
string | A lang propriedade identifica o idioma do conteúdo de texto neste objeto. Quando estiver presente, tem de ser um código de idioma conforme ao RFC5646. Se a propriedade não estiver presente, o idioma do conteúdo será en (inglês).Esta propriedade deve estar presente se o tipo de objeto contiver propriedades de texto traduzíveis (por exemplo, nome, descrição). O idioma dos campos individuais neste objeto pode substituir a lang propriedade em marcas granulares (consulte a secção 7.2.3). |
object_marking_refs (opcional, incluindo TLP) |
lista de cadeias | A object_marking_refs propriedade especifica uma lista de propriedades de ID de objetos de definição de marcação que se aplicam a este objeto. Por exemplo, utilize o ID de definição de marcação TLP (Traffic Light Protocol) para designar a sensibilidade da origem do indicador. Para obter detalhes sobre os IDs de definição de marcação a utilizar para conteúdo TLP, consulte a secção 7.2.1.4Em alguns casos, embora invulgares, as próprias definições de marcação podem ser marcadas com orientações de partilha ou processamento. Neste caso, esta propriedade não pode conter quaisquer referências ao mesmo objeto Definição de Marcação (ou seja, não pode conter referências circulares). Consulte a secção 7.2.2 para obter 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. Esta propriedade é utilizada para fornecer um ou mais URLs, descrições ou IDs a registos noutros 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 indicador é inglês, en mas a descrição é alemão, de.Em alguns casos, embora invulgares, as próprias definições de marcação podem ser marcadas com orientações de partilha ou processamento. Neste caso, esta propriedade não pode conter quaisquer referências ao mesmo objeto Definição de Marcação (ou seja, não pode conter referências circulares). Consulte a secçã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 http status. Veja esta tabela para obter mais informações sobre como interpretar o resultado da chamada à API.
| Código de status | Descrição |
|---|---|
| 200 | Sucesso. A API devolve 200 quando um ou mais indicadores são validados e publicados com êxito. |
| 400 | Formato incorreto. Algo no pedido não está corretamente formatado. |
| 401 | Não autorizado. |
| 404 | Ficheiro não encontrado. Normalmente, este erro ocorre quando o ID da área de trabalho não é encontrado. |
| 429 | O número de pedidos num minuto foi excedido. |
| 500 | Erro do servidor. Normalmente, ocorre um erro na API ou nos serviços 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 no pedido |
| errorMessages | Matriz de cadeias de caracteres | Mensagens de erro |
Limites de limitação da API
Todos os limites são aplicados por utilizador:
- 100 indicadores por pedido.
- 100 pedidos por minuto.
Se existirem mais pedidos do que o limite, é devolvido um 429 código http status 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 indicadores por minuto é o débito máximo antes de ser recebido um erro de limitação.
Corpo do pedido de exemplo
{
"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, é devolvido um http 200 status com um corpo de resposta vazio.
Se a validação falhar para um ou mais indicadores, 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 HTTP status código 200 juntamente 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, pelo que começa recordIndex em 0.
Próxima etapa
Esta API é legada. Migre para utilizar a API de objetos STIX para carregar informações sobre ameaças. Para obter mais informações, veja API de objetos STIX.