Importación de inteligencia sobre amenazas a Microsoft Sentinel con la API de carga (versión preliminar)

Importe la inteligencia sobre amenazas para usarla en Microsoft Sentinel con la API de carga. Tanto si usa una plataforma de inteligencia sobre amenazas como una aplicación personalizada, use este documento como referencia complementaria a las instrucciones de Conexión de la SUGERENCIA con la API de carga. No es necesario instalar el conector de datos para conectarse a la API. La inteligencia sobre amenazas que puede importar incluye indicadores de peligro y otros objetos de dominio STIX.

Expresión de información sobre amenazas estructurada (STIX) es un lenguaje para expresar ciberamenazas e información observable. Se incluye compatibilidad mejorada con los siguientes objetos de dominio con la API de carga:

• indicador
• patrón de ataque
• actor de amenazas
• identidad
• Relación

Para obtener más información, consulte Introducción a STIX.

Llamar a la API

Una llamada a la API de carga tiene cinco componentes:

1. Uri de solicitud
2. Encabezado del mensaje de solicitud HTTP
3. Cuerpo del mensaje de solicitud HTTP
4. Opcionalmente, procese el encabezado del mensaje de respuesta HTTP.
5. Opcionalmente, procese el cuerpo del mensaje de respuesta HTTP.

Registre la aplicación cliente con Microsoft Entra ID

Para autenticarse en Microsoft Sentinel, la solicitud a la API de carga requiere un token de acceso Microsoft Entra válido. Para obtener más información sobre el registro de aplicaciones, consulte Registro de una aplicación con el Plataforma de identidad de Microsoft o consulte los pasos básicos como parte de la configuración de connect threat intelligence with upload API.

Esta API requiere que se conceda a la aplicación de Microsoft Entra llamada el rol de colaborador Microsoft Sentinel en el nivel de área de trabajo.

Creación de la solicitud

En esta sección se tratan los tres primeros componentes descritos anteriormente. Primero debe adquirir el token de acceso de Microsoft Entra ID, que se usa para ensamblar el encabezado del mensaje de solicitud.

Adquirir un token de acceso

Adquiera un token de acceso de Microsoft Entra con la autenticación de OAuth 2.0. V1.0 y V2.0 son tokens válidos aceptados por la API.

La versión del token (v1.0 o v2.0) recibida viene determinada por la accessTokenAcceptedVersion propiedad del manifiesto de aplicación de la API a la que llama la aplicación. Si accessTokenAcceptedVersion se establece en 1, la aplicación recibe un token v1.0.

Use la Biblioteca de autenticación de Microsoft (MSAL) para adquirir un token de acceso v1.0 o v2.0. Use el token de acceso para crear el encabezado de autorización que contiene el token de portador.

Por ejemplo, una solicitud a la API de carga usa los siguientes elementos para recuperar un token de acceso y crear el encabezado de autorización, que se usa en cada solicitud:

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

Encabezados para usar Microsoft Entra App:

• grant_type: "client_credentials"
• client_id: {Id. de cliente de Microsoft Entra App}
• client_secret o client_certificate: {secretos de la aplicación de Microsoft Entra}
• ámbito: "https://management.azure.com/.default"

Si accessTokenAcceptedVersion en el manifiesto de la aplicación se establece en 1, la aplicación recibe un token de acceso v1.0 aunque llame al punto de conexión del token v2.

El valor de recurso o ámbito es la audiencia del token. Esta API solo acepta las siguientes audiencias:

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

Ensamblar el mensaje de solicitud

URI de solicitud

Control de versiones de API: api-version=2024-02-01-preview
Punto de conexión: https://api.ti.sentinel.azure.com/workspaces/{workspaceId}/threat-intelligence-stix-objects:upload?api-version={apiVersion}
Método: POST

Encabezado de solicitud

Authorization: contiene el token de portador de OAuth2.
Content-Type: application/json

Cuerpo de la solicitud

El objeto JSON del cuerpo contiene los campos siguientes:

Cree la matriz de objetos STIX mediante la especificación de formato STIX. Algunas de las especificaciones de la propiedad STIX se amplían aquí para su comodidad con vínculos a las secciones pertinentes del documento STIX. Tenga en cuenta también que algunas propiedades, aunque son válidas para STIX, no tienen propiedades de esquema de objeto correspondientes en Microsoft Sentinel.

Mensaje de solicitud de ejemplo

Esta es una función de PowerShell de ejemplo que usa un certificado autofirmado cargado en un registro de aplicación Entra para generar el token de acceso y el encabezado de autorización:

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
}

Propiedades comunes

Todos los objetos que importe con la API de carga comparten estas propiedades comunes.

Para obtener más información, vea Propiedades comunes de STIX.

Indicador

Para obtener más información, consulte indicador STIX.

Patrón de ataque

Siga las especificaciones de STIX para crear un objeto STIX de patrón de ataque. Use este ejemplo como referencia adicional.

Para obtener más información, vea Patrón de ataque STIX.

Identidad

Siga las especificaciones de STIX para crear un objeto STIX de identidad. Use este ejemplo como referencia adicional.

Para obtener más información, consulte Identidad STIX.

Actor de amenazas

Siga las especificaciones de STIX para crear un objeto STIX de actor de amenaza. Use este ejemplo como referencia adicional.

Para obtener más información, vea STIX threat actor( Actor de amenazas de STIX).

Relación

Siga las especificaciones de STIX para crear un objeto STIX de relación. Use este ejemplo como referencia adicional.

Para obtener más información, vea Relación STIX.

Procesar el mensaje de respuesta

El encabezado de respuesta contiene un código de estado HTTP. Haga referencia a esta tabla para obtener más información sobre cómo interpretar el resultado de la llamada API.

El cuerpo de la respuesta es una matriz de mensajes de error en formato JSON:

Error (objeto)

Límites de limitación para la API

Todos los límites se aplican por usuario:

• 100 objetos por solicitud.
• 100 solicitudes por minuto.

Si hay más solicitudes que el límite, se devuelve un 429 código de estado HTTP en el encabezado de respuesta con el siguiente cuerpo de la respuesta:

{
    "statusCode": 429,
    "message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
}

Aproximadamente 10 000 objetos por minuto es el rendimiento máximo antes de recibir un error de limitación.

Cuerpo de la solicitud del indicador de ejemplo

En el ejemplo siguiente se muestra cómo representar dos indicadores en la especificación STIX. Test Indicator 2 resalta el protocolo de semáforos (TLP) establecido en blanco con el marcado de objetos asignados, y la aclaración de su descripción y etiquetas está en 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"
                }
            ]
        }
    ]
}

Cuerpo de la respuesta de ejemplo con error de validación

Si todos los objetos STIX se validan correctamente, se devuelve un estado HTTP 200 con un cuerpo de respuesta vacío.

Si se produce un error en la validación de uno o varios objetos, el cuerpo de la respuesta se devuelve con más información. Por ejemplo, si envía una matriz con cuatro indicadores y los tres primeros son buenos, pero el cuarto no tiene ( id un campo obligatorio), se genera una respuesta de código de estado HTTP 200 junto con el siguiente cuerpo:

{
    "errors": [
        {
            "recordIndex":3, 
            "errorMessages": [
                "Error for Property=id: Required property is missing. Actual value: NULL."
            ]
        }
    ]
}

Los objetos se envían como una matriz, por lo que recordIndex comienza en 0.

Otros ejemplos

Indicador de ejemplo

En este ejemplo, el indicador se marca con el TLP verde mediante marking-definition--089a6ecb-cc15-43cc-9494-767639779123 en la object_marking_refs propiedad común. También se incluyen más atributos de extensión de toxicity y rank . Aunque estas propiedades no están en el esquema Microsoft Sentinel para los indicadores, la ingesta de un objeto con estas propiedades no desencadena un error. Simplemente no se hace referencia a las propiedades ni se indexa en el área de trabajo.

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

Patrón de ataque de ejemplo

Este patrón de ataque y cualquier otro objeto STIX que no sea indicador solo se puede ver en la interfaz de administración a menos que se opte por las nuevas tablas STIX. Para obtener más información sobre las tablas necesarias para ver objetos como este en KQL, consulte Visualización de la inteligencia sobre amenazas.

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

Relación de ejemplo con el actor de amenazas y la identidad

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

Pasos siguientes

Para obtener más información sobre cómo trabajar con inteligencia sobre amenazas en Microsoft Sentinel, consulte los artículos siguientes:

• Descripción de la inteligencia sobre amenazas
• Trabajar con indicadores de amenazas
• Uso de análisis coincidentes para detectar amenazas
• Uso de la fuente de inteligencia de Microsoft y habilitación del conector de datos MDTI