Referencia a la API de indicadores de carga heredados

La API de indicadores de carga de Microsoft Sentinel permite que las plataformas de inteligencia sobre amenazas o las aplicaciones personalizadas importen indicadores de peligro en el formato STIX en un área de trabajo de Microsoft Sentinel. Este documento sirve como referencia a la API heredada.

Una llamada API de indicadores 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 indicadores 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 vea los pasos básicos como parte de la configuración del conector de datos de API de indicadores de carga.

Permissions

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) que recibe la aplicación viene determinada por la accessTokenAcceptedVersion propiedad del manifiesto de la aplicación de la API a la que llama la aplicación. Si accessTokenAcceptedVersion se establece en 1, la aplicación recibirá un token v1.0.

Use MSAL de la biblioteca de autenticación de Microsoft para adquirir un token de acceso v1.0 o v2.0. O bien, envíe solicitudes a la API REST en el formato siguiente:

• 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: {secreto de Microsoft Entra App}
• ámbito: "https://management.azure.com/.default"

Si accessTokenAcceptedVersion en el manifiesto de la aplicación se establece en 1, la aplicación recibirá 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

Había dos versiones de la API heredada. En función del punto de conexión, se requiere un nombre de matriz diferente en el cuerpo de la solicitud. Esto también se representó mediante dos versiones de la acción del conector de aplicación lógica.

1. Nombre de la acción del conector: Inteligencia sobre amenazas: indicadores de carga de peligro (en desuso)
   • Punto de conexión: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators
   • Matriz de nombre de indicadores: value

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

• Nombre de la acción del conector: Inteligencia sobre amenazas: Indicadores de carga de peligro (V2) (versión preliminar)
  • Punto de conexión: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload
  • Matriz de nombre de indicadores: indicators

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

URI de solicitud

Control de versiones de API: api-version=2022-07-01
Punto de conexión: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload?api-version=2022-07-01
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 indicadores con la especificación de formato de indicador STIX 2.1, que se ha condensado aquí para su comodidad con vínculos a secciones importantes. Tenga en cuenta también que algunas propiedades, aunque son válidas para STIX 2.1, no tienen propiedades de indicador correspondientes en Microsoft Sentinel.

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 indicadores 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 indicadores por minuto es el rendimiento máximo antes de recibir un error de limitación.

Cuerpo de la solicitud de ejemplo

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

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

Si todos los indicadores 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 indicadores, 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 indicadores se envían como una matriz, por lo que comienza recordIndex en 0.

Paso siguiente

Esta API es heredada. Migre para usar la API de objetos STIX para cargar la inteligencia sobre amenazas. Para obtener más información, consulte API de objetos STIX.