Плейбуки в Kaspersky EDR Expert 8.1: Полное руководство

1.1. Определение

Плейбук (Playbook) — это объект, который реагирует на алерты или инциденты в соответствии с заданным алгоритмом. Плейбук запускает алгоритм, включающий в себя последовательность действий по реагированию, которые помогают анализировать и обрабатывать алерты или инциденты.

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

1.2. Режимы работы плейбука

Плейбук может выполняться в одном из трёх режимов:

1.3. Зачем нужны плейбуки

Плейбуки решают три ключевые задачи SOC:

1.4. Область применения

Плейбуки используются в следующих сценариях:

• 🔴 Автоматическое реагирование на критические угрозы — ransomware, sandbox-детекты, компрометация учётных записей
• 🟡 Автоматическое обогащение данных — отправка наблюдаемых объектов (IP, хеши, домены, URL) в Kaspersky Threat Intelligence Portal через действие iocsEnrichment для получения дополнительной информации об угрозах
• 🟢 Ручное реагирование — аналитик выбирает инцидент и запускает плейбук
• 🔵 Расследование — сбор дампов памяти, образов дисков, ключей реестра

1.5. Перечень возможностей плейбуков

Плейбуки в Kaspersky EDR Expert 8.1 предоставляют следующие возможности:

В этом разделе разберём, какие бывают плейбуки в Kaspersky EDR Expert, как выбрать область действия и какие архитектурные ограничения нужно учитывать при проектировании сценариев реагирования.

2.1. Два типа плейбуков

В Kaspersky EDR Expert 8.1 существует два типа плейбуков: предустановленные (от Лаборатории Касперского) и пользовательские (созданные администраторами SOC).

2.1.1. Предустановленные плейбуки [KL]

Предустановленные плейбуки созданы специалистами «Лаборатории Касперского» и отмечены префиксом [KL] в названии. Они основаны на правилах корреляции KUMA и закрывают типовые сценарии реагирования на угрозы.

Список предустановленных плейбуков:

Особенности предустановленных плейбуков:

Как модифицировать предустановленный плейбук:

Поскольку алгоритм предустановленного плейбука нельзя изменить напрямую, необходимо:

1. Открыть плейбук [KL] в Консоли OSMP (Мониторинг → Плейбуки).
2. Нажать кнопку «Дублировать и изменить».
3. Система создаст копию плейбука с новым именем (например, My P003 Custom).
4. В копии можно изменять алгоритм, триггер и все параметры.
5. Оригинальный плейбук [KL] остаётся неизменным.

💡 Рекомендация: Перед дублированием убедитесь, что настроены интеграции, необходимые для работы плейбука (Active Directory для blockLDAPAccount, Kaspersky TIP для iocsEnrichment, KASAP для assignKasapGroup).

2.1.2. Пользовательские плейбуки

Пользовательские плейбуки создаются администраторами SOC под конкретные задачи инфраструктуры. В отличие от предустановленных, они предоставляют полный контроль над всеми компонентами.

Обязательные параметры при создании пользовательского плейбука:

Дополнительные возможности:

• Импорт/экспорт через XDR REST API для переноса плейбуков между тенантами
• Полное управление версиями (сравнение, восстановление)
• Настройка ручного подтверждения для опасных действий
• Использование любых из 19 действий по реагированию

2.2. Область действия (критическое ограничение)

Критическое ограничение архитектуры: Область действия одного плейбука ограничена только алертами или только инцидентами. Нельзя создать плейбук, который обрабатывает оба типа объектов одновременно.

2.2.1. Как это влияет на синтаксис

Выбранная область действия определяет, какое ключевое слово используется в jq-выражениях триггера и алгоритма:

2.2.2. Почему структура различается

Различие в синтаксисе связано с моделью данных:

• Алерт — самостоятельный объект. Его активы, наблюдаемые объекты и события лежат непосредственно в корне: alert.Assets[].
• Инцидент — агрегатор нескольких алертов. У инцидента нет собственных активов — все данные находятся внутри вложенных алертов: incident.Alerts[].Assets[].

