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:
- 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
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.
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":[] }
- Punto de conexión:
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":[] }
- Punto de conexión:
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:
- 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