مرحبًا بالعالم لواجهة برمجة تطبيقات REST Microsoft Defender XDR

ينطبق على: Microsoft Defender XDR

هام

تتعلق بعض المعلومات بالمنتج الذي تم إصداره مسبقا والذي يمكن تعديله بشكل كبير قبل توفره بشكل عام. لا تقدم Microsoft أي ضمانات، سواءً كانت صريحة أم ضمنية، فيما يتعلق بالمعلومات الواردة هنا.

الحصول على الحوادث باستخدام برنامج PowerShell نصي بسيط

يجب أن يستغرق إكمال هذا المشروع من 5 إلى 10 دقائق. يتضمن هذا التقدير الزمني تسجيل التطبيق، وتطبيق التعليمات البرمجية من نموذج البرنامج النصي PowerShell.

تسجيل تطبيق في Microsoft Entra ID

سجل الدخول إلى Azure.
انتقل إلى تسجيلات>Microsoft Entra ID> Appتسجيل جديد.
في نموذج التسجيل، اختر اسما للتطبيق الخاص بك، ثم حدد تسجيل. تحديد عنوان URI لإعادة التوجيه اختياري. لا تحتاج إلى واحد لإكمال هذا المثال.
في صفحة التطبيق الخاص بك، حدد أذونات واجهة برمجة التطبيقات إضافة واجهات> برمجة تطبيقاتالأذونات>التي تستخدمها> مؤسستي، واكتب الحماية من التهديدات من Microsoft، وحدد الحماية من التهديدات من Microsoft. يمكن لتطبيقك الآن الوصول إلى Microsoft Defender XDR.

تلميح

الحماية من التهديدات من Microsoft هو اسم سابق Microsoft Defender XDR، ولا يظهر في القائمة الأصلية. تحتاج إلى البدء في كتابة اسمه في مربع النص لمشاهدته يظهر.
- اختر أذونات> التطبيقIncident.Read.All وحدد Add permissions.
حدد منح موافقة المسؤول. في كل مرة تضيف فيها إذنا، يجب عليك تحديد منح موافقة المسؤول حتى يصبح ساري المفعول.
إضافة سر إلى التطبيق. حدد Certificates & secrets، وأضف وصفا إلى السر، ثم حدد Add.

تلميح

بعد تحديد إضافة، حدد نسخ القيمة السرية التي تم إنشاؤها. لن تتمكن من استرداد القيمة السرية بعد المغادرة.
سجل معرف التطبيق ومعرف المستأجر في مكان آمن. يتم سردها ضمن نظرة عامة على صفحة التطبيق الخاص بك.

احصل على رمز مميز باستخدام التطبيق واستخدم الرمز المميز للوصول إلى واجهة برمجة التطبيقات

لمزيد من المعلومات حول الرموز المميزة Microsoft Entra، راجع البرنامج التعليمي Microsoft Entra.

هام

على الرغم من أن المثال في هذا التطبيق التجريبي يشجعك على اللصق في القيمة السرية الخاصة بك لأغراض الاختبار، يجب عدم تضمين البيانات السرية في تطبيق يعمل في الإنتاج. يمكن لجهة خارجية استخدام سرك للوصول إلى الموارد. يمكنك المساعدة في الحفاظ على أمان أسرار تطبيقك باستخدام Azure Key Vault. للحصول على مثال عملي حول كيفية حماية تطبيقك، راجع إدارة الأسرار في تطبيقات الخادم باستخدام Azure Key Vault.

انسخ البرنامج النصي التالي والصقه في محرر النص المفضل لديك. حفظ ك Get-Token.ps1. يمكنك أيضا تشغيل التعليمات البرمجية كما هي في PowerShell ISE، ولكنك تحتاج إلى حفظها لأننا بحاجة إلى تشغيلها مرة أخرى عندما نستخدم البرنامج النصي لجلب الحوادث في القسم التالي.

ينشئ هذا البرنامج النصي رمزا مميزا ويحفظه في مجلد العمل تحت الاسم ،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

التحقق من صحة الرمز المميز

انسخ والصق الرمز المميز الذي تلقيته في JWT لفك ترميزه.
يرمز JWTإلى JSON Web Token. يحتوي الرمز المميز الذي تم فك ترميزه على العديد من العناصر أو المطالبات بتنسيق JSON. تأكد من أن مطالبة الأدوار داخل الرمز المميز الذي تم فك ترميزه تحتوي على الأذونات المطلوبة.

في الصورة التالية، يمكنك مشاهدة رمز مميز تم فك ترميزه تم الحصول عليه من تطبيق، مع Incidents.Read.Allالأذونات Incidents.ReadWrite.Allو و AdvancedHunting.Read.All :

الحصول على قائمة بالحوادث الأخيرة

يستخدم البرنامج النصي التالي Get-Token.ps1 للوصول إلى واجهة برمجة التطبيقات. ثم يسترد قائمة بالحوادث التي تم تحديثها آخر مرة خلال ال 48 ساعة الماضية، ويحفظ القائمة كملف JSON.

هام

احفظ هذا البرنامج النصي في المجلد نفسه الذي حفظته 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

لقد انتهيت! لقد نجحت في:

إنشاء تطبيق وتسجيله.
منح إذن لهذا التطبيق لقراءة التنبيهات.
متصل بواجهة برمجة التطبيقات.
استخدم برنامج PowerShell النصي لإرجاع الحوادث التي تم تحديثها في الساعات ال 48 الماضية.

تلميح

هل تريد معرفة المزيد؟ تفاعل مع مجتمع أمان Microsoft في مجتمعنا التقني: Microsoft Defender XDR Tech Community.

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2025-04-18