Microsoft Defender för slutpunkts-API – Hello World
Gäller för:
Vill du uppleva Microsoft Defender för Endpoint? Registrera dig för en kostnadsfri utvärderingsversion.
Anteckning
Om du är myndighetskund i USA kan du använda de URI:er som visas i Microsoft Defender för Slutpunkt för kunder inom myndigheter i USA.
Tips
För bättre prestanda kan du använda servern närmare din geografiska plats:
- api-us.securitycenter.microsoft.com
- api-eu.securitycenter.microsoft.com
- api-uk.securitycenter.microsoft.com
Få aviseringar med ett enkelt PowerShell-skript
Hur lång tid tar det att gå igenom det här exemplet?
Det tar bara 5 minuter att göra i två steg:
- Appregistrering
- Använd exempel: kräver endast kopiera/klistra in ett kort PowerShell-skript
Behöver jag behörighet för att ansluta?
För registreringssteget för program måste du ha en global administratörsroll i Azure Active Directory klientorganisationen (Azure AD).
Steg 1 – Skapa ett program i Azure Active Directory
Logga in på Azure med den globala administratörsanvändaren.
Gå till Azure Active Directory > Appregistreringar > Ny registrering.
I registreringsformuläret väljer du ett namn på din ansökan och klickar sedan på Registrera.
Tillåt att programmet får åtkomst till Defender för Endpoint och tilldela behörigheten Läs alla aviseringar:
På programsidan klickar du på API-behörigheter Lägg till behörighetS-API:er som min organisation använder för > > > WindowsDefenderATP och klickar på WindowsDefenderATP.
Anteckning
WindowsDefenderATP visas inte i den ursprungliga listan. Du måste börja skriva namnet i textrutan för att det ska visas.
Välj Avisering om > programbehörigheter.Read.All > Klicka på Lägg till behörigheter.
Viktigt
Du måste välja rätt behörighet. "Läs alla aviseringar" är bara ett exempel!
Till exempel:
- Om du vill köra avanceradefrågor väljer du behörigheten Kör avancerade frågor.
- Om du vill isolera endator väljer du behörigheten Isolera dator.
- Ta reda på vilken behörighet du behöver i avsnittet Behörigheter i det API du är intresserad av att anropa.
Klicka på Bevilja medgivande.
Anteckning
Varje gång du lägger till behörighet måste du klicka på Ge medgivande för att den nya behörigheten ska gälla.

Gör programmet hemligt.
Klicka på Certifikat & , lägg till en beskrivning av hemligheten och klicka på Lägg till.
Viktigt
Efter att ha klickat på Lägg till kopierar du det genererade hemliga värdet. Du kan inte hämta igen när du har lämnat!

Skriv ned ditt program-ID och ditt klient-ID.
Gå till Översikt på programsidan och kopiera följande:

Klart! Du har registrerat ett program!
Steg 2 – Hämta en token med appen och använd denna token för att få åtkomst till API:t.
Kopiera skriptet nedan till PowerShell ISE eller en textredigerare och spara den som Get-Token.ps1.
När du kör det här skriptet genereras en token och sparar den i arbetsmappen under namnetLatest-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 $tokenSanity Check:
- Kör skriptet.
- Öppna webbläsaren och gå till: https://jwt.ms/ .
- Kopiera tokenet (innehållet i Latest-token.txt filen).
- Klistra in i den övre rutan.
- Titta efter avsnittet "roller". Leta reda på rollen Avisering.Läs.Alla.
Låt oss få aviseringarna!
Skriptet nedan använder en Get-Token.ps1 för att få åtkomst till API:et och får aviseringar under de senaste 48 timmarna.
Spara skriptet i samma mapp som du sparade föregående skript Get-Token.ps1.
Skriptet skapar två filer (json och CSV) med data i samma mapp som skripten.
# 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 at Https://TBD- add the documentation link $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
Nu är allt klart! Du har just lyckats:
- Skapad och registrerad och program
- Beviljad behörighet för det programmet att läsa aviseringar
- Anslöt API:t
- Använde ett PowerShell-skript för att returnera aviseringar som skapats de senaste 48 timmarna