Udostępnij za pośrednictwem

Interfejs API usługi Microsoft Defender dla punktów końcowych — Hello World

  • Artykuł

Dotyczy:

Chcesz poznać usługę ochrony punktu końcowego w usłudze Microsoft Defender? Utwórz konto, aby skorzystać z bezpłatnej wersji próbnej.

Uwaga

Jeśli jesteś klientem rządowym USA, użyj identyfikatorów URI wymienionych w usłudze Microsoft Defender for Endpoint dla klientów rządowych USA.

Porada

Aby uzyskać lepszą wydajność, możesz użyć serwera bliżej lokalizacji geograficznej:

  • 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

Pobieranie alertów przy użyciu prostego skryptu programu PowerShell

Jak długo trwa przechodzenie przez ten przykład?

Trwa to tylko 5 minut w dwóch krokach:

  • Rejestracja aplikacji
  • Przykłady użycia: wymaga tylko kopiowania/wklejania krótkiego skryptu programu PowerShell

Czy potrzebuję uprawnienia do nawiązywania połączenia?

Na etapie rejestracji aplikacji musisz mieć przypisaną rolę administratora globalnego w dzierżawie usługi Microsoft Entra.

Krok 1. Tworzenie aplikacji w usłudze Microsoft Entra ID

  1. Zaloguj się do witryny Azure Portal.

  2. Przejdź do obszaruRejestracje> aplikacji Microsoft Entra ID>Nowa rejestracja.

    Opcja Rejestracje aplikacji w okienku Zarządzanie w centrum administracyjnym usługi Microsoft Entra

  3. W formularzu rejestracji wybierz nazwę aplikacji, a następnie wybierz pozycję Zarejestruj.

  4. Zezwalaj aplikacji na dostęp do usługi Defender for Endpoint i przypisz jej uprawnienie "Odczyt wszystkich alertów" :

    • Na stronie aplikacji wybierz pozycję Uprawnienia interfejsu API Dodaj interfejsy> APIuprawnień>,których moja organizacja używa> typu WindowsDefenderATP, a następnie wybierz pozycję WindowsDefenderATP.

      Uwaga

      WindowsDefenderATP nie jest wyświetlany na oryginalnej liście. Aby je wyświetlić, musisz zacząć pisać jego nazwę w polu tekstowym.

      Opcja Uprawnienia interfejsu API w okienku Zarządzanie w centrum administracyjnym usługi Microsoft Entra

    • Wybierz pozycję Uprawnienia> aplikacjiAlert.Read.All, a następnie wybierz pozycję Dodaj uprawnienia.

      Okienka typów uprawnień i ustawień na stronie Żądania uprawnień interfejsu API

      Ważna

      Musisz wybrać odpowiednie uprawnienia. Odczyt wszystkich alertów jest tylko przykładem.

      Przykład:

  5. Wybierz pozycję Udziel zgody.

    Uwaga

    Za każdym razem, gdy dodasz uprawnienie, musisz kliknąć pozycję Udziel zgody , aby nowe uprawnienie weszło w życie.

    Opcja udzielania zgody na uprawnienia w centrum administracyjnym usługi Microsoft Entra

  6. Dodaj wpis tajny do aplikacji.

    Wybierz pozycję Certyfikaty & wpisów tajnych, dodaj opis do wpisu tajnego i wybierz pozycję Dodaj.

    Ważna

    Po kliknięciu przycisku Dodaj skopiuj wygenerowaną wartość wpisu tajnego. Nie będzie można pobrać po opuszczeniu!

    Element menu Certyfikaty & wpisów tajnych w okienku Zarządzanie w centrum administracyjnym usługi Microsoft Entra

  7. Zapisz identyfikator aplikacji i identyfikator dzierżawy.

    Na stronie aplikacji przejdź do pozycji Przegląd i skopiuj następujące elementy:

    Okienko szczegółów aplikacji w elemencie menu Przegląd w centrum administracyjnym usługi Microsoft Entra

Ukończono! Aplikacja została pomyślnie zarejestrowana!

Krok 2. Uzyskiwanie tokenu przy użyciu aplikacji i używanie tego tokenu do uzyskiwania dostępu do interfejsu API.

  • Skopiuj następujący skrypt do programu PowerShell ISE lub do edytora tekstów i zapisz go jako Get-Token.ps1.

  • Uruchomienie tego skryptu powoduje wygenerowanie tokenu i zapisanie go w folderze roboczym pod nazwą 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

  • Sprawdzanie kondycji:

    • Uruchom skrypt.
    • W przeglądarce przejdź do: https://jwt.ms/.
    • Skopiuj token (zawartość pliku Latest-token.txt).
    • Wklej w górnym polu.
    • Poszukaj sekcji "role". Znajdź rolę Alert.Read.All .

    Okienko Token dekodowany dla jwt.ms

Pobierzmy alerty!

  • Poniższy skrypt służy Get-Token.ps1 do uzyskiwania dostępu do interfejsu API i pobiera alerty z ostatnich 48 godzin.

  • Zapisz ten skrypt w tym samym folderze, w który zapisano poprzedni skrypt Get-Token.ps1.

  • Skrypt tworzy dwa pliki (json i csv) z danymi w tym samym folderze co skrypty.

    # 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

Wszystko gotowe! Pomyślnie:

  • Utworzone i zarejestrowane oraz aplikacja
  • Udzielono tej aplikacji uprawnień do odczytywania alertów
  • Połączono interfejs API
  • Używany skrypt programu PowerShell do zwracania alertów utworzonych w ciągu ostatnich 48 godzin

Porada

Chcesz dowiedzieć się więcej? Skontaktuj się ze społecznością zabezpieczeń firmy Microsoft w naszej społeczności technicznej: Microsoft Defender for Endpoint Tech Community.