Compartir a través de


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

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:

  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

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

Hay dos versiones de la API de indicadores de carga. Según el punto de conexión, se requiere un nombre de matriz diferente en el cuerpo de la solicitud. Esto también se representa mediante dos versiones de la acción del conector de la aplicación lógica.

Captura de pantalla de los nombres de acción del conector de aplicación lógica para la API de indicadores de carga de Microsoft Sentinel.

  • Nombre de la acción del conector: Inteligencia sobre amenazas: indicadores de carga de riesgo (en desuso)

    • Punto de conexión: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators
    • Matriz de indicadores nombre: value
      {
         "sourcesystem":"TIsource-example",
         "value":[]
      }
      
  • Nombre de la acción del conector: Inteligencia sobre amenazas: indicadores de carga de riesgo (V2) (versión preliminar)

    • Punto de conexión: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload
    • Matriz de indicadores nombre: indicators
      {
         "sourcesystem":"TIsource-example",
         "indicators":[]
      }
      

URI de solicitud

Control de versiones de la 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:

Nombre del campo Tipo de datos Descripción
SourceSystem (obligatorio) string Identifique el nombre del sistema de origen. El valor Microsoft Sentinel está restringido.
indicadores (obligatorios) 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 Type 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. Revocar un objeto es permanente; No se deben crear versiones futuras del objeto con esto.id

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", 
    "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 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: