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

ينطبق على:

هام

تتعلق بعض المعلومات الواردة في هذه المقالة بالناتج الذي تم إصداره مسبقًا والذي قد يتم تعديله بشكل كبير قبل إصداره تجاريًا. لا تقدم 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

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

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

القيود

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

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

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

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

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

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

    ملاحظة

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

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

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

ملاحظة

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

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

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

الأذونات

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

نوع الإذن إذن اسم عرض الإذن
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.