تشغيل أوامر الاستجابة المباشرة على جهاز

ينطبق على:

• Defender for Endpoint الخطة 2

هام

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

هل تريد تجربة Defender لنقطة النهاية؟ التسجيل للحصول على إصدار تجريبي مجاني.

ملاحظة

إذا كنت أحد عملاء حكومة الولايات المتحدة، فالرجاء استخدام معرفات URI المدرجة في Microsoft Defender لنقطة النهاية لعملاء حكومة الولايات المتحدة.

تلميح

للحصول على أداء أفضل، يمكنك استخدام الخادم الأقرب إلى موقعك الجغرافي:

• us.api.security.microsoft.com
• eu.api.security.microsoft.com
• uk.api.security.microsoft.com
• au.api.security.microsoft.com
• swa.api.security.microsoft.com
• ina.api.security.microsoft.com

وصف واجهة برمجة التطبيقات

تشغيل تسلسل أوامر الاستجابة المباشرة على جهاز

القيود

1. قيود المعدل لواجهة برمجة التطبيقات هذه هي 10 مكالمات في الدقيقة (يتم الرد على طلبات إضافية باستخدام HTTP 429).

2. 25 جلسات عمل قيد التشغيل بشكل متزامن (تتلقى الطلبات التي تتجاوز حد التقييد استجابة "429 - طلبات كثيرة جدا").

3. إذا لم يكن الجهاز متوفرا، يتم وضع جلسة العمل في قائمة الانتظار لمدة تصل إلى ثلاثة أيام.

4. مهلات أوامر RunScript بعد 10 دقائق.

5. لا يمكن وضع أوامر الاستجابة المباشرة في قائمة الانتظار ولا يمكن تنفيذها إلا مرة واحدة في كل مرة.

6. إذا كان الجهاز الذي تحاول تشغيل استدعاء واجهة برمجة التطبيقات هذا موجودا في مجموعة أجهزة RBAC التي لم يتم تعيين مستوى معالجة تلقائي لها، فأنت بحاجة على الأقل إلى تمكين الحد الأدنى لمستوى المعالجة لمجموعة أجهزة معينة.

   ملاحظة

   يتم دعم إنشاء مجموعة الأجهزة في خطة Defender لنقطة النهاية 1 والخطة 2.

7. يمكن تشغيل أوامر استجابة مباشرة متعددة على استدعاء واجهة برمجة تطبيقات واحد. ومع ذلك، عندما يفشل أمر الاستجابة المباشرة، لن يتم تنفيذ جميع الإجراءات اللاحقة.

8. لا يمكن تنفيذ جلسات استجابة مباشرة متعددة على نفس الجهاز (إذا كان إجراء الاستجابة المباشرة قيد التشغيل بالفعل، يتم الاستجابة للطلبات اللاحقة باستخدام HTTP 400 - ActiveRequestAlreadyExists).

ملاحظة

لا تتوفر إجراءات الاستجابة المباشرة التي بدأت من صفحة Device في واجهة برمجة تطبيقات machineactions.

الحد الأدنى من المتطلبات

قبل أن تتمكن من بدء جلسة عمل على جهاز، تأكد من استيفاء المتطلبات التالية:

• تحقق من تشغيل إصدار Windows أو macOS أو Linux مدعوم.

  يجب تشغيل الأجهزة بأحد الإجراءات التالية:

  • Windows 11

  • Windows 10

    • الإصدار 1909 أو أحدث
    • الإصدار 1903 مع KB4515384
    • الإصدار 1809 (RS 5) مع KB4537818
    • الإصدار 1803 (RS 4) مع KB4537795
    • الإصدار 1709 (RS 3) مع KB4537816

  • Windows Server 2019 - ينطبق فقط على المعاينة العامة

    • الإصدار 1903 أو (مع KB4515384) لاحقا
    • الإصدار 1809 (مع KB4537818)

  • Windows Server 2022

  • macOS(يتطلب ملفات تعريف تكوين إضافية)

    • 13 (فنتورا)
    • 12 (مونتيري)
    • 11 (بيغ سور)

  • Linux

    • توزيعات خادم Linux المدعومة وإصدارات kernel

الأذونات

أحد الأذونات التالية مطلوب لاستدعاء واجهة برمجة التطبيقات هذه. لمعرفة المزيد، بما في ذلك كيفية اختيار الأذونات، راجع بدء الاستخدام.

نوع الإذن	إذن	اسم عرض الإذن
Application	Machine.LiveResponse	تشغيل الاستجابة المباشرة على جهاز معين
مفوض (حساب العمل أو المؤسسة التعليمية)	Machine.LiveResponse	تشغيل الاستجابة المباشرة على جهاز معين

