Создайте глубинные ссылки на запросы к графу Microsoft Sentinel

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

Запросы глубокой ссылки внедрены в URL-адрес в виде текста Base64 (base64url), чтобы они могли надежно передаваться в качестве одного параметра URL-адреса. Запрос не шифруется, не подписывается или сжимается.

Prerequisites

Чтобы создать глубокую ссылку, вам потребуется следующее:

• Экземпляр графа, который существует в клиенте. Вы передаете его имя через параметр graphInstance. Сведения о поиске допустимых имен см. в разделе "Поиск допустимых значений graphInstance".
• Текст запроса, который нужно открыть в редакторе.

Чтобы открыть связанный запрос, необходимо разрешение на просмотр графа и выполнение запросов. Глубокие ссылки не обходят средства контроля доступа, поэтому пользователь без необходимых разрешений не может получить доступ к запросу, на который ведёт ссылка. Дополнительные сведения см. в разделе "Начало работы с пользовательскими графами" в Microsoft Sentinel.

Создание URL-адреса глубокой ссылки

URL-адрес глубокой ссылки состоит из нескольких компонентов. Ниже описаны основные структуры и каждая часть:

https://security.microsoft.com/graphs?tid=<tenant-id>&graphInstance=<graph-name>&query=<encoded-query>&autoRun=<true|false>&addQuery=<true|false>

Компоненты URL-адреса

Пример разбора

Следующая глубокая ссылка открывает страницу графа Microsoft Sentinel с определенным запросом, предварительно заполненным в редакторе, но не выполняет его автоматически:

https://security.microsoft.com/graphs
  ?tid=12345678-1234-1234-1234-123456789012
  &graphInstance=IdentityAttackScenarioGraph
  &query=Ly8gVmlzdWFsaXplIGFueSBncmFwaApNQVRDSCAoeCktW3ldLT4oeikKUkVUVVJOICoKTElNSVQgMTAw
  &autoRun=false

Параметр query декодирует следующий запрос GQL:

// Visualize any graph
MATCH (x)-[y]->(z)
RETURN *
LIMIT 100

Разбивка:

• Базовая база: https://security.microsoft.com/graphs
• Арендатор: tid=12345678-1234-1234-1234-123456789012
• Граф:graphInstance=IdentityAttackScenarioGraph
• Запрос: query=Ly8gVmlzdWFsaXplIGFueSBncmFwaApNQVRDSCAoeCktW3ldLT4oeikKUkVUVVJOICoKTElNSVQgMTAw (кодирует GQL, показанный выше)
• Автоматическое выполнение: autoRun=false (запрос не будет выполняться автоматически)

Кодирование запроса с помощью base64url

query Кодируйте значение следующими шагами. Эти шаги соответствуют функции encodeQueryBase64 в QueryUtils.ts.

1. UTF-8 кодирует необработанный текст запроса в байты.
2. Base64 кодирует эти байты.
3. Замените + на -, а / — на _, чтобы сделать значение безопасным для URL.
4. Удалите все завершающие символы-заполнители =.
5. Поместите результат в URL как параметр query. Стандартная кодировка URL-адресов безопасна для применения сверху.

Создание ссылки

Следующий код JavaScript в точности соответствует кодировщику приложения и формирует полную глубокую ссылку:

function encodeQueryBase64(query) {
  const bytes = new TextEncoder().encode(query);
  const binary = String.fromCharCode(...bytes);
  return btoa(binary)
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/g, '');
}

const base = 'https://security.microsoft.com/graphs';
const params = new URLSearchParams({
  graphInstance: 'IdentityAttackScenarioGraph',
  query: encodeQueryBase64('MATCH (x)-[y]->(z)\nRETURN *\nLIMIT 100'),
  autoRun: 'true',
});
const deeplink = `${base}?${params.toString()}`;

Условия автоматического запуска

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

• autoRun не задано для литеральной строки false.
• Декодированные запросы не пусты.
• graphInstance существует для арендатора.

Найдите допустимые значения graphInstance

Вы можете использовать любой имеющийся в вашем арендаторе экземпляр графа по имени экземпляра. Чтобы найти доступные названия, либо просмотрите интерфейс графов Microsoft Sentinel, либо вызовите API службы графов Microsoft Sentinel GET /graph-instances. Этот API возвращает экземпляры графа, доступные вашему клиенту. При необходимости можно отфильтровать результаты с помощью ?graphTypes=. Используйте имя любого возвращённого экземпляра.

GET https://api.securityplatform.microsoft.com/graphs/graph-instances?graphTypes=Custom

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

• Откройте график и предварительно заполните запрос, не выполняя его: Установите autoRun=false, как показано в примере. Пользователи могут просматривать и изменять запрос перед выполнением, что позволяет избежать ненужных затрат на запрос.
• Откройте граф без запроса: опустите query параметр или задайте.addQuery=false Используйте этот параметр для перенаправления пользователей в граф для ручного изучения без применения предопределенного запроса.
• Выбрать определенного арендатора: Включите tid=<tenant-id>. Затем глубокая ссылка открывается в правильном арендаторе без необходимости вручную переключаться между арендаторами.

Связанные материалы

• Общие сведения о графе Microsoft Sentinel
• Настраиваемые графы в Microsoft Sentinel
• Создание настраиваемых графов в Microsoft Sentinel
• Справочник по GQL для графа Microsoft Sentinel