han-app/VM1_app/codebase/backend/deployment/kesl/RUNBOOK.KESL.ru.md

# KESL 12.4 standalone на production ВМ1

Это операторский runbook для поэтапного внедрения Kaspersky Endpoint Security
для Linux 12.4 на Ubuntu 24.04 ВМ1. Команды выполняются только персональной
ролью `admin` через `sudo`; repository automation этот runbook не запускает.

Цель: реализовать АВЗ.1 (обнаружение и реагирование) и АВЗ.2 (обновление баз)
без деградации Docker-стека HAN Chat.

Не выполняйте установку одновременно с deploy, миграциями, backup, ротацией
секретов, TLS renewal, перезапуском Docker или host reboot.

Официальная документация:

- [программные требования](https://support.kaspersky.ru/kes-for-linux/12.4.0/197645);
- [краткое руководство по установке](https://support.kaspersky.ru/kes-for-linux/12.4.0/install/16099);
- [автоматическая первоначальная настройка](https://support.kaspersky.ru/kes-for-linux/12.4.0/197909);
- [параметры autoinstall.ini](https://support.kaspersky.ru/kes-for-linux/12.4.0/197593);
- [ограничение CPU и памяти](https://support.kaspersky.ru/kes-for-linux/12.4.0/264979);
- [настройка File Threat Protection](https://support.kaspersky.ru/kes-for-linux/12.4.0/248490);
- [проверка контейнеров](https://support.kaspersky.ru/kes-for-linux/12.4.0/197612);
- [удаление DEB-пакета](https://support.kaspersky.ru/kes-for-linux/12.4.0/197596).

## 0. Участники, входные данные и stop conditions

До окна работ зафиксируйте:

- change ID, время окна, оператора, approver Security и on-call;
- hostname/IP ВМ1, фактическую версию Ubuntu и ядра;
- точное имя, версию и SHA-256 полученного от Kaspersky DEB-пакета;
- источник пакета и лицензию/код активации;
- текущий release SHA и image digests;
- место хранения evidence вне immutable release.

Значения лицензии, activation code, proxy credentials и секреты HAN нельзя
помещать в репозиторий, shell history, журналы или evidence.

Немедленно остановитесь, если:

- ОС, архитектура или ядро отсутствуют в матрице KESL 12.4;
- уже установлен другой антивирус или неизвестная версия KESL;
- свободно менее 4 ГБ или нет рабочего swap;
- до установки есть unhealthy/restarting контейнеры, 5xx или дефицит ресурсов;
- не совпал SHA-256 пакета;
- после этапа выросли restart count, 5xx, Redis latency/blocked clients,
  OTEL queue или host IO wait сверх согласованного порога;
- File Threat Protection изменил UFW/iptables или доступность портов;
- базы не загрузились либо лицензия недействительна.

Рекомендуемые пороги отката для пилота (утвердить до установки):

- новый unhealthy/restart любого steady-state сервиса;
- публичный smoke не проходит два запуска подряд;
- host available memory менее 2 ГБ или начинается устойчивый swap-in/swap-out;
- IO wait более 10% в течение 5 минут;
- p95 API/Redis latency выросла более чем на 20% от baseline в течение 10 минут;
- свободное место уменьшилось ниже 10 ГБ или ниже 15%.

### 0.1. Исключение только для constrained test VM

На тестовой ВМ допускается пилот с 4 ГБ RAM без увеличения памяти только по
явному решению владельца среды. Это не отменяет production-gate и не является
обоснованием для переноса той же конфигурации в боевую среду.

Обязательные ограничения такого пилота:

- provider snapshot/console и оператор доступны до начала;
- `ScanMemoryLimit=512`, `MaxMemory=1024MB`;
- `UseOnDemandCPULimit=Yes`, `OnDemandCPULimit=15`;
- не запускать full filesystem scan и проверку архивов;
- ODS и ContainerScan выполнять по одному объекту, не одновременно;
- сначала Update и health, затем один stateless image, затем File Threat
  Protection в `Notify`;
- остановить KESL при available memory менее 512 МБ, устойчивом swap IO,
  появлении host/container OOM, restart или провале smoke;
- до режима `Block` требуется отдельное подтверждение стабильности.

Перед production-внедрением повторить sizing и baseline на боевых ресурсах;
test-профиль 512/1024 МБ автоматически не переносить.

## 1. Read-only preflight и baseline

Команды разделены на небольшие блоки: сохраните вывод каждого блока в
change record, предварительно проверив отсутствие секретов. Не публикуйте
полный `docker inspect`, Compose config или environment.

### 1.1. Host и совместимость

```sh
date -Is
hostnamectl
uname -a
dpkg --print-architecture
findmnt -no TARGET,SOURCE,FSTYPE,OPTIONS / /var/lib/docker /tmp 2>/dev/null
free -h
swapon --show
df -hT / /var/lib/docker /tmp
df -ih / /var/lib/docker /tmp
systemctl is-active docker fail2ban ufw
dpkg-query -W -f='${Package}\t${Version}\t${Status}\n' \
  kesl kesl-gui kav4fs 2>/dev/null || true
```

Проверка проходит только для `amd64`/поддерживаемой архитектуры, Ubuntu 24.04
LTS и поддерживаемого KESL ядра. Требования Kaspersky — минимум 2 ГБ RAM,
1 ГБ swap и 4 ГБ свободного диска, но этого недостаточно для данной ВМ:
Compose-лимиты суммарно около 11,6 ГБ. При RAM менее 16 ГБ установка требует
отдельного решения владельца сервиса о доступном запасе.

### 1.2. Docker и приложение

```sh
docker info --format \
  'driver={{.Driver}} root={{.DockerRootDir}} containers={{.Containers}} running={{.ContainersRunning}}'
/usr/local/sbin/han-vm1-compose ps
docker ps --format \
  'table {{.Names}}\t{{.Status}}\t{{.Image}}'
docker stats --no-stream --format \
  'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.BlockIO}}\t{{.PIDs}}'
```

Сохраните список и состояние именованных volumes без содержимого:

```sh
for volume in redis-data otel-queue nginx-cache; do
  docker volume ls --format '{{.Name}}' |
    while IFS= read -r name; do
      case "$name" in
        *"$volume"*)
          docker volume inspect --format \
            '{{.Name}}\t{{.Mountpoint}}' "$name"
          ;;
      esac
    done
done
```

В change record перенесите три фактических mountpoint. Не подставляйте
предполагаемый Compose prefix.

### 1.3. Health, edge и firewall

Под root на ВМ:

```sh
systemctl --no-pager status \
  han-secrets@production.service han-stack@production.service
iptables -S HAN-CHAT-DOCKER
iptables -L HAN-CHAT-DOCKER -n -v
ufw status verbose
journalctl --since '-30 min' --no-pager \
  -u han-stack@production.service -p warning
```

С trusted external host выполните smoke из
`deployment/RUNBOOK.production.ru.md`, раздел 10. Если запускается repository
`deployment/scripts/smoke.sh`, он должен использовать штатный secret launcher;
не печатайте resolved environment.

Снимите из штатного observability baseline:

- API request rate, 5xx и p50/p95/p99 latency;
- Redis latency, blocked clients и memory;
- container restart/OOM count;
- host CPU, available RAM, swap, disk IO/IO wait;
- OTEL exporter failures и queue depth.

Без доступных baseline и rollback approver к установке не переходить.

## 2. Проверка пакета и подготовка

GUI на сервер не устанавливается. Пакет передаётся в root-only staging,
например `/root/kesl-install`, и удаляется после приёмки.

```sh
install -d -m 0700 -o root -g root /root/kesl-install
install -m 0600 -o root -g root \
  /tmp/<KESL_12_4_AMD64_DEB> /root/kesl-install/kesl.deb
sha256sum /root/kesl-install/kesl.deb
dpkg-deb -f /root/kesl-install/kesl.deb Package Version Architecture
```

Сравните SHA-256 с опубликованным/полученным по доверенному каналу значением.
Не продолжайте при package name не `kesl`, неверной архитектуре или версии не
12.4.x.

Перед установкой сохраните только безопасные snapshots:

```sh
cp -a /etc/docker/daemon.json /root/kesl-install/docker-daemon.before.json
iptables-save > /root/kesl-install/iptables.before
ufw status verbose > /root/kesl-install/ufw.before
```

## 3. Установка с отключённой защитой

Установка изменяет host и выполняется только в maintenance window.

```sh
apt-get install /root/kesl-install/kesl.deb
```

Создайте `/root/kesl-install/autoinstall.ini` с mode `0600`. Значения EULA,
Privacy Policy и KSN должны быть осознанно согласованы с Security/Legal, а не
скопированы механически:

```ini
KSVLA_MODE=No
ENDPOINT_AGENT_MODE=No
EULA_AGREED=<Yes_AFTER_APPROVAL>
PRIVACY_POLICY_AGREED=<Yes_AFTER_APPROVAL>
USE_KSN=<Yes_OR_No_AFTER_APPROVAL>
GROUP_CLEAN=Yes
LOCALE=ru_RU.UTF-8
INSTALL_LICENSE=None
UPDATER_SOURCE=KLServers
UPDATE_EXECUTE=No
KERNEL_SRCS_INSTALL=No
USE_GUI=No
CONFIGURE_SELINUX=No
DISABLE_PROTECTION=Yes
INTERCEPTOR_MODE=UseFanotify
ENABLE_TRACES_ON_FIRST_STARTUP=No
```

Для Ubuntu AppArmor значение `CONFIGURE_SELINUX=No` ожидаемо. `UseFanotify`
не требует сборки стороннего kernel module. Если выбран KSN, документируйте
передачу данных и правовое основание.

Первоначальная настройка:

```sh
chmod 0600 /root/kesl-install/autoinstall.ini
/opt/kaspersky/kesl/bin/kesl-setup.pl \
  --autoinstall=/root/kesl-install/autoinstall.ini
test "$?" -eq 0
systemctl --no-pager status kesl
kesl-control --app-info
kesl-control --supported-tech-info
kesl-control --get-task-list
```

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

## 4. Ресурсные ограничения до первого scan

В KESL 12.4 `ScanMemoryLimit` по умолчанию равен 8192 МБ, а `MaxMemory=auto`
может разрешить до 50% доступной RAM. Для ВМ1 эти defaults не принимаются без
измерений.

Выберите значения по фактическому baseline:

- constrained test VM, 4 ГБ RAM: `ScanMemoryLimit=512`,
  `MaxMemory=1024MB`, `OnDemandCPULimit=15`; только по разделу 0.1;
- 16 ГБ RAM: начните с `ScanMemoryLimit=1024`, `MaxMemory=2048MB`;
- 24–32 ГБ RAM: начните с `ScanMemoryLimit=2048`, `MaxMemory=4096MB`;
- иной размер: согласуйте значения; `ScanMemoryLimit` должен быть ниже
  `MaxMemory`, а после резервирования KESL у приложения должен оставаться
  исходный запас.

Сначала сохраните исходные настройки:

```sh
kesl-control --get-app-settings \
  --file /root/kesl-install/app-settings.before.ini
install -m 0600 -o root -g root \
  /var/opt/kaspersky/kesl/common/kesl.ini \
  /root/kesl-install/kesl.ini.before
```

Установите CPU limit для ODS/ContainerScan:

```sh
kesl-control --set-app-settings \
  UseOnDemandCPULimit=Yes OnDemandCPULimit=<15_FOR_TEST_OR_APPROVED_VALUE>
```

Для изменения `ScanMemoryLimit` и `MaxMemory` следуйте официальной процедуре:
остановите KESL, внесите значения в секцию `[General]` файла
`/var/opt/kaspersky/kesl/common/kesl.ini`, затем запустите KESL. Не заменяйте
файл целиком и не применяйте шаблон из репозитория как готовый конфиг.

После запуска проверьте:

```sh
systemctl is-active kesl
kesl-control --get-app-settings
kesl-control --app-info
```

## 5. Обновление баз — АВЗ.2

Запустите предустановленную задачу Update (ID 6) и дождитесь результата:

```sh
kesl-control --get-settings 6
kesl-control --get-schedule 6
kesl-control --start-task 6 -W
kesl-control --get-task-state 6
kesl-control --app-info
```

Проверьте действующую лицензию, `Базы приложения загружены: Да`, свежую дату
выпуска баз и успешное завершение Update. Затем задайте почасовой запуск:

```sh
kesl-control --set-schedule 6 RuleType=Hourly
kesl-control --get-schedule 6
```

Если установленная сборка требует интервал в `StartTime`, не угадывайте
синтаксис: экспортируйте schedule и измените его по документации именно этой
сборки. До успешного автообновления АВЗ.2 не принимается.

Сразу после обновления повторите разделы 1.2–1.3. При деградации выполните
rollback из раздела 11.

## 6. Исключения hot-data

Исключения создаются только после получения фактических mountpoint в разделе
1.2. Разрешены три области:

- `<REDIS_DATA_MOUNTPOINT>` — AOF/RDB;
- `<OTEL_QUEUE_MOUNTPOINT>` — persistent telemetry queue;
- `<NGINX_CACHE_MOUNTPOINT>` — regenerable cache.

До изменения экспортируйте параметры:

```sh
kesl-control --get-settings 1 \
  --file /root/kesl-install/file-threat.before.ini
```

Добавьте обычные исключения File Threat Protection:

```sh
kesl-control --set-settings 1 \
  --add-exclusion <REDIS_DATA_MOUNTPOINT>
kesl-control --set-settings 1 \
  --add-exclusion <OTEL_QUEUE_MOUNTPOINT>
kesl-control --set-settings 1 \
  --add-exclusion <NGINX_CACHE_MOUNTPOINT>
kesl-control --get-settings 1
```

Не исключать:

- весь `/var/lib/docker`, `/var/lib/docker/overlay2` или все volumes;
- `/opt/han-chat/releases` и `/opt/han-chat/current`;
- `/var/lib/han-deploy/incoming`;
- `/etc/han`, `/run/han-chat`, `/etc/letsencrypt`;
- `/tmp`, `/var/tmp`, `/root` или весь filesystem.

Обычное исключение из scan может не исключить файловый перехват. Не создавайте
bind mounts и не добавляйте `ExcludedMountPoint` в первой итерации. Это
допустимо только если измерена деградация и Security письменно принял
компенсацию плановой проверкой/container scan.

## 7. Пилот задач проверки

Убедитесь, что все ODS/ContainerScan schedules, кроме Update, пока ручные:

```sh
kesl-control --get-task-list
kesl-control --get-schedule 2
kesl-control --get-schedule 18
kesl-control --set-schedule 2 RuleType=Manual
kesl-control --set-schedule 18 RuleType=Manual
```

Идентификаторы подтвердите через `--get-task-list`; не применяйте команды,
если тип задачи не совпадает.

### 7.1. Ограниченная on-demand проверка host

Сначала проверьте небольшой immutable release, не корень filesystem:

```sh
kesl-control --scan-file /opt/han-chat/current/backend \
  --action Inform
```

В первом пилоте действие `Inform` не изменяет release. Проверьте результат,
events, ресурсы и application health:

```sh
kesl-control -E --query -n 100 --reverse
kesl-control --get-statistic
/usr/local/sbin/han-vm1-compose ps
docker stats --no-stream
```

### 7.2. Проверка контейнеров

Перед scan снимите список running containers. Проверяйте по одному объекту,
начиная с stateless/oneshot image, не Redis и не Keycloak:

```sh
docker ps --format '{{.Names}}\t{{.Image}}'
kesl-control --get-settings 19
kesl-control --scan-container <STATELESS_CONTAINER_OR_IMAGE>
```

После успешного одиночного теста задачу `Container_Scan` (ID 18) можно
назначить еженедельно в согласованное время. Перед этим проверьте параметры:
по умолчанию `ContainerScanAction=StopContainerIfFailed`; production-контейнер
не должен останавливаться из-за технической ошибки сканирования. Итоговое
действие отдельно утверждает Security.

Container scan после deploy выполняется только после завершения smoke, а не
одновременно с pull/start/migrations.

## 8. Ступенчатое включение File Threat Protection — АВЗ.1

`DISABLE_PROTECTION=Yes` отключает компоненты после setup. До старта сохраните
параметры и убедитесь, что `ScanArchived=No`:

```sh
kesl-control --get-settings 1
kesl-control --get-task-state 1
```

Для пилота включите асинхронный режим перехватчика `Notify`, при котором
KESL журналирует обнаружения, но не выполняет блокирующее действие:

```sh
kesl-control --set-app-settings InterceptorProtectionMode=Notify
kesl-control --start-task 1
kesl-control --get-task-state 1
```

Пилот длится минимум 2–4 часа обычной нагрузки. Каждые 15 минут проверяйте
метрики раздела 1 и события KESL. Не считайте этот режим конечной реализацией
АВЗ.1: он не обеспечивает блокирование/лечение.

Если пилот стабилен, в том же maintenance window:

1. проверьте, что `ActionOnThreat=DisinfectDeleteIfNotPossible`;
2. установите `InterceptorProtectionMode=Block`;
3. перезапустите task 1, если этого требует текущая сборка;
4. повторите health, smoke, firewall и resource checks.

```sh
kesl-control --set-settings 1 \
  ActionOnThreat=DisinfectDeleteIfNotPossible ScanArchived=No
kesl-control --set-app-settings InterceptorProtectionMode=Block
kesl-control --stop-task 1
kesl-control --start-task 1
kesl-control --get-task-state 1
kesl-control --app-info
```

В режиме `Block` доступ к файлу ожидает результат проверки. При появлении
latency вернитесь в `Notify` либо остановите task 1 и выполните rollback;
не расширяйте исключения вслепую.

## 9. Приёмочный тест и evidence

Тест EICAR выполняется только с письменным разрешением Security в отдельном
безопасном каталоге, не в release, volume, backup, secret или upload path.
Используйте официальную контрольную строку/файл с сайта EICAR/Kaspersky; этот
репозиторий намеренно не содержит тестовый образец.

До теста:

```sh
install -d -m 0700 -o root -g root /root/kesl-eicar-test
date -Is
kesl-control --app-info
kesl-control --get-task-state 1
```

Ожидается блокирование/лечение/карантин и событие KESL. Не прикладывайте сам
образец к evidence. Сохраните:

```sh
kesl-control --app-info
kesl-control --get-task-list
kesl-control --get-settings 1
kesl-control --get-schedule 6
kesl-control -E --query -n 100 --reverse
```

Очистите тестовый каталог после подтверждения реакции и заполните
`deployment/kesl/EVIDENCE.AVZ.ru.md`.

## 10. Финальные проверки

На ВМ:

```sh
systemctl is-active kesl docker \
  han-secrets@production.service han-stack@production.service
kesl-control --app-info
kesl-control --get-task-state 1
kesl-control --get-task-state 6
/usr/local/sbin/han-vm1-compose ps
iptables -S HAN-CHAT-DOCKER
ufw status verbose
```

С внешнего trusted host повторите production smoke и negative port probes.
Сравните метрики минимум за 24 часа. Не выполняйте reboot только ради KESL.
Если пакет/ядро явно запросили reboot, проведите его отдельным окном по
reboot gate основного production-runbook.

После приёмки удалите package/autoinstall и временные snapshots с ВМ только
после переноса разрешённого evidence:

```sh
rm -rf /root/kesl-install /root/kesl-eicar-test
```

## 11. Rollback

### 11.1. До включения блокирующей защиты

```sh
kesl-control --stop-task 1 2>/dev/null || true
apt-get purge kesl
systemctl daemon-reload
systemctl restart han-chat-docker-firewall.service
/usr/local/sbin/han-vm1-compose ps
iptables -S HAN-CHAT-DOCKER
ufw status verbose
```

Повторите smoke и resource checks. Docker и application stack без причины не
перезапускайте.

### 11.2. При инциденте после включения Block

Сначала минимально обратимое действие:

```sh
kesl-control --set-app-settings InterceptorProtectionMode=Notify
```

Если управление KESL не отвечает:

```sh
systemctl stop kesl
```

Затем восстановите доступность и соберите события. Полный `apt-get purge kesl`
выполняйте только по решению change approver. Reboot — только если он требуется
для удаления/ядра и есть отдельное окно.

Нельзя выполнять `docker compose down -v`, удалять volumes, чистить Redis AOF,
пересоздавать VM или менять firewall ради обхода проблемы KESL.

## 12. Эксплуатационный режим

- Update (ID 6): каждый час; alert при ошибке или устаревании баз.
- File Threat Protection (ID 1): постоянно, `Block`,
  `DisinfectDeleteIfNotPossible`, `ScanArchived=No`.
- ODS: еженедельно в низкую нагрузку после подтверждения resource budget.
- ContainerScan: еженедельно и после deploy, только после smoke.
- Ежедневно: статус лицензии, компонентов, дата баз и ошибки KESL.
- Ежемесячно: review исключений и фактической нагрузки.
- После upgrade KESL/kernel/Docker: повтор пилота, smoke и evidence delta.

Любое новое исключение должно иметь владельца, причину, срок пересмотра,
компенсирующую проверку и подтверждение Security.