Microsoft Defender voor Eindpunt API - Hallo wereld

Van toepassing op:

• Plan 1 voor Microsoft Defender voor Eindpunt
• Plan 2 voor Microsoft Defender voor Eindpunt

Wilt u Microsoft Defender voor Eindpunt ervaren? Meld u aan voor een gratis proefversie.

Opmerking

Als u een klant van de Amerikaanse overheid bent, gebruikt u de URI's die worden vermeld in Microsoft Defender voor Eindpunt voor klanten van de Amerikaanse overheid.

Tip

Voor betere prestaties kunt u de server dichter bij uw geografische locatie gebruiken:

• 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

Waarschuwingen ophalen met een eenvoudig PowerShell-script

Hoe lang duurt het om dit voorbeeld te doorlopen?

Dit duurt slechts 5 minuten in twee stappen:

• Toepassingsregistratie
• Voorbeelden gebruiken: alleen kopiëren/plakken van een kort PowerShell-script is vereist

Heb ik een machtiging nodig om verbinding te maken?

Voor de fase Toepassingsregistratie moet u een Globale beheerder rol hebben in uw Microsoft Entra-tenant.

Stap 1: een app Creatie in Microsoft Entra ID

1. Meld u aan bij Azure met uw Globale beheerder gebruiker.

2. Navigeer naar Microsoft Entra ID>App-registraties>Nieuwe registratie.

   

3. Kies in het registratieformulier een naam voor uw toepassing en klik vervolgens op Registreren.

4. Geef uw toepassing toegang tot Defender voor Eindpunt en wijs de machtiging Alle waarschuwingen lezen toe :

   • Klik op uw toepassingspagina op API-machtigingenToevoegenmachtigings-API's >>die mijn organisatie gebruikt>, type WindowsDefenderATP en klik op WindowsDefenderATP.

     Opmerking

     WindowsDefenderATP wordt niet weergegeven in de oorspronkelijke lijst. U moet beginnen met het schrijven van de naam in het tekstvak om deze weer te geven.

     

   • Kies Toepassingsmachtigingen>Waarschuwing.Read.All> Klik op Machtigingen toevoegen.

     

     Belangrijk

     U moet de relevante machtigingen selecteren. 'Alle waarschuwingen lezen' is slechts een voorbeeld.

     Bijvoorbeeld:

     • Als u geavanceerde query's wilt uitvoeren, selecteert u de machtiging Geavanceerde query's uitvoeren.
     • Als u een computer wilt isoleren, selecteert u De machtiging Machine isoleren.
     • Als u wilt bepalen welke machtiging u nodig hebt, raadpleegt u de sectie Machtigingen in de API die u wilt aanroepen.

5. Klik op Toestemming verlenen.

   Opmerking

   Telkens wanneer u een machtiging toevoegt, moet u op Toestemming verlenen klikken om de nieuwe machtiging van kracht te laten worden.

   

6. Voeg een geheim toe aan de toepassing.

   Klik op Certificaten & geheimen, voeg een beschrijving toe aan het geheim en klik op Toevoegen.

   Belangrijk

   Nadat u op Toevoegen hebt geklikt, kopieert u de gegenereerde geheime waarde. U kunt niet meer ophalen nadat u weggaat.

   

7. Noteer uw toepassings-id en uw tenant-id.

   Ga op de toepassingspagina naar Overzicht en kopieer het volgende:

   

Gereed! U hebt een aanvraag geregistreerd!

Stap 2: Haal een token op met behulp van de app en gebruik dit token om toegang te krijgen tot de API.

• Kopieer het onderstaande script naar PowerShell ISE of naar een teksteditor en sla het op als Get-Token.ps1.

• Als u dit script uitvoert, wordt een token gegenereerd en wordt het opgeslagen in de werkmap onder de naam 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
  

• Sanity Check:

  • Voer het script uit.
  • Ga in uw browser naar: https://jwt.ms/.
  • Kopieer het token (de inhoud van het Latest-token.txt-bestand).
  • Plak in het bovenste vak.
  • Zoek naar de sectie 'rollen'. Zoek de rol Alert.Read.All .

  

Laten we de waarschuwingen ophalen.

• Het onderstaande script gebruikt Get-Token.ps1 om toegang te krijgen tot de API en krijgt de afgelopen 48 uur waarschuwingen.

• Sla dit script op in dezelfde map waarin u het vorige script hebt opgeslagenGet-Token.ps1.

• Het script maakt twee bestanden (json en CSV) met de gegevens in dezelfde map als de 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
  

Jullie zijn klaar. U hebt zojuist het volgende voltooid:

• Gemaakt en geregistreerd en toepassing
• Toestemming verleend voor die toepassing om waarschuwingen te lezen
• De API verbonden
• Een PowerShell-script gebruikt om waarschuwingen te retourneren die in de afgelopen 48 uur zijn gemaakt

Verwant onderwerp

• Microsoft Defender voor Eindpunt-API's
• Toegang tot Microsoft Defender voor Eindpunt met toepassingscontext
• Toegang tot Microsoft Defender voor Eindpunt met gebruikerscontext

Tip

Wil je meer weten? Engage met de Microsoft Security-community in onze Tech Community: Microsoft Defender voor Eindpunt Tech Community.