Ссылка на API индикаторов отправки (предварительная версия) для импорта аналитики угроз в Microsoft Sentinel

Мақала
10/18/2023

API индикаторов отправки Microsoft Sentinel позволяет платформам аналитики угроз или пользовательским приложениям импортировать индикаторы компрометации в формате STIX в рабочую область Microsoft Sentinel. Независимо от того, используется ли API с соединителем данных API индикаторов Microsoft Sentinel или как часть пользовательского решения, этот документ служит ссылкой.

Внимание

Этот API в настоящее время находится в предварительной версии. Предварительная версия дополнительных условий использования Azure включают дополнительные юридические условия, применимые к функциям Azure, которые находятся в бета-версии, предварительной версии или еще не общедоступны по другим причинам.

Вызов API индикаторов отправки содержит пять компонентов:

URI запроса...
Заголовок сообщения HTTP-запроса
Текст сообщения HTTP-запроса
При необходимости обработать заголовок сообщения HTTP-ответа
При необходимости обработайте текст сообщения HTTP-ответа

Регистрация клиентского приложения с помощью идентификатора Microsoft Entra

Чтобы пройти проверку подлинности в Microsoft Sentinel, запрос к API индикаторов отправки требует допустимого маркера доступа Microsoft Entra. Дополнительные сведения о регистрации приложений см. в статье "Регистрация приложения с помощью платформа удостоверений Майкрософт" или основные действия в рамках настройки соединителя данных API индикаторов отправки.

Разрешения

Для этого API требуется, чтобы вызывающее приложение Microsoft Entra было предоставлено роль участника Microsoft Sentinel на уровне рабочей области.

Создание запроса

В этом разделе рассматриваются первые три из пяти компонентов, рассмотренных ранее. Сначала необходимо получить маркер доступа из идентификатора Microsoft Entra, который используется для сборки заголовка сообщения запроса.

Получение маркера доступа

Получите маркер доступа Microsoft Entra с проверкой подлинности OAuth 2.0. Версии 1.0 и V2.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}
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.net
https://management.azure.com/
https://management.azure.com

Сборка сообщения запроса

Существует две версии API индикаторов отправки. В зависимости от конечной точки в тексте запроса требуется другое имя массива. Это также представлено двумя версиями действия соединителя приложения логики.

Снимок экрана: имена действий соединителя приложения логики для API отправки индикаторов Microsoft Sentinel.

