שתף באמצעות

עדכן API של אירועים

  • מאמר

חל על:

הערה

נסה את ממשקי ה- API החדשים שלנו באמצעות API של אבטחה של MS Graph. קבל מידע נוסף ב: השתמש ב- API לאבטחה של Microsoft Graph - Microsoft Graph | Microsoft Learn. לקבלת מידע אודות ה- API החדש לעדכון מקרי באמצעות API של אבטחה של MS Graph, ראה עדכון מקרה.

חשוב

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

תיאור API

עדכונים מאפיינים של מקרה קיים. המאפיינים הניתנים לעדכון הם: status, determination, classification, assignedTo, tagsו- comments.

מיכסות, הקצאת משאבים ואילוצים אחרים

  1. באפשרותך לבצע עד 50 שיחות בדקה או 1,500 שיחות בשעה לפני שתעבור לסף הוויסות.
  2. באפשרותך להגדיר את המאפיין determination רק אם הוא classification מוגדר ל- TruePositive.

אם הבקשה שלך מווסתת, היא מחזירה קוד 429 תגובה. גוף התגובה מציין את הזמן שבו באפשרותך להתחיל לבצע שיחות חדשות.

הרשאות

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

סוג הרשאה הרשאה שם תצוגה של הרשאה
יישום Incident.ReadWrite.All קריאה וכתיבה של כל האירועים
מוסמך (חשבון בעבודה או בבית ספר) Incident.ReadWrite קריאה וכתיבה של אירועים

הערה

בעת השגת אסימון באמצעות אישורי משתמש, המשתמש צריך להיות בעל הרשאה לעדכון האירוע בפורטל.

בקשת HTTP

PATCH /api/incidents/{id}

כותרות בקשות

Name סוג תיאור
ההרשאות מחרוזת נושא {token}. נדרש .
סוג תוכן מחרוזת application/json. נדרש .

גוף הבקשה

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

המאפיין סוג תיאור
מצב Enum מציין את המצב הנוכחי של האירוע. הערכים האפשריים הם: Active, Resolved, InProgress, ו- Redirected.
Assignedto מחרוזת בעלים של האירוע.
סיווג Enum מפרט המקרה. הערכים האפשריים הם: TruePositive (True positive), InformationalExpectedActivity (Informational, expected activity) ו- FalsePositive (False Positive).
נחישות Enum מציין את קביעה של המקרה.

ערכי קביעה אפשריים עבור כל סיווג הם:

  • חיובי אמיתי: MultiStagedAttack (תקיפה מרובת שלבים), MaliciousUserActivity (פעילות משתמשים זדונית), CompromisedAccount (חשבון שנחשף לסכנה) – שקול לשנות את שם הספירה ב- api הציבורי בהתאם, Malware (תוכנות זדוניות), Phishing (דיוג), UnwantedSoftware (תוכנה לא רצויה) Other וכן (אחר).
  • מידע, פעילות צפויה:SecurityTesting (בדיקת אבטחה), LineOfBusinessApplication (יישום קו פעולה עסקי), ConfirmedActivity (פעילות מאושרת) - שקול לשנות את שם הספירה ב- API הציבורי בהתאם וכן Other (אחר).
  • חיובית מוטעית:Clean (לא זדוני) - שקול לשנות בהתאם את שם הספירה ב- api הציבורי NoEnoughDataToValidate (אין די נתונים לאימות) וכן Other (אחר).
    		•
    תגיות רשימת מחרוזות רשימה של תגיות מקרה.
    תגובה מחרוזת הערה שיש להוסיף לתקרית.

    הערה

    בסביבות 29 באוגוסט 2022, ערכי קביעת ההתראה הנתמכים בעבר ('Apt' ו- 'SecurityPersonnel') לא יהיו עוד זמינים דרך ה- API.

    תגובה

    אם פעולת השירות הצליחה, שיטה זו מחזירה 200 OK. גוף התגובה מכיל את ישות האירוע עם מאפיינים מעודכנים. אם מקרה עם המזהה שצוין לא נמצא, פעולת השירות מחזירה 404 Not Found.

    דוגמה

    דוגמה לבקשה

    להלן דוגמה לבקשה.

     PATCH https://api.security.microsoft.com/api/incidents/{id}

    דוגמה לנתונים של בקשה

    {
    "status": "Resolved",
    "assignedTo": "secop2@contoso.com",
    "classification": "TruePositive",
    "determination": "Malware",
    "tags": ["Yossi's playground", "Don't mess with the Zohan"],
    "comments": [
          {
              "comment": "pen testing",
              "createdBy": "secop2@contoso.com",
              "createdTime": "2021-05-02T09:34:21.5519738Z"
          },
          {
              "comment": "valid incident",
              "createdBy": "secop2@contoso.comt",
              "createdTime": "2021-05-02T09:36:27.6652581Z"
          }
      ]
}

    עצה

    האם ברצונך לקבל מידע נוסף? צור קשר עם קהילת האבטחה של Microsoft בקהילת הטכנולוגיה שלנו: קהילת האבטחה של Microsoft Defender XDR.