Delen via

Microsoft Defender voor Eindpunt API - Hallo wereld

  • Artikel

Van toepassing op:

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
  • ina.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 registratiefase van de toepassing moet een geschikte rol zijn toegewezen in uw Microsoft Entra-tenant. Zie Machtigingsopties voor meer informatie over rollen.

Stap 1: een app maken in Microsoft Entra ID

  1. Meld u aan bij Azure Portal.

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

    De optie App-registraties onder het deelvenster Beheren in de Microsoft Entra-beheercentrum

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

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

    • Selecteer op de toepassingspagina API-machtigingenToevoegenmachtigings-API's >>die mijn organisatie gebruikt> het type WindowsDefenderATP en selecteer 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.

      De optie API-machtigingen onder het deelvenster Beheren in de Microsoft Entra-beheercentrum

    • Kies Toepassingsmachtigingen>Waarschuwing.Read.All en selecteer vervolgens Machtigingen toevoegen.

      De deelvensters machtigingstype en instellingen op de pagina API-machtigingen aanvragen

      Belangrijk

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

      Bijvoorbeeld:

  5. Selecteer Toestemming verlenen.

    Opmerking

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

    De optie toestemming verlenen in de Microsoft Entra-beheercentrum

  6. Voeg een geheim toe aan de toepassing.

    Selecteer Certificaten & geheimen, voeg een beschrijving toe aan het geheim en selecteer Toevoegen.

    Belangrijk

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

    Het menu-item Certificaten & geheimen in het deelvenster Beheren in de Microsoft Entra-beheercentrum

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

    Ga op de toepassingspagina naar Overzicht en kopieer het volgende:

    Het deelvenster toepassingsdetails onder het menu-item Overzicht in de Microsoft Entra-beheercentrum

Gereed! U hebt een toepassing 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 volgende 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 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 .

    Het deelvenster Gedecoded Token voor jwt.ms

Laten we de waarschuwingen ophalen.

  • Het volgende script gebruikt Get-Token.ps1 voor toegang tot de API en ontvangt waarschuwingen voor de afgelopen 48 uur.

  • Sla dit script op in de map waarin u het vorige script Get-Token.ps1hebt opgeslagen.

  • 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 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

Tip

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