Initial commit: forge-tools-proxmox — MCP-сервер для Proxmox VE

2026-10-01 10:41:43 +07:00
commit a7addaead9
30 changed files with 4226 additions and 0 deletions
@@ -0,0 +1,52 @@
+# Безопасность
+
+`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)).