Hola mundo para Microsoft Defender XDR API REST

  • Artículo

Se aplica a:

  • Microsoft Defender XDR

Importante

Parte de la información se refiere a productos preliminares que pueden ser modificados sustancialmente antes de su lanzamiento comercial. Microsoft no otorga garantías, expresas o implícitas, con respecto a la información que aquí se proporciona.

Obtención de incidentes mediante un script de PowerShell sencillo

Este proyecto tardará entre 5 y 10 minutos. Esta estimación de tiempo incluye el registro de la aplicación y la aplicación del código desde el script de ejemplo de PowerShell.

Registro de una aplicación en Microsoft Entra ID

  1. Inicie sesión en Azure como usuario con el rol Administrador global.

  2. Vaya a Microsoft Entra ID>Registros de aplicaciones>Nuevo registro.

    La sección Nuevo registro del portal de Microsoft Defender

  3. En el formulario de registro, elija un nombre para la aplicación y, a continuación, seleccione Registrar. La selección de un URI de redireccionamiento es opcional. No necesitará uno para completar este ejemplo.

  4. En la página de la aplicación, seleccione Permisos> de API Agregar API depermisos>que usa> mi organización, escriba Microsoft Threat Protection y seleccione Microsoft Threat Protection. La aplicación ahora puede acceder a Microsoft Defender XDR.

    Sugerencia

    Microsoft Threat Protection es un nombre anterior para Microsoft Defender XDR y no aparecerá en la lista original. Debe empezar a escribir su nombre en el cuadro de texto para verlo aparecer. La sección de uso de LAS API en el portal de Microsoft Defender

    • Elija Permisos> de aplicaciónIncident.Read.All y seleccione Agregar permisos.

      Panel de permisos de una aplicación en el portal de Microsoft Defender

  5. Seleccione Conceder consentimiento de administrador. Cada vez que agregue un permiso, debe seleccionar Conceder consentimiento del administrador para que surta efecto.

    La sección Conceder consentimiento del administrador en el portal de Microsoft Defender

  6. Agregue un secreto a la aplicación. Seleccione Certificados & secretos, agregue una descripción al secreto y, a continuación, seleccione Agregar.

    Sugerencia

    Después de seleccionar Agregar, seleccione Copiar el valor de secreto generado. No podrá recuperar el valor del secreto después de salir.

    La sección agregar secreto en el portal de Microsoft Defender

  7. Registre el identificador de la aplicación y el identificador de inquilino en un lugar seguro. Se enumeran en Información general en la página de la aplicación.

    La sección Información general del portal de Microsoft Defender

Obtención de un token mediante la aplicación y uso del token para acceder a la API

Para obtener más información sobre los tokens de Microsoft Entra, consulte el tutorial de Microsoft Entra.

Importante

Aunque el ejemplo de esta aplicación de demostración le anima a pegar el valor secreto con fines de prueba, nunca debe codificar de forma rígida los secretos en una aplicación que se ejecuta en producción. Un tercero podría usar el secreto para acceder a los recursos. Puede ayudar a proteger los secretos de la aplicación mediante Azure Key Vault. Para obtener un ejemplo práctico de cómo proteger la aplicación, consulte Administración de secretos en las aplicaciones de servidor con Azure Key Vault.

  1. Copie el script siguiente y péguelo en el editor de texto que prefiera. Guarde como Get-Token.ps1. También puede ejecutar el código tal como está en PowerShell ISE, pero debe guardarlo, ya que tendremos que volver a ejecutarlo cuando usemos el script de captura de incidentes en la sección siguiente.

    Este script generará un token y lo guardará en la carpeta de trabajo bajo el nombre ,Latest-token.txt.

    # This script gets the app context token and saves it to a file named "Latest-token.txt" under the current directory.
# Paste in your tenant ID, client ID and app secret (App key).

$tenantId = '' # Paste your directory (tenant) ID here
$clientId = '' # Paste your application (client) ID here
$appSecret = '' # # Paste your own app secret here to test, then store it in a safe place!

$resourceAppIdUri = 'https://api.security.microsoft.com'
$oAuthUri = "https://login.windows.net/$tenantId/oauth2/token"
$authBody = [Ordered] @{
  resource = $resourceAppIdUri
  client_id = $clientId
  client_secret = $appSecret
  grant_type = 'client_credentials'
}
$authResponse = Invoke-RestMethod -Method Post -Uri $oAuthUri -Body $authBody -ErrorAction Stop
$token = $authResponse.access_token
Out-File -FilePath "./Latest-token.txt" -InputObject $token
return $token

Validar el token

  1. Copie y pegue el token que recibió en JWT para descodificarlo.

  2. JWT significa JSON Web Token. El token descodificado contendrá una serie de notificaciones o elementos con formato JSON. Asegúrese de que la notificación de roles dentro del token descodificado contiene los permisos deseados.

    En la imagen siguiente, puede ver un token descodificado adquirido de una aplicación, con Incidents.Read.Allpermisos , Incidents.ReadWrite.Ally AdvancedHunting.Read.All :

    La sección Token descodificado del portal de Microsoft Defender

Obtener una lista de incidentes recientes

El script siguiente usará Get-Token.ps1 para acceder a la API. A continuación, recupera una lista de incidentes que se actualizaron por última vez en las últimas 48 horas y guarda la lista como un archivo JSON.

Importante

Guarde este script en la misma carpeta que guardó Get-Token.ps1.

# This script returns incidents last updated within the past 48 hours.

$token = ./Get-Token.ps1

# Get incidents from the past 48 hours.
# The script may appear to fail if you don't have any incidents in that time frame.
$dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")

# This URL contains the type of query and the time filter we created above.
# Note that `$filter` does not refer to a local variable in our script --
# it's actually an OData operator and part of the API's syntax.
$url = "https://api.security.microsoft.com/api/incidents`?`$filter=lastUpdateTime+ge+$dateTime"

# Set the webrequest headers
$headers = @{
    'Content-Type' = 'application/json'
    'Accept' = 'application/json'
    'Authorization' = "Bearer $token"
}

# Send the request and get the results.
$response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop

# Extract the incidents from the results.
$incidents =  ($response | ConvertFrom-Json).value | ConvertTo-Json -Depth 99

# Get a string containing the execution time. We concatenate that string to the name 
# of the output file to avoid overwriting the file on consecutive runs of the script.
$dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}

# Save the result as json
$outputJsonPath = "./Latest Incidents $dateTimeForFileName.json"

Out-File -FilePath $outputJsonPath -InputObject $incidents

¡Ya has terminado! Ha realizado correctamente lo siguiente:

  • Ha creado y registrado una aplicación.
  • Se ha concedido permiso para que esa aplicación lea alertas.
  • Conectado a la API.
  • Se ha usado un script de PowerShell para devolver los incidentes actualizados en las últimas 48 horas.

Sugerencia

¿Desea obtener más información? Engage con la comunidad de seguridad de Microsoft en nuestra comunidad tecnológica: Microsoft Defender XDR Tech Community.