2.2.3. Примеры для разных областей действия

Пример 1: Извлечение ID хостов

Для плейбука с областью «Алерт»:

[alert.Assets[] | select(.Type == "host") | .ID]

Для плейбука с областью «Инцидент»:

[incident.Alerts[].Assets[] | select(.Type == "host") | .ID]

Пример 2: Извлечение хешей SHA256

Для плейбука с областью «Алерт»:

[alert.Observables[] | select(.Type == "sha256") | .Value]

Для плейбука с областью «Инцидент»:

[incident.Alerts[].Observables[] | select(.Type == "sha256") | .Value]

2.2.4. Ошибка при несоответствии области действия

Если в плейбуке с областью «Алерт» использовать ключевое слово incident (или наоборот), система выдаст ошибку:

Expression does not match the selected scope

Типичные ошибки:

2.2.5. Как выбрать область действия

💡 Рекомендация: Если сценарий реагирования требует анализа нескольких связанных событий (например, фишинг + запуск вредоноса + очистка журналов), выбирайте область «Инцидент». Для точечных детектов (один файл, один процесс) достаточно области «Алерт».

2.3. Дочерние инциденты (ограничение автозапуска)

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

2.3.1. Что такое дочерние инциденты

В Kaspersky EDR Expert поддерживается сегментация — разделение инфраструктуры на логические сегменты (тенанты). При срабатывании правила корреляции может создаваться:

• Родительский инцидент — в корневом тенанте
• Дочерние инциденты — в дочерних тенантах (копии родительского для каждого сегмента)

2.3.2. Почему автоматический запуск не работает

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

• Дочерние инциденты создаются системой автоматически при сегментации
• Автоматический запуск плейбука на каждом дочернем инциденте привёл бы к дублированию действий (например, многократной изоляции одного и того же хоста)
• Аналитик должен вручную оценить, какие действия применять к дочерним инцидентам

2.3.3. Как работать с дочерними инцидентами

Способ 1: Ручной запуск

1. Открыть дочерний инцидент в Консоли OSMP (Мониторинг → Инциденты → XDR-инциденты).
2. Нажать «Выбрать плейбук».
3. Выбрать нужный плейбук из списка.
4. При необходимости выбрать целевые активы и наблюдаемые объекты.
5. Нажать «Запустить».

Способ 2: Настройка сегментации

Если критично, чтобы плейбук срабатывал автоматически, можно настроить сегментацию так, чтобы критичные инциденты не становились дочерними. Это требует планирования на этапе проектирования SOC.

Способ 3: Реагирование через родительский инцидент

Если плейбук работает с родительским инцидентом, его действия (например, addFilePreventionRules с selector: execution-tenant) применяются ко всем хостам в тенанте, включая дочерние. Это позволяет централизованно реагировать на угрозу.

2.4. Наследование тенантов

Плейбук принадлежит одному тенанту и автоматически наследуется всеми дочерними тенантами.

2.4.1. Как работает наследование

2.4.2. Как отключить наследование

Если плейбук специфичен для конкретного тенанта (например, использует уникальные интеграции, локальные скрипты или специфичные пути к файлам), наследование можно отключить:

1. Открыть плейбук для создания или изменения.
2. В настройках плейбука снять флажок «Наследовать дочерними тенантами».
3. Сохранить изменения.

После этого плейбук будет доступен только в том тенанте, где был создан.

2.4.3. Практические рекомендации

💡 Рекомендация: При создании нового плейбука всегда оценивайте, нужен ли он во всех тенантах. Если есть сомнения — отключите наследование. Включить его позже можно в любой момент.

В этом разделе разберём структуру плейбука: из каких компонентов он состоит, какие параметры обязательны, как устроен алгоритм и как система выполняет шаги.

3.1. Три компонента плейбука

Согласно официальной документации, плейбук состоит из трёх основных компонентов:

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 249249 «Плейбуки».

3.2. Параметры плейбука

При создании плейбука в Консоли OSMP настраиваются следующие параметры:

