# Безопасность

`omnichannel-mcp` даёт ассистенту право управлять платформой, поэтому
безопасность строится в несколько независимых слоёв: конфигурация модуля,
подтверждения, и ограничения на стороне `config_server`.

## Модель угроз

- **Ошибочный или злонамеренный вызов управляющего инструмента** (остановить
  прод, залить чужой конфиг).
- **Утечка секретов** (пароли, токен GitLab) в логи, в контекст модели, в
  репозиторий.
- **Доступ не туда** (SSRF, подмена хоста стенда).
- **Чрезмерные привилегии** (учётная запись только для чтения там, где нужен
  мониторинг).

## Слои защиты

### 1. Учётные данные и секреты

- Пароли и токены — только из `${VAR}` окружения или `config.local.json`
  (в `.gitignore`). В репозитории — лишь шаблон.
- `--check-config` печатает конфиг с маской секретов — можно безопасно проверять
  настройку и выкладывать вывод в тикеты.
- Секреты не логируются: логи идут в stderr с маскированием, токен GitLab в
  выводе не отражается.

### 2. Режим «только чтение»

- `read_only: true` (значение по умолчанию) запрещает все изменяющие инструменты.
- Для наблюдательных агентов поднимайте **отдельный инстанс** с `read_only: true`
  и отдельной read-only учётной записью:

  ```json
  { "servers": [{ "alias": "prod", "base_url": "http://…",
                  "readonly_username": "${OMNI_RO_USER}",
                  "readonly_password": "${OMNI_RO_PASSWORD}" }],
    "read_only": true }
  ```
- Если заданы `readonly_*`-креды, read-инструменты ходят именно под ними —
  это least-privilege на стороне модуля.

### 3. Подтверждения (`confirm`)

Разрушительные операции требуют `confirm="true"`:

- `down`, `restore_compose`, `restore_env_version`, `update_front`,
  `download_release`, `cleanup_old_versions`.

Это второй слой: даже при включённом `read_only=false` ассистент обязан явно
подтвердить опасное действие. Дополнительно настройте политику подтверждений
вашего MCP-клиента (человеческое «да/нет» на управляющие инструменты).

### 4. Изоляция сети (`allow_hosts`)

Если задан `allow_hosts`, `base_url` любого сервера обязан быть на этих хостах —
защита от опечаток и подмены адреса.

### 5. Файловый jail (`front_roots`)

`update_front` принимает только каталоги внутри `front_roots`; при проверке
разрешаются симлинки и отсекаются побеги (`..`, ссылки наружу). Пусто —
загрузка фронта запрещена полностью.

### 6. Ограничение нагрузки

- Таймауты (`timeout_sec`, `upload_timeout_sec`), лимиты вывода
  (`max_output_bytes`) и размера загрузки (`max_upload_bytes`).
- Семафор мутаций (`max_concurrent_mutations`) предотвращает наложение операций.
- GET-запросы повторяются при сетевом сбое; **мутации не повторяются** — действие
  не выполнится дважды.

## Что модуль НЕ делает

- Не работает с агентскими эндпоинтами `config_server`
  (`/api/register`, `/api/tasks/<host>`) — только с пользовательским API.
- Не хранит состояние и не пишет секреты на диск.
- Не выполняет код на хостах: все действия выполняет агент `config_server`.

## Рекомендации оператору

1. Заведите **отдельные учётные записи**: read-only для мониторинга,
   полную — только для деплой-агента.
2. Для мониторинга запускайте инстанс с `read_only: true`.
3. Держите секреты в окружении/`config.local.json`, не в `config.json`.
4. Включите подтверждения управляющих инструментов в MCP-клиенте.
5. Ограничьте сетевой доступ к `config_server` (VPN/private network); наружу
   порт 5005 не публикуйте.
6. Об уязвимостях сообщайте в службу безопасности компании (не публикуйте в
   общих трекерах).