Содержание
1. Используемые термины
2. Архитектура решения
3. Требования для установки
4. Установка и настройка сервисов
4.1. Быстрая установка
4.2. Установка без доступа к сети Интернет
4.3. Установка при наличии доступа к сети Интернет
4.3.1. HTTP
4.3.2. HTTPS
4.4. Действия после установки
4.5. Установка агентов Lambda Executor
4.5.1. Установка на машинах под управлением ОС Windows
4.5.2. Установка на машинах под управлением ОС Linux
4.6. Удаление агентов Lambda Executor
4.6.1. Удаление с машин под управлением ОС Windows
4.6.2. Удаление с машин под управлением ОС Linux
5. Загрузка скриптов, плейбуков и сопутствующих метаданных
5.1. Требования для запуска утилиты
5.1.1. Требования к программному обеспечению
5.1.2. Требования к размещению файлов
5.2. Подготовка к запуску утилиты
5.3. Запуск утилиты
5.3.1. Запуск с помощью Docker
5.3.2. Запуск без использования контейнеров
5.3.3. Автоматизация установки с помощью make
6. Управление сервисами
6.1. Настройка сетевых портов
6.2. Запуск и приостановка сервисов
6.3. Обновление сервисов
6.4. Резервное копирование и восстановление
6.5. Логирование работы сервисов
6.5.1. Просмотр лог-файлов в MinIO
7. Описание параметров ENV-файлов
7.1.HTTP
7.2. HTTPS
8. Адреса сервисов по умолчанию

1. Используемые термины
1.1. Лямбда-функция
Функция, которая создается и выполняется в ответ на заданные события. Состоит из
тела (скрипта) и метаинформации (имени, описания, свойств, тегов и т. д.).
1.2. Плейбук
Упорядоченный набор скриптов, предназначенный для автоматизации
определенной последовательности действий.
1.3. Рантайм
Среда работы (выполнения) скриптов. Предоставляет дополнительные библиотеки и
переменные окружения, требуемые для их работы.
1.4. Секрет
Конфиденциальные учетные данные, используемые для аутентификации при
исполнении плейбуков.
1.5. Скрипт
Тело лямбда-функции, написанное на каком-либо языке, требующем интерпретатор
(компилятор) для запуска (например, Python).

2. Архитектура решения
UDV SOAR — программное решение класса SOAR, в которое входят следующие подсистемы и компоненты:
• подсистема оркестрации, предназначенная для автоматического выполнения части
действий на всех этапах обработки инцидентов ИБ (локализация, расследование,
реагирование);
• подсистема реагирования на инциденты ИБ, предназначенная для сбора инцидентов
ИБ из различных источников, их классификации, формирования плана мероприятий
по реагированию и отслеживанию этапов и метрик реализации данного плана;
• служебные компоненты авторизации, хранения данных и интеграции между
подсистемами.

Решение включает компоненты двух типов: зависимости (программное обеспечение с
открытым исходным кодом) и приложения SOAR.

Приложения SOAR

1. Lambda Executor — агент для удаленного запуска кода лямбда-функций. По
умолчанию устанавливается один внутренний. При необходимости можно
установить дополнительные агенты на нужных клиентских машинах (см. Установка
агентов Lambda Executor).
2. Lambda Service — компонент, обеспечивающий запуск лямбда-функций и
предоставляющий REST API для управления им.
3. Proxy Service — сервис интеграции данных между сервисами подсистемы
реагирования на инциденты ИБ и подсистемой оркестрации.
4. State Machine Executor — компонент, управляющий расписанием и порядком запуска
плейбуков.
5. State Machine Service — компонент, управляющий созданием и хранением заданий
на запуск плейбуков, предоставляет Web API (REST) и Web Socket для управления
плейбуками, их запуском и связанной с ними информацией.

Зависимости

1. Grafana — система визуализации метрик работы сервисов. Тип лицензии: AGPL-3.0
license.
2. Keycloak — система авторизации для сервисов подсистемы реагирования на
инциденты ИБ, подсистемы оркестрации. Тип лицензии: Apache-2.0 license.
3. MinIO — объектное хранилище подсистемы оркестрации. В нем хранятся файлы
плейбуков (JSON), файлы скриптов функций (PY, PS1), файлы входных данных и контекста выполнения плейбуков (JSON), а также временные файлы, связанные с выполнением лямбда-функций. Тип лицензии: AGPL-3.0 license.
4. NATS — система обмена сообщениями между компонентами Lambda Service и Lambda
Executor. Тип лицензии: Apache-2.0 license.
5. Pgadmin — инструмент для управления базой данных PostgreSQL. Тип лицензии:
PostgreSQL license.
6. PostgreSQL — базы данных для сервисов KeyCloak, Vault, подсистемы реагирования
на инциденты ИБ, подсистемы оркестрации. Тип лицензии: PostgreSQL license.
7. Prometheus — система сбора и хранения метрик работы сервисов. Тип лицензии:
Apache-2.0 license.
8. Vault — система безопасного хранения секретов подсистемы оркестрации. Тип
лицензии: Business Source License.

3. Требования для установки
Для успешной установки решения должны выполняться следующие требования:
Табл. 1. Требования к аппаратному обеспечению

Если Docker и Docker Compose ранее были установлены на компьютере с дистрибутивом на основе Debian, рекомендуется удалить это ПО и установить заново, используя следующие команды:

sudo apt update && sudo apt install wget -y

wget https://
download.docker.com/linux/debian/dists/stretch/pool/stable/amd64/containerd.io_1.4.3-1_amd64.deb

wget https://download.docker.com/linux/debian/dists/stretch/pool/stable/amd64/docker-ce-
cli_19.03.9~3-0~debian-stretch_amd64.deb

wget https://
download.docker.com/linux/debian/dists/stretch/pool/stable/amd64/docker-ce_19.03.9~3-0~debian-stretch_amd64.deb

sudo dpkg -i containerd.io_1.4.3-1_amd64.deb docker-ce-cli_19.03.9~3-0~debian-stretch_amd64.deb docker-ce_19.03.9~3-0~debian-stretch_amd64.deb

wget https://github.com/docker/compose/releases/download/v2.16.0/docker-compose-linux-x86_64

sudo mv ./docker-compose-linux-x86_64 /usr/bin/docker-compose

sudo chmod +x /usr/bin/docker-compose

По умолчанию вместе с дистрибутивом предоставляются реквизиты для авторизации в
реестре контейнеров разработчика. Для авторизации в реестре контейнеров используется команда docker login cr.udv.group.

4. Установка и настройка сервисов

4.1. Быстрая установка
Чтобы быстро развернуть готовое к работе решение UDV SOAR в выбранной конфигурации, воспользуйтесь установочным скриптом. Он предоставляется
разработчиком в отдельном файле.

Чтобы узнать о других вариантах развертывания, изучите разделы Установка без доступа к сети Интернет и Установка при наличии доступа к сети Интернет.

4.2. Установка без доступа к сети Интернет

Чтобы установить ПО без доступа к сети Интернет:

1. Запустите дистрибутив для установки через Интернет на чистой системе с доступом
в Интернет.

2. После успешного запуска сохраните все скачанные образы в единый архив:
docker save $(docker images | sed '1d' | awk '{print $1":" $2 }') -o soar-images.tar
&& tar czvf soar-images.tar.gz soar-images.tar && rm soar-images.tar

3. Скопируйте полученный архив soar-images.tar.gz на сервер без доступа в
Интернет.

4. На сервере без доступа к Интернету загрузите образы в систему из архива:
tar vfzx soar-images.tar.gz && docker load -i soar-images.tar

5. Далее установка производится аналогично процессу установки при наличии доступа
в сеть Интернет.

4.3. Установка при наличии доступа к сети Интернет

4.3.1. HTTP
Чтобы установить ПО при наличии доступа к сети Интернет с использованием протокола
HTTP:
1. Распакуйте полученный архив в любую удобную директорию и перейдите в нее.
2. Откройте ENV-файл и в основных параметрах замените значение параметра
COMPOSE_PROXY_HTTP_IP со стандартного на IP-адрес хоста (далее — HOST_IP), на
котором выполняется развертывание сервисов.
3. Запустите сервисы:
docker-compose up -d

4.3.2. HTTPS
Чтобы установить ПО при наличии доступа к сети Интернет с использованием протокола
HTTPS:
1. Распакуйте полученный архив в любую удобную директорию и перейдите в нее.
2. Для использования своего самоподписанного wildcard-сертификата, который
автоматически генерируется при первом запуске:
a. Откройте ENV-файл.
b. В основных параметрах замените значение параметра COMPOSE_PROXY_DOMAIN со стандартного на доменное имя вашего wildcard-сертификата.
c. Скопируйте файл сертификата и файл ключа в папки nginx.crt и nginx.key.
d. Для корректной работы добавьте выбранные DNS-имена на DNS-сервер или
на локальные машины, на которых будут использоваться сервисы.
3. Запустите сервисы:
docker-compose up -d

4.4. Действия после установки
Перед запуском убедитесь, что у текущего пользователя имеются полные права (на чтение,
запись и запуск содержимого папки дистрибутива). Если необходимых прав нет, смените
пользователя, от имени которого которого запускаются сервисы, или расширьте права
текущего пользователя.

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

Проверить корректность работы запущенных сервисов можно двумя способами:
1. в веб-интерфейсе Grafana;
2. путем входа на адрес каждого сервиса.

Данные для входа, устанавливаемые по умолчанию, приведены в разделе Адреса сервисов
по умолчанию.

Чтобы проверить версию установленной подсистемы, откройте пользовательский
интерфейс по адресу http://HOST_IP:10500/ (при использовании HTTP) или https://
soar.test.local (при использовании HTTPS) по умолчанию и наведите указатель на левое
боковое меню. Версия будет указана в его нижней части.

4.5. Установка агентов Lambda Executor
Чтобы автоматизировать развертывание агентов Lambda Executor на устройствах,
разработаны установочные скрипты. Ниже приведены инструкции по их использованию.

4.5.1. Установка на машинах под управлением ОС Windows
Состав инсталлятора:
1. full_installer.bat — главный установщик, с помощью которого можно
развернуть агент и все необходимые зависимости;
2. agent_installer.py — установщик агента;
3. nssm-2.24 — утилита для установки службы Windows.

4. certs — папка с сертификатами безопасности (требуемый формат имен — *.crt).

Для работы главного установщика full_installer.bat поместите в одну директорию с ним:
• файлы lambdaExecutor.exe и lambdaExecutorConfig.json;
• папку venv с виртуальным окружением Python;
• папку certs с CRT-сертификатами (необязательный элемент).

Чтобы запустить установку, введите команду:
.\full_installer.bat le_agent nats.local:4222

Здесь:
• le_agent — это задаваемое имя агента Lambda Executor (необязательный параметр
— если его не указать, имя будет сгенерировано автоматически);
• nats.local:4222 — это адрес NATS (необязательный параметр).

Установщик full_installer.bat выполняет следующие операции:
• создает директорию %SYSTEMDRIVE%/soar/python и копирует в нее содержимое
папки venv;
• устанавливает PATH на %SYSTEMDRIVE%/soar/python/Scripts;
• запускает скрипт-установщик агента agent_installer.py;
• копирует сертификаты, если они были размещены в папке certs.

Требования для работы установщика агента agent_installer.py:
1. Состав файлов — в директорию со скриптом поместите:
◦ папку nssm-2.24;
◦ готовый бинарный файл — lambdaExecutor.exe;
◦ конфигурационный файл — lambdaExecutorConfig.json.

2. Пути к файлам, требуемым для установки, не должны содержать пробелы.

3. Для установки и запуска службы запустите терминал с правами администратора.

Чтобы запустить установку в директорию по умолчанию с именем на основе сетевого,
введите команду:
python.exe .\agent_installer.py

Чтобы запустить установку в произвольную директорию, введите команду:
python.exe .\agent_installer.py --install_dir=D:\Agent

Чтобы запустить установку в произвольную директорию с произвольным именем, введите
команду:
python.exe .\agent_installer.py --install_dir=D:\Agent --executor_name=Agent6457

Установщик agent_installer.py выполняет следующие операции:
1. копирует исполняемый файл lambdaExecutor.exe и файл конфигурации
lambdaExecutorConfig.json в установочную директорию;

2. редактирует конфигурацию в установочной директории, чтобы задать уникальное
имя агента, передаваемое в параметре --executor_name;

3. устанавливает runtimes.json, исходя из переданного параметра --python;
4. устанавливает lambdaExecutor.exe в качестве службы и запускает ее;
5. выводит имя агента в консоль и файл ./executor_name.txt в директории с
установочным скриптом.

4.5.2. Установка на машинах под управлением ОС Linux

Состав инсталлятора:
1. full_installer.sh — главный установщик, с помощью которого можно
развернуть агент и все необходимые зависимости;
2. agent_installer.py — установщик агента.

Для работы главного установщика full_installer.sh поместите в одну директорию с ним:
• готовый бинарный файл lambdaExecutor;
• конфигурационный файл lambdaExecutorConfig.json;
• скрипт agent_installer.py;
• папку venv с виртуальным окружением Python.

Чтобы запустить установку, введите команду:
sudo ./full_installer.sh 3.8 le_agent nats.local:4222

Здесь:
• 3.8 — это указанная в venv версия Python;
• le_agent — это задаваемое имя агента Lambda Executor (необязательный параметр
— если его не указать, имя будет сгенерировано автоматически);
• nats.local:4222 — это адрес NATS (необязательный параметр).

Установщик выполняет следующие операции:
• копирует Python и требуемые библиотеки в директорию агента;
• устанавливает PATH и PYTHONPATH для использования интерпретатора и библиотек;
• запускает agent_installer.py:
◦ копирует бинарный и конфигурационный файлы;
◦ создает и запускает systemd-демон soar_agent.

4.6. Удаление агентов Lambda Executor

Чтобы автоматизировать удаление агентов Lambda Executor c устройств, разработаны
скрипты. Ниже приведены инструкции по их использованию.

4.6.1. Удаление с машин под управлением ОС Windows

Состав деинсталлятора:
1. uninstaller.bat — главный деинсталлятор, с помощью которого можно удалить
службу агента и все связанные с ним файлы;
2. agent_uninstaller.py — деинсталлятор агента;
3. nssm-2.24 — утилита для удаления Windows-службы.

Чтобы запустить деинсталлятор, введите команду:
.\uninstaller.bat

Деинсталлятор выполняет следующие операции:
• останавливает и удаляет службу агента Lambda Executor;
• удаляет файлы приложения soar_agent;
• удаляет Python с машины, на которой был установлен агент.

4.6.2. Удаление с машин под управлением ОС Linux

Состав деинсталлятора:
1. uninstaller.sh — главный деинсталлятор, с помощью которого можно удалить службу агента и все связанные с ним файлы;
2. agent_uninstaller.py — деинсталлятор агента.

Чтобы запустить деинсталлятор, введите команду: sudo ./uninstaller.sh

Деинсталлятор выполняет следующие операции:

• останавливает systemd-сервис soar_agent и удаляет soar_agent.servicer из
директории /etc/systemd/systemd-демон;
• удаляет файлы агента;
• удаляет Python и переменные среды для поиска интерпретатора.

5. Загрузка скриптов, плейбуков и сопутствующих метаданных

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

5.1. Требования для запуска утилиты

5.1.1. Требования к программному обеспечению
Для запуска утилиты потребуются следующие компоненты:
1. Python 3.8 и более поздних версий;
2. Docker Сompose (для запуска скрипта как контейнера);
3. утилита make (для удобства запуска).

5.1.2. Требования к размещению файлов
Все загружаемые файлы должны быть размещены в корневой директории проекта в папке
data. Плейбуки в формате JSON должны располагаться в директории /data/playbooks,
скрипты — в директории /data/scripts.

Количество поддиректорий не имеет значения. Это означает, что утилита найдет скрипты
и плейбуки вне зависимости от того, насколько «глубоко» они расположены. Например,
скрипт может располагаться следующим образом:

Даже в таком случае утилита найдет и загрузит EchoScript в подсистему.
То же самое касается плейбуков. Ниже приведен пример возможного расположения
скриптов и плейбуков перед загрузкой:

5.2. Подготовка к запуску утилиты

Чтобы подготовиться к запуску, в корневой директории (рядом с файлом docker-
compose.yaml) создайте ENV-файл со следующими переменными:

• KEYCLOAK_CLIENT_ID='client_id' — client_id для Keycloak;
• KEYCLOAK_CLIENT_SECRET='s3cr3t' — client_secret для Keycloak;
• KEYCLOAK_SCOPE='profile' — scope для Keycloak;
• KEYCLOAK_GRANT_TYPE='password' — grant_type для Keycloak;
• KEYCLOAK_USERNAME='username' — имя пользователя Keycloak;
• KEYCLOAK_PASSWORD= password — пароль пользователя Keycloak;
• KEYCLOAK_URL='http://HOST_IP:8080' — адрес сервера Keycloak;
• LAMBDA_SERVICE_URL='http://HOST_IP:8089' — адрес Lambda Service;
• STATE_MACHINE_SERVICE_URL='http://HOST_IP:8088' — адрес State Machine
Service;
• SOAR_API_VERSION = 'v3.6' — текущая версия API SOAR.

5.3. Запуск утилиты

Запустить утилиту можно тремя способами: с помощью Docker, без использования
контейнеров и автоматически с помощью утилиты make.

Результаты работы выводятся в консоль:
Всего загружено плейбуков: 5
Всего загружено скриптов: 14
Всего загружено секретов: 6
Имена и id доступны в лог файле

Критические ошибки также появляются в консоли. Логи располагаются в папке logs, при
запуске с использованием Docker — volume c логами также называется logs.

5.3.1. Запуск с помощью Docker
Чтобы запустить утилиту с помощью Docker, в корневой папке введите следующую
команду: docker-compose up --build

5.3.2. Запуск без использования контейнеров

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

1. Установите виртуальное окружение: python3.8 -m venv venv
2. Активируйте виртуальное окружение: source ./venv/bin/activate
3. Установите зависимости: pip install -r requirements.txt
4. Запустите скрипт: python3.8 main.py

5.3.3. Автоматизация установки с помощью make

Утилита make позволяет автоматизировать установку. Для этого используйте следующие
команды:

1. Создайте контейнер со скриптом и контентом: build-container
2. Запустите контейнер: start-container
3. Подготовьте ENV-файл: env-prepare
4. Запустите скрипт без использования контейнера: run

6. Управление сервисами

6.1. Настройка сетевых портов

Всем сервисам системы назначены порты для взаимодействия, которые описаны
в переменных ENV-файла. Чтобы переназначить порт сервиса, достаточно изменить
значение соответствующего параметра *_PORT и перезапустить сервис.

6.2. Запуск и приостановка сервисов

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

1. Чтобы запустить работу, выполните команду: docker-compose up -d
2. Чтобы приостановить работу, выполните команду: docker-compose down

6.3. Обновление сервисов

Чтобы обновить сервисы, выполните следующую команду:
docker-compose pull soar-lambda-service soar-state-machine-service
soar-state-machine-executor
soar-proxy-service soar-lambda-executor soar-asleditor

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

6.4. Резервное копирование и восстановление

Чтобы создать резервную копию подсистемы, выполните следующую команду:
docker-compose exec backup-client bash backup-client-entrypoint.sh backup all

Архив с резервной копией появится в папке ./docker-compose-backups/.

Чтобы восстановить систему из резервной копии, выполните следующие команды:
docker-compose down docker-compose up -d postgres minio backup-client docker-compose
exec backup-client bash backup-client-entrypoint.sh restore <.tar.gz name> all

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

1. Чтобы создать резервную копию всех данных сервиса MinIO:
docker-compose exec backup-client bash backup-client-entrypoint.sh backup minio
2. Чтобы создать резервную копию всех данных сервиса PostgreSQL:
docker-compose exec backup-client bash backup-client-entrypoint.sh backup
postgres
3. Чтобы создать резервную копию секретов Docker volume:
docker-compose exec backup-client bash backup-client-entrypoint.sh backup secrets

6.5. Логирование работы сервисов

В процессе функционирования системы осуществляется логирование событий разного
уровня значимости (level) как в каждом из сервисов, входящих в состав решения, так и в
сервере авторизации Keycloak.

Есть следующие уровни логирования в порядке увеличения количества логируемой
информации:
• error — уровень ошибок, т. е. в лог-файлы будут попадать только записи об ошибках
в приложении;
• warn — уровень предупреждений, т. е. в лог-файлы будут попадать предупреждения
и ошибки;
• info — обычный уровень (по умолчанию) для просмотра информационных сообщений, предупреждений и ошибок;
• debug — уровень отладки для просмотра отладочной информации;
• trace — уровень детального логирования отладки, содержащий большее количество
отладочной информации по сравнению с debug.

Для эксплуатации системы рекомендуется выбирать уровень логирования error — info.
В таблице ниже указаны лог-файлы сервисов системы и их расположение.

Табл. 3. Расположение лог-файлов

6.5.1. Просмотр лог-файлов в MinIO

Чтобы посмотреть лог-файлы приложений SOAR в MinIO:

1. Откройте веб-интерфейс MinIO по адресу http://HOST_IP:9001/ (при использовании
HTTP) или https://minio.test.local/ (при использовании HTTPS).
2. Укажите реквизиты доступа по умолчанию (логин: minioadmin, пароль: ***) и
нажмите Login. Откроется страница Buckets.
3. Рядом с нужным бакетом нажмите Browse-> и откройте файл в соответствии с
таблицей Таблица 3. Расположение лог-файлов.

7. Описание параметров ENV-файлов

В разделе описаны параметры ENV-файлов при развертывании с использованием HTTP- и
HTTPS-протоколов.

7.1. HTTP

Основные параметры
Табл. 4. IP-адрес хоста, на котором разворачиваются сервисы

Табл. 6. Часовой пояс, используемый в сервисах