مشاركة عبر

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

  • مقالة

ينطبق على:

  • Microsoft Defender XDR

هام

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

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

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

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

  1. سجل الدخول إلى Azure كمستخدم مع دور مسؤول عمومي.

  2. انتقل إلى تسجيلات>Microsoft Entra ID> Appتسجيل جديد.

    قسم التسجيل الجديد في مدخل Microsoft Defender

  3. في نموذج التسجيل، اختر اسما للتطبيق الخاص بك، ثم حدد تسجيل. تحديد عنوان URI لإعادة التوجيه اختياري. لن تحتاج إلى واحد لإكمال هذا المثال.

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

    تلميح

    الحماية من التهديدات من Microsoft هو اسم سابق Microsoft Defender XDR، ولن يظهر في القائمة الأصلية. تحتاج إلى البدء في كتابة اسمه في مربع النص لمشاهدته يظهر. قسم استخدام واجهات برمجة التطبيقات في مدخل Microsoft Defender

    • اختر أذونات> التطبيقIncident.Read.All وحدد Add permissions.

      جزء أذونات التطبيق في مدخل Microsoft Defender

  5. حدد منح موافقة المسؤول. في كل مرة تضيف فيها إذنا، يجب عليك تحديد منح موافقة المسؤول حتى يصبح ساري المفعول.

    قسم منح موافقة المسؤول في مدخل Microsoft Defender

  6. إضافة سر إلى التطبيق. حدد Certificates & secrets، وأضف وصفا إلى السر، ثم حدد Add.

    تلميح

    بعد تحديد إضافة، حدد نسخ القيمة السرية التي تم إنشاؤها. لن تتمكن من استرداد القيمة السرية بعد المغادرة.

    قسم إضافة بيانات سرية في مدخل Microsoft Defender

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

    قسم نظرة عامة في مدخل Microsoft Defender

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

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

هام

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

  1. انسخ البرنامج النصي أدناه والصقه في محرر النص المفضل لديك. حفظ ك 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

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

  1. انسخ والصق الرمز المميز الذي تلقيته في JWT لفك ترميزه.

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

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

    قسم الرمز المميز الذي تم فك ترميزه في مدخل Microsoft Defender

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

سيستخدم البرنامج النصي أدناه 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.