Halo Dunia untuk REST API Microsoft Defender XDR

  • Berlaku untuk: Microsoft Defender XDR

Penting

Beberapa informasi berkaitan dengan produk yang telah dilepas sebelumnya yang mungkin dimodifikasi secara substansial sebelum ketersediaan umumnya. Microsoft tidak memberikan jaminan, tersurat maupun tersirat, sehubungan dengan informasi yang diberikan di sini.

Mendapatkan insiden menggunakan skrip PowerShell sederhana

Diperlukan waktu 5 hingga 10 menit untuk menyelesaikan proyek ini. Perkiraan waktu ini termasuk mendaftarkan aplikasi, dan menerapkan kode dari skrip sampel PowerShell.

Mendaftarkan aplikasi di ID Microsoft Entra

  1. Masuk ke Azure.

  2. Navigate ke Microsoft Entra ID>Pendaftaran aplikasi>Pendaftaran baru.

    Bagian Pendaftaran baru di portal Microsoft Defender

  3. Dalam formulir pendaftaran, pilih nama untuk aplikasi Anda, lalu pilih Daftar. Memilih URI pengalihan bersifat opsional. Anda tidak memerlukannya untuk menyelesaikan contoh ini.

  4. Pada halaman aplikasi Anda, pilih IZIN> APITambahkan API izin>yang digunakan> organisasi saya, ketik Microsoft Perlindungan Ancaman, dan pilih Microsoft Perlindungan Ancaman. Aplikasi Anda sekarang dapat mengakses Microsoft Defender XDR.

    Tip

    Microsoft Threat Protection adalah nama sebelumnya untuk Microsoft Defender XDR, dan tidak muncul dalam daftar asli. Anda perlu mulai menulis namanya di kotak teks untuk melihatnya muncul. Bagian penggunaan API di portal Microsoft Defender

    • Pilih Izin aplikasi>Incident.Read.All dan pilih Tambahkan izin.

      Panel izin aplikasi di portal Microsoft Defender

  5. Pilih Berikan perizinan admin. Setiap kali Anda menambahkan izin, Anda harus memilih Beri persetujuan admin agar berlaku.

    Bagian Berikan persetujuan admin di portal Microsoft Defender

  6. Tambahkan rahasia ke aplikasi. Pilih Sertifikat & rahasia, tambahkan deskripsi ke rahasia, lalu pilih Tambahkan.

    Tip

    Setelah Anda memilih Tambahkan, pilih salin nilai rahasia yang dihasilkan. Anda tidak akan dapat mengambil nilai rahasia setelah anda pergi.

    Bagian tambahkan rahasia di portal Microsoft Defender

  7. Rekam ID aplikasi dan ID penyewa Anda di tempat yang aman. Mereka tercantum di bawah Gambaran Umum di halaman aplikasi Anda.

    Bagian Gambaran Umum di portal Microsoft Defender

Dapatkan token menggunakan aplikasi dan gunakan token untuk mengakses API

Untuk informasi selengkapnya tentang token Microsoft Entra, lihat tutorial Microsoft Entra.

Penting

Meskipun contoh dalam aplikasi demo ini mendorong Anda untuk menempelkan nilai rahasia Anda untuk tujuan pengujian, Anda tidak boleh melakukan hardcode rahasia ke dalam aplikasi yang berjalan dalam produksi. Pihak ketiga dapat menggunakan rahasia Anda untuk mengakses sumber daya. Anda dapat membantu menjaga rahasia aplikasi tetap aman dengan menggunakan Azure Key Vault. Untuk contoh praktis tentang cara melindungi aplikasi, lihat Mengelola rahasia di aplikasi server Anda dengan Azure Key Vault.

  1. Salin skrip berikut dan tempelkan ke editor teks favorit Anda. Simpan sebagai Get-Token.ps1. Anda juga dapat menjalankan kode as-is di PowerShell ISE, tetapi Anda perlu menyimpannya karena kita perlu menjalankannya lagi ketika kita menggunakan skrip pengambilan insiden di bagian berikutnya.

    Skrip ini menghasilkan token dan menyimpannya di folder kerja dengan nama, 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

Validasi token

  1. Salin dan tempel token yang Anda terima ke JWT untuk mendekodenya.

  2. JWT adalah singkatan dari JSON Web Token. Token yang didekodekan berisi beberapa item atau klaim berformat JSON. Pastikan bahwa klaim peran dalam token yang didekodekan berisi izin yang diinginkan.

    Dalam gambar berikut, Anda dapat melihat token yang didekodekan yang diperoleh dari aplikasi, dengan Incidents.Read.Allizin , Incidents.ReadWrite.All, dan AdvancedHunting.Read.All :

    Bagian Token yang Didekodekan di portal Microsoft Defender

Mendapatkan daftar insiden terbaru

Skrip berikut menggunakan Get-Token.ps1 untuk mengakses API. Kemudian mengambil daftar insiden yang terakhir diperbarui dalam 48 jam terakhir, dan menyimpan daftar sebagai file JSON.

Penting

Simpan skrip ini di folder yang sama dengan yang Anda simpan Get-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

Kalian semua sudah selesai! Anda berhasil:

  • Membuat dan mendaftarkan aplikasi.
  • Diberikan izin untuk aplikasi tersebut untuk membaca pemberitahuan.
  • Tersambung ke API.
  • Menggunakan skrip PowerShell untuk mengembalikan insiden yang diperbarui dalam 48 jam terakhir.

Tip

Apakah Anda ingin mempelajari lebih lanjut? Terlibatlah dengan komunitas Microsoft Security di Komunitas Teknologi kami: Microsoft Defender XDR Tech Community.

  • Last updated on