Hello World para la API Microsoft 365 Defender REST

Nota

¿Quiere experimentar Microsoft 365 Defender? Obtenga más información sobre cómo puede evaluar y probar Microsoft 365 Defender.

Se aplica a:

  • Microsoft 365 Defender

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.

Obtener incidentes con un script de PowerShell simple

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

Registrar una aplicación en Azure Active Directory

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

  2. Vaya a Azure Active Directory > Inscripciones de la aplicaciónNuevo > registro.

    La sección Nuevo registro en el portal de Microsoft 365 Defender registro

  3. En el formulario de registro, elija un nombre para la aplicación y, a continuación, seleccione Registrar. Seleccionar 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 APIAgregue > permisosAPIs > mi organización usa >, escriba Protección contra amenazas de Microsoft y seleccione Protección contra amenazas de Microsoft. La aplicación ahora puede acceder a Microsoft 365 Defender.

    Sugerencia

    Microsoft Threat Protection es un nombre antiguo para Microsoft 365 Defender y no aparecerá en la lista original. Debe empezar a escribir su nombre en el cuadro de texto para verlo aparecer. Sección de uso de API en el portal de Microsoft 365 Defender web

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

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

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

    Sección Conceder consentimiento de administrador en el portal Microsoft 365 Defender administración

  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 secreto generado. No podrá recuperar el valor secreto después de salir.

    La sección agregar secreto en el portal Microsoft 365 Defender web

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

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

Obtener un token con la aplicación y usar el token para obtener acceso a la API

Para obtener más información sobre Azure Active Directory tokens, consulte el Azure AD tutorial.

Importante

Aunque el ejemplo de esta aplicación de demostración te anima a pegar el valor secreto con fines de prueba, nunca debes codificar los secretos en una aplicación que se ejecute en producción. Un tercero podría usar el secreto para obtener acceso a los recursos. Puedes ayudar a proteger los secretos de la aplicación con Azure Key Vault. Para obtener un ejemplo práctico de cómo proteger la aplicación, consulta Administrar secretos en las aplicaciones de servidor con Azure Key Vault.

  1. Copie el script siguiente y péguelo en el editor de texto favorito. Guardar 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 siguiente sección.

    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 es el token web JSON. 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 siguiente imagen, puedes ver un token descodificado adquirido desde una aplicación, con Incidents.Read.All, Incidents.ReadWrite.Ally AdvancedHunting.Read.All permisos:

    Sección Token descodificado en el portal de Microsoft 365 Defender de datos

Obtener una lista de incidentes recientes

El script siguiente usaráGet-Token.ps1para obtener acceso 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 ha terminado! Ha realizado correctamente lo siguiente:

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