Hello world interfejsu API REST Microsoft Defender XDR

  • Artykuł

Dotyczy:

  • Microsoft Defender XDR

Ważna

Niektóre informacje odnoszą się do wstępnie wydanego produktu, który może zostać znacząco zmodyfikowany przed jego komercyjną premierą. Firma Microsoft nie udziela żadnych gwarancji, wyraźnych ani dorozumianych, w odniesieniu do podanych tutaj informacji.

Pobieranie zdarzeń przy użyciu prostego skryptu programu PowerShell

Ukończenie tego projektu powinno potrwać od 5 do 10 minut. Tym razem oszacowanie obejmuje zarejestrowanie aplikacji i zastosowanie kodu z przykładowego skryptu programu PowerShell.

Rejestrowanie aplikacji w Tożsamość Microsoft Entra

  1. Zaloguj się do platformy Azure jako użytkownik z rolą administrator globalny.

  2. Przejdź do Tożsamość Microsoft Entra>Rejestracje aplikacji>Nowa rejestracja.

    Sekcja Nowa rejestracja w portalu Microsoft Defender

  3. W formularzu rejestracji wybierz nazwę aplikacji, a następnie wybierz pozycję Zarejestruj. Wybranie identyfikatora URI przekierowania jest opcjonalne. Nie będzie potrzebny do ukończenia tego przykładu.

  4. Na stronie aplikacji wybierz pozycję Uprawnienia interfejsu APIDodaj interfejsy> API uprawnień > używane przez >moją organizację, wpisz Microsoft Threat Protection i wybierz pozycję Microsoft Threat Protection. Aplikacja może teraz uzyskiwać dostęp do Microsoft Defender XDR.

    Porada

    Usługa Microsoft Threat Protection jest poprzednią nazwą Microsoft Defender XDR i nie będzie wyświetlana na oryginalnej liście. Aby je wyświetlić, musisz zacząć pisać jego nazwę w polu tekstowym. Sekcja użycia interfejsów API w portalu Microsoft Defender

    • Wybierz pozycję Uprawnienia> aplikacjiIncident.Read.All i wybierz pozycję Dodaj uprawnienia.

      Okienko uprawnień aplikacji w portalu Microsoft Defender

  5. Wybierz pozycję Udziel zgody administratora. Za każdym razem, gdy dodasz uprawnienie, musisz wybrać opcję Udziel zgody administratora , aby ta zgoda weszła w życie.

    Sekcja Udzielanie zgody administratora w portalu Microsoft Defender

  6. Dodaj wpis tajny do aplikacji. Wybierz pozycję Certyfikaty & wpisy tajne, dodaj opis do wpisu tajnego, a następnie wybierz pozycję Dodaj.

    Porada

    Po wybraniu pozycji Dodaj wybierz pozycję Skopiuj wygenerowaną wartość wpisu tajnego. Nie będzie można pobrać wartości wpisu tajnego po opuszczeniu.

    Sekcja dodawania wpisu tajnego w portalu Microsoft Defender

  7. Zarejestruj identyfikator aplikacji i identyfikator dzierżawy w bezpiecznym miejscu. Są one wyświetlane w obszarze Przegląd na stronie aplikacji.

    Sekcja Przegląd w portalu Microsoft Defender

Uzyskiwanie tokenu przy użyciu aplikacji i używanie tokenu w celu uzyskania dostępu do interfejsu API

Aby uzyskać więcej informacji na temat tokenów Microsoft Entra, zobacz samouczek Microsoft Entra.

Ważna

Chociaż przykład w tej aplikacji demonstracyjnej zachęca do wklejania wartości wpisu tajnego do celów testowych, nigdy nie należy kodować wpisów tajnych do aplikacji działającej w środowisku produkcyjnym. Inna firma może użyć Twojego wpisu tajnego do uzyskania dostępu do zasobów. Możesz pomóc w zabezpieczeniu wpisów tajnych aplikacji przy użyciu usługi Azure Key Vault. Praktyczny przykład sposobu ochrony aplikacji można znaleźć w temacie Zarządzanie wpisami tajnymi w aplikacjach serwera przy użyciu usługi Azure Key Vault.

  1. Skopiuj poniższy skrypt i wklej go do ulubionego edytora tekstów. Zapisz jako Get-Token.ps1. Możesz również uruchomić kod tak, jak jest w programie PowerShell ISE, ale należy go zapisać, ponieważ będziemy musieli uruchomić go ponownie, gdy użyjemy skryptu pobierania zdarzeń w następnej sekcji.

    Ten skrypt wygeneruje token i zapisze go w folderze roboczym pod nazwą 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

Weryfikowanie tokenu

  1. Skopiuj i wklej otrzymany token do narzędzia JWT, aby go odkodować.

  2. JWT to skrót od JSON Web Token. Zdekodowany token będzie zawierać wiele elementów lub oświadczeń sformatowanych w formacie JSON. Upewnij się, że oświadczenia ról w ramach dekodowanego tokenu zawierają żądane uprawnienia.

    Na poniższej ilustracji widać dekodowany token uzyskany z aplikacji z Incidents.Read.Alluprawnieniami , Incidents.ReadWrite.Alli :AdvancedHunting.Read.All

    Sekcja Token dekodowany w portalu Microsoft Defender

Pobieranie listy ostatnio używanych zdarzeń

Poniższy skrypt użyje Get-Token.ps1 , aby uzyskać dostęp do interfejsu API. Następnie pobiera listę zdarzeń, które zostały ostatnio zaktualizowane w ciągu ostatnich 48 godzin, i zapisuje listę jako plik JSON.

Ważna

Zapisz ten skrypt w tym samym folderze, który został zapisanyGet-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

Wszystko gotowe! Pomyślnie:

  • Utworzono i zarejestrowano aplikację.
  • Udzielono tej aplikacji uprawnień do odczytywania alertów.
  • Połączony z interfejsem API.
  • Użyto skryptu programu PowerShell do zwracania zdarzeń zaktualizowanych w ciągu ostatnich 48 godzin.

Porada

Chcesz dowiedzieć się więcej? Zaangażuj się w społeczność rozwiązań zabezpieczających firmy Microsoft w naszej społeczności technicznej Społeczność techniczna usługi Microsoft Defender XDR.