Microsoft Defender XDR REST API için Merhaba Dünya

Şunlar için geçerlidir:

• Microsoft Defender XDR

Basit bir PowerShell betiği kullanarak olayları alma

Bu projenin tamamlanması 5-10 dakika sürmelidir. Bu zaman tahmini, uygulamayı kaydetmeyi ve PowerShell örnek betiğinden kodu uygulamayı içerir.

uygulamayı Microsoft Entra ID'a kaydetme

1. Genel yönetici rolüyle Azure'da kullanıcı olarak oturum açın.

2. Microsoft Entra ID>Uygulama kayıtları>Yeni kayıt'a gidin.

   

3. Kayıt formunda, uygulamanız için bir ad seçin ve ardından Kaydet'i seçin. Yeniden yönlendirme URI'sini seçmek isteğe bağlıdır. Bu örneği tamamlamak için ihtiyacınız olmayacaktır.

4. Uygulama sayfanızda API İzinleriKuruluşumun kullandığı> izin > API'lerini >ekle'yiseçin, Microsoft Tehdit Koruması yazın ve Microsoft Tehdit Koruması'yı seçin. Uygulamanız artık Microsoft Defender XDR erişebilir.

   İpucu

   Microsoft Tehdit Koruması, Microsoft Defender XDR için eski bir addır ve özgün listede görünmez. Görünmesini sağlamak için metin kutusuna adını yazmaya başlamanız gerekir.

   • Uygulama izinleri>Incident.Read.All öğesini seçin ve İzin ekle'yi seçin.

     

5. Yönetici onayı ver'i seçin. Her izin eklediğinizde, geçerli olması için Yönetici onayı ver'i seçmeniz gerekir.

   

6. Uygulamaya gizli dizi ekleyin. Sertifikalar & gizli dizileri seçin, gizli diziye bir açıklama ekleyin ve ardından Ekle'yi seçin.

   İpucu

   Ekle'yi seçtikten sonra oluşturulan gizli dizi değerini kopyala'yı seçin. Ayrıldıktan sonra gizli dizi değerini alamazsınız.

   

7. Uygulama kimliğinizi ve kiracı kimliğinizi güvenli bir yere kaydedin. Bunlar uygulama sayfanızda Genel Bakış altında listelenir.

   

Uygulamayı kullanarak belirteç alma ve belirteci kullanarak API'ye erişme

Microsoft Entra belirteçleri hakkında daha fazla bilgi için Microsoft Entra öğreticisine bakın.

1. Aşağıdaki betiği kopyalayın ve sık kullandığınız metin düzenleyiciye yapıştırın. Get-Token.ps1olarak kaydedin. Kodu PowerShell ISE'de olduğu gibi de çalıştırabilirsiniz, ancak bunu kaydetmeniz gerekir çünkü sonraki bölümde olay getirme betiğini kullandığımızda yeniden çalıştırmamız gerekir.

   Bu betik bir belirteç oluşturur ve Latest-token.txtadlı çalışma klasörüne kaydeder.

   # 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
   

Belirteci doğrulama

1. Aldığınız belirteci kopyalayıp JWT'ye yapıştırarak kodunu çözebilirsiniz.

2. JWT , JSON Web Belirteci'nin kısaltmasıdır. Kodu çözülen belirteç bir dizi JSON biçimli öğe veya talep içerir. Kodu çözülen belirteç içindeki rol talebi için istenen izinlerin bulunduğundan emin olun.

   Aşağıdaki görüntüde, , Incidents.ReadWrite.Allve AdvancedHunting.Read.All izinleriyle Incidents.Read.Allbir uygulamadan alınan kodu çözülen belirteci görebilirsiniz:

   

Son olayların listesini alma

Aşağıdaki betik, API'ye erişmek için Get-Token.ps1 kullanır. Ardından son 48 saat içinde güncelleştirilen olayların listesini alır ve listeyi JSON dosyası olarak kaydeder.

# 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

Hepsi bu kadar! Başarılı bir şekilde:

• Uygulama oluşturuldu ve kaydedildi.
• Bu uygulamaya uyarıları okuma izni verildi.
• API'ye bağlı.
• Son 48 saat içinde güncelleştirilen olayları döndürmek için bir PowerShell betiği kullandı.

İlgili makaleler

• api'lere genel bakış Microsoft Defender XDR
• Microsoft Defender XDR API'lerine erişme
• Kullanıcı olmadan Microsoft Defender XDR erişmek için bir uygulama İçerik Oluşturucu
• Kullanıcı adına Microsoft Defender XDR API'lere erişmek için bir uygulama İçerik Oluşturucu
• Microsoft Defender XDR API'lerine çok kiracılı iş ortağı erişimi olan bir uygulamayı İçerik Oluşturucu
• Azure Key Vault ile sunucu uygulamalarınızdaki gizli dizileri yönetme
• Kullanıcı oturum açma ve API erişimi için OAuth 2.0 Yetkilendirmesi