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

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

Структурированное выражение информации об угрозах (STIX) — это язык для выражения киберугрышей и наблюдаемой информации. В API отправки включена расширенная поддержка следующих объектов домена:

• Индикатор
• Шаблон атаки
• субъект угрозы
• Идентичности
• Отношение

Дополнительные сведения см. в статье Введение в STIX.

Вызов API

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

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

Регистрация клиентского приложения в Microsoft Entra ID

Чтобы пройти проверку подлинности для Microsoft Sentinel, запрос к API отправки требует допустимого маркера доступа Microsoft Entra. Дополнительные сведения о регистрации приложений см. в статье Регистрация приложения с помощью платформа удостоверений Майкрософт или основные шаги в рамках настройки api для аналитики угроз connect с помощью 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. Используйте маркер доступа, чтобы создать заголовок авторизации, содержащий маркер носителя.

Например, запрос к API отправки использует следующие элементы для получения маркера доступа и создания заголовка авторизации, который используется в каждом запросе:

• POST https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token

Заголовки для использования приложения Microsoft Entra:

• grant_type: "client_credentials"
• client_id: {Идентификатор клиента Microsoft Entra App}
• client_secret или client_certificate: {секреты приложения Microsoft Entra}
• область:"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

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

URI запроса

Управление версиями API: api-version=2024-02-01-preview
Конечной точки: https://api.ti.sentinel.azure.com/workspaces/{workspaceId}/threat-intelligence-stix-objects:upload?api-version={apiVersion}
Метод: POST

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

Authorization: содержит токен носителя OAuth2.
Content-Type: application/json

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

Объект JSON для текста содержит следующие поля:

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

Пример сообщения запроса

Ниже приведен пример функции PowerShell, которая использует самозаверяющий сертификат, отправленный в Entra регистрации приложения, для создания маркера доступа и заголовка авторизации:

function Test-UploadApi {
<#
.SYNOPSIS
    requires Powershell module MSAL.PS version 4.37 or higher
    https://www.powershellgallery.com/packages/MSAL.PS/
.EXAMPLE
    Test-Api -API UploadApi -WorkspaceName "workspacename" -ResourceGroupName "rgname" -AppId "00001111-aaaa-2222-bbbb-3333cccc4444" -TenantName "contoso.onmicrosoft.com" -FilePath "C:\Users\user\Documents\stixobjects.json"
#>
[CmdletBinding()]
param (
    [Parameter(Mandatory = $true)]
    [string]$TenantName,
    [Parameter(Mandatory = $true)]
    [string]$CertThumbprint,
    [Parameter(Mandatory = $true)]
    [string]$AppId,
    [Parameter(Mandatory = $true)]
    [string]$WorkspaceId,
    [Parameter(Mandatory = $true)]
    [string]$FilePath
)
$Scope = "https://management.azure.com/.default"
# Connection details for getting initial token with self-signed certificate from local store
$connectionDetails = @{
    'TenantId'          = $TenantName
    'ClientId'          = $AppId
    'ClientCertificate' = Get-Item -Path "Cert:\CurrentUser\My\$CertThumbprint"
    scope               = $Scope
}
# Request the token
#  Using Powershell module MSAL.PS https://www.powershellgallery.com/packages/MSAL.PS/
#  Get-MsalToken is automatically using OAuth 2.0 token endpoint https://login.microsoftonline.com/$TenantName/oauth2/v2.0/token
#  and sets auth flow to grant_type = 'client_credentials'
$token = Get-MsalToken @connectionDetails

# Create header
#  Again relying on MSAL.PS which has method CreateAuthorizationHeader() getting us the bearer token
$Header = @{
    'Authorization' = $token.CreateAuthorizationHeader()
}
$Uri = "https://api.ti.sentinel.azure.com/workspaces/$workspaceId/threat-intelligence-stix-objects:upload?api-version=$apiVersion"
$stixobjects = get-content -path $FilePath
if(-not $stixobjects) { Write-Host "No file found at $FilePath"; break }
$results = Invoke-RestMethod -Uri $Uri -Headers $Header -Body $stixobjects -Method POST -ContentType "application/json"

$results | ConvertTo-Json -Depth 4
}

Общие свойства

Все объекты, импортируемые с помощью API отправки, используют эти общие свойства.

Дополнительные сведения см. в разделе Общие свойства STIX.

Индикатор

Дополнительные сведения см. в разделе Индикатор STIX.

Шаблон атаки

Следуйте спецификациям STIX для создания объекта STIX шаблона атаки. Используйте этот пример в качестве дополнительной ссылки.

Дополнительные сведения см. в статье Шаблон атаки STIX.

Удостоверение

Следуйте спецификациям STIX для создания объекта STIX удостоверения. Используйте этот пример в качестве дополнительной ссылки.

Дополнительные сведения см. в разделе Удостоверение STIX.

Субъект угрозы

Следуйте спецификациям STIX для создания объекта STIX субъекта угроз. Используйте этот пример в качестве дополнительной ссылки.

Дополнительные сведения см. в разделе СУБЪЕКТ угроз STIX.

Связь

Следуйте спецификациям STIX для создания объекта STIX связи. Используйте этот пример в качестве дополнительной ссылки.

Дополнительные сведения см. в разделе Связь STIX.

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

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

Текст ответа представляет собой массив сообщений об ошибках в формате JSON:

Объект Error

Ограничения регулирования для API

Для каждого пользователя применяются все ограничения:

• 100 объектов на запрос.
• 100 запросов в минуту.

Если количество запросов превышает ограничение, 429 возвращается код состояния HTTP в заголовке ответа со следующим текстом ответа:

{
    "statusCode": 429,
    "message": "Rate limit is exceeded. Try again in <number of seconds> seconds."
}

Приблизительно 10 000 объектов в минуту — это максимальная пропускная способность до получения ошибки регулирования.

Пример текста запроса индикатора

В следующем примере показано, как представить два индикатора в спецификации STIX. Test Indicator 2 выделяет значение протокола светофора (TLP) с маркировкой сопоставленного объекта, а также уточняет его описание и метки на английском языке.

{
    "sourcesystem": "test", 
    "stixobjects":[
        {
            "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"
                }
            ]
        }
    ]
}

Пример текста ответа с ошибкой проверки

Если все объекты STIX успешно проверены, возвращается состояние HTTP 200 с пустым текстом ответа.

Если проверка одного или нескольких объектов завершается ошибкой, текст ответа возвращается с дополнительными сведениями. Например, если вы отправляете массив с четырьмя индикаторами и первые три являются хорошими, но четвертый не имеет id (обязательное поле), то создается ответ http status code 200 вместе со следующим текстом:

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

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

Другие примеры

Пример индикатора

В этом примере индикатор помечается зеленым TLP, используя marking-definition--089a6ecb-cc15-43cc-9494-767639779123 в общем свойстве object_marking_refs . Дополнительные атрибуты toxicity расширения и rank также включены. Хотя эти свойства отсутствуют в схеме Microsoft Sentinel индикаторов, прием объекта с этими свойствами не приводит к ошибке. На свойства просто не ссылаются и не индексируются в рабочей области.

{
    "sourcesystem": "TestStixObjects",
    "stixobjects": [
    {
          "type": "indicator",
          "spec_version": "2.1",
          "id": "indicator--12345678-71a2-445c-ab86-927291df48f8",
          "created": "2010-02-26T18:29:07.778Z",
          "modified": "2011-02-26T18:29:07.778Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ],
          "extensions": {
            "extension-definition--d83fce45-ef58-4c6c-a3f4-1fbc32e98c6e": {
              "extension_type": "property-extension",
              "rank": 5,
              "toxicity": 8
            }
          },
          "name": "Indicator 2.1 Test",
          "description": "TS ID: 35766958; iType: bot_ip; State: active; Org: 52.3667; Source: Emerging Threats - Compromised",
          "indicator_types": [
            "threatstream-severity-low",
            "threatstream-confidence-80"
          ],
          "pattern": "[ipv4-addr:value = '94.102.52.185']",
          "pattern_type": "stix",
          "pattern_version": "2.1",
          "valid_from": "2015-02-26T18:29:07.778Z",
          "valid_until": "2016-02-26T18:29:07.778Z",
          "kill_chain_phases": [
            {
              "kill_chain_name": "lockheed-martin-cyber-kill-chain",
              "phase_name": "reconnaissance"
            }
          ]
        }
    ]
}

Пример шаблона атаки

Этот шаблон атаки и любые другие объекты STIX, не являющиеся индикаторами, доступны только в интерфейсе управления, если вы не согласитесь на новые таблицы STIX. Дополнительные сведения о таблицах, необходимых для просмотра подобных объектов в KQL, см. в разделе Просмотр аналитики угроз.

{
    "sourcesystem": "TestStixObjects",
    "stixobjects": [
        {
          "type": "attack-pattern",
          "spec_version": "2.1",
          "id": "attack-pattern--fb6aa549-c94a-4e45-b4fd-7e32602dad85",
          "created": "2015-05-15T09:12:16.432Z",
          "modified": "2015-05-20T09:12:16.432Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": false,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ],
          "extensions": {
            "extension-definition--d83fce45-ef58-4c6c-a3f4-1fbc32e98c6e": {
              "extension_type": "property-extension",
              "rank": 5,
              "toxicity": 8
            }
          },
          "external_references": [
            {
              "source_name": "capec",
              "description": "spear phishing",
              "external_id": "CAPEC-163"
            }
          ],
          "name": "Attack Pattern 2.1",
          "description": "menuPass appears to favor spear phishing to deliver payloads to the intended targets. While the attackers behind menuPass have used other RATs in their campaign, it appears that they use PIVY as their primary persistence mechanism.",
          "kill_chain_phases": [
            {
              "kill_chain_name": "mandiant-attack-lifecycle-model",
              "phase_name": "initial-compromise"
            }
          ],
          "aliases": [
            "alias_1",
            "alias_2"
          ]
        }
    ]
}

Пример связи с субъектом угроз и удостоверением

{
    "sourcesystem": "TestStixObjects",
    "stixobjects": [
    {
          "type": "identity",
          "spec_version": "2.1",
          "id": "identity--733c5838-34d9-4fbf-949c-62aba761184c",
          "created": "2016-08-23T18:05:49.307Z",
          "modified": "2016-08-23T18:05:49.307Z",
          "name": "Identity 2.1",
          "description": "Disco Team is the name of an organized threat actor crime-syndicate.",
          "identity_class": "organization",
          "contact_information": "disco-team@stealthemail.com",
          "roles": [
            "administrators"
          ],
          "sectors": [
            "education"
          ],
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ]
        },
        {
          "type": "threat-actor",
          "spec_version": "2.1",
          "id": "threat-actor--dfaa8d77-07e2-4e28-b2c8-92e9f7b04428",
          "created": "2014-11-19T23:39:03.893Z",
          "modified": "2014-11-19T23:39:03.893Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ],
          "name": "Threat Actor 2.1",
          "description": "This organized threat actor group operates to create profit from all types of crime.",
          "threat_actor_types": [
            "crime-syndicate"
          ],
          "aliases": [
            "Equipo del Discoteca"
          ],
          "first_seen": "2014-01-19T23:39:03.893Z",
          "last_seen": "2014-11-19T23:39:03.893Z",
          "roles": [
            "agent"
          ],
          "goals": [
            "Steal Credit Card Information"
          ],
          "sophistication": "expert",
          "resource_level": "organization",
          "primary_motivation": "personal-gain",
          "secondary_motivations": [
            "dominance"
          ],
          "personal_motivations": [
            "revenge"
          ]
        },
        {
          "type": "relationship",
          "spec_version": "2.1",
          "id": "relationship--a2e3efb5-351d-4d46-97a0-6897ee7c77a0",
          "created": "2020-02-29T18:01:28.577Z",
          "modified": "2020-02-29T18:01:28.577Z",
          "relationship_type": "attributed-to",
          "description": "Description Relationship 2.1",
          "source_ref": "threat-actor--dfaa8d77-07e2-4e28-b2c8-92e9f7b04428",
          "target_ref": "identity--733c5838-34d9-4fbf-949c-62aba761184c",
          "start_time": "2020-02-29T18:01:28.577Z",
          "stop_time": "2020-03-01T18:01:28.577Z",
          "created_by_ref": "identity--f431f809-377b-45e0-aa1c-6a4751cae5ff",
          "revoked": true,
          "labels": [
            "heartbleed",
            "has-logo"
          ],
          "confidence": 55,
          "lang": "en",
          "external_references": [
            {
              "source_name": "veris",
              "description": "Threat report",
              "external_id": "0001AA7F-C601-424A-B2B8-BE6C9F5164E7",
              "url": "https://abc.com//example.json",
              "hashes": {
                "SHA-256": "6db12788c37247f2316052e142f42f4b259d6561751e5f401a1ae2a6df9c674b"
              }
            }
          ],
          "object_marking_refs": [
            "marking-definition--34098fce-860f-48ae-8e50-ebd3cc5e41da"
          ],
          "granular_markings": [
            {
              "marking_ref": "marking-definition--089a6ecb-cc15-43cc-9494-767639779123",
              "selectors": [
                "description",
                "labels"
              ],
              "lang": "en"
            }
          ]
        }
    ]
}

Дальнейшие действия

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

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