Hello world interfejsu API REST Microsoft Defender XDR

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.

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

   

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.

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

     

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.

   

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.

   

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

   

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

   

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.

Artykuły pokrewne

• Omówienie interfejsów API Microsoft Defender XDR
• Uzyskiwanie dostępu do interfejsów API Microsoft Defender XDR
• Tworzenie aplikacji w celu uzyskania dostępu do Microsoft Defender XDR bez użytkownika
• Tworzenie aplikacji w celu uzyskania dostępu do interfejsów API Microsoft Defender XDR w imieniu użytkownika
• Tworzenie aplikacji z dostępem partnerów z wieloma dzierżawami do interfejsów API Microsoft Defender XDR
• Zarządzanie wpisami tajnymi w aplikacjach serwera przy użyciu usługi Azure Key Vault
• Autoryzacja protokołu OAuth 2.0 na potrzeby logowania użytkownika i dostępu do interfejsu API

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.