طلب HTTP

POST https://api.securitycenter.microsoft.com/API/machines/{machine_id}/runliveresponse

عناوين الطلبات

الاسم	نوع	الوصف
إذن	سلسلة	الرمز المميز> للحامل<. مطلوب.
نوع المحتوى	خيط	application/json. مطلوب.

نص الطلب

البارامتر	نوع	الوصف
التعليق	سلسلة	التعليق لإقرانه بالإجراء.
الاوامر	صفيف	أوامر للتشغيل. القيم المسموح بها هي PutFile وRunScript و GetFile (يجب أن تكون بهذا الترتيب دون أي حد للتكرار).

الاوامر

نوع الأمر	البارامترات	الوصف
PutFile	المفتاح: اسم الملف القيمة: <اسم الملف>	يضع ملفا من المكتبة إلى الجهاز. يتم حفظ الملفات في مجلد عمل ويتم حذفها عند إعادة تشغيل الجهاز بشكل افتراضي. ملاحظة: لا تحتوي على نتيجة استجابة.
RunScript	المفتاح: ScriptName القيمة: <البرنامج النصي من المكتبة> المفتاح: Args القيمة: <وسيطات البرنامج النصي>	تشغيل برنامج نصي من المكتبة على جهاز. يتم تمرير المعلمة Args إلى البرنامج النصي الخاص بك. المهلات بعد 10 دقائق.
GetFile	المفتاح: المسار القيمة: <مسار الملف>	اجمع الملف من جهاز. ملاحظة: يجب إلغاء المائلة الخلفية في المسار.

استجابه

• إذا نجحت، فترجع هذه الطريقة 201 تم إنشاؤها.

  كيان الإجراء. إذا لم يتم العثور على الجهاز ذي المعرف المحدد - 404 غير موجود.

مثل

مثال على الطلب

فيما يلي مثال على الطلب.

POST https://api.securitycenter.microsoft.com/api/machines/1e5bc9d7e413ddd7902c2932e418702b84d0cc07/runliveresponse

```JSON
{
   "Commands":[
      {
         "type":"RunScript",
         "params":[
            {
               "key":"ScriptName",
               "value":"minidump.ps1"
            },
            {
               "key":"Args",
               "value":"OfficeClickToRun"
            }

         ]
      },
      {
         "type":"GetFile",
         "params":[
            {
               "key":"Path",
               "value":"C:\\windows\\TEMP\\OfficeClickToRun.dmp.zip"
            }
         ]
      }
   ],
   "Comment":"Testing Live Response API"
}

مثال على الاستجابة

فيما يلي مثال على الاستجابة.

القيم المحتملة لكل حالة أمر هي "تم الإنشاء" و"مكتمل" و"فشل".

HTTP/1.1 200 Ok

نوع المحتوى: application/json

{
    "@odata.context": "https://api.securitycenter.microsoft.com/api/$metadata#MachineActions/$entity",
    "id": "{machine_action_id}",
    "type": "LiveResponse",
    "requestor": "analyst@microsoft.com",
    "requestorComment": "Testing Live Response API",
    "status": "Pending",
    "machineId": "{machine_id}",
    "computerDnsName": "hostname",
    "creationDateTimeUtc": "2021-02-04T15:36:52.7788848Z",
    "lastUpdateDateTimeUtc": "2021-02-04T15:36:52.7788848Z",
    "errorHResult": 0,
    "commands": [
        {
            "index": 0,
            "startTime": null,
            "endTime": null,
            "commandStatus": "Created",
            "errors": [],
            "command": {
                "type": "RunScript",
                "params": [
                    {
                        "key": "ScriptName",
                        "value": "minidump.ps1"
                    },{
                        "key": "Args",
                        "value": "OfficeClickToRun"
                    }
                ]
            }
        }, {
            "index": 1,
            "startTime": null,
            "endTime": null,
            "commandStatus": "Created",
            "errors": [],
            "command": {
                "type": "GetFile",
                "params": [{
                        "key": "Path", "value": "C:\\windows\\TEMP\\OfficeClickToRun.dmp.zip"
                    }
                ]
            }
        }
    ]
}

المواضيع ذات الصلة

• الحصول على واجهة برمجة تطبيقات إجراء الجهاز
• الحصول على نتيجة استجابة مباشرة
• إجراء إلغاء الجهاز

تلميح

هل تريد معرفة المزيد؟ التفاعل مع مجتمع أمان Microsoft في مجتمع التكنولوجيا لدينا: Microsoft Defender for Endpoint Tech Community.