Hello World para la API Microsoft 365 REST de DefenderHello World for Microsoft 365 Defender REST API

Importante

El Centro de seguridad de Microsoft 365 mejorado está ahora disponible.The improved Microsoft 365 security center is now available. Esta nueva experiencia incluye Defender para punto de conexión, Defender para Office 365, Microsoft 365 Defender y más en el Centro de seguridad de Microsoft 365.This new experience brings Defender for Endpoint, Defender for Office 365, Microsoft 365 Defender, and more into the Microsoft 365 security center. Ver las novedades.Learn what's new.

Se aplica a:Applies to:

  • Microsoft 365 DefenderMicrosoft 365 Defender

Importante

Parte de la información se refiere a productos preliminares que pueden ser modificados sustancialmente antes de su lanzamiento comercial.Some information relates to prereleased product which may be substantially modified before it's commercially released. Microsoft no otorga garantías, expresas o implícitas, con respecto a la información que aquí se proporciona.Microsoft makes no warranties, express or implied, with respect to the information provided here.

Obtener incidentes con un script de PowerShell simpleGet incidents using a simple PowerShell script

Este proyecto debe tardar entre 5 y 10 minutos.It should take 5 to 10 minutes to complete this project. Esta estimación de tiempo incluye registrar la aplicación y aplicar el código desde el script de ejemplo de PowerShell.This time estimate includes registering the application, and applying the code from the PowerShell sample script.

Registrar una aplicación en Azure Active DirectoryRegister an app in Azure Active Directory

  1. Inicie sesión en Azure como usuario con el rol De administrador global.Sign in to Azure as a user with the Global administrator role.

  2. Vaya a Azure Active Directory > registros de aplicaciones Nuevo > registro.Navigate to Azure Active Directory > App registrations > New registration.

    Imagen de Microsoft Azure navegación al registro de aplicaciones

  3. En el formulario de registro, elija un nombre para la aplicación y, a continuación, seleccione Registrar.In the registration form, choose a name for your application, then select Register. Seleccionar un URI de redireccionamiento es opcional.Selecting a redirect URI is optional. No necesitará uno para completar este ejemplo.You won't need one to complete this example.

  4. En la página de la aplicación, seleccione Permisos de API Agregar API de permisos que mi organización usa > > >, escriba Protección contra amenazas de Microsoft y seleccione Protección contra amenazas de Microsoft.On your application page, select API Permissions > Add permission > APIs my organization uses >, type Microsoft Threat Protection, and select Microsoft Threat Protection. La aplicación ahora puede acceder a Microsoft 365 Defender.Your app can now access Microsoft 365 Defender.

    Sugerencia

    Protección contra amenazas de Microsoft es un nombre antiguo de Microsoft 365 Defender y no aparecerá en la lista original.Microsoft Threat Protection is a former name for Microsoft 365 Defender, and will not appear in the original list. Debe empezar a escribir su nombre en el cuadro de texto para verlo aparecer.You need to start writing its name in the text box to see it appear. Imagen de selección de permisos de APIImage of API permission selection

    • Elija Permisos de aplicación > Incident.Read.All y seleccione Agregar permisos.Choose Application permissions > Incident.Read.All and select Add permissions.

    Imagen de acceso a api y selección de API

  5. Seleccione Conceder consentimiento de administrador.Select Grant admin consent. Cada vez que agregue un permiso, debe seleccionar Conceder consentimiento de administrador para que su efecto.Every time you add a permission, you must select Grant admin consent for it to take effect.

    Imagen de concesión de permisos

  6. Agregue un secreto a la aplicación.Add a secret to the application. Seleccione Certificados & secretos, agregue una descripción al secreto y, a continuación, seleccione Agregar.Select Certificates & secrets, add a description to the secret, then select Add.

    Sugerencia

    Después de seleccionar Agregar, seleccione copiar el valor secreto generado.After you select Add, select copy the generated secret value. No podrá recuperar el valor secreto después de salir.You won't be able to retrieve the secret value after you leave.

    Imagen de crear clave de aplicación

  7. Registre el identificador de la aplicación y el identificador de inquilino en un lugar seguro.Record your application ID and your tenant ID somewhere safe. Aparecen en Información general en la página de la aplicación.They're listed under Overview on your application page.

    Imagen del identificador de aplicación creado

Obtener un token con la aplicación y usar el token para obtener acceso a la APIGet a token using the app and use the token to access the API

Para obtener más información sobre Azure Active Directory tokens, consulte el tutorial de Azure AD.For more information on Azure Active Directory tokens, see the 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.Although the example in this demo app encourage you to paste in your secret value for testing purposes, you should never hardcode secrets into an application running in production. Un tercero podría usar el secreto para obtener acceso a los recursos.A third party could use your secret to access resources. Puedes ayudar a proteger los secretos de la aplicación con Azure Key Vault.You can help keep your app's secrets secure by using 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.For a practical example of how you can protect your app, see Manage secrets in your server apps with Azure Key Vault.

  1. Copie el script siguiente y péguelo en el editor de texto favorito.Copy the script below and paste it into your favorite text editor. Guardar como Get-Token.ps1.Save as 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.You can also run the code as-is in PowerShell ISE, but you should save it, because we'll need to run it again when we use the incident-fetching script in the next section.

    Este script generará un token y lo guardará en la carpeta de trabajo bajo el nombre, Latest-token.txt.This script will generate a token and save it in the working folder under the name, 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 tokenValidate the token

  1. Copie y pegue el token que recibió en JWT para descodificarlo.Copy and paste the token you received into JWT to decode it.

  2. JWT significa token web JSON.JWT stands for JSON Web Token. El token descodificado contendrá una serie de notificaciones o elementos con formato JSON.The decoded token will contain a number of JSON-formatted items or claims. Asegúrese de que la notificación de roles dentro del token descodificado contiene los permisos deseados.Make sure that the roles claim within the decoded token contains the desired permissions.

    En la siguiente imagen, puedes ver un token descodificado adquirido desde una aplicación, con Incidents.Read.All , Incidents.ReadWrite.All y AdvancedHunting.Read.All permisos:In the following image, you can see a decoded token acquired from an app, with Incidents.Read.All, Incidents.ReadWrite.All, and AdvancedHunting.Read.All permissions:

    Imagen jwt.ms

Obtener una lista de incidentes recientesGet a list of recent incidents

El script siguiente usará Get-Token.ps1para obtener acceso a la API.The script below will use Get-Token.ps1 to access the 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.It then retrieves a list of incidents that were last updated within the past 48 hours, and saves the list as a JSON file.

Importante

Guarde este script en la misma carpeta que guardóGet-Token.ps1.Save this script in the same folder you saved 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!You're all done! Ha realizado correctamente lo siguiente:You've successfully:

  • Creó y registró una aplicación.Created and registered an application.
  • Se ha concedido permiso para que esa aplicación lea alertas.Granted permission for that application to read alerts.
  • Conectado a la API.Connected to the API.
  • Se usó un script de PowerShell para devolver incidentes actualizados en las últimas 48 horas.Used a PowerShell script to return incidents updated in the past 48 hours.