שתף באמצעות

הפעלת פקודות תגובה בזמן חי במכשיר

  • מאמר

חל על:

חשוב

חלק מהמידע במאמר זה מתייחס למוצר שהופץ מראש, אשר עשוי להיות שונה באופן משמעותי לפני ההפצה המסחרית שלו. Microsoft אינה מעניקה כל אחריות, מפורשת או משתמעת, ביחס למידע המסופק כאן.

רוצה להתנסות ב- Microsoft Defender עבור נקודת קצה? הירשם לקבלת גירסת ניסיון ללא תשלום.

הערה

אם אתה לקוח של ממשלת ארה"ב, השתמש בURI המפורטים ב - Microsoft Defender for Endpoint עבור לקוחות של ממשלת ארה"ב.

עצה

לקבלת ביצועים טובים יותר, באפשרותך להשתמש בשרת קרוב יותר למיקום הגיאוגרפי שלך:

  • 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

תיאור API

הפעלת רצף של פקודות תגובה בזמן חי במכשיר

מגבלות

  1. מגבלות תעריף עבור API זה הן 10 שיחות לדקה (בקשות נוספות מגיבות ב- HTTP 429).

  2. 25 הפעלות בו-זמנית (בקשות שחורגות ממגבלת הוויסות מקבלות תגובה מסוג "429 - בקשות רבות מדי").

  3. אם המחשב אינו זמין, ההפעלה ממתינה בתור עד שלושה ימים.

  4. זמן קצוב לפקודה RunScript הסתיים לאחר 10 דקות.

  5. לא ניתן להציב בתור פקודות תגובה בזמן אמת ובאפשרותך לבצע רק אחת בכל פעם.

  6. אם המחשב שאתה מנסה להפעיל שיחת API זו נמצא בקבוצת מכשירים מסוג RBAC שלא הוקצתה לה רמת תיקון אוטומטית, עליך להפעיל לפחות את רמת התיקון המינימלית עבור קבוצת מכשירים נתונה.

    הערה

    יצירת קבוצת מכשירים נתמכת ב- Defender for Endpoint Plan 1 ובתוכנית 2.

  7. ניתן להפעיל פקודות תגובה מרובות בשידור חי על שיחת API אחת. עם זאת, כאשר פקודת תגובה חיה נכשלת כל הפעולות הבאות לא יופעלו.

  8. לא ניתן לבצע הפעלות תגובה מרובות בשידור חי באותו מחשב (אם פעולת תגובה חיה כבר פועלת, הבקשות הבאות מגיבות ל- HTTP 400 - ActiveRequestAlreadyExists).

הערה

פעולות תגובה בזמן חי שהותחלו מהדף 'מכשיר' אינן זמינות ב- API של machineactions.

דרישות מינימליות

לפני שתוכל ליזום הפעלה במכשיר, הקפד לעמוד בדרישות הבאות:

הרשאות

אחת מההרשאות הבאות נדרשת כדי לקרוא ל- API זה. לקבלת מידע נוסף, כולל כיצד לבחור הרשאות, ראה תחילת העבודה.

סוג הרשאה הרשאה שם תצוגה של הרשאה
יישום Machine.LiveResponse הפעלת תגובה חיה במחשב ספציפי
מוסמך (חשבון בעבודה או בבית ספר) Machine.LiveResponse הפעלת תגובה חיה במחשב ספציפי

בקשת HTTP

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

כותרות בקשות

Name סוג תיאור
ההרשאות מחרוזת אסימון נושא<>. חובה.
סוג תוכן מחרוזת application/json. חובה.

גוף הבקשה

פרמטר סוג תיאור
תגובה מחרוזת הערה לשיוך לפעולה.
פקודות מערך פקודות להפעלה. הערכים המותרים הם PutFile, RunScript, GetFile (חייב להיות בסדר זה ללא הגבלה על חזרות).

פקודות

סוג פקודה פרמטרים תיאור
קובץ PutFile מפתח: שם קובץ

ערך: <שם קובץ>

 העברת קובץ מהספריה למכשיר. הקבצים נשמרים בתיקיה עבודה ונמחקים כאשר המכשיר מופעל מחדש כברירת מחדל. הערה: אין לה תוצאת תגובה.
RunScript מפתח: ScriptName
ערך: קובץ <Script מספריה>

מפתח: Args
ערך: <ארגומנטים של Script>

 הפעלת קובץ Script מהספריה במכשיר.

הפרמטר Args מועבר ל- Script שלך.

הזמן הקצוב הסתיים לאחר 10 דקות.
קובץ GetFile מפתח: נתיב
ערך: <נתיב קובץ>		 אסוף קובץ ממכשיר. הערה: נטוי הפוך בנתיב חייב להיות עם תו ביטול.

תגובה

  • אם שיטה זו הצליחה, היא מחזירה 201 Created.

    ישות פעולה. אם מחשב עם המזהה שצוין לא נמצא - 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

סוג תוכן: יישום/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.