interfejs API Ochrona punktu końcowego w usłudze Microsoft Defender — Hello world

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ą odpowiednią rolę w dzierżawie Microsoft Entra. Aby uzyskać więcej informacji na temat ról, zobacz Opcje uprawnień.

Krok 1. Tworzenie aplikacji w Tożsamość Microsoft Entra

1. Zaloguj się do witryny Azure Portal.

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

   

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.

     

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

     

     Ważna

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

     Przykład:

     • Aby uruchomić zaawansowane zapytania, wybierz uprawnienie "Uruchom zaawansowane zapytania".
     • Aby wyizolować maszynę, wybierz uprawnienie "Izolowanie maszyny".
     • Aby określić, którego uprawnienia potrzebujesz, zobacz sekcję Uprawnienia w interfejsie API, który chcesz wywołać.

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.

   

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!

   

7. Zapisz identyfikator aplikacji i identyfikator dzierżawy.

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

   

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.security.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 .

  

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.security.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

Artykuły pokrewne

• interfejsy API Ochrona punktu końcowego w usłudze Microsoft Defender
• Dostęp Ochrona punktu końcowego w usłudze Microsoft Defender z kontekstem aplikacji
• Dostęp Ochrona punktu końcowego w usłudze Microsoft Defender z kontekstem użytkownika