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

`forge-tools-proxmox` намеренно устроен так, чтобы AI-ассистент не мог выйти за
рамки, заданные оператором. Если вы нашли способ обойти эти рамки — сообщите,
пожалуйста, команде разработки, не открывая публичный issue.

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

- **Хосты и кластеры.** URL гипервизора объявляет оператор в конфиге; модель его
  не задаёт. Права изолированы **per-host**: `allow_nodes`/`allow_vmids` у каждого
  `hosts[]` свои, поэтому одинаковый `vmid` на разных кластерах даёт разный вердикт.
- **Неоднозначность — отказ.** При `len(hosts) > 1` параметр `host` обязателен для
  всех инструментов (кроме `clusters_list`); глобальный allowlist при мульти-хосте
  запрещён как ошибка конфигурации. Всё это fail-closed.
- **Учётные данные.** Ассистент работает только с alias хоста; `token_id` и
  `token_secret` берутся из конфига (подстановка `${VAR}` или gitignored
  `*.local.json`). Произвольные токены/пароли из модели не используются.
- **Мутации.** Дефолт `read_only: true`; без явных `allow_vmids` мутации
  недостижимы. Деструктивные операции требуют `confirm="true"` и эмитят
  permission-паттерны (`host=<alias> node=<node> vmid=<vmid>`) для внешнего
  движка одобрения. `DenyConfigKey` блокирует правку потенциально опасных ключей
  конфига ВМ (delete/revert/hotplug/spice/…).
- **Инъекции.** Значения `node`/`vmid`/`snapshot`/`storage`/`upid` проходят
  guard-валидацию (`ValidateIdentifier`/`ValidateUPID`) и `url.PathEscape` перед
  попаданием в URL API.
- **Таймауты и объёмы.** Настраиваемые `timeout_sec`, `task_poll_max_sec` и
  `max_output_bytes` ограничивают время и размер ответа.

## Границы модуля

- **Запуск кода внутри гостя не реализуется** — это зона `ssh__run` (remote exec).
- **Восстановление/удаление бэкапов, Ceph/ZFS/SDN/firewall/HA/ACL, node
  reboot/shutdown** — сознательно вне модуля (blast-radius и отдельная семантика;
  см. Roadmap в README).

## Известные ограничения

- **`insecure: true`** отключает проверку TLS-сертификата. Это осознанный
  компромисс только для локального dev-lab; в проде используйте `ca_file`.
- **Главный барьер — на стороне PVE.** Токен заводите с минимальными правами
  (для чтения достаточно `Sys.Audit, VM.Audit, Datastore.Audit`); guard модуля —
  лишь второй слой.

## Гигиена репозитория

- Реальные адреса и токены в репозиторий не коммитятся: только
  `pve.json.example` с подстановками `${VAR}`.
- Бинарник и локальные конфиги исключены через `.gitignore` (`/forge-tools-proxmox`,
  `/pve.json`, `*.local.json`).

Перед публикацией убедитесь, что токены и рабочие конфиги не попали в репозиторий
(см. [`.gitignore`](.gitignore)).