Referencia a la API de indicadores de carga (versión preliminar) para importar inteligencia sobre amenazas en Microsoft Sentinel

Artículo
11/15/2023

La API de indicadores de carga de Microsoft Sentinel permite que las plataformas de inteligencia sobre amenazas o las aplicaciones personalizadas importen indicadores de riesgo en el formato STIX en un área de trabajo de Microsoft Sentinel. Tanto si usa la API con el conector de datos de la API de indicadores de carga de Microsoft Sentinel como si lo hace como parte de una solución personalizada, este documento le servirá de referencia.

Importante

Esta API está actualmente en VERSIÓN PRELIMINAR. En la página Términos de uso complementarios para las Versiones preliminares de Microsoft Azure se incluyen términos legales adicionales que se aplican a las características de Azure que se encuentran en versión beta, versión preliminar o que todavía no se han publicado para su disponibilidad general.

Una llamada API de indicadores de carga tiene cinco componentes:

URI de solicitud
Encabezado del mensaje de solicitud HTTP
Cuerpo del mensaje de solicitud HTTP
Opcionalmente, procese el encabezado del mensaje de respuesta HTTP
Opcionalmente, procese el cuerpo del mensaje de respuesta HTTP

Registro de 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 de Microsoft Entra válido. Para más información sobre el registro de aplicaciones, consulte Registrar una aplicación en la plataforma de identidades de Microsoft o vea los pasos básicos como parte de la configuración del conector de datos de la API de indicadores de carga.

Permisos

Esta API requiere que se conceda a la aplicación Microsoft Entra el rol de colaborador de 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. En primer lugar, debe adquirir el token de acceso de Microsoft Entra ID, que se usa para ensamblar el encabezado del mensaje de solicitud.

Adquisición de un token de acceso

Adquiera un token de acceso de Microsoft Entra con 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 propiedad accessTokenAcceptedVersion 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 la biblioteca de autenticación de Microsoft MSAL para adquirir un token de acceso v1.0 o v2.0. O bien, envíe solicitudes a la API de REST con el formato siguiente:

POST https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token
Encabezados para usar la aplicación Microsoft Entra:
grant_type: "client_credentials"
client_id: {Id. de cliente de la aplicación Microsoft Entra}
client_secret: {secreto de la aplicación Microsoft Entra}
ámbito: "https://management.azure.com/.default"

Si accessTokenAcceptedVersion en el manifiesto de la aplicación está establecido en 1, la aplicación recibirá un token de acceso v1.0 aunque llame al punto de conexión del token v2.

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

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

Ensamblado del mensaje de solicitud

URI de solicitud

Control de versiones de la API: api-version=2022-07-01
Punto de conexión: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators?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:

Nombre del campo	Tipo de datos	Descripción
SourceSystem (obligatorio)	string	Identifique el nombre del sistema de origen. El valor `Microsoft Sentinel` está restringido.
Valor (obligatorio)	array	Matriz de indicadores en formato STIX 2.0 o 2.1

Cree la matriz de indicadores mediante la especificación de formato de indicadores STIX 2.1, que se ha condensado aquí para su comodidad con enlaces a secciones importantes. Tenga en cuenta también que algunas propiedades, aunque válidas para STIX 2.1, no tienen propiedades de indicador correspondientes en Microsoft Sentinel.

Nombre de propiedad	Escribir	Descripción
`id` (obligatorio)	string	Identificador usado para identificar el indicador. Consulte la sección 2.9 para obtener especificaciones sobre cómo crear un `id`. El formato es algo parecido a `indicator--<UUID>`
`spec_version` (opcional)	string	Versión del indicador STIX. Este valor es necesario en la especificación STIX, pero dado que esta API solo admite STIX 2.0 y 2.1, cuando no se establece este campo, la API tendrá como valor predeterminado `2.1`
`type` (obligatorio)	string	El valor de esta propiedad debe ser `indicator`.
`created` (obligatorio)	timestamp	Consulte la sección 3.2 para ver las especificaciones de esta propiedad común.
`modified` (obligatorio)	timestamp	Consulte la sección 3.2 para ver las especificaciones de esta propiedad común.
`name` (opcional)	string	Nombre usado para identificar el indicador. Los productores deben proporcionar esta propiedad para ayudar a los productos y analistas a comprender lo que realmente hace este indicador.
`description` (opcional)	string	Descripción que proporciona más detalles y contexto sobre el indicador, incluyendo potencialmente su propósito y sus características clave. Los productores deben proporcionar esta propiedad para ayudar a los productos y analistas a comprender lo que realmente hace este indicador.
`indicator_types` (opcional)	lista de cadenas	Un conjunto de categorizaciones para este indicador. Los valores de esta propiedad deben provenir del indicador-type-ov
`pattern` (obligatorio)	cadena	El patrón de detección de este indicador puede expresarse como un patrón STIX u otro lenguaje adecuado, como SNORT, YARA, etc.
`pattern_type` (obligatorio)	string	Lenguaje de patrón usado en este indicador. Los valores de esta propiedad deberían provenir del indicador-type-ov. El valor de esta propiedad debe coincidir con el tipo de datos de patrón incluidos en la propiedad pattern.
`pattern_version` (opcional)	string	La versión del lenguaje de patrones que se usa para los datos de la propiedad pattern, que debe coincidir con el tipo de datos de patrón incluidos en la propiedad pattern. En el caso de los patrones que no tienen una especificación formal, se debería usar la versión de compilación o código con la que se sabe que el patrón funciona. Para el lenguaje de patrones STIX, la versión de especificación del objeto determina el valor predeterminado. Para otros lenguajes, el valor predeterminado debería ser la versión más reciente del lenguaje de patrones en el momento de la creación de este objeto.
`valid_from` (obligatorio)	timestamp	El momento a partir del cual este indicador se considera un indicador válido de los comportamientos con los que está relacionado o que representa.
`valid_until` (opcional)	timestamp	El momento en el que este indicador ya no debería considerarse un indicador válido de los comportamientos con los que está relacionado o que representa. Si se omite la propiedad valid_until, no hay ninguna restricción en la hora más reciente para la que el indicador es válido. Esta marca de tiempo debe ser mayor que la marca de tiempo valid_from.
`kill_chain_phases` (opcional)	Lista de cadenas	Fases de cadena de eliminación a las que corresponde este indicador. El valor de esta propiedad debería provenir de la fase de cadena de eliminación.
`created_by_ref` (opcional)	string	La propiedad created_by_ref especifica la propiedad ID de la entidad que creó este objeto. Si se omite este atributo, el origen de esta información no está definido. Para los creadores de objetos que desean permanecer anónimos, mantenga este valor sin definir.
`revoked` (opcional)	boolean	Los objetos revocados ya no se consideran válidos por el creador del objeto. La revocación de un objeto es permanente; `id`no deben crearse futuras versiones del objeto con este. El valor predeterminado de esta propiedad es false.
`labels` (opcional)	lista de cadenas	La propiedad `labels` especifica un conjunto de términos utilizados para describir este objeto. Los términos están definidos por el usuario o por el grupo de confianza. Estas etiquetas se mostrarán como etiquetas en Microsoft Sentinel.
`confidence` (opcional)	integer	La propiedad `confidence` identifica la confianza que el creador tiene en la corrección de sus datos. El valor de confianza debe ser un número en el intervalo de 0 a 100. El apéndice A contiene una tabla de asignaciones normativas a otras escalas de confianza que se deben usar al presentar el valor de confianza en una de esas escalas. Si la propiedad de confianza no está presente, no se especifica la confianza del contenido.
`lang` (opcional)	string	La propiedad `lang` identifica el idioma del contenido del texto en este objeto. Cuando está presente, debe ser un código de lenguaje conforme a RFC5646. Si la propiedad no está presente, el idioma del contenido es `en` (inglés). Esta propiedad debe estar presente si el tipo de objeto contiene propiedades de texto traducibles (por ejemplo, nombre, descripción). El idioma de los campos individuales de este objeto puede invalidar la propiedad `lang` en marcas pormenorizadas (vea la sección 7.2.3).
`object_marking_refs` (opcional, incluido TLP)	lista de cadenas	La propiedad `object_marking_refs` especifica una enumeración de propiedades ID de objetos de definición de marcado que se aplican a este objeto. Por ejemplo, utilice el ID de definición de marcado del Protocolo de semáforos (TLP) para designar la sensibilidad de la fuente del indicador. Para obtener más información sobre qué ID de definición de marcado utilizar para el contenido TLP, consulte la sección 7.2.1.4. En algunos casos, aunque no es habitual, las definiciones de marcado se pueden marcar con instrucciones de uso compartido o control. En este caso, esta propiedad no debe contener ninguna referencia al mismo objeto de Definición de marcado (es decir, no puede contener referencias circulares). Consulte la sección 7.2.2 para obtener una definición más detallada de las marcas de datos.
`external_references` (opcional)	list of object	La propiedad `external_references` especifica una lista de referencias externas que hace referencia a información no STIX. Esta propiedad se utiliza para proporcionar una o varias URL, descripciones o ID a registros de otros sistemas.
`granular_markings` (opcional)	lista de marcado granular	La propiedad `granular_markings` ayuda a definir partes del indicador de forma diferente. Por ejemplo, el idioma del indicador es el inglés, `en` pero la descripción es el alemán, `de`. En algunos casos, aunque no es habitual, las definiciones de marcado se pueden marcar con instrucciones de uso compartido o control. En este caso, esta propiedad no debe contener ninguna referencia al mismo objeto de Definición de marcado (es decir, no puede contener referencias circulares). Consulte la sección 7.2.3 para obtener una definición más detallada de las marcas de datos.

Procesamiento del mensaje de respuesta

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

status code	Descripción
200	Correcto. La API devuelve 200 cuando uno o varios indicadores se validan y publican correctamente.
400	Formato incorrecto. Algo en la solicitud no tiene el formato correcto.
401	No autorizado.
404	No se encontró el archivo. Normalmente, este error se produce cuando no se encuentra el identificador del área de trabajo.
429	Se ha superado el número de solicitudes en un minuto.
500	Error de servidor. Normalmente, un error en la API o en los servicios de Microsoft Sentinel.

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

Nombre del campo	Tipo de datos	Descripción
errors	Matriz de objetos de error	Lista de errores de validación

Objeto Error

Nombre del campo	Tipo de datos	Descripción
recordIndex	int	Índice de los indicadores de la solicitud
errorMessages	Matriz de cadenas	Mensajes de error

Límites de 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 código de estado HTTP 429 en el encabezado de respuesta con el siguiente cuerpo de 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.

Ejemplo de cuerpo de la solicitud

{
    "sourcesystem": "test", 
    "value":[
        {
            "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 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, se devuelve el cuerpo de la respuesta con más información. Por ejemplo, si envía una matriz con cuatro indicadores y las tres primeras son buenas, pero la cuarta no tiene un id (un campo obligatorio), se genera una respuesta de código de estado HTTP 200 junto con el cuerpo siguiente:

{
    "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 el recordIndex comienza en 0.

Pasos siguientes

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

Información sobre la inteligencia sobre amenazas
Uso de indicadores de amenazas
Uso de análisis de coincidencias para detectar amenazas
Uso de la fuente de inteligencia de Microsoft y habilitación del conector de datos MDTI

Share via