API de Microsoft Defender para punto de conexión: Hola mundo

Se aplica a:

• Microsoft Defender para punto de conexión Plan 1
• Microsoft Defender para punto de conexión Plan 2

¿Quiere experimentar Microsoft Defender para punto de conexión? Regístrese para obtener una prueba gratuita.

Nota:

Si es cliente del Gobierno de EE. UU., use los URI que aparecen en Microsoft Defender para punto de conexión para los clientes del Gobierno de EE. UU.

Sugerencia

Para mejorar el rendimiento, puede usar el servidor más cercano a la ubicación geográfica:

• us.api.security.microsoft.com
• eu.api.security.microsoft.com
• uk.api.security.microsoft.com
• au.api.security.microsoft.com
• swa.api.security.microsoft.com

Obtención de alertas mediante un script de PowerShell sencillo

¿Cuánto tiempo se tarda en pasar por este ejemplo?

Solo tarda 5 minutos en realizarse en dos pasos:

• Registro de la aplicación
• Ejemplos de uso: solo se requiere copiar y pegar un script corto de PowerShell

¿Necesito un permiso para conectarme?

Para la fase de registro de la aplicación, debe tener un rol de Administrador global en el inquilino de Microsoft Entra.

Paso 1: Create una aplicación en Microsoft Entra ID

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

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

   

3. En el formulario de registro, elija un nombre para la aplicación y, a continuación, haga clic en Registrar.

4. Permita que la aplicación acceda a Defender para punto de conexión y asígnele el permiso "Leer todas las alertas" :

   • En la página de la aplicación, haga clic en Permisos> de APIAgregar API de permisos>. Mi organización usa>el tipo WindowsDefenderATP y haga clic en WindowsDefenderATP.

     Nota:

     WindowsDefenderATP no aparece en la lista original. Debe empezar a escribir su nombre en el cuadro de texto para verlo aparecer.

     

   • Elija Permisos> de aplicaciónAlert.Read.All> Haga clic en Agregar permisos.

     

     Importante

     Debe seleccionar los permisos pertinentes. "Leer todas las alertas" es solo un ejemplo.

     Por ejemplo:

     • Para ejecutar consultas avanzadas, seleccione el permiso "Ejecutar consultas avanzadas".
     • Para aislar una máquina, seleccione el permiso "Aislar máquina".
     • Para determinar qué permiso necesita, consulte la sección Permisos de la API a la que está interesado llamar.

5. Haga clic en Conceder consentimiento.

   Nota:

   Cada vez que agregue permiso, debe hacer clic en Conceder consentimiento para que el nuevo permiso surta efecto.

   

6. Agregue un secreto a la aplicación.

   Haga clic en Certificados & secretos, agregue una descripción al secreto y haga clic en Agregar.

   Importante

   Después de hacer clic en Agregar, copie el valor de secreto generado. ¡No podrás recuperarlo después de irte!

   

7. Anote el identificador de la aplicación y el identificador de inquilino.

   En la página de la aplicación, vaya a Información general y copie lo siguiente:

   

¡Listo! Ha registrado correctamente una aplicación.

Paso 2: Obtener un token mediante la aplicación y usar este token para acceder a la API.

• Copie el script siguiente en PowerShell ISE o en un editor de texto y guárdelo como Get-Token.ps1.

• La ejecución de este script generará un token y lo guardará en la carpeta de trabajo con el nombre Latest-token.txt.

  # That code gets the App Context Token and save it to a file named "Latest-token.txt" under the current directory
  # Paste below your Tenant ID, App ID and App Secret (App key).
  
  $tenantId = '' ### Paste your tenant ID here
  $appId = '' ### Paste your Application ID here
  $appSecret = '' ### Paste your Application secret here
  
  $resourceAppIdUri = 'https://api.securitycenter.microsoft.com'
  $oAuthUri = "https://login.microsoftonline.com/$TenantId/oauth2/token"
  $authBody = [Ordered] @{
       resource = "$resourceAppIdUri"
       client_id = "$appId"
       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
  

• Comprobación de integridad:

  • Ejecute el script.
  • En el explorador, vaya a: https://jwt.ms/.
  • Copie el token (el contenido del archivo Latest-token.txt).
  • Pegue en el cuadro superior.
  • Busque la sección "roles". Busque el rol Alert.Read.All .

  

¡Vamos a obtener las alertas!

• El script siguiente usará Get-Token.ps1 para acceder a la API y obtendrá las alertas de las últimas 48 horas.

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

• El script crea dos archivos (json y csv) con los datos en la misma carpeta que los scripts.

  # Returns Alerts created in the past 48 hours.
  
  $token = ./Get-Token.ps1       #run the script Get-Token.ps1  - make sure you are running this script from the same folder of Get-Token.ps1
  
  # Get Alert from the last 48 hours. Make sure you have alerts in that time frame.
  $dateTime = (Get-Date).ToUniversalTime().AddHours(-48).ToString("o")
  
  # The URL contains the type of query and the time filter we create above
  # Read more about [other query options and filters](get-alerts.md).
  $url = "https://api.securitycenter.microsoft.com/api/alerts?`$filter=alertCreationTime ge $dateTime"
  
  # Set the WebRequest headers
  $headers = @{
      'Content-Type' = 'application/json'
      Accept = 'application/json'
      Authorization = "Bearer $token"
  }
  
  # Send the webrequest and get the results.
  $response = Invoke-WebRequest -Method Get -Uri $url -Headers $headers -ErrorAction Stop
  
  # Extract the alerts from the results.
  $alerts =  ($response | ConvertFrom-Json).value | ConvertTo-Json
  
  # Get string with the execution time. We concatenate that string to the output file to avoid overwrite the file
  $dateTimeForFileName = Get-Date -Format o | foreach {$_ -replace ":", "."}
  
  # Save the result as json and as csv
  $outputJsonPath = "./Latest Alerts $dateTimeForFileName.json"
  $outputCsvPath = "./Latest Alerts $dateTimeForFileName.csv"
  
  Out-File -FilePath $outputJsonPath -InputObject $alerts
  ($alerts | ConvertFrom-Json) | Export-CSV $outputCsvPath -NoTypeInformation
  

¡Ya has terminado! Acaba de tener éxito:

• Creación y registro y aplicación
• Se ha concedido permiso para que esa aplicación lea alertas.
• Conexión de la API
• Se ha usado un script de PowerShell para devolver las alertas creadas en las últimas 48 horas.

Tema relacionado

• API de Microsoft Defender para punto de conexión
• Acceso a Microsoft Defender para punto de conexión con contexto de aplicación
• Acceso a Microsoft Defender para punto de conexión con el contexto de usuario

Sugerencia

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