Hola mundo para Microsoft Defender XDR API REST
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.
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.
Inicie sesión en Azure.
Vaya a Microsoft Entra ID>Registros de aplicaciones>Nuevo registro.
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.
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.
Seleccione Conceder consentimiento de administrador. Cada vez que agregue un permiso, debe seleccionar Conceder consentimiento del administrador para que surta efecto.
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.
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.
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.
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
Copie y pegue el token que recibió en JWT para descodificarlo.
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.All
permisos ,Incidents.ReadWrite.All
yAdvancedHunting.Read.All
:
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.
- Introducción a las API de Microsoft Defender XDR
- Acceso a las API de Microsoft Defender XDR
- Creación de una aplicación para acceder a Microsoft Defender XDR sin un usuario
- Creación de una aplicación para acceder a Microsoft Defender XDR API en nombre de un usuario
- Creación de una aplicación con acceso de asociado multiinquilino a las API de Microsoft Defender XDR
- Administración de secretos en las aplicaciones de servidor con Azure Key Vault
- Autorización de OAuth 2.0 para el inicio de sesión de usuario y el acceso a la API
Sugerencia
¿Desea obtener más información? Participe con la comunidad de Seguridad de Microsoft en nuestra Tech Community: Tech Community de Microsoft Defender XDR.