Имя действия соединителя: Аналитика угроз — передача индикаторов компрометации (не рекомендуется)
- Конечная точка: https://sentinelus.azure-api.net/{workspaceId}/threatintelligence:upload-indicators
- Массив индикаторов: value
```
{
   "sourcesystem":"TIsource-example",
   "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 для текста содержит следующие поля:

Имя поля	Тип данных	Description
SourceSystem (обязательно)	строка	Определите имя исходной системы. Значение `Microsoft Sentinel` ограничено.
индикаторы (обязательные)	array	Массив индикаторов в формате STIX 2.0 или 2.1

Создайте массив индикаторов с помощью спецификации формата индикатора STIX 2.1, которая была сокращена здесь для удобства со ссылками на важные разделы. Кроме того, обратите внимание на некоторые свойства, допустимые для STIX 2.1, не имеют соответствующих свойств индикатора в Microsoft Sentinel.

Имя свойства	Type	Описание
`id` (обязательно)	строка	Идентификатор, используемый для идентификации индикатора. См. раздел 2.9 для спецификаций `id`о том, как создать объект. Формат выглядит примерно так: `indicator--<UUID>`
`spec_version` (необязательно)	строка	Версия индикатора STIX. Это значение требуется в спецификации STIX, но так как этот API поддерживает только STIX 2.0 и 2.1, если это поле не задано, API по умолчанию будет иметь значение `2.1`
`type` (обязательно)	строка	Значение этого свойства должно быть `indicator`.
`created` (обязательно)	TIMESTAMP	См. раздел 3.2 для спецификаций этого общего свойства.
`modified` (обязательно)	TIMESTAMP	См. раздел 3.2 для спецификаций этого общего свойства.
`name` (необязательно)	строка	Имя, используемое для идентификации индикатора. Производители должны предоставить это свойство, чтобы помочь продуктам и аналитикам понять, что этот индикатор на самом деле делает.
`description` (необязательно)	строка	Описание, предоставляющее дополнительные сведения и контекст о индикаторе, потенциально включая его назначение и ключевые характеристики. Производители должны предоставить это свойство, чтобы помочь продуктам и аналитикам понять, что этот индикатор на самом деле делает.
`indicator_types` (необязательно)	список строк	Набор классификаций для этого индикатора. Значения этого свойства должны поступать из индикатора типа ov
`pattern` (обязательно)	строка	Шаблон обнаружения для этого индикатора может быть выражен как шаблон STIX или другой подходящий язык, например SNORT, YARA и т. д.
`pattern_type` (обязательно)	строка	Язык шаблона, используемый в этом индикаторе. Значение этого свойства должно поступать из типов шаблонов. Значение этого свойства должно соответствовать типу данных шаблона, включенным в свойство шаблона.
`pattern_version` (необязательно)	строка	Версия языка шаблона, используемого для данных в свойстве шаблона, которая должна соответствовать типу данных шаблона, включенным в свойство шаблона. Для шаблонов, не имеющих официальной спецификации, следует использовать версию сборки или кода, с которым должен работать шаблон. Для языка шаблонов STIX версия спецификации объекта определяет значение по умолчанию. Для других языков значение по умолчанию должно быть последней версией языка шаблонирования во время создания этого объекта.
`valid_from` (обязательно)	TIMESTAMP	Время, с которого этот индикатор считается допустимым индикатором поведения, с которым он связан или представляет.
`valid_until` (необязательно)	TIMESTAMP	Время, когда этот индикатор больше не должен считаться допустимым индикатором поведения, с которым он связан или представляет. Если свойство valid_until опущено, ограничение на последнее время, для которого является допустимым индикатором, отсутствует ограничение. Эта метка времени должна превышать метку времени valid_from.
`kill_chain_phases` (необязательно)	список строк	Этапы цепочки убийств, к которым соответствует этот индикатор. Значение этого свойства должно поступать из этапа цепочки убийств.
`created_by_ref` (необязательно)	строка	Свойство created_by_ref указывает свойство идентификатора сущности, созданной этим объектом. Если этот атрибут опущен, источник этой информации не определен. Для создателей объектов, желающих оставаться анонимными, сохраните это значение неопределенным.
`revoked` (необязательно)	boolean	Отозванные объекты больше не считаются допустимыми создателем объекта. Отзыв объекта является постоянным; Будущие версии объекта с этим `id` не должны быть созданы. Значение по умолчанию для этого свойства — false.
`labels` (необязательно)	список строк	Свойство `labels` задает набор терминов, используемых для описания этого объекта. Термины определяются пользователем или группа доверия. Эти метки будут отображаться как теги в Microsoft Sentinel.
`confidence` (необязательно)	integer	Свойство `confidence` определяет уверенность, что создатель имеет правильность своих данных. Значение достоверности должно быть числом в диапазоне от 0 до 100. Приложение A содержит таблицу нормативных сопоставлений с другими шкалами достоверности, которые необходимо использовать при представлении достоверности в одном из этих масштабов. Если свойство достоверности отсутствует, то достоверность содержимого не определена.
`lang` (необязательно)	строка	Свойство `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` В некоторых случаях, хотя и редко, сами определения маркировки могут быть помечены с помощью общих или обрабатывавших рекомендаций. В этом случае это свойство не должно содержать ссылки на тот же объект "Определение маркировки" (т. е. не может содержать циклические ссылки). Дополнительные сведения об определении маркировки данных см. в разделе 7.2.3 .

Обработка сообщения ответа

Заголовок ответа содержит код состояния HTTP. Дополнительные сведения о интерпретации результата вызова API см. в этой таблице.

Код состояния	Description
200	Успешно. API возвращает значение 200, когда один или несколько индикаторов успешно проверяются и публикуются.
400	Недопустимый формат. Что-то в запросе неправильно отформатировано.
401	Не авторизовано.
404	Файл не найден. Обычно эта ошибка возникает, когда идентификатор рабочей области не найден.
429	Превышено количество запросов за минуту.
500	Ошибка сервера. Обычно ошибка в службах API или Microsoft Sentinel.

Текст ответа — это массив сообщений об ошибках в формате JSON:

Имя поля	Тип данных	Description
ошибки	Массив объектов ошибок	Список ошибок проверки

Объект Error

Имя поля	Тип данных	Description
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 200 создается вместе со следующим текстом:

{
    "errors": [
        {
            "recordIndex":3, 
            "errorMessages": [
                "Error for Property=id: Required property is missing. Actual value: NULL."
            ]
        }
    ]
}

Индикаторы отправляются в виде массива, поэтому recordIndex начинается с 0.

Следующие шаги

Дополнительные сведения о работе с аналитикой угроз в Microsoft Sentinel см. в следующих статьях:

Общие сведения об аналитике угроз
Работа с индикаторами угроз
Использование аналитики сопоставления для обнаружения угроз
Использование веб-канала аналитики от Майкрософт и включение соединителя данных MDTI

Бөлісу құралы: