Использование Microsoft Graph Security API

Microsoft Graph Security API предоставляет унифицированный интерфейс и схему для интеграции с решениями безопасности от Майкрософт и партнеров по экосистеме. Это позволяет клиентам упростить операции, связанные с безопасностью, и лучше защититься от возрастающих киберугроз. API безопасности Microsoft Graph объединяет запросы для всех подключенных поставщиков безопасности и агрегирует ответы. Используйте Microsoft Graph Security API для создания приложений, которые:

Консолидируйте и сопоставляйте оповещения системы безопасности из нескольких источников.
Извлекайте и исследуйте все инциденты и оповещения от служб, которые входят в состав Microsoft 365 Defender или интегрированы с ним.
Разблокируют контекстные данные для информирования расследований.
Автоматизируйте задачи безопасности, бизнес-процессы, рабочие процессы и отчетность.
Отправка индикаторов угроз в продукты Майкрософт для настраиваемого обнаружения.
Вызывайте действия в ответ на новые угрозы.
Обеспечьте видимость данных безопасности для упреждающего управления рисками.

Microsoft Graph Security API предоставляет основные функции, как описано в следующих разделах.

Расширенная охота

Расширенное выслеживание— это средство для выслеживания угроз на основе запросов, которое позволяет изучать необработанные данные за период до 30 дней. Вы можете проводить инспекцию событий в своей сети для поиска индикаторов и объектов угроз на профилактической основе. Гибкий доступ к данным обеспечивает неограниченную охоту на известные и потенциальные угрозы.

Используйте runHuntingQuery для выполнения запроса на языке запросов язык запросов Kusto (KQL) к данным, хранящимся в Microsoft 365 Defender. Используйте возвращенный набор результатов для расширения имеющихся результатов исследования или для обнаружения необнаруженных угроз в сети.

Квоты и выделение ресурсов

Следующие условия относятся ко всем запросам.

Запросы изучают и возвращают данные за последние 30 дней.
Результаты могут возвращать до 100 000 строк.
Вы можете сделать до 45 звонков в минуту на одного клиента. Количество звонков зависит от размера клиента.
Каждому клиенту выделяются ресурсы ЦП в зависимости от размера клиента. Если клиент достигает 100 % выделенных ресурсов, запросы блокируются до истечения следующего 15-минутного цикла. Чтобы избежать блокировки запросов из-за чрезмерного потребления, следуйте инструкциям в статье "Оптимизация запросов, чтобы избежать превышения квот ЦП".
Если один запрос выполняется более трех минут, время ожидания истекло и возвращается ошибка.
Код ответа 429 HTTP указывает на достижение выделенных ресурсов ЦП либо по количеству отправленных запросов, либо по выделенному времени работы. Прочитайте текст ответа, чтобы понять достигнутый предел.
Общий размер результатов запроса не должен превышать 50 МБ. Это ограничение относится не только к количеству записей; На размер результатов запроса также влияют такие факторы, как число столбцов, типы данных и длина полей.

Миграция из старых API

Расширенные API поиска в Microsoft Graph заменяют более раннюю версию API, которая была доступна через https://api.security.microsoft.com/api/advancedhunting/run конечные точки and https://api.security.microsoft.com/api/advancedqueries/run . Поддержка старых API прекращена и они перестанут возвращать данные 1 февраля 2027 года.

Чтобы перейти на расширенные API поиска в Microsoft Graph, обновите следующие параметры в приложении:

Subject	Старые параметры	Microsoft Graph
Конечные точки	https://api.securitycenter.microsoft.com/api/advancedqueries/run https://api.security.microsoft.com/api/advancedhunting/run	https://graph.microsoft.com/v1.0/security/runHuntingQuery
URI ресурса	Расширенная защита от угроз в Microsoft Defender для конечной точки включена`https://api.securitycenter.microsoft.com`	Microsoft Graph включен `https://graph.microsoft.com`
Разрешения API	AdvancedQuery.Read (делегированный) и AdvancedQuery.Read.All (приложение) в Microsoft Defender для конечной точки (ранее Advanced Threat Protection в Защитнике Windows) AdvancedHunting.Read (делегированный) и AdvancedHunting.Read.All (приложение) в системе защиты от угроз (Майкрософт)	ThreatHunting.Read.All (делегированные и прикладные)
Текст запроса	Свойство запроса . Пример `{"Query":"DeviceProcessEvents \\|where InitiatingProcessFileName =~ 'powershell.exe' \\|where ProcessCommandLine contains 'appdata'\\|project Timestamp, FileName, InitiatingProcessFileName, DeviceId\\|limit 2"}`	Свойства "Запрос " и "Отрезок времени ". Пример: `{"Query": "DeviceProcessEvents", "Timespan": "P90D"}`
Отклик	Объект QueryResponse , состоящий из Stats, Schema и Results	huntingQueryResults", состоящий из схемы (вместо схемы) и результатов (вместо результатов).

Дополнительные сведения о том, как разрешить приложению вызывать API Microsoft Graph, см. в статьях " Получение доступа от имени пользователя " и "Получение доступа без пользователя".

Миграция потока Power Platform (PowerApps / Power Automate / Logic Apps)

В Microsoft Graph отсутствует встроенное действие расширенного поиска, которое было доступно в соединителе Power Platform для ATP в Microsoft Defender. Чтобы продолжить использование расширенного поиска в потоках Power Platform, создайте настраиваемый соединитель. Дополнительные сведения см. в статье " Создание пользовательского соединителя пакетного пакета Microsoft Graph JSON для Power Automate " и использование параметров Microsoft Graph, описанных в предыдущей таблице.

Миграция потока Power BI

Если вы используете настраиваемый отчет Power BI, созданный с помощью более ранней версии API, обновите запрос Power BI, чтобы использовать параметры Microsoft Graph, описанные в предыдущей таблице. Дополнительные сведения см. в статье Создание настраиваемых отчетов Microsoft Defender XDR с помощью Microsoft Graph Security API и Power BI.

Настраиваемое обнаружение

Вы можете создавать расширенные пользовательские правила обнаружения для операций безопасности, чтобы заблаговременно отслеживать угрозы и принимать меры. Например, можно создать настраиваемые правила обнаружения для поиска известных индикаторов или неправильно настроенных устройств. Эти правила автоматически вызывают оповещения и любые указанные вами ответные действия.

Квоты

Вывод списка правил обнаружения: 10 правил в минуту для каждого приложения, 300 правил в час для каждого приложения и 600 правил в час для каждого клиента.
Получение правила обнаружения: 100 правил в минуту для каждого приложения, 1500 правил в час для каждого приложения и 1800 правил в час для каждого клиента.
Создание правила обнаружения: 10 правил в минуту для каждого приложения, 1 500 правил в час для каждого приложения и 1 800 правил в час для каждого клиента.
Обновление правила обнаружения: 100 правил в минуту для каждого приложения, 1 500 правил в час для каждого приложения и 1 800 правил в час для каждого клиента.
Удаление правила обнаружения: 100 правил в минуту для каждого приложения, 1 500 правил в час для каждого приложения и 1 800 правил в час для каждого клиента.

Оповещения

Оповещения — это подробные предупреждения о подозрительных действиях в клиенте клиента, которые Майкрософт или партнерские поставщики безопасности определили и пометили для действия. В атаках обычно используются различные методы против разных типов объектов, таких как устройства, пользователи и почтовые ящики. Результатом являются оповещения от нескольких поставщиков безопасности для нескольких сущностей в клиенте. Объединение отдельных оповещений для получения информации об атаке может быть сложной задачей и отнимать много времени.

API безопасности предлагает два типа оповещений: они объединяют другие оповещения от поставщиков безопасности и упрощают анализ атак и определение ответных мер:

Оповещения и инциденты — это новейшее поколение оповещений в Microsoft Graph API безопасности. Они представлены ресурсом оповещения и его коллекцией, ресурсом инцидентаmicrosoft.graph.security, определенным в пространстве имен.
Устаревшие оповещения — это первое поколение оповещений в ИИ безопасности Microsoft Graph. Они представлены ресурсом оповещений , microsoft.graph определенным в пространстве имен.

Важно!

Чтобы просматривать оповещения и инциденты Sentinel, необходимо подключить Sentinel к порталу Defender. Дополнительные сведения см. в разделе Подключение Microsoft Sentinel к порталу Microsoft Defender.

Оповещения и инциденты

Эти ресурсы оповещений сначала получают данные оповещений из служб поставщиков безопасности, которые являются частью Microsoft 365 Defender или интегрированы с ним. Затем они потребляют данные, чтобы вернуть подробные и ценные подсказки о завершенной или продолжающейся атаке, затронутых активах и связанных с ними доказательствах. Кроме того, они автоматически сопоставляют другие оповещения с теми же методами атаки или тем же злоумышленником с инцидентом, чтобы предоставить более широкий контекст атаки. Они рекомендуют действия по реагированию и исправлению, предлагая согласованные действия для всех различных поставщиков. Богатое содержимое облегчает аналитикам коллективное расследование угроз и реагирование на них.

Оповещения от следующих поставщиков безопасности доступны в этих расширенных оповещениях и инцидентах:

Устаревшие оповещения

Важно!

Устаревший API оповещений не рекомендуется использовать и будет снят с поддержки 15 октября 2026 г. Перейдите на новый API оповещений и инцидентов . Дополнительные сведения см. в разделе Переход от устаревших оповещений к API оповещений и инцидентов.

Устаревшие ресурсы оповещений объединяют вызовы федерации поддерживаемых поставщиков безопасности Azure и Microsoft 365 Defender. Они объединяют общие данные оповещений между различными доменами, что позволяет приложениям унифицировать и оптимизировать управление проблемами безопасности во всех интегрированных решениях. Они позволяют приложениям сопоставлять оповещения и контекст, чтобы улучшить защиту от угроз и реагирование.

Устаревшая версия API безопасности предоставляет ресурс оповещений, который объединяет вызовы поддерживаемых поставщиков безопасности Azure и Microsoft 365 Defender. Этот ресурс оповещений объединяет данные оповещений, общие для различных доменов, что позволяет приложениям унифицировать и оптимизировать управление проблемами безопасности во всех интегрированных решениях. Это позволяет приложениям сопоставлять оповещения и контекст для улучшения защиты от угроз и реагирования.

С помощью функции обновления оповещений можно синхронизировать состояние определенных оповещений в различных продуктах и службах для обеспечения безопасности, интегрированных с Microsoft Graph Security API, обновив объект оповещения .

Оповещения от следующих поставщиков доступны в ресурсе оповещений . Поддержка оповещений RECEIVE, PATCH alerts и подписки (через веб-перехватчики) указана в следующей таблице.

Поставщик безопасности	Оповещение GET	Оповещение PATCH	Подписка на оповещения
Защита Microsoft Entra ID	✓	Уведомление о проблеме *	✓
Microsoft 365 По умолчанию Cloud App Security Пользовательское оповещение	✓	Уведомление о проблеме	Уведомление о проблеме
Microsoft Defender for Cloud Apps	✓	Уведомление о проблеме *	✓
Microsoft Defender для конечной точки **	✓	✓	Уведомление о проблеме
Microsoft Defender для удостоверений ***	✓	Уведомление о проблеме *	✓
Microsoft Sentinel (прежнее название — Azure Sentinel)	✓	Не поддерживается в Microsoft Sentinel	✓

Примечание. Новые поставщики постоянно подключаются к экосистеме безопасности Microsoft Graph. Чтобы запросить у новых поставщиков или получить расширенную поддержку от существующих поставщиков, отправьте сообщение о проблеме в репозитории GitHub по безопасности Microsoft Graph.

* Проблема с файлом: состояние оповещения обновляется в приложениях, интегрированных с API безопасности Microsoft Graph, но не отражается в интерфейсе управления поставщика.

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

Оповещения Microsoft Defender for Idability доступны через интеграцию Microsoft Defender for Cloud Apps. Это означает, что вы будете получать оповещения Microsoft Defender for Credential только в том случае, если вы присоединились к Unified SecOps и подключили Microsoft Defender for Credential к Microsoft Defender for Cloud Apps. Узнайте больше о том, как интегрировать Microsoft Defender для удостоверений и Microsoft Defender for Cloud Apps.

Имитация атак и обучение

Симуляция атак и обучение входит в состав Microsoft Defender для Office 365. Эта служба позволяет пользователям в клиенте испытать на себе реалистичную учебную фишинговую атаку и извлечь уроки. Симуляция социотехники и обучение пользователей помогают снизить риск взлома с применением таких методов атаки. API симуляции атак и обучения позволяет администраторам клиентов просматривать запущенные упражнения и тренинги по симуляции и получать отчеты об аналитике поведения пользователей в Интернете в условиях симуляции фишинга.

Обнаружение электронных данных

Microsoft Purview eDiscovery предоставляет комплексный рабочий процесс для хранения, сбора, анализа, просмотра и экспорта контента, реагирующего на внутренние и внешние исследования вашей организации.

Запрос в журнал аудита

Аудит Microsoft Purview Microsoft Purview предоставляет интегрированное решение, помогающее организациям эффективно реагировать на события безопасности, судебные расследования, внутренние расследования и обязательства по обеспечению соответствия требованиям. Тысячи операций, выполняемых пользователями и администраторами в десятках служб и решений Microsoft 365, записываются и сохраняются в едином журнале аудита организации. Записи аудита для этих событий доступны для поиска службе безопасности, ИТ-администраторам, командам по управлению внутренними рисками и исследователям в области законодательства и соответствия требованиям в организации. Эта возможность обеспечивает информированность о действиях, выполняемых в организации Microsoft 365.

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

Проблемы со здоровьем

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

Примечание. API проблем с работоспособностью Microsoft Defender for Credential доступен только в плане Defender для удостоверений или планах обслуживания безопасности Microsoft 365 E5/A5/G5/F5.

Датчики

API управления датчиками удостоверений в Defender позволяют:

Создавайте подробные отчеты о датчиках в рабочей области, включая сведения об имени сервера, версии, типе, состоянии и состоянии работоспособности.
Управляйте параметрами датчика, например добавлением описаний, включением или отключением отложенных обновлений и указанием контроллера домена, к которому датчик подключается для отправки запроса Entra ID.
Определите датчики, готовые к активации.
Определите, должны ли датчики в вашей инфраструктуре активироваться автоматически или вручную.
Определите серверы, готовые к активации с помощью единого агента.
Включение или отключение автоматической активации подходящих серверов для единого агента.
Активация или деактивация единого агента на соответствующих серверах.
Включение или отключение автоматического включения необходимой конфигурации аудита событий во время активации датчика.

identityAccounts

Ресурс identityAccounts и связанные с ним API позволяют получать сведения о пользователях, помеченных оповещениями Microsoft Defender for Credential, и применять такие действия, как отключение учетных записей и сброс пароля пользователя для скомпрометированного пользователя.

Инциденты

Инцидент — это совокупность взаимосвязанных оповещений и связанных с ними данных, составляющих историю атаки. Управление инцидентами является частью Microsoft 365 Defender и доступно на портале Microsoft 365 Defender (https://security.microsoft.com/).

Службы и приложения Microsoft 365 создают оповещения при обнаружении подозрительного или вредоносного события или действия. Отдельные оповещения предоставляют ценные подсказки о завершенной или продолжающейся атаке. Однако в атаках обычно используются различные методы против различных типов сущностей, например устройств, пользователей и почтовых ящиков. Это приводит к созданию нескольких оповещений для нескольких сущностей в клиенте.

Поскольку объединение отдельных оповещений для получения информации об атаке может быть сложной и трудоемкой задачей, Microsoft 365 Defender автоматически объединяет оповещения и связанные с ними сведения в инцидент.

Группировка связанных оповещений в инцидент дает полное представление об атаке. Например, вы можете увидеть:

Где началась атака.
Какие методы использовались.
Насколько далеко зашла атака на ваш арендатор.
Область атаки, например количество затронутых устройств, пользователей и почтовых ящиков.
Все данные, связанные с атакой.

Ресурс инцидентов и его API позволяют сортировать инциденты для создания обоснованного реагирования кибербезопасности. Он предоставляет коллекцию инцидентов и связанных с ними оповещений, которые были помечены в вашей сети, в пределах интервала времени, указанного в политике хранения среды.

Защита информации

API оценки угроз Microsoft Graph помогает организациям оценить угрозу, полученную любым пользователем в клиенте. Благодаря этому пользователи могут сообщать в корпорацию Майкрософт о полученной нежелательной почте, фишинговых URL-адресах и вредоносных вложениях. Результат проверки политики и результат повторного сканирования может помочь администраторам клиента понять заключение сканирования угроз и настроить политику организации.

Управление записями

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

Оценка безопасности

Оценка безопасности (Майкрософт) — это решение аналитики безопасности, обеспечивающее обзор вашего набора решений безопасности и способов его улучшения. С помощью единой оценки вы сможете лучше понять, что вы сделали для снижения риска в решениях Майкрософт. Также можно сравнить свою оценку с другими организациями и просмотреть ее изменение со временем. Сущности безопасности Microsoft Graph secureScore и secureScoreControlProfile помогают сбалансировать потребности организации в безопасности и производительности, обеспечивая при этом оптимальный набор функций безопасности. Вы также можете спрогнозировать значение оцени после внедрения функций безопасности.

Аналитика угроз

Аналитика угроз в Microsoft Defender предоставляет средства анализа угроз мирового класса, которые помогают защитить вашу организацию от современных киберугроз. С помощью аналитики угроз можно выявлять злоумышленников и их операции, ускорять обнаружение и устранение угроз, а также улучшать инвестиции и рабочие процессы в области безопасности.

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

Основные варианты использования

Ниже приведены некоторые из наиболее популярных запросов на работу с Microsoft Graph Security API.

Варианты использования	Ресурсы REST	Попробовать в песочнице Graph
Обновление профилей составляющих оценки безопасности	Обновление объектов secureScoreControlProfile	https://graph.microsoft.com/v1.0/security/secureScoreControlProfiles/{id}
Оповещения и инциденты
Перечисление оповещений	Перечисление оповещений	https://graph.microsoft.com/v1.0/security/alerts_v2
Обновление оповещения	Обновление оповещения	https://graph.microsoft.com/v1.0/security/alerts/{id}
Получение списка инцидентов	Получение списка инцидентов	https://graph.microsoft.com/v1.0/security/incidents
Составление списка инцидентов с оповещениями	Получение списка инцидентов	https://graph.microsoft.com/v1.0/security/incidents?$expand=оповещения
Обновление данных об инциденте	Обновление данных об инциденте	https://graph.microsoft.com/v1.0/security/incidents/{id}
Обнаружение электронных данных
Перечисление случаев обнаружения электронных данных	Перечисление eDiscoveryCases	https://graph.microsoft.com/v1.0/security/cases/eDiscoveryCases
Перечисление операций со случаями обнаружения электронных данных	Перечисление caseOperations	https://graph.microsoft.com/v1.0/security/cases/ediscoveryCases/{id}/operations
Удостоверения
Перечисление проблем с работоспособностью	Перечисление проблем с работоспособностью	https://graph.microsoft.com/v1.0/security/identities/healthIssues
Список датчиков	Список датчиков	https://graph.microsoft.com/v1.0/security/identities/sensors
Устаревшие оповещения
Перечисление оповещений	Перечисление оповещений	https://graph.microsoft.com/v1.0/security/alerts
Обновление оповещений	Обновление оповещения	https://graph.microsoft.com/v1.0/security/alerts/{alert-id}
Оценки безопасности
Список оценок безопасности	Список объектов secureScore	https://graph.microsoft.com/v1.0/security/secureScores
Получение оценки безопасности	Получение объектов secureScore	https://graph.microsoft.com/v1.0/security/secureScores/{id}
Список профилей составляющих оценки безопасности	Список объектов secureScoreControlProfiles	https://graph.microsoft.com/v1.0/security/secureScoreControlProfiles
Получение профилей составляющих оценки безопасности	Получение объектов secureScoreControlProfile	https://graph.microsoft.com/v1.0/security/secureScoreControlProfiles/{id}

Вы можете использовать уведомления об изменениях Microsoft Graph для подписки и получения уведомлений об обновлениях сущностей безопасности Microsoft Graph.

Ресурсы

Написание кода и участие в следующих примерах API безопасности Microsoft Graph:

Взаимодействие с сообществом:

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

API безопасности Microsoft Graph может открывать новые способы взаимодействия с различными решениями безопасности от корпорации Майкрософт и ее партнеров. Чтобы приступить к работе, следуйте указанным ниже инструкциям.

Подробно изучите оповещения, объекты secureScore и secureScoreControlProfile.
Опробуйте API в песочнице Graph. В разделе Примеры запросов выберите элемент Показать другие примеры и установите категорию безопасности в положение Вкл.
Попробуйте подписаться на получение уведомлений об изменениях объекта.

Напишите код и участвуйте в этом примере API безопасности Microsoft Graph:

Пример для PowerShell

Изучите другие варианты подключения к API безопасности Microsoft Graph: