Схемы автоматизации

В данном разделе представлен обзор структуры, принципов работы и процесса создания схем автоматизации в системе. Управление схемами автоматизации в системе осуществляется в разделе Экспертиза.

О схемах автоматизации

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

Расчеты в схемах автоматизации

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

Расчеты могут возвращать результат следующих типов:

  • число;

  • строка;

  • дата;

  • логический;

  • элемент перечисления (Enum).

Расчеты поддерживают наследование — возможность переопределять формулы расчетов для дочерних сущностей.

Политики в схемах автоматизации

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

Добавление схемы автоматизации

Чтобы добавить схему автоматизации в систему, необходимо выполнить следующие действия:

  1. Создать схему автоматизации в разделе Экспертиза.

  2. Определить структуру схемы автоматизации.

  3. Настроить запуск расчетов по схеме и отображение их результатов в интерфейсе.

  4. Настроить запуск политик в разделе Автоматизация → Политики веб-интерфейса системы.

Работа со схемой автоматизации

Доступные операции над схемой автоматизации:

Структура схемы автоматизации

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

Поле Описание Тип данных Обязательное поле

id

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

строка

да

name

Название схемы автоматизации. Допустимы латинские буквы, цифры, подчеркивания.

строка

да

description

Краткое описание назначения схемы автоматизации.

строка

нет

type

Тип элемента экспертизы. Всегда устанавливается значение calculation_schema.

перечисление

да

tags

Теги для классификации и поиска схемы в системе.

массив строк

нет

version

Версия схемы в формате Semantic Versioning.

строка

да

status

Статус текущей версии схемы автоматизации. Может принимать любые текстовые значения.

Примеры значений:

  • debug — версия в разработке;

  • experimental — экспериментальная версия;

  • test — версия для тестирования;

  • stable — стабильная версия.

строка

нет

author

Имя и контактные данные автора схемы.

строка

нет

date

Дата создания или изменения схемы. Задается в формате YYYY-MM-DD, то есть "год-месяц-день".

Поле не связано с полями Дата создания и Дата изменения в карточке элемента экспертизы.

строка

нет

extends

FQID схемы автоматизации, для которой текущая схема является наследником.

строка

нет

calculations

Массив расчетов. Каждый расчет включает FQID сущностей, к которым применяются расчеты, а также формулы или ссылки на скрипты, которые определяют логику расчетов. Ознакомьтесь с описанием поля.

массив объектов

нет

summary_calculations

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

массив объектов

нет

counters_management

Массив правил управления счетчиками. Ознакомьтесь с описанием поля counters_management.

массив объектов

нет

policies

Массив политик. Каждая политика включает FQID сущности, к которой она применяется, а также условия ее срабатывания и действия, применяемые в случае срабатывания. См. описание поля.

массив объектов

нет
В схеме автоматизации должен быть определен хотя бы один расчет в поле calculations или summary_calculations или политика в поле policies.

Расчеты: поле calculations

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

Расчеты могут возвращать результат следующих типов:

  • число;

  • строка;

  • дата;

  • логический;

  • элемент перечисления (Enum).

Объект расчета имеет следующую структуру:

Поле Описание Тип данных Обязательное поле

id

Уникальный идентификатор расчета, по которому можно сослаться на расчет. Должен быть уникальным в пределах схемы автоматизации. Можно использовать UUID в качестве значения.

строка

да

name

Имя расчета, отображаемое в интерфейсе.

строка

да

description

Краткое описание назначения расчета.

строка

нет

entity

FQID сущности, к которой применяется расчет.

строка

да

expression

Формула, по которой выполняется расчет. Ознакомьтесь с правилами описания формулы.

строка

да

complexity_limit

Максимальная сложность расчета.

Сложность рассчитывается следующим образом:

  • базовая сложность выражения в формуле — 1;

  • каждый скрипт, входящий в выражение, увеличивает его сложность на 10;

  • к сложности родительского расчета прибавляется сложность всех дочерних расчетов.

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

Необязательно точно рассчитывать лимит сложности для расчета. Можно указать достаточно большое число, например, 100. Если этот предел будет превышен, возникшая ошибка укажет на то, что расчет следует оптимизировать.

положительное целое число

да

auto_recalculation

Будет ли расчет автоматически запущен при обновлении свойств или связей объекта, связанного с ним.

булево

да

target

Идентификатор атрибута сущности, в который необходимо записать значение результата расчета.

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

строка

нет

children

Дочерние расчеты.

массив объектов

нет

pre_mapping

Условия премаппинга — преобразования входных значений перед подстановкой в выражение expression.

объект

нет

post_mapping

Условия постмаппинга — преобразования результата расчета в требуемый выходной формат.

объект

нет

Правила описания формулы расчета

В поле expression следует указать формулу для расчета согласно следующим правилам:

  • В формулах можно использовать следующие аргументы:

    • целые и дробные числовые константы;

    • строковые константы;

    • дату и время;

    • логические значения (true, false);

    • все атрибуты сущности, указанной в поле entity расчета, которые имеют типы Timestamp, Date, Time, String, Bool, Decimal, Integer и Float;

    • глобальные переменные типов Integer, Float;

    • скрипты;

    • расчеты для сущностей, связанных с текущей сущностью. Связь должна быть настроена в схеме домена в поле linkages описания текущей сущности.

      Расчеты для связанных сущностей нужно обязательно указать в поле children. В таком случае расчет для текущей сущности называется родительским, а расчеты для связанных сущностей — дочерними.

  • Для числовых аргументов в формулах поддерживаются все операции, реализованные в библиотеке JavaScript math.js, а также ряд дополнительных функций.

    Справка по использованию функций библиотеки math.js приведена в официальной документации math.js.

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

Пример формулы 
- id: test_calc
  name: Тестовый расчет
  entity: test_domain/TestEntity
  expression: "roundTo(2 * {field:weight} / {variable:divisor}, 2)"
  auto_recalculation: false
  complexity_limit: 1

Здесь:

  • roundTo — вызов дополнительной функции округления до двух знаков после запятой.

  • 2 — числовая константа.

  • {field:weight} — значение поля weight сущности TestEntity.

  • {variable:divisor} — значение глобальной переменной divisor.

Ссылки на атрибуты, переменные и скрипты следует указывать в фигурных скобках, например, {variable:divisor}.

Применение скриптов в расчетах

В поле expression можно указать идентификатор скрипта, который будет выполнен при запуске расчета. В расчете будет использоваться значение, возвращенное скриптом.

Результатом работы скрипта должно быть конечное число. Автоматическая валидация возвращаемого значения в системе не предусмотрена, поэтому разработчик скрипта должен реализовать его так, чтобы он возвращал только числа.
Пример формулы, дополненный вызовом скрипта 
- id: test_calc
  name: Тестовый расчет
  entity: test_domain/TestEntity
  expression: |
    mean(
      2 * {field:weight} / {variable:divisor},
      {script:test_calculation_script}
    )
  auto_recalculation: false
  complexity_limit: 11

Здесь:

  • {script:test_calculation_script} — вызов скрипта test_calculation_script.

Минимально допустимое значение complexity_limit для данного расчета — 11, поскольку к базовой сложности расчета 1 следует прибавить 10 — сложность вызова скрипта.

Дочерние расчеты

Дочерние расчеты — это расчеты для связанных сущностей, участвующие в расчете для текущей сущности (родительском расчете). Ссылки на них следует указать в поле children родительского расчета.

Ссылка на дочерний расчет содержит следующие поля:

  • linkage — идентификатор связи между сущностью, для которой выполняется родительский расчет, и сущностью, для которой выполняется дочерний расчет. Связь должна быть настроена в схеме домена в поле linkages описания сущности, для которой выполняется родительский расчет.

  • calculation — идентификатор дочернего расчета.

Дочерний расчет выполняется для всех сущностей, связанных с текущей, поэтому его результат всегда интерпретируется системой как массив. Чтобы преобразовать результат дочернего расчета в одно значение, используйте функции массивов, такие как min, max или sum для числовых значений или strConcat для строк.
Пример настройки дочернего расчета 
- id: test_calc_with_child
  name: Тестовый расчет с дочерним
  entity: test_domain/TestEntity
  expression: |
    mean(
      2 * {field:weight},
      sum({calculation:child_calc})
    )
  children:
    - linkage: test_domain/TestEntity_ChildEntity
      calculation: child_calc
  auto_recalculation: true
  complexity_limit: 200

- id: child_calc
  name: Дочерний расчет
  entity: test_domain/ChildEntity
  expression: "{script:child_calculation_script}"
  auto_recalculation: true
  complexity_limit: 100

Здесь:

  • Результат дочернего расчета преобразован в одно значение с помощью функции sum: sum({calculation:child_calc}).

  • test_domain/TestEntity_ChildEntity — идентификатор связи между сущностями TestEntity и ChildEntity, заданной в схеме домена test_domain в разделе linkages описания сущности TestEntity.

  • child_calc — идентификатор дочернего расчета.

Правила управления счетчиками: поле counters_management

Поле counters_management содержит правила управления счетчиками. Правила не сохраняют результаты расчетов, а запускают и останавливают счетчики.

Каждая политика включает:

  • Условие запуска действия — тип события, на которое реагирует правило, и выражение в поле expression.

  • Действие, выполняемое, если условие истинно. Поддерживаются следующие действия:

    • запуск счетчика;

    • постановка счетчика на паузу;

    • возобновление работы счетчика.

Объект правила имеет следующую структуру:

Поле Описание Тип данных Обязательное поле

id

Уникальный идентификатор правила.

строка

да

name

Название правила.

строка

да

entity

FQID сущности, атрибутом которой является счетчик.

строка

да

counter_attribute

Идентификатор атрибута типа Счетчик.

строка

да

event

Описание события, на которое реагирует правило. Ознакомьтесь с описанием поля event.

объект

да

action

Действие, выполняемое при срабатывании правила. Ознакомьтесь с описанием поля action.

объект

да

expression

Выражение, определяющее необходимость выполнения действия. Действие выполняется, если выражение возвращает true. В выражении могут использоваться:

  • данные из поля события data в формате {event: <event_data_field>};

  • поля объекта в формате {field: <entityAttribute>}.

строка

да

Описание события, на которое реагирует правило (event)

Поле event имеет следующую структуру:

Поле Описание Тип данных Обязательное поле

type

Тип события, на которое реагирует правило. Допустимые значения:

  • object.create — создание объекта;

  • object.update — изменение объекта;

  • link.create — создание связи;

  • link.delete — удаление связи.

строка

да

linkage

FQID связи.

строка

да (для link.create и link.delete)

side

Сторона связи. Если не указана, правило будет реагировать при событиях для обеих сторон связи. Допустимые значения:

  • 1;

  • 2.

число

нет

Описание действия правила (action)

Объект действия имеет следующую структуру:

Поле Описание Тип данных Обязательное поле

type

Тип действия. Допустимые значения:

  • counter_start — запуск счетчика;

  • counter_pause — постановка счетчика на паузу;

  • counter_resume — продолжение работы счетчика.

строка

да

duration

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

целое число

нет

Преобразование входных и выходных данных: поля pre_mapping и post_mapping

Схемы автоматизации позволяют преобразовывать входные данные перед их использованием в расчетах и выходные — для приведения к требуемому формату. Для этого в атрибутах расчета следует указать условия маппинга.

Существуют следующие виды маппинга:

  • Премаппинг — преобразования входных значений перед подстановкой в формулу расчета. Настраиваются в атрибуте расчета pre_mapping.

  • Постмаппинг — преобразования результата расчета в требуемый выходной формат. Настраиваются в атрибуте расчета post_mapping.

Пример использования премаппинга и постмаппинга

Пусть требуется определить уровень риска как произведение оценки его вероятности на оценку ущерба. Вероятность и оценка ущерба указываются пользователем в интерфейсе системы в виде строки: Низкая, Средняя или Высокая.

Уровень риска, вычисленный в результате расчета, также требуется отобразить в интерфейсе в виде строки.

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

  • Низкая — 0.1;

  • Средняя — 0.5;

  • Высокая — 1.0.

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

  • от 0 до 0.3 включительно — Низкий уровень риска;

  • от 0.3 до 0.7 включительно — Средний уровень риска;

  • от 0.7 до 1 включительно — Высокий уровень риска.

Объект маппинга имеет следующую структуру:

  • Вид маппинга: pre_mapping или post_mapping.

  • Для премаппинга:

    • Для маппинга типа list, enum или range: идентификатор атрибута сущности, для которой выполняется расчет (сущности, указанной в атрибуте entity расчета).

    • Для маппинга типа matrix: идентификатор матрицы, который будет использоваться в формуле расчета с префиксом computed.

  • Атрибуты маппинга:

    Поле Описание Тип данных Обязательное поле

    type

    Тип маппинга.

    строка

    да

    enum

    FQID перечисления, значения которого сопоставляются со значениями из values.

    Задается в формате <domain_schema_id>/<enum_id>, где <domain_schema_id> — идентификатор схемы домена, а <enum_id> — идентификатор перечисления.

    строка

    да для маппинга типа enum

    row

    Идентификатор атрибута, значения которого являются строками матрицы маппинга типа matrix.

    Задается в формате {field:<field_id>}, где <field_id> — идентификатор атрибута.

    строка

    да для маппинга типа matrix

    column

    Идентификатор атрибута, значения которого являются столбцами матрицы маппинга типа matrix.

    Задается в формате {field:<field_id>}, где <field_id> — идентификатор атрибута.

    строка

    да для маппинга типа matrix

    values

    Словарь (для маппингов типа list и enum) или массив (для маппингов типа range и matrix) соответствия входных и выходных показателей.

    словарь, массив

    да

    default_value

    Значение по умолчанию, если значение на входе маппинга не найдено в словаре values.

    логическое, строка, число

    да

Обращаться к результату премаппинга в формуле expression расчета следует:

  • В случае маппинга типа list, enum или range — через префикс field:

    {field:<attribute>}

    Здесь:

    • <attribute> — идентификатор атрибута сущности, для которой выполняется расчет.

    Пример обращения к результату премаппинга типа enum 
    - id: issue_criticality
  name: Уровень критичности замечания
  entity: evo.compliance.audit/Issue
  expression: "{field:criticalityLevel}"
  pre_mapping:
    criticalityLevel:
      type: enum
      enum: evo.compliance.audit/CriticalityLevelEnum
      default_value: 0
      values:
        critical: 1
        high: 0.75
        medium: 0.5
        low: 0.25

    Здесь criticalityLevel — атрибут сущности evo.compliance.audit/Issue, значение которого преобразуется из строки в число с помощью премаппинга.

  • В случае маппинга типа matrix — через префикс computed:

    {computed:<matrix_id>}

    Здесь:

    • <matrix_id> — идентификатор матрицы маппинга.

    Пример обращения к результату премаппинга типа matrix 
    - id: risk_level
  name: Уровень риска
  entity: evo.compliance.risk/Risk
  expression: "{computed:riskLevel}"
  pre_mapping:
    riskLevel:
      type: matrix
      row: "{field:riskProbability}"
      column: "{field:riskDamage}"
      default_value: Низкий
      values:
        - row: Низкая
          column: Низкий
          value: Низкий
        - row: Низкая
          column: Высокий
          value: Средний
        - row: Высокая
          column: Низкий
          value: Средний
        - row: Высокая
          column: Высокий
          value: Высокий

====ds

Типы маппинга показателей

В системе существуют следующие типы маппинга:

Маппинг типа list

Маппинг типа list используется для сопоставления пар входных и выходных значений.

Пример маппинга типа list

Премаппинг:

pre_mapping:
  isCritical:
    type: list
    default_value: 0
    values:
      true: 1
      false: 0.5

Интерпретация примера: у сущности есть логический атрибут Критичная с идентификатором isCritical. Если флажок Критичная в представлении сущности установлен, в расчете для сущности будет использован коэффициент 1, иначе — 0.5.

Постмаппинг:

post_mapping:
  type: list
  default_value: Не определена
  values:
    0.1: Минимальная
    0.5: Средняя
    1.0: Критическая

Интерпретация примера: расчет вернет следующий результат:

  • если формула в expression вернула 0.1 — Минимальная;

  • 0.5 — Средняя;

  • 1.0 — Критическая;

  • любое другое значение — Не определена.

Маппинг типа enum

Маппинг типа enum используется для сопоставления значений в схемах автоматизации и значений из перечисления (атрибута сущности типа Enum).

Пример маппинга типа enum

Премаппинг:

pre_mapping:
  criticalityLevel:
    type: enum
    enum: issues/CriticalityLevelEnum
    default_value: 0
    values:
      critical: 1
      high: 0.75
      medium: 0.5
      low: 0.25

Интерпретация примера: в схеме домена issues определена сущность Замечание аудита (Issue). У замечания есть атрибут Уровень критичности, значения которого определены в перечислении CriticalityLevelEnum схемы домена issues:

  • critical — Критический;

  • high — Высокий;

  • medium — Средний;

  • low — Низкий.

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

  • Критический — 1;

  • Высокий — 0.75;

  • Средний — 0.5;

  • Низкий — 0.25.

Постмаппинг:

post_mapping:
  type: enum
  enum: documents/DocumentStatusEnum
  default_value: inactive
  values:
    true: active
    false: inactive

Интерпретация примера: в схеме домена documents определено перечисление Статус документа (DocumentStatusEnum) с двумя возможными значениями — Активен (active) и Неактивен (inactive). Статус документа примет следующие значения в зависимости от результатов расчета:

  • Активен — если расчет вернет true;

  • Неактивен — если расчет вернет false или любое другое значение.

Маппинг типа range

Маппинг типа range используется, если требуется преобразовать число, лежащее в определенном диапазоне, в конкретное значение.

В массиве values правая граница включается в интервал, левая — нет: (from, to].

Границы интервалов должны пересекаться, например:

Валидный маппинг
values:
  - from: 0
    to: 5
    value: 1
  - from: 5
    to: 10
    value: 2

Границы интервалов (0, 5] и (5, 10] пересекаются на значении 5.

Невалидный маппинг
values:
  - from: 0
    to: 5
    value: 1
  - from: 10
    to: 15
    value: 2

Границы интервалов (0, 5] и (10, 15] не пересекаются, что недопустимо.

В качестве левой границы диапазона можно использовать значение -Infinity, означающее любое число, меньшее либо равное to: (-Infinity, to].

В качестве правой границы диапазона можно использовать значение +Infinity, означающее любое число, большее from: (from, +Infinity).
Пример маппинга типа range

Премаппинг:

pre_mapping:
  subjectCount:
    type: range
    default_value: 1
    values:
      - from: 0
        to: 10000
        value: 0.2
      - from: 10000
        to: 50000
        value: 0.5

Интерпретация примера: у сущности есть числовой атрибут Количество субъектов персональных данных с идентификатором subjectCount. Его значения преобразуются при премаппинге следующим образом:

  • от 0 до 10 000 включительно — 0.2;

  • от 10 000 до 50 000 включительно — 0.5;

  • более 50 000 — 1 как значение по умолчанию (default_value).

Премаппинг с +Infinity:

pre_mapping:
  subjectCount:
    type: range
    default_value: -1
    values:
      - from: 0
        to: 10000
        value: 0.2
      - from: 10000
        to: 50000
        value: 0.5
      - from: 50000
        to: +Infinity
        value: 1

Интерпретация примера: аналогична предыдущему, но для диапазона "более 50 000" значение задано с помощью верхней границы +Infinity. В качестве значения по умолчанию используется -1 как индикатор, что количество субъектов персональных данных задано некорректно.

Постмаппинг:

post_mapping:
  type: range
  default_value: Низкая
  values:
    - from: 25
      to: 75
      value: Средняя
    - from: 75
      to: 100
      value: Высокая

Интерпретация примера: пусть требуется оценить показатель эффективности сущности. Итоговая оценка будет сформирована следующим образом:

  • Если оценка ниже 25, включая отрицательные значения, расчет вернет значение Низкая как значение по умолчанию (default_value).

  • Если оценка находится между 25 и 75 включительно, расчет вернет значение Средняя.

  • Если оценка находится между 75 и 100 включительно, расчет вернет значение Высокая.

Постмаппинг с -Infinity:

post_mapping:
  type: range
  default_value: Не определена
  values:
    - from: -Infinity
      to: 25
      value: Низкая
    - from: 25
      to: 75
      value: Средняя
    - from: 75
      to: 100
      value: Высокая

Интерпретация примера: аналогична предыдущему, но для диапазона "менее 25" значение задано с помощью нижней границы -Infinity. В качестве значения по умолчанию используется Не определена как индикатор, что исходное значение оценки некорректно.

Маппинг типа matrix

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

  • В качестве строк и столбцов можно использовать:

  • К результату премаппинга типа matrix следует обращаться в expression с префиксом computed.
Пример премаппинга типа matrix

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

Оценка ущерба от реализации риска

Вероятность реализации риска

Низкий

Высокий

Низкая

Низкий

Средний

Высокая

Средний

Высокий

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

pre_mapping:
  riskLevel:
    type: matrix
    row: "{field:riskProbability}"
    column: "{field:riskDamage}"
    default_value: Низкий
    values:
      - row: Низкая
        column: Низкий
        value: Низкий
      - row: Низкая
        column: Высокий
        value: Средний
      - row: Высокая
        column: Низкий
        value: Средний
      - row: Высокая
        column: Высокий
        value: Высокий

Обобщающие расчеты: поле summary_calculations

Обобщающие расчеты — это расчеты, позволяющие вычислить метрики для сущностей, для которой нет обобщающей сущности: например, среднее время выполнения задач операторами.

В схеме автоматизации обобщающие расчеты настраиваются в поле summary_calculations.

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

Чтобы использовать свойство сущности в обобщающем расчете, это свойство нужно указать в поле expression другого расчета.

Обобщающий расчет имеет следующую структуру:

Поле Описание Тип данных Обязательное поле

id

Уникальный идентификатор расчета, по которому можно сослаться на расчет. Должен быть уникальным в пределах схемы автоматизации. Можно использовать UUID в качестве значения.

строка

да

name

Имя расчета, отображаемое в интерфейсе.

строка

да

description

Краткое описание назначения расчета.

строка

нет

expression

Математическая формула для обобщающего расчета.

строка

да
Пример обобщающего расчета 
calculations:
  - id: task_processing_time
    name: Время обработки задачи
    entity: test_tasks/Task
    expression: "{field:processing_time}"
    auto_recalculation: true
    complexity_limit: 1

summary_calculations:
  - id: mean_task_processing_time
    name: Среднее время обработки задачи
    expression: "mean({calculation:task_processing_time})"

Здесь:

  • task_processing_time — расчет, возвращающий время выполнения одной задачи.

  • mean_task_processing_time — обобщающий расчет, возвращающий среднее время выполнения всех задач в системе.

Политики: поле policies

Поле policies содержит объекты политик — правил автоматизированной обработки сущностей системы. Каждая политика включает:

  • Условие запуска действия. Условие может быть задано как:

    • логическое выражение;

    • расчет, выражение которого в поле expression возвращает True или False.

  • Действие, выполняемое, если условие истинно. Поддерживаются следующие действия:

Объект политики имеет следующую структуру:

Поле Описание Тип данных Обязательное поле

id

Уникальный идентификатор политики. Должен быть уникальным в пределах схемы автоматизации. Можно использовать UUID в качестве значения.

строка

да

name

Имя политики, отображаемое в интерфейсе.

строка

да

description

Краткое описание назначения политики.

строка

нет

entity

FQID сущности, к которой применяется политика.

строка

да

conditions

Массив условий срабатывания политики. См. правила описания условий.

массив объектов

да

actions

Массив действий, выполняемых при срабатывании политики. См. правила описания действий.

массив объектов

да

Правила описания условий срабатывания политики

Условия в массиве политики (policy → conditions) объединяются логическим И (AND), однако вложенные условия (policy → conditions → conditions) объединяются логическим ИЛИ (OR).

Объект условия имеет следующую структуру:

Поле Описание Тип данных Обязательное поле

type

Тип условия:

  • expression — если в качестве условия будет использоваться логическое выражение, составленное в поле expression условия;

  • calculation — если в качестве условия будет использоваться выражение (expression) расчета, идентификатор которого указан в поле calculation.

строка

нет, если в поле conditions определены вложенные условия

expression

Логическое выражение, при истинности которого запускается действие, указанное в action.

Выражение обязательно должно возвращать True или False.

В выражении можно использовать следующие аргументы:

  • Поля сущности, указанной в поле entity, в формате {field:<field_id>}. Пример: {field:description}.

  • Значения контекстных переменных в формате {context:<variable_id>}. Пример: {context:message}.

    Идентификаторы и значения контекстных переменных определяются в таблице Переменные экземпляров политик в разделе Автоматизация → Политики.

  • Для числовых аргументов поддерживаются все операции, реализованные в библиотеке JavaScript math.js, а также ряд дополнительных функций.

    Справка по использованию функций библиотеки math.js приведена в официальной документации math.js.

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

строка

да для условия типа expression

calculation

Идентификатор расчета, формула expression которого будет использована в качестве условия запуска действий по политике.

Расчет обязательно должен возвращать True или False.

Можно указать:

  • Идентификатор расчета из текущей схемы автоматизации. Пример: test_calculation.

  • Идентификатор расчета из другой схемы автоматизации в формате <automation_schema_id>/<calculation_id>. Пример: external.schema/external_test_calculation.

строка

да для условия типа calculation

maxParallel

Ограничение максимального количества расчетов, которые могут быть запущены параллельно.

число

нет, доступно только для условия типа calculation

conditions

Массив вложенных условий срабатывания политики.

Структура вложенных условий (policy → conditions → conditions) аналогична структуре условий верхнего уровня (policy → conditions).

Вложенные условия второго уровня (policy → conditions → conditions → conditions) и ниже не поддерживаются.

При проверке условия срабатывания политики вложенные условия объединяются логическим ИЛИ (OR).

массив объектов

нет
При использовании условия типа calculation рекомендуется указывать параметр maxParallel. Отсутствие ограничения на количество параллельно выполняемых расчетов может привести к значительной вычислительной нагрузке на систему при обработке политикой большого количества объектов.

Правила описания действий политики

Действия в массиве политики (policy → actions) выполняются последовательно, однако вложенные действия (policy → actions → actions) выполняются параллельно.

Объект действия имеет следующую структуру:

Поле Описание Тип данных Обязательное поле

type

Тип действия:

  • playbook — отдельный запуск скрипта или плейбука для каждого обрабатываемого объекта.

  • batch_playbook — один запуск скрипта или плейбука для всей выборки обрабатываемых объектов.

    Скрипты, запускаемые с помощью действия типа batch_playbook, должны принимать и отправлять данные об объектах в стрим брокера сообщений NATS. Логика обработки данных такими скриптами описана в разделе Тип действия batch_playbook в политике.

    В политике может быть только одно действие типа batch_playbook, при этом оно должно быть указано последним.

  • chunk_playbook — обрабатываемые объекты разбиваются на группы по 100, и для каждой группы происходит отдельный запуск скрипта или плейбука.

  • calculation — запуск расчета для каждого обрабатываемого объекта.

  • linkage — изменение связей для каждого обрабатываемого объекта.

    Действие типа linkage имеет ряд особенностей работы.

строка

да

playbook

Идентификатор скрипта или плейбука, который требуется запустить.

строка

да для действия типа playbook, batch_playbook или chunk_playbook

extraParams

Дополнительные параметры запуска скрипта или плейбука в формате ключ: значение.

словарь

нет, доступно для действия типа playbook, batch_playbook или chunk_playbook

msgTimeout

Время в миллисекундах ожидания сервисом автоматизации поступления новых объектов в стрим NATS. Если за указанное время не поступают новые объекты, выполнение действий политики считается завершенным по таймауту.

число

да для действия типа batch_playbook

finishEvent​Header

Заголовок финального объекта, который сигнализирует о завершении обработки объектов при действии batch_playbook.

Значение по умолчанию — X-Finish-Event.

строка

да для действия типа batch_playbook

calculation

Идентификатор расчета, который будет запускаться при срабатывании политики.

Можно указать:

  • Идентификатор расчета из текущей схемы автоматизации. Пример: test_calculation.

  • Идентификатор расчета из другой схемы автоматизации в формате <automation_schema_id>/<calculation_id>. Пример: external.schema/external_test_calculation.

строка

да для действия типа calculation

maxParallel

Ограничение максимального количества расчетов или плейбуков, которые могут быть запущены параллельно.

число

нет, доступно только для действия типа calculation или playbook

timeout

Время в миллисекундах ожидания выполнения всех запусков скрипта или плейбука в рамках экземпляра политики. По истечении таймаута выполнение экземпляра политики завершится с ошибкой.

число

нет, доступно для действия типа playbook или chunk_playbook

linkage

FQID связи, которую необходимо изменить, в формате <domain_schema_id>/<linkage_id>. Пример: evo.test.domain/FirstEntity_SecondEntity.

строка

да для действия типа linkage

mode

Режим изменения связей:

  • replace — все существующие связи объекта удаляются и заменяются на новые из массива object_ids.

  • add — связи из массива object_ids добавляются к существующим связям объекта.

строка

да для действия типа linkage, если связь, указанная в поле linkage, имеет тип 1_n или n_n

object_ids

Список UUID объектов, связи с которыми должны быть добавлены.

массив строк

нет

actions

Массив вложенных действий при срабатывании политики.

Структура вложенных действий (policy → actions → actions) аналогична структуре действий верхнего уровня (policy → actions).

Вложенные действия второго уровня (policy → actions → actions → actions) и ниже не поддерживаются.

При срабатывании политики вложенные действия выполняются параллельно.

массив объектов

нет
При использовании действий типа calculation, playbook и chunk_playbook рекомендуется указывать параметры maxParallel и/или timeout. Отсутствие ограничения на количество параллельно выполняемых расчетов и плейбуков и длительность их выполнения может привести к значительной вычислительной нагрузке на систему при обработке политикой большого количества объектов.

Особенности действия типа linkage

Действие типа linkage имеет следующие особенности:

  • Если поле mode имеет значение replace, но поле object_ids не задано, то все существующие связи обрабатываемых объектов удаляются.

  • Для связи типа 1_1 действие работает в режиме replace: можно либо удалить связь, если не заполнять поле object_ids, либо заменить ее на новую, если указать единственный идентификатор в массиве object_ids.

  • Если связь имеет тип 1_1, но в поле object_ids указаны несколько идентификаторов, выполнение экземпляра политики завершится с ошибкой.

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

source: !deno |
  import { type Context } from '@expertise/policy_batch_action_handler_executor';

  export async function main(): Promise<void> {
    const context: Context = JSON.parse(get_context());
    // Остальной код скрипта.
  }

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

context.policy.context.<variable_id>

Здесь:

  • <variable_id> — идентификатор контекстной переменной.

Пример использования контекстной переменной:

const taskName = strConcat("Задача на устранение уязвимости ", context.policy.context.vulnerabilityName)

Примеры схем автоматизации

Пример расчетов в схеме автоматизации

В данном разделе приведен пример настройки расчетов в схеме автоматизации.

id: evo.compliance.audit.automation
name: audit_automation
description: Автоматизация для аудитов
type: calculation_schema
tags: [audit, automation]
version: 1.0.0
status: stable
author: Ivan Ivanov <ivanov@example.ru>
calculations:
  - id: audit_assessment_sum_compliance_index
    name: Сумма индексов соответствия
    entity: evo.compliance.audit/Audit
    expression: |
      round(
        sum({calculation:audit_assessment_compliance_index}),
        {variable:audit_assessment_compliance_index_round}
      )
    children:
      - linkage: evo.compliance.audit/Audits_RequirementValues
        calculation: audit_assessment_compliance_index
    auto_recalculation: true
    complexity_limit: 100

  - id: issue_weighted_criticality
    name: Взвешенный уровень критичности замечания
    entity: evo.compliance.audit/Issue
    expression: |
      {field:criticalityLevel} *
      {calculation:audit_assessment_compliance_index}
    children:
      - linkage: evo.compliance.audit/Issues_RequirementValues
        calculation: audit_assessment_compliance_index
    auto_recalculation: true
    complexity_limit: 100
    pre_mapping:
      criticalityLevel:
        type: enum
        enum: evo.compliance.audit/CriticalityLevelEnum
        default_value: 0
        values:
          critical: 1
          high: 0.75
          medium: 0.5
          low: 0.25
    post_mapping:
      type: range
      default_value: Не определен
      values:
        - from: -Infinity
          to: 0.5
          value: Низкий
        - from: 0.5
          to: 1.5
          value: Средний
        - from: 1.5
          to: 2.0
          value: Высокий

  - id: audit_assessment_compliance_index
    name: Индекс соответствия, вычисленный через скрипт
    entity: evo.compliance.audit/Requirement
    expression: "{script:calculate_comp_index}"
    auto_recalculation: true
    complexity_limit: 20

  - id: progress_metric
    name: Прогресс аудита в процентах
    entity: evo.compliance.audit/Audit
    expression: "{field:progress}"
    auto_recalculation: true
    complexity_limit: 1

  - id: is_kii
    name: Аудит объекта КИИ
    entity: evo.compliance.audit/Audit
    expression: |
      strIncludes({field:name}, "КИИ")
    auto_recalculation: true
    complexity_limit: 1
    target: isKii

summary_calculations:
  - id: mean_audit_progress
    name: Средний прогресс по аудиту
    expression: "mean({calculation:progress_metric})"

Интерпретация примера

Метаданные схемы автоматизации

  • id: идентификатор схемы автоматизации — evo.compliance.audit.automation.

  • name: наименование схемы автоматизации — audit_automation.

  • description: описание схемы автоматизации — "Автоматизация для аудитов".

  • type: тип элемента экспертизы — calculation_schema.

  • tags: теги схемы автоматизации, используемые для классификации — audit, automation.

  • version: версия схемы автоматизации — 1.0.0.

  • status: статус разработки схемы — stable.

  • author: автор схемы автоматизации — Ivan Ivanov <ivanov@example.ru>.

Расчеты

Схема содержит следующие расчеты:

  • audit_assessment_sum_compliance_index — сумма индексов соответствия требований аудита, округленная до количества разрядов, определенного глобальной переменной audit_assessment_compliance_index_round. Индексы соответствия отдельных требований вычисляются с помощью дочернего расчета audit_assessment_compliance_index.

  • issue_weighted_criticality — взвешенный уровень критичности замечания о несоответствии требованию. Рассчитывается как произведение уровня критичности замечания, заданного в виде перечисления, и индекса соответствия требования.

    • С помощью премаппинга текстовое значение уровня критичности замечания преобразуется в числовой множитель.

    • С помощью постмаппинга результат вычисления уровня критичности интерпретируется как строка.

    • Индекс соответствия требования вычисляется с помощью дочернего расчета audit_assessment_compliance_index.

  • audit_assessment_compliance_index — индекс соответствия требования, вычисляемый скриптом calculate_comp_index.

  • progress_metric — расчет, возвращающий значение поля прогресса аудита progress для обобщающего расчета mean_audit_progress.

  • is_kii — расчет, записывающий в атрибут аудита isKii логическое значение: true, если наименование аудита содержит подстроку "КИИ" (аудит проводится по объекту КИИ), false иначе.

Обобщающие расчеты

Схема содержит обобщающий расчет mean_audit_progress, вычисляющий средний прогресс по аудитам в системе с помощью расчета progress_metric.

Пример политик в схеме автоматизации

В данном разделе приведены примеры настройки политик в схеме автоматизации.

Пример настройки политики без вложенности

id: evo.vulnerability.policy.basic
type: calculation_schema
name: Базовая политика создания задач на устранение уязвимостей
tags: [vulnerabilities, policy, automation]
version: 1.0.0
status: stable
author: Ivan Ivanov <ivanov@example.ru>

policies:
  - id: create_task_if_vulnerability_is_critical
    name: Создать задачу, если уязвимость критическая
    entity: vulnerabilities.rvision.ru/Vulnerability
    conditions:
      - type: expression
        expression: 'equalText({field:criticalityLevel}, "Критический")'
    actions:
      - type: playbook
        playbook: create_tasks_from_critical_vulnerabilities
        maxParallel: 5
        timeout: 10000

Интерпретация примера

Схема содержит политику create_task_if_vulnerability_is_critical — автоматическое создание задач для уязвимостей с уровнем Критический:

  • Условие запуска политики типа expression содержит выражение, которое возвращает True, если уровень уязвимости — Критический. В выражении используется функция equalText из библиотеки math.js.

  • Действие политики — запуск плейбука create_tasks_from_critical_vulnerabilities для каждой критической уязвимости. В один момент времени может выполняться не более 5 запусков плейбука. Завершение всех запусков плейбука ожидается в течение 10 секунд.

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

id: evo.vulnerability.policy.nested
type: calculation_schema
name: Политика обработки уязвимостей со вложенными условиями и действиями
tags: [vulnerabilities, policy, automation]
version: 1.0.0
status: stable
author: Ivan Ivanov <ivanov@example.ru>

calculations:
 - id: vuln_is_risk
   auto_recalculation: true
   name: Является ли уязвимость критичной
   entity: vulnerabilities.rvision.ru/Vulnerability
   complexity_limit: 1
   expression: '{field:cvssScore} > 7'

policies:
  - id: escalate_if_high_risk_or_calc
    name: Эскалировать обработку уязвимости
    description: Пример сложного условия с вложенными условиями и действиями
    entity: vulnerabilities.rvision.ru/Vulnerability

    conditions:
      - type: expression
        expression: 'equalText({field:status}, "Открыта")'
      - conditions:
          - type: calculation
            calculation: vuln_is_risk
          - type: expression
            expression: 'equalText({field:criticalityLevel}, "Критический")'

    actions:
      - type: playbook
        playbook: notify_responsible_employee
        extraParams:
          priority: "high"
          source: "policy"

      - type: calculation
        calculation: vulnerability.calculations/vuln_calculation

      - actions:
          - type: playbook
            playbook: create_link_incident
            extraParams:
              urgency: "critical"
            maxParallel: 5
            timeout: 10000
          - type: playbook
            playbook: create_link_task
            extraParams:
              type: "vulnTask"
            maxParallel: 5
            timeout: 10000

Интерпретация примера

Схема содержит следующие элементы:

  • Расчет vuln_is_risk, который возвращает True, если рейтинг CVSS уязвимости (cvssScore) больше 7, False — иначе.

  • Политика escalate_if_high_risk_or_calc запускает эскалацию необходимости обработать уязвимость.

    • Политика срабатывает при выполнении обоих условий (логическое И):

      • статус уязвимости — Открыта;

      • выполняется одно из двух вложенных условий (логическое ИЛИ): расчет vuln_is_risk для уязвимости возвращает True или уровень критичности уязвимости — Критический.

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

      • Плейбук notify_responsible_employee создает оповещение для ответственного за устранение уязвимости. Плейбук получает на вход параметры приоритета (priority) и источника оповещения (source).

      • Выполняется расчет vuln_calculation, определенный в схеме автоматизации vulnerability.calculations.

      • Параллельно запускаются плейбуки создания инцидента create_link_incident и задачи create_link_task, связанных с уязвимостью.

Запуск расчетов и отображение их результатов

Способы запуска расчетов и вывода их в интерфейс системы описаны в разделе Запуск расчетов и отображение их результатов.

Запуск политик

Настраивать запуск политик необходимо в разделе Автоматизация → Политики веб-интерфейса системы.

Была ли полезна эта страница?

+7 (499) 755 55 70 sales@rvision.ru

О компании Пользовательское соглашение Политика cookies

Обратная связь