Microsoft Defender for Endpoint API – Hello World

Gælder for:

• Microsoft Defender for Endpoint Plan 1
• Microsoft Defender for Endpoint Plan 2

Vil du opleve Microsoft Defender for Endpoint? Tilmeld dig en gratis prøveversion.

Bemærk!

Hvis du er us government-kunde, skal du bruge de URI'er, der er angivet i Microsoft Defender for Endpoint for us Government-kunder.

Tip

For at opnå en bedre ydeevne kan du bruge serveren tættere på din geografiske placering:

• 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

Få beskeder ved hjælp af et simpelt PowerShell-script

Hvor lang tid tager det at gennemgå dette eksempel?

Det tager kun 5 minutter udført i to trin:

• Programregistrering
• Brug eksempler: Kræver kun kopiering/indsættelse af et kort PowerShell-script

Skal jeg have tilladelse til at oprette forbindelse?

I fasen Programregistrering skal du have en Global administrator rolle i din Microsoft Entra lejer.

Trin 1 – Create en app i Microsoft Entra ID

1. Log på Azure med din Global administrator bruger.

2. Gå til Microsoft Entra ID>Appregistreringer>Ny registrering.

   

3. Vælg et navn til din ansøgning i registreringsformularen, og klik derefter på Registrer.

4. Tillad, at dit program får adgang til Defender for Endpoint, og tildel det tilladelsen "Læs alle beskeder" :

   • På programsiden skal du klikke på API-tilladelser>TilføjtilladelseS-API'er>, som min organisation bruger > til at skrive WindowsDefenderATP og klikke på WindowsDefenderATP.

     Bemærk!

     WindowsDefenderATP vises ikke på den oprindelige liste. Du skal begynde at skrive navnet i tekstfeltet for at se det blive vist.

     

   • Vælg Programtilladelser>Alert.Read.All> Klik på Tilføj tilladelser.

     

     Vigtigt!

     Du skal vælge de relevante tilladelser. 'Læs alle beskeder' er kun et eksempel!

     Det kan f.eks. være:

     • Hvis du vil køre avancerede forespørgsler, skal du vælge tilladelsen 'Kør avancerede forespørgsler'.
     • Hvis du vil isolere en computer, skal du vælge tilladelsen "Isoler computer".
     • Hvis du vil finde ud af, hvilken tilladelse du har brug for, skal du se afsnittet Tilladelser i den API, du er interesseret i at kalde.

5. Klik på Giv samtykke.

   Bemærk!

   Hver gang du tilføjer tilladelse, skal du klikke på Giv samtykke , for at den nye tilladelse træder i kraft.

   

6. Føj en hemmelighed til programmet.

   Klik på Certifikater & hemmeligheder, føj en beskrivelse til hemmeligheden, og klik på Tilføj.

   Vigtigt!

   Når du har klikket på Tilføj, skal du kopiere den genererede værdi for hemmeligheden. Du vil ikke være i stand til at hente efter du forlader!

   

7. Skriv dit program-id og dit lejer-id ned.

   Gå til Oversigt på din programside, og kopiér følgende:

   

Gjort! Du har registreret et program!

Trin 2 – Hent et token ved hjælp af appen, og brug dette token til at få adgang til API'en.

• Kopiér scriptet nedenfor til PowerShell ISE eller til en teksteditor, og gem det som Get-Token.ps1.

• Hvis du kører dette script, oprettes der et token, og det gemmes i arbejdsmappen under navnet 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
  

• Sanitetskontrol:

  • Kør scriptet.
  • I din browser skal du gå til: https://jwt.ms/.
  • Kopiér tokenet (indholdet af Latest-token.txt-filen).
  • Indsæt i det øverste felt.
  • Se efter afsnittet "roller". Find rollen Alert.Read.All .

  

Lad os få beskederne!

• Scriptet nedenfor bruger Get-Token.ps1 til at få adgang til API'en og får de seneste 48 timers beskeder.

• Gem dette script i den samme mappe, som du gemte det forrige script Get-Token.ps1.

• Scriptet opretter to filer (json og csv) med dataene i samme mappe som 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
  

Du er færdig! Du har lige oprettet:

• Oprettet og registreret samt program
• Tildelt tilladelse til, at programmet kan læse beskeder
• Oprettede forbindelse til API'en
• Brugte et PowerShell-script til at returnere beskeder, der er oprettet inden for de seneste 48 timer

Relateret emne

• Microsoft Defender for Endpoint API'er
• Adgang Microsoft Defender for Endpoint med programkontekst
• Adgang Microsoft Defender for Endpoint med brugerkontekst

Tip

Vil du vide mere? Engage med Microsoft Security-community'et i vores tech-community: Microsoft Defender for Endpoint Tech Community.