Hello world interfejsu API REST Microsoft Defender XDR
Dotyczy:
- Microsoft Defender XDR
Ważne
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.
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.
Zaloguj się do platformy Azure.
Przejdź do Tożsamość Microsoft Entra>Rejestracje aplikacji>Nowa rejestracja.
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.
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.
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.
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.
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żne
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.
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
Skopiuj i wklej otrzymany token do narzędzia JWT, aby go odkodować.
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.All
uprawnieniami ,Incidents.ReadWrite.All
i :AdvancedHunting.Read.All
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żne
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.
- 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.