Delen via

Hallo wereld voor Microsoft Defender XDR REST API

  • Artikel

Van toepassing op:

  • Microsoft Defender XDR

Belangrijk

Sommige informatie is gerelateerd aan voorlopige productversies die mogelijk aanzienlijk gewijzigd worden voordat ze commercieel gepubliceerd worden. Microsoft geeft geen garantie, uitdrukkelijk of impliciet, met betrekking tot de informatie die hier wordt beschreven.

Incidenten ophalen met behulp van een eenvoudig PowerShell-script

Het duurt 5 tot 10 minuten om dit project te voltooien. Deze tijdsraming omvat het registreren van de toepassing en het toepassen van de code uit het PowerShell-voorbeeldscript.

Een app registreren in Microsoft Entra ID

  1. Meld u als gebruiker aan bij Azure met de rol Globale beheerder.

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

    De sectie Nieuwe registratie in de Microsoft Defender-portal

  3. Kies in het registratieformulier een naam voor uw toepassing en selecteer vervolgens Registreren. Het selecteren van een omleidings-URI is optioneel. U hebt er geen nodig om dit voorbeeld te voltooien.

  4. Selecteer op uw toepassingspagina API-machtigingenToevoegenmachtigings-API's >> diemijn organisatie gebruikt>, typ Microsoft Threat Protection en selecteer Microsoft Threat Protection. Uw app heeft nu toegang tot Microsoft Defender XDR.

    Tip

    Microsoft Threat Protection is een voormalige naam voor Microsoft Defender XDR en 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 sectie over het gebruik van API's in de Microsoft Defender-portal

    • Kies Toepassingsmachtigingen>Incident.Read.All en selecteer Machtigingen toevoegen.

      Het deelvenster Machtigingen van een toepassing in de Microsoft Defender-portal

  5. Selecteer Beheerderstoestemming verlenen. Telkens wanneer u een machtiging toevoegt, moet u Beheerderstoestemming verlenen selecteren om deze van kracht te laten worden.

    De sectie Beheerderstoestemming verlenen in de Microsoft Defender portal

  6. Voeg een geheim toe aan de toepassing. Selecteer Certificaten & geheimen, voeg een beschrijving toe aan het geheim en selecteer vervolgens Toevoegen.

    Tip

    Nadat u Toevoegen hebt geselecteerd, selecteert u de gegenereerde geheime waarde kopiëren. U kunt de geheime waarde niet meer ophalen nadat u bent weg gelaten.

    De sectie Geheim toevoegen in de Microsoft Defender-portal

  7. Noteer uw toepassings-id en uw tenant-id ergens veilig. Ze worden weergegeven onder Overzicht op de pagina van uw toepassing.

    De sectie Overzicht in de Microsoft Defender-portal

Een token ophalen met behulp van de app en het token gebruiken om toegang te krijgen tot de API

Zie de zelfstudie Microsoft Entra voor meer informatie over Microsoft Entra tokens.

Belangrijk

Hoewel het voorbeeld in deze demo-app u aanmoedigt om uw geheime waarde te plakken voor testdoeleinden, moet u geheimen nooit hardcoderen in een toepassing die in productie wordt uitgevoerd. Een derde partij kan uw geheim gebruiken om toegang te krijgen tot resources. U kunt de geheimen van uw app beveiligen met behulp van Azure Key Vault. Zie Geheimen in uw server-apps beheren met Azure Key Vault voor een praktisch voorbeeld van hoe u uw app kunt beveiligen.

  1. Kopieer het onderstaande script en plak het in uw favoriete teksteditor. Opslaan als Get-Token.ps1. U kunt de code ook as-is uitvoeren in PowerShell ISE, maar u moet deze opslaan, omdat we deze opnieuw moeten uitvoeren wanneer we het script voor het ophalen van incidenten in de volgende sectie gebruiken.

    Met dit script wordt een token gegenereerd en opgeslagen in de werkmap onder de naam 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

Het token valideren

  1. Kopieer en plak het token dat u hebt ontvangen in JWT om het te decoderen.

  2. JWT staat voor JSON-webtoken. Het gedecodeerde token bevat een aantal items of claims in JSON-indeling. Zorg ervoor dat de rollenclaim binnen het gedecodeerde token de gewenste machtigingen bevat.

    In de volgende afbeelding ziet u een gedecodeerd token dat is verkregen uit een app, met Incidents.Read.Allmachtigingen , Incidents.ReadWrite.Allen AdvancedHunting.Read.All :

    De sectie Gedecoded Token in de Microsoft Defender-portal

Een lijst met recente incidenten ophalen

In het onderstaande script wordt Get-Token.ps1 gebruikt om toegang te krijgen tot de API. Vervolgens wordt een lijst met incidenten opgehaald die de afgelopen 48 uur voor het laatst zijn bijgewerkt en wordt de lijst opgeslagen als een JSON-bestand.

Belangrijk

Sla dit script op in dezelfde map die u hebt opgeslagenGet-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

Jullie zijn klaar. U hebt het volgende gedaan:

  • Een toepassing gemaakt en geregistreerd.
  • Toestemming verleend voor die toepassing om waarschuwingen te lezen.
  • Verbonden met de API.
  • Een PowerShell-script gebruikt om incidenten te retourneren die in de afgelopen 48 uur zijn bijgewerkt.

Tip

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