API инцидентов обновления

  • Статья

Область применения:

Примечание.

Попробуйте наши новые API с помощью API безопасности MS Graph. Дополнительные сведения см. в статье Использование API безопасности Microsoft Graph — Microsoft Graph | Microsoft Learn. Сведения о новом API инцидентов обновления с помощью API безопасности MS Graph см. в разделе Обновление инцидента.

Важно!

Некоторые сведения относятся к предварительным выпускам продуктов, которые могут быть существенно изменены до коммерческого выпуска. Корпорация Майкрософт не дает никаких гарантий, явных или подразумеваемых, относительно предоставленных здесь сведений.

Описание API

Обновления свойства существующего инцидента. Обновляемые свойства: status, determination, classification, assignedTo, tagsи comments.

Квоты, выделение ресурсов и другие ограничения

  1. Вы можете выполнить до 50 вызовов в минуту или 1500 вызовов в час, прежде чем достичь порогового значения регулирования.
  2. Свойство можно задать только в determination том случае, если classification задано значение TruePositive.

Если запрос регулируется, он возвращает 429 код ответа. Текст ответа указывает время начала новых вызовов.

Разрешения

Для вызова этого API требуется одно из следующих разрешений. Дополнительные сведения, включая выбор разрешений, см. в статье Доступ к API Microsoft Defender XDR.

Тип разрешения Разрешение Отображаемое имя разрешения
Приложение Incident.ReadWrite.All Чтение и запись всех инцидентов
Делегированные (рабочая или учебная учетная запись) Incident.ReadWrite Инциденты чтения и записи

Примечание.

При получении маркера с использованием учетных данных пользователя пользователь должен иметь разрешение на обновление инцидента на портале.

HTTP-запрос

PATCH /api/incidents/{id}

Заголовки запросов

Имя Тип Описание
Авторизация String Bearer {token}. Обязательное поле.
Content-Type String application/json. Обязательное поле.

Текст запроса

В тексте запроса укажите значения для полей, которые должны быть обновлены. Существующие свойства, которые не включены в текст запроса, сохраняют свои значения, если их не нужно пересчитывать из-за изменений связанных значений. Для максимальной производительности следует опустить существующие значения, которые не изменились.

Свойство Тип Описание
status Перечисление Указывает текущее состояние инцидента. Возможные значения: Active, Resolved, InProgress и Redirected.
assignedTo string Владелец инцидента.
classification Перечисление Спецификация инцидента. Возможные значения: TruePositive (True positive), InformationalExpectedActivity (Информационный, ожидаемое действие) и FalsePositive (False Positive).
Определение Перечисление Указывает определение инцидента.

Возможные значения определения для каждой классификации:

  • Истинный положительный результат: MultiStagedAttack (многоэтапная атака), MaliciousUserActivity (вредоносные действия пользователей), CompromisedAccount (скомпрометированная учетная запись) — рассмотрите возможность изменения имени перечисления в общедоступном API соответствующим образом ( Malware вредоносные программы), Phishing (фишинг), UnwantedSoftware (нежелательное программное обеспечение) и Other (другое).
  • Информационное ожидаемое действие:SecurityTesting (Проверка безопасности), LineOfBusinessApplication (бизнес-приложение), ConfirmedActivity (подтвержденное действие) — рассмотрите возможность изменения имени перечисления в общедоступном API соответствующим образом и Other (Другое).
  • Ложноположительный результат:Clean (Не вредоносный) — рассмотрите возможность изменения имени перечисления в общедоступном API соответствующим образом( NoEnoughDataToValidate Недостаточно данных для проверки) и Other (Другое).
    		•
    tags список строк Список тегов инцидента.
    comment string Комментарий, добавляемый к инциденту.

    Примечание.

    Примерно 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"
          }
      ]
}

    Совет

    Хотите узнать больше? Engage с сообществом Microsoft Security в нашем техническом сообществе: Microsoft Defender XDR Техническое сообщество.