API de REST de Defender for Cloud Apps

Artículo
01/23/2024

En este artículo se describe cómo interactuar con Defender for Cloud Apps a través de HTTPS.

La API de Microsoft Defender for Cloud Apps proporciona acceso mediante programación a Defender for Cloud Apps mediante puntos de conexión de API REST. Las aplicaciones pueden usar la API para realizar operaciones de lectura y actualización en objetos y datos de Defender for Cloud Apps. Por ejemplo, la API de Defender for Cloud Apps admite las siguientes operaciones comunes para un objeto de usuario:

Cargar archivos de registro para Cloud Discovery
Generar scripts de bloqueo
Enumeración de actividades y alertas
Descartar o resolver alertas

Estructura de la URL de la API

Para utilizar la API de Defender for Cloud Apps, primero debes obtener la URL de la API de tu inquilino. La URL de la API utiliza el siguiente formato: https://<portal_url>/api/<endpoint>.

Para obtener la dirección URL de la API de Defender for Cloud Apps para el inquilino, sigue estos pasos:

En el portal de Microsoft Defender, selecciona Configuración. A continuación, elige Aplicaciones en la nube. En Sistema, selecciona Acerca de.
En la pantalla Acerca de Defender for Cloud Apps, puedes ver la dirección URL de la API.

Una vez que tengas la dirección URL de API, agrégale el sufijo /api para obtener la dirección URL de la API. Por ejemplo, si la dirección URL del portal es https://mytenant.us2.contoso.com, la dirección URL de la API es https://mytenant.us2.portal.cloudappsecurity.com/api.

Tokens de API

Defender for Cloud Apps requiere un token de API en el encabezado de todas las solicitudes de API al servidor, como las siguientes:

Authorization: Token <your_token_key>

Donde <your_token_key> es el token de API personal.

Para obtener más información sobre los tokens de API, consulta Administración de tokens de API.

Tokens de API: ejemplo

curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint"

¿Qué acciones se admiten?

La siguiente tabla describe las acciones admitidas:

Resource	Verbos HTTP	Rutas de URI
Actividades	GET o POST	/api/v1/activities/
Alertas	GET o POST	/api/v1/alerts/
Enriquecimiento de datos	GET, POST o DELETE	/api/subnet/
Entities	GET o POST	/api/v1/entities/
Archivos	GET o POST	/api/v1/files/

Donde Recurso representa un grupo de entidades relacionadas.

¿Qué tipos de campo se admiten?

En la tabla siguiente se describen los tipos de campo admitidos:

Campo	Descripción
string	Una cadena de texto
boolean	Un valor booleano que representa true/false
integer	Entero de 32 bits con signo
timestamp	Milisegundos desde la época

Marcas de tiempo

Las menciones de marcas de tiempo en la API de Defender for Cloud Apps hacen referencia a la marca de tiempo de Unix en milisegundos. Esta marca de tiempo viene determinada por el número de milisegundos desde 1970-01-01 0:00:00. Puedes usar el cmdlet de PowerShell get-date para convertir fechas a marcas de tiempo.

Límites

Puedes optar por limitar las solicitudes proporcionando un parámetro de límite en la solicitud.

Se admiten los siguientes métodos para proporcionar el parámetro límite:

Codificado con dirección URL (con encabezado Content-Type: application/x-www-form-urlencoded)
Datos de formulario
Cuerpo JSON (con Content-Type: multipart/form-data y un encabezado de límite adecuado)

Nota:

Si no se proporciona ningún límite, se establecerá un valor predeterminado de 100.
Las respuestas de todas las solicitudes realizadas con el token de API se limitan a un máximo de 100 elementos.
El límite de todas las solicitudes de API es de 30 solicitudes por minuto por inquilino.

Filters

Cuando tengas un gran número de resultados, te resultará útil ajustar las solicitudes mediante filtros. En esta sección se describe la estructura de los filtros y los operadores que pueden utilizarse con ellos.

Estructura

Algunos de nuestros puntos de conexión de API admiten filtros al realizar consultas. En sus secciones pertinentes, encontrarás una referencia en la que se enumeran todos los campos filtrables disponibles y los operadores admitidos para ese recurso.

La mayoría de los filtros admiten varios valores para proporcionar consultas eficaces. Al combinar filtros y operadores, usamos AND como operador lógico entre los filtros.

Ejemplos de filtro

curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint" -d '{
  "filters": {
    "some.field": {
      "eq": ["value1", "value2"],
      "isset": true
    },
    "some.field2": {
      "gte": 5
    }
  },
  "skip": 5,
  "limit": 10
}'

Operadores