Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
API Microsoft Sentinel отправки индикаторов позволил платформам аналитики угроз или пользовательским приложениям импортировать индикаторы компрометации в формате STIX в рабочую область Microsoft Sentinel. Этот документ служит ссылкой на устаревший API.
Важно!
Этот API находится в предварительной версии, но больше не рекомендуется. Используйте новый API объектов STIX в предварительной версии для отправки аналитики угроз. Дополнительные сведения см. в разделе API объектов STIX. Дополнительные условия предварительной версии Azure включают дополнительные юридические условия, применимые к Azure функциям, которые находятся в бета-версии, предварительной версии или еще не выпущены в общедоступную версию.
Вызов API индикаторов отправки состоит из пяти компонентов:
- URI запроса
- Заголовок сообщения HTTP-запроса
- Текст сообщения HTTP-запроса
- При необходимости обработайте заголовок сообщения ответа HTTP.
- При необходимости обработайте текст сообщения ответа HTTP.
Регистрация клиентского приложения в Microsoft Entra ID
Для проверки подлинности для Microsoft Sentinel запрос к API индикаторов отправки требует допустимого маркера доступа Microsoft Entra. Дополнительные сведения о регистрации приложения см. в статье Регистрация приложения с помощью платформа удостоверений Майкрософт или основные действия в рамках настройки соединителя данных API индикаторов отправки.
Разрешения
Для этого API требуется, чтобы вызывающему приложению Microsoft Entra была предоставлена роль Microsoft Sentinel участник на уровне рабочей области.
Создание запроса
В этом разделе рассматриваются первые три из пяти компонентов, рассмотренных ранее. Сначала необходимо получить маркер доступа из Microsoft Entra ID, который используется для сборки заголовка сообщения запроса.
Получение маркера доступа
Получите маркер доступа Microsoft Entra с проверкой подлинности OAuth 2.0. Версии 1.0 и 2.0 являются допустимыми маркерами, принятыми API.
Версия маркера (версии 1.0 или 2.0), которую получает приложение, определяется свойством accessTokenAcceptedVersion в манифесте приложения API, вызываемого приложением. Если accessTokenAcceptedVersion задано значение 1, приложение получит токен версии 1.0.
Используйте библиотеку проверки подлинности Майкрософт MSAL для получения маркера доступа версии 1.0 или 2.0. Или отправьте запросы в REST API в следующем формате:
- POST
https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token - Заголовки для использования приложения Microsoft Entra:
- grant_type: "client_credentials"
- client_id: {Идентификатор клиента Microsoft Entra App}
- client_secret: {secret of Microsoft Entra App}
- область:
"https://management.azure.com/.default"
Если accessTokenAcceptedVersion в манифесте приложения задано значение 1, приложение получит маркер доступа версии 1.0, даже если оно вызывает конечную точку маркера версии 2.
Ресурс или значение область — это аудитория маркера. Этот API принимает только следующие аудитории:
https://management.core.windows.net/https://management.core.windows.nethttps://management.azure.com/https://management.azure.com
Сборка сообщения запроса
Существовали две версии устаревшего API. В зависимости от конечной точки в тексте запроса требовалось другое имя массива. Это также было представлено двумя версиями действия соединителя приложения логики.
- Имя действия соединителя: Аналитика угроз — отправка индикаторов компрометации (не рекомендуется)
- Конечной точки:
https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators - Массив имен индикаторов:
value
- Конечной точки:
- Имя действия соединителя: аналитика угроз — отправка индикаторов компрометации (версия 2) (предварительная версия)
- Конечной точки:
https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload - Массив имен индикаторов:
indicators{ "sourcesystem":"TIsource-example", "indicators":[] }
- Конечной точки:
URI запроса
Управление версиями API: api-version=2022-07-01
Конечной точки: https://sentinelus.azure-api.net/workspaces/{workspaceId}/threatintelligenceindicators:upload?api-version=2022-07-01
Метод: POST
Заголовок запроса
Authorization: содержит токен носителя OAuth2.
Content-Type: application/json
Текст запроса
Объект JSON для текста содержит следующие поля:
| Имя поля | Тип данных | Описание |
|---|---|---|
| SourceSystem (обязательно) | string | Определите имя исходной системы. Значение Microsoft Sentinel ограничено. |
| индикаторы (обязательные) | массив | Массив индикаторов в формате STIX 2.0 или 2.1 |
Создайте массив индикаторов с помощью спецификации формата индикаторов STIX 2.1, которая была сокращена здесь для вашего удобства со ссылками на важные разделы. Кроме того, обратите внимание, что некоторые свойства, допустимые для STIX 2.1, не имеют соответствующих свойств индикатора в Microsoft Sentinel.
| Имя свойства | Тип | Описание |
|---|---|---|
id (обязательно) |
string | Идентификатор, используемый для идентификации индикатора. Спецификации создания см. в idразделе 2.9. Формат выглядит примерно так: indicator--<UUID> |
spec_version (необязательный) |
string | Версия индикатора STIX. Это значение является обязательным в спецификации STIX, но так как этот API поддерживает только STIX 2.0 и 2.1, если это поле не задано, API по умолчанию будет иметь значение 2.1 |
type (обязательно) |
string | Значение этого свойства должно иметь значение indicator. |
created (обязательно) |
Timestamp | Спецификации этого общего свойства см. в разделе 3.2 . |
modified (обязательно) |
Timestamp | Спецификации этого общего свойства см. в разделе 3.2 . |
name (необязательный) |
string | Имя, используемое для идентификации индикатора. Производители должны предоставить это свойство, чтобы помочь продуктам и аналитикам понять, что на самом деле делает этот показатель. |
description (необязательный) |
string | Описание, включающее дополнительные сведения и контекст о индикаторе, потенциально включая его назначение и ключевые характеристики. Производители должны предоставить это свойство, чтобы помочь продуктам и аналитикам понять, что на самом деле делает этот показатель. |
indicator_types (необязательный) |
список строк | Набор классификаций для этого индикатора. Значения для этого свойства должны поступать из типа индикатора |
pattern (обязательно) |
string | Шаблон обнаружения для этого индикатора может быть выражен в виде шаблона STIX или другого соответствующего языка, например SNORT, YARA и т. д. |
pattern_type (обязательно) |
string | Язык шаблона, используемый в этом индикаторе. Значение для этого свойства должно исходить из типов шаблонов. Значение этого свойства должно соответствовать типу данных шаблона, включенных в свойство pattern. |
pattern_version (необязательный) |
string | Версия языка шаблонов, используемого для данных в свойстве pattern, которая должна соответствовать типу данных шаблона, включенных в свойство pattern. Для шаблонов, которые не имеют формальной спецификации, следует использовать версию сборки или кода, с которыми, как известно, работает шаблон. Для языка шаблонов STIX версия спецификации объекта определяет значение по умолчанию. Для других языков значением по умолчанию должна быть последняя версия языка шаблонов на момент создания этого объекта. |
valid_from (обязательно) |
Timestamp | Время, с которого этот индикатор считается допустимым индикатором поведения, с которым он связан или представляется. |
valid_until (необязательный) |
Timestamp | Время, когда этот индикатор больше не должен считаться допустимым индикатором поведения, с которым он связан или представляется. Если свойство valid_until опущено, то нет ограничений на последнее время, в течение которого индикатор действителен. Эта метка времени должна быть больше метки времени valid_from. |
kill_chain_phases (необязательный) |
list of string | Этапы цепочки завершения, которым соответствует этот индикатор. Значение этого свойства должно исходить из этапа завершения цепочки. |
created_by_ref (необязательный) |
string | Свойство created_by_ref указывает свойство ID сущности, создающей этот объект. Если этот атрибут опущен, источник этой информации не определен. Для создателей объектов, которые хотят оставаться анонимными, оставьте это значение неопределенным. |
revoked (необязательный) |
логический | Отозванные объекты больше не считаются допустимыми создателем объектов. Отзыв объекта является постоянным; будущие версии объекта с этим id не должны создаваться.Значение по умолчанию для этого свойства — false. |
labels (необязательный) |
список строк | Свойство labels задает набор терминов, используемых для описания этого объекта. Термины определяются пользователем или группой доверия. Эти метки будут отображаться в виде тегов в Microsoft Sentinel. |
confidence (необязательный) |
integer | Свойство confidence определяет уверенность создателя в правильности данных. Значение доверия должно быть числом в диапазоне от 0 до 100.Приложение А содержит таблицу нормативных сопоставлений с другими шкалами доверия, которые необходимо использовать при представлении значения достоверности в одной из этих шкал. Если свойство confidence отсутствует, достоверность содержимого не указана. |
lang (необязательный) |
string | Свойство lang определяет язык текстового содержимого в этом объекте. Если он присутствует, это должен быть код языка, соответствующий RFC5646. Если свойство отсутствует, язык содержимого — en (английский).Это свойство должно присутствовать, если тип объекта содержит переводимые текстовые свойства (например, имя, описание). Язык отдельных полей в этом объекте может переопределять lang свойство в детализированной маркировке (см . раздел 7.2.3). |
object_marking_refs (необязательно, включая TLP) |
список строк | Свойство object_marking_refs задает список свойств идентификаторов объектов определения маркировки, применяемых к этому объекту. Например, используйте идентификатор определения маркировки по протоколу светофора (TLP), чтобы указать чувствительность источника индикатора. Дополнительные сведения об идентификаторах определения маркировки для содержимого TLP см. в разделе 7.2.1.4.В некоторых случаях, хотя и редко, сами определения маркировки могут быть помечены рекомендациями по совместному использованию или обработке. В этом случае это свойство не должно содержать ссылок на один и тот же объект определения маркировки (то есть оно не может содержать циклические ссылки). Дополнительные сведения о маркировке данных см. в разделе 7.2.2 . |
external_references (необязательный) |
список объектов | Свойство external_references задает список внешних ссылок, которые ссылаются на сведения, отличные от STIX. Это свойство используется для предоставления одного или нескольких URL-адресов, описаний или идентификаторов для записей в других системах. |
granular_markings (необязательный) |
список детализированной маркировки | Свойство granular_markings помогает по-разному определять части индикатора. Например, язык индикатора — английский, en а описание — немецкий, de.В некоторых случаях, хотя и редко, сами определения маркировки могут быть помечены рекомендациями по совместному использованию или обработке. В этом случае это свойство не должно содержать ссылок на один и тот же объект маркировки Definition (т. е. оно не может содержать циклические ссылки). Дополнительные сведения о маркировке данных см. в разделе 7.2.3 . |
Обработка ответного сообщения
Заголовок ответа содержит код состояния HTTP. Дополнительные сведения о интерпретации результата вызова API см. в этой таблице.
| Код состояния | Описание |
|---|---|
| 200 | Успешно. API возвращает значение 200 при успешной проверке и публикации одного или нескольких индикаторов. |
| 400 | Неправильный формат. Что-то в запросе неправильно отформатировано. |
| 401 | Недостаточно полномочий. |
| 404 | Файл не найден. Обычно эта ошибка возникает, когда идентификатор рабочей области не найден. |
| 429 | Превышено количество запросов в минуту. |
| 500 | Ошибка сервера. Обычно ошибка в API или службах Microsoft Sentinel. |
Текст ответа представляет собой массив сообщений об ошибках в формате JSON:
| Имя поля | Тип данных | Описание |
|---|---|---|
| ошибки | Массив объектов ошибок | Список ошибок проверки |
Объект Error
| Имя поля | Тип данных | Описание |
|---|---|---|
| recordIndex | int | Индекс индикаторов в запросе |
| errorMessages | Массив строк | Сообщения об ошибках |
Ограничения регулирования для API
Для каждого пользователя применяются все ограничения:
- 100 индикаторов на запрос.
- 100 запросов в минуту.
Если количество запросов превышает ограничение, 429 возвращается код состояния HTTP в заголовке ответа со следующим текстом ответа:
{
"statusCode": 429,
"message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
}
Приблизительно 10 000 индикаторов в минуту — это максимальная пропускная способность до получения ошибки регулирования.
Пример текста запроса
{
"sourcesystem": "test",
"indicators":[
{
"type": "indicator",
"spec_version": "2.1",
"id": "indicator--10000003-71a2-445c-ab86-927291df48f8",
"name": "Test Indicator 1",
"created": "2010-02-26T18:29:07.778Z",
"modified": "2011-02-26T18:29:07.778Z",
"pattern": "[ipv4-addr:value = '172.29.6.7']",
"pattern_type": "stix",
"valid_from": "2015-02-26T18:29:07.778Z"
},
{
"type": "indicator",
"spec_version": "2.1",
"id": "indicator--67e62408-e3de-4783-9480-f595d4fdae52",
"created": "2023-01-01T18:29:07.778Z",
"modified": "2025-02-26T18:29:07.778Z",
"created_by_ref": "identity--19f33886-d196-468e-a14d-f37ff0658ba7",
"revoked": false,
"labels": [
"label 1",
"label 2"
],
"confidence": 55,
"lang": "en",
"external_references": [
{
"source_name": "External Test Source",
"description": "Test Report",
"external_id": "e8085f3f-f2b8-4156-a86d-0918c98c498f",
"url": "https://fabrikam.com//testreport.json",
"hashes": {
"SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
}
}
],
"object_marking_refs": [
"marking-definition--613f2e26-407d-48c7-9eca-b8e91df99dc9"
],
"granular_markings": [
{
"marking_ref": "marking-definition--beb3ec79-03aa-4594-ad24-09982d399b80",
"selectors": [ "description", "labels" ],
"lang": "en"
}
],
"name": "Test Indicator 2",
"description": "This is a test indicator to demo valid fields",
"indicator_types": [
"threatstream-severity-low", "threatstream-confidence-80"
],
"pattern": "[ipv4-addr:value = '192.168.1.1']",
"pattern_type": "stix",
"pattern_version": "2.1",
"valid_from": "2023-01-01T18:29:07.778Z",
"valid_until": "2025-02-26T18:29:07.778Z",
"kill_chain_phases": [
{
"kill_chain_name": "lockheed-martin-cyber-kill-chain",
"phase_name": "reconnaissance"
}
]
}
]
}
Пример текста ответа с ошибкой проверки
Если все индикаторы успешно проверены, возвращается состояние HTTP 200 с пустым текстом ответа.
Если проверка одного или нескольких индикаторов завершается ошибкой, текст ответа возвращается с дополнительными сведениями. Например, если вы отправляете массив с четырьмя индикаторами и первые три являются хорошими, но четвертый не имеет id (обязательное поле), то создается ответ http status code 200 вместе со следующим текстом:
{
"errors": [
{
"recordIndex":3,
"errorMessages": [
"Error for Property=id: Required property is missing. Actual value: NULL."
]
}
]
}
Индикаторы отправляются в виде массива recordIndex , поэтому начинается с 0.
Следующее действие
Этот API является устаревшим. Выполните миграцию, чтобы использовать API объектов STIX для отправки аналитики угроз. Дополнительные сведения см. в разделе API объектов STIX.