3.2.1. Обязательные параметры

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 267548 «Алгоритм плейбука».

3.2.2. Дополнительные параметры

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, разделы 249267 «Создание плейбуков» и 267548 «Алгоритм плейбука».

3.3. Режимы работы плейбука

Плейбук может выполняться в одном из трёх режимов. Режим выбирается при создании плейбука и может быть изменён позже.

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 249249 «Плейбуки».

3.3.1. Поведение при одновременном запуске (для автоматического режима)

Если плейбук в автоматическом режиме уже выполняется и появляется новый алерт/инцидент, соответствующий триггеру, можно настроить одно из трёх поведений:

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 249268 «Изменение плейбуков».

3.4. Алгоритм плейбука (executionFlow)

Алгоритм плейбука описывается в формате JSON и определяет последовательность шагов выполнения.

3.4.1. Структура JSON алгоритма

{
  "version": "1",
  "dslSpecVersion": "1.1.0",
  "actionsSpecVersion": "1",
  "playbookRunTimeout": "24h",
  "executionFlow": [
    /* шаги выполнения */
  ]
}

Обязательные поля:

• version — версия плейбука
• dslSpecVersion — версия схемы DSL
• actionsSpecVersion — версия спецификации действий
• executionFlow — массив шагов выполнения

Опциональные поля:

• playbookRunTimeout — максимальное время выполнения (по умолчанию 24h, максимум 48h)
• input — jq-выражение для преобразования входящих данных
• output — jq-выражение для изменения вывода плейбука
• timeouts — политики тайм-аута для шагов

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 267548 «Алгоритм плейбука».

3.4.2. Типы шагов выполнения

Массив executionFlow содержит шаги, которые выполняются в порядке, указанном в массиве. Существует пять типов шагов:

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, разделы 270357, 270351, 270352, 270354, 270355.

3.4.3. Пример: шаг типа «Действие»

Из предустановленного плейбука [KL] P003 "Suspicious child process from wmiprvse.exe" (область действия — Алерт):

{
  "action": {
    "function": {
      "type": "blockLDAPAccount",
      "assets": "${[ alert.Assets[] | select(.Type == \"user\" and .IsAttacker) | .ID]}"
    }
  },
  "onError": "stop"
}

Разбор:

• type: "blockLDAPAccount" — действие блокировки учётной записи в Active Directory
• assets — jq-выражение, извлекающее ID пользователей-атакующих из алерта
• onError: "stop" — при ошибке прервать выполнение плейбука

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 271611 «[KL] P003».

3.4.4. Пример: шаг типа «Цикл»

Из того же плейбука [KL] P003:

{
  "loop": {
    "batchSize": 1,
    "input": "${ [alert.OriginalEvents[] | [select(.DestinationProcessName != null and .DestinationProcessName != \"\")][] | .DestinationProcessName] }",
    "mode": "parallel",
    "onError": "stop",
    "steps": [
      {
        "action": {
          "function": {
            "type": "killProcess",
            "assets": "${[ alert.Assets[] | select(.Type == \"host\") | .ID]}",
            "params": {
              "path": "${ .[0] }"
            }
          }
        }
      }
    ]
  }
}

Разбор:

• input — jq-выражение, извлекающее имена процессов из исходных событий алерта
• batchSize: 1 — обрабатывать по одному элементу за итерацию
• mode: "parallel" — выполнять итерации параллельно
• .[0] — внутри шагов цикла текущий элемент доступен через .[0]

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 271611 «[KL] P003».

3.4.5. Пример: шаг типа «Ветвление»

Из предустановленного плейбука [KL] "Playbook for checking external IP addresses" (область действия — Инцидент):

{
  "decision": {
    "conditions": [
      {
        "condition": "${[.details.observableData[] | select(.status == \"ok\" and .ipObservableData.ipGeneralInfo.threatScore > 80)] | length > 0}",
        "name": "Condition 1",
        "steps": [
          /* шаги, выполняемые при истинности условия */
        ]
      }
    ]
  }
}

Разбор:

• condition — jq-выражение, возвращающее true или false
• name — название условия (для удобства чтения)
• steps — шаги, выполняемые, если условие истинно

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 318589 «[KL] Playbook for checking external IP addresses».

3.4.6. Обработка ошибок

Каждый шаг может содержать параметр onError, определяющий поведение при ошибке:

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 267548 «Алгоритм плейбука».

3.5. Визуальный редактор vs JSON

Алгоритм плейбука можно создавать двумя способами:

3.5.1. Визуальный редактор

Преимущества:

• Не требует знания синтаксиса JSON
• Автоматическая проверка синтаксиса
• Подсказки по полям при вводе jq-выражений
• Наглядное отображение потока выполнения

Недостатки:

• Ограниченная гибкость по сравнению с ручным написанием JSON
• Сложность при отладке больших алгоритмов

3.5.2. Ручное написание JSON

Преимущества:

• Полный контроль над структурой
• Возможность копирования алгоритмов из других плейбуков
• Удобство при работе с системами контроля версий

Недостатки:

• Требует знания синтаксиса JSON и jq
• Риск синтаксических ошибок

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 303486 «Настройка шагов выполнения плейбука в визуальном редакторе».

3.6. Статусы плейбуков

Плейбук может находиться в одном из следующих статусов:

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 264606 «Таблица плейбуков».

В этом разделе разберём, как Kaspersky EDR Expert хранит информацию об угрозах, какие данные доступны в плейбуках и как правильно к ним обращаться в зависимости от контекста выполнения.

ℹ️ Источники информации:

• Официальная справка Kaspersky EDR Expert 8.1, раздел 269125 «Модель данных алерта»
• Официальная справка Kaspersky EDR Expert 8.1, раздел 269168 «Модель данных инцидента»
• Официальная справка Kaspersky EDR Expert 8.1, раздел 267548 «Алгоритм плейбука»
• Официальная справка Kaspersky EDR Expert 8.1, раздел 273327 «Триггер плейбука»
• Примеры из предустановленных плейбуков [KL]

4.1. Модель данных алерта

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

4.1.1. Ключевые поля алерта

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

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 269125 «Модель данных алерта».

4.1.2. Структура элементов массива Assets

Каждый элемент массива Assets содержит информацию об активе:

Пример из документации ([KL] P003):

[ alert.Assets[] | select(.Type == "user" and .IsAttacker) | .ID]

Это jq-выражение извлекает ID всех пользователей-атакующих из алерта.

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 271611 «[KL] P003».

4.1.3. Структура элементов массива Observables

Каждый элемент массива Observables содержит информацию о наблюдаемом объекте:

Пример из документации ([KL] P004):

[alert.ScannedFiles[] | select(any(.DetectionTechnologies[] == "SB"; .)) | .Hashes | map(.Value)] | flatten

Это jq-выражение извлекает хеши файлов, обнаруженных через Sandbox.

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 271772 «[KL] P004».

4.2. Модель данных инцидента

Инцидент — это объект, объединяющий несколько связанных алертов в одно расследование. Инцидент создаётся либо автоматически (по правилам сегментации или корреляции), либо вручную аналитиком.

4.2.1. Ключевые поля инцидента

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

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 269168 «Модель данных инцидента».

4.2.2. Вложенная структура инцидента

Критически важно: У инцидента нет собственных активов, наблюдаемых объектов и событий. Все эти данные находятся внутри вложенных алертов в массиве Alerts.

incident
├── Name, Severity, Priority, Status, CreatedAt
└── Alerts[]                  ← массив алертов
    ├── Name, Severity, Status, DetectSource
    ├── Assets[]              ← активы каждого алерта
    ├── Observables[]         ← наблюдаемые объекты каждого алерта
    ├── BaseEvents[]          ← нормализованные события каждого алерта
    ├── OriginalEvents[]      ← исходные события каждого алерта
    └── ScannedFiles[]        ← просканированные файлы каждого алерта

4.2.3. Как обращаться к данным инцидента

Чтобы получить доступ к активам, наблюдаемым объектам или событиям инцидента, необходимо сначала обратиться к массиву Alerts:

Пример из документации ([KL] P002):

[ incident.Alerts[] | select(.OriginalEvents[] | .ExternalID == "R050") | .Assets[] | select(.Type == "user" and .IsAttacker) | .ID]

Это jq-выражение извлекает ID пользователей-атакующих из алертов инцидента, у которых исходные события содержат ExternalID == "R050".

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 271609 «[KL] P002».

4.3. Три типа данных в плейбуке

Согласно официальной документации (раздел 267548), в плейбуке используются три типа данных:

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 267548 «Алгоритм плейбука».

4.3.1. Глобальные данные

Определение из документации:

«Глобальные данные содержат информацию об алерте или инциденте. Доступны только для чтения на любом шаге.»

Как обращаться:

• Для плейбука с областью действия «Алерт»: alert.Assets[], alert.Observables[], alert.Severity
• Для плейбука с областью действия «Инцидент»: incident.Alerts[], incident.Severity, incident.Priority

Особенности:

• Доступны на любом шаге алгоритма
• Нельзя изменить через плейбук
• Ключевые слова alert и incident используются без точки в начале

Пример из документации ([KL] P003):

[ alert.Assets[] | select(.Type == "user" and .IsAttacker) | .ID]

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 267548 «Алгоритм плейбука» и 271611 «[KL] P003».

4.3.2. Операционные данные

Определение из документации:

«Операционные данные передаются между шагами алгоритма. Обращение через контекст .input.»

Как обращаться:

• Через префикс .input: .input.hashes, .input.hostIds, .input.assets

Особенности:

• Создаются и изменяются шагами updateData
• Доступны на любом шаге после сохранения
• В операционных данных имена полей задаются разработчиком плейбука

Пример из документации ([KL] "Playbook for isolating a device where an infected file is detected"):

{
  "decision": {
    "conditions": [
      {
        "condition": "${((.input.assets // []) | length) > 0 and ([.input.observables[] | select(.type == \"md5\" or .type == \"sha256\" and .value != null and .value != \"\")] | length) > 0}",
        "name": "has input data"
      }
    ]
  }
}

В этом примере используются операционные данные .input.assets и .input.observables, которые передаются плейбуку при ручном запуске с выбором целевых объектов.

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 324933 «[KL] Playbook for isolating a device where an infected file is detected».

4.3.3. Локальные данные

Локальные данные ограничены одним шагом выполнения. Они создаются через параметр input шага и преобразуются в операционные данные через параметр output.

Пример из документации ([KL] P003) — шаг Loop:

{
  "loop": {
    "input": "${ [alert.OriginalEvents[] | [select(.DestinationProcessName != null and .DestinationProcessName != \"\")][] | .DestinationProcessName] }",
    "steps": [
      {
        "action": {
          "function": {
            "type": "killProcess",
            "params": {
              "path": "${ .[0] }"
            }
          }
        }
      }
    ]
  }
}

В этом примере:

• input шага loop — jq-выражение, возвращающее массив имён процессов
• Внутри шагов цикла текущий элемент доступен через .[0] (локальные данные)

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 271611 «[KL] P003».

4.4. Контекст выполнения: триггер vs алгоритм

Согласно официальной документации (раздел 273327), синтаксис обращения к данным зависит от того, где пишется jq-выражение — в триггере или в алгоритме.

4.4.1. В триггере плейбука

Определение из документации:

«Триггер плейбука — это фильтр, позволяющий выбрать алерты или инциденты, для которых необходимо запустить плейбук. Фильтр применяется к каждому объекту (алерту или инциденту) индивидуально.»

Контекст триггера — это сам алерт или инцидент, поэтому обращение идёт без префикса:

Примеры из документации:

Триггер плейбука [KL] P001 (область «Алерт»):

[.OriginalEvents[] | .ExternalID == "R350"] | any

Триггер плейбука [KL] P002 (область «Инцидент»):

[.Alerts[] | .OriginalEvents[] | .ExternalID == "R050"] | any

Триггер плейбука [KL] P004 (область «Алерт»):

event.new and .Severity == "medium" and any(.DetectionTechnologies[] == "SB"; .)

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, разделы 271609–271772 (предустановленные плейбуки [KL]).

4.4.2. В алгоритме плейбука (executionFlow)

Определение из документации:

«Алгоритм плейбука описывается в формате JSON и состоит из шагов выполнения.»

В алгоритме используются полные пути с ключевыми словами alert или incident:

Пример из документации ([KL] P002):

[ incident.Alerts[] | select(.OriginalEvents[] | .ExternalID == "R050") | .Assets[] | select(.Type == "user" and .IsAttacker) | .ID]

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 271609 «[KL] P002».

4.4.3. Сравнительная таблица

4.5. Визуальная шпаргалка

┌─────────────────────────────────────────────────────────────┐
│                     ПЛЕЙБУК (Playbook)                      │
├─────────────────────────────────────────────────────────────┤
│  ТРИГГЕР                                                    │
│  Контекст: сам алерт/инцидент                               │
│  Обращение: .Severity, .Name, .Alerts[], .Assets[]          │
│  (без префикса alert. или incident.)                        │
├─────────────────────────────────────────────────────────────┤
│  АЛГОРИТМ (executionFlow)                                   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ ГЛОБАЛЬНЫЕ ДАННЫЕ (read-only)                       │   │
│  │ Для алерта:  alert.Assets[]                         │   │
│  │              alert.Observables[]                    │   │
│  │              alert.Severity                         │   │
│  │ Для инцидента: incident.Alerts[].Assets[]           │   │
│  │                incident.Alerts[].Observables[]      │   │
│  │                incident.Severity                    │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ ОПЕРАЦИОННЫЕ ДАННЫЕ (read/write)                    │   │
│  │ .input.hashes                                       │   │
│  │ .input.hostIds                                      │   │
│  │ .input.assets                                       │   │
│  │ (обновляются через updateData)                      │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ ЛОКАЛЬНЫЕ ДАННЫЕ (в рамках шага)                    │   │
│  │ .[0] — текущий элемент в цикле                      │   │
│  │ . — текущий контекст                                │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
│  Шаги: action → decision → loop → parallel → updateData     │
└─────────────────────────────────────────────────────────────┘

В этом разделе разберём, почему регистр символов критически важен в jq-выражениях плейбуков, какие ошибки возникают при неправильном регистре и как их избежать.

ℹ️ Источники информации:

• Официальная справка Kaspersky EDR Expert 8.1, раздел 267548 «Алгоритм плейбука»
• Примеры из предустановленных плейбуков [KL] (разделы 271609–324934)
• Практический опыт команды pre-sales и AntiAPT Community

5.1. Почему регистр имеет значение

Согласно официальной документации (раздел 267548), jq-выражения в плейбуках чувствительны к регистру символов. Это означает, что Assets и assets — это два разных поля, и система обрабатывает их по-разному.

Причина: Модель данных Kaspersky EDR Expert использует строгую типизацию с фиксированными именами полей. Имена полей в модели данных алерта и инцидента зафиксированы в документации и не могут быть изменены.

⚠️ Критически важно: Даже одна буква в неправильном регистре приведёт к ошибке выполнения плейбука или к тому, что jq-выражение вернёт пустой результат.

5.2. Примеры ошибок из-за регистра

5.2.1. Ошибка 1: Неправильный регистр ключевого слова

❌ Неправильно:

jq1

✅ Правильно:

jq1

Объяснение: Ключевое слово alert всегда пишется строчными буквами. Alert с заглавной буквы система не распознает.

ℹ️ Источник: Примеры из официальной документации ([KL] P001–P005).

5.2.2. Ошибка 2: Неправильный регистр имени поля

❌ Неправильно:

jq1

✅ Правильно:

jq1

Объяснение: Имя поля Assets в модели данных алерта пишется с заглавной буквы A. Строчное assets не существует в модели данных.

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 269125 «Модель данных алерта».

5.2.3. Ошибка 3: Неправильный регистр значения поля Type

❌ Неправильно:

jq1

✅ Правильно:

jq1

Объяснение: Поле Type в элементе массива Assets пишется с заглавной буквы T. Строчное type не существует.

ℹ️ Источник: Пример из официальной документации ([KL] P003):

[ alert.Assets[] | select(.Type == "host") | .ID]

5.2.4. Ошибка 4: Неправильный регистр значения поля Value

❌ Неправильно:

jq1

✅ Правильно:

jq1

Объяснение: Поле Value в элементе массива Observables пишется с заглавной буквы V.

ℹ️ Источник: Пример из официальной документации ([KL] P004):

[alert.ScannedFiles[] | select(any(.DetectionTechnologies[] == "SB"; .)) | .Hashes | map(.Value)] | flatten

5.2.5. Ошибка 5: Неправильный регистр в операционных данных

❌ Неправильно:

jq1

✅ Правильно:

jq1

Объяснение: В операционных данных (.input) имена полей задаются разработчиком плейбука. В примере из документации ([KL] "Playbook for isolating a device where an infected file is detected") используется строчное .input.assets:

jq1

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 324933.

5.3. Таблица правильных написаний полей

5.3.1. Для алертов (alert)

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 269125 «Модель данных алерта».

5.3.2. Для инцидентов (incident)

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 269168 «Модель данных инцидента».

5.3.3. Для элементов массивов

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, разделы 269125 и 269168.

5.4. Разный регистр в глобальных и операционных данных

5.4.1. Глобальные данные (alert/incident)

В глобальных данных имена полей зафиксированы в модели данных и пишутся с заглавных букв:

jq1234

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 267548 «Алгоритм плейбука».

5.4.2. Операционные данные (.input)

В операционных данных имена полей задаются разработчиком плейбука через шаг updateData. В примерах из официальной документации используется строчный регистр:

jq1234

Пример из документации ([KL] "Playbook for isolating a device where an infected file is detected"):

jq1

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 324933.

5.4.3. Почему разный регистр?

Глобальные данные — это часть модели данных KUMA, где имена полей стандартизированы и пишутся с заглавных букв (CamelCase).

Операционные данные — это "переменные", которые создаёт разработчик плейбука. В примерах от Лаборатории Касперского используется соглашение: когда в .input сохраняются те же данные, что были в alert.Assets[], разработчики используют строчные буквы для визуального различия.

⚠️ Важно: Это соглашение, а не требование системы. Вы можете назвать поле в .input как угодно (например, .input.MyCustomField), но для совместимости с примерами из документации рекомендуется использовать строчные буквы.

5.5. Практические рекомендации

5.5.1. Используйте подсказки интерфейса

При вводе jq-выражений в Консоли OSMP система автоматически показывает подсказки с правильными именами полей:

• Начните вводить alert. → появится список полей с правильным регистром
• Начните вводить incident. → появится список полей с правильным регистром
• Начните вводить " (кавычку) → появится список допустимых значений для полей

ℹ️ Источник: Официальная справка Kaspersky EDR Expert 8.1, раздел 303486 «Настройка шагов выполнения плейбука в визуальном редакторе».

5.5.2. Копируйте примеры из документации

Вместо того чтобы писать имена полей по памяти, копируйте их из:

• Официальной документации (разделы 269125, 269168)
• Предустановленных плейбуков [KL] (разделы 271609–324934)
• Этой статьи (таблицы 5.3.1–5.3.3)

5.5.3. Проверяйте регистр при возникновении ошибок

Если плейбук не работает или возвращает пустой результат:

1. Проверьте, что все имена полей написаны с правильным регистром
2. Сравните с таблицами 5.3.1–5.3.3
3. Убедитесь, что в глобальных данных используется заглавный регистр, а в операционных — строчный (если следуете соглашению)

5.5.4. Создайте шпаргалку для команды

Распечатайте или сохраните таблицы 5.3.1–5.3.3 как шпаргалку для аналитиков SOC. Это сократит количество ошибок при создании плейбуков.