diff --git a/ops/audits/LLM-TOOL-AUDIT-2026-11-17.md b/ops/audits/LLM-TOOL-AUDIT-2026-11-17.md new file mode 100644 index 0000000..d63bcf9 --- /dev/null +++ b/ops/audits/LLM-TOOL-AUDIT-2026-11-17.md @@ -0,0 +1,296 @@ +# LLM-аудит Tool Gateway (предложение, требует проверки) + +> Выполнено OpenClaw (DeepSeek) 17.11.2026 за 51 секунду по каталогу +> `hub-core/services.yaml` (без секретов и без обращений к сервисам). +> Это **предложение**, а не истина: названия сервисов и API нужно проверять. + +## Ревью ведущего агента + +**Что хорошо:** +* принципы (идемпотентность, секреты только на gateway, узкий скоуп, аудит); +* раздел «чего НЕ делать инструментом» — совпадает с нашей политикой; +* ограничения на передачу данных облачной LLM — важный раздел; +* приоритеты P0/P1/P2. + +**С чем не согласен:** +* ~55 инструментов — это не цель, а простыня. Практический предел — 15–20, + иначе поддержка съест выгоду. +* часть сервисов в каталоге может быть неточной (duplicati, loki/dozzle, + beszel, firefly, paperless, memos, netbox) — проверить перед реализацией. +* P0 всё ещё широкий (9 пунктов); начинать надо с 4–5 read-инструментов. + +**Мой P0-набор (предлагаю):** +1. `hub.service_detail` — детали службы. +2. `alerts.active` — активные алерты. +3. `uptime.summary` — сводка Kuma. +4. `backup.status` — наш бэкап-контур (не Duplicati, если его нет). +5. `media.search` / `media.request` — то, что просил чат. +6. `ha.search` + allowlist доменов для `ha.call`. + +--- + +# Каталог инструментов Tool Gateway — аудит (v1) + +Дата: 2026-11-17. Основание: `hub-core/services.yaml` (72 записи), состав +deploy/ctNNN, существующие 10 инструментов. Входные данные — только каталог, +секреты не читались, к сервисам не обращались, изменений не вносилось. + +Общие принципы каталога: + +- **Идемпотентность обязательна** для write: повторный вызов не должен создавать дубль + (idempotency key или проверка по естественному ключу). +- **Секреты живут только на gateway**: инструменты не принимают и не возвращают токены, + только результат. LLM не видит ни токенов, ни полных URL с basic-auth. +- **Скоуп по умолчанию**: чтение узкое (последние N, фильтр по сервису/хосту), + запись — по одному объекту за вызов. +- **Аудит**: каждый write логируется (кто, что, когда, id объекта) в локальный лог, + не в облако. +- **Dry-run**: у всех write-инструментов флаг `dryRun` по умолчанию `true` на старте внедрения. + +Легенда риска: 🟢 низкий (чтение, без секретов) · 🟡 средний (чтение состояния с +inventory/PII или write в «мягкую» сущность) · 🔴 высокий (write в security/identity/ +backup/инфраструктуру) · ⚫ критический (не реализуем как инструмент). + +Приоритеты: **P0** — первая волна, **P1** — вторая, **P2** — по запросу/позже. + +--- + +## 1. Инструменты: наблюдаемость и состояние хаба + +| tool | сервис | назначение | API/аутентификация | R/W | риск | подтверждение | приоритет | +|---|---|---|---|---|---|---|---| +| `hub.status` | hub-core (Proxmox + docker) | сколько сервисов, кто down/restarting, срок uptime | существующий: SSH/API узлов через gateway + `services.yaml` | read | 🟢 | нет | P0 (есть) | +| `hub.service_detail` | hub-core | состояние одного сервиса: контейнеры CT, is_up, последний restart, порты | локальный docker/pct через gateway | read | 🟢 | нет | P0 | +| `uptime.summary` | uptime_kuma (107) | сводка мониторов: up/down, response time, инциденты за 24h | Uptime Kuma API (`/api/status-page/*` или Prometheus exporter), API-key/read-only | read | 🟢 | нет | P0 | +| `prometheus.query` | prometheus (134) | узкие готовые запросы (CPU/RAM/диск узла, restarts, targetup) по фиксированному allowlist | Prometheus HTTP `/api/v1/query`, bearer/token read-only | read | 🟡 (нагрузка/инференс инфраструктуры) | нет, но allowlist промптов | P1 | +| `alerts.active` | alertmanager (134) + buryan-alert-webhook | активные алерты: severity, service, since, silenced | Alertmanager `/api/v2/alerts`, basic-auth/read | read | 🟢 | нет | P0 | +| `logs.recent` | loki (113) / dozzle (110) | последние N строк логов сервиса по фильтру (сервис, уровень, окно ≤15 мин) | Loki `/loki/api/v1/query_range`, read; логи через gateway, не наружу | read | 🟡 (логи могут содержать PII/секреты в тексте) | нет, но redaction обязательна | P1 | +| `backup.status` | duplicati (111) | последний бэкап по job: время, статус, размер, ошибки | Duplicati `/api/v1/backup/{id}` + `/api/v1/serverstate`, token | read | 🟡 | нет | P0 | +| `beszel.system` | beszel (110) | CPU/RAM/диск/сеть по узлам, тренд | Beszel API (pocketbase) `/api/collections/*`, token read | read | 🟢 | нет | P1 | + +## 2. Home Assistant / Zigbee / сеть + +| tool | сервис | назначение | API/аутентификация | R/W | риск | подтверждение | приоритет | +|---|---|---|---|---|---|---|---| +| `ha.states` | homeassistant (106), zigbee2mqtt | состояния сущностей, фильтр по домену/зоне | существующий: HA REST `/api/states`, long-lived token в gateway | read | 🟡 (presence дома = приватность) | нет | P0 (есть) | +| `ha.call` | homeassistant (106) | вызов сервиса: свет, сцены, климат, медиа | существующий: HA REST `/api/services/{domain}/{service}` | write | 🟡→🔴 по домену | **да**: allowlist доменов/сервисов (light/scene/media_player/script); запрет `lock`, `alarm_control_panel`, `cover` без отдельного подтверждения | P0 (есть) | +| `ha.history` | homeassistant (106) | «что было с датчиком за 24h» (темп., влажность, движение — агрегаты) | HA `/api/history/period`, read | read | 🟡 | нет | P2 | +| `zigbee.network` | zigbee2mqtt | недоступные устройства, LQI, батареи | MQTT `zigbee2mqtt/bridge/request/*` (read-only топики) | read | 🟢 | нет | P2 | +| `adguard.stats` / `adguard.pause` | adguard (107) | статистика блокировок; пауза фильтрации на N минут | AdGuard Home API `/control/stats`, `/control/…set_protection`, basic-auth | R/W | 🟡 write | **да** для `pause` (таймер ≤60 мин, авто-возврат) | P1 (stats) / P2 (pause) | +| `mqtt.publish` | mosquitto (107) | публикация в топик | MQTT, per-service креды | write | 🔴 | **да**, allowlist топиков, никаких `homeassistant/…/config` и `zigbee2mqtt/bridge/*` | не рекомендую (см. §4) | + +## 3. Медиа + +| tool | сервис | назначение | API/аутентификация | R/W | риск | подтверждение | приоритет | +|---|---|---|---|---|---|---|---| +| `media.queue` | radarr (118), sonarr (117), lidarr (111) | очередь загрузок: прогресс, ETA, ошибки | существующий: `*arr` `/api/v3/queue`, API-key в gateway | read | 🟢 | нет | P0 (есть) | +| `media.recent` | jellyfin (103) | недавно добавленные фильмы/серии | существующий: Jellyfin `/Items?sortBy=DateCreated`, API-key | read | 🟢 | нет | P0 (есть) | +| `media.wanted` | radarr/sonarr | чего не хватает / missing, с границами | `/api/v3/wanted/missing`, read | read | 🟢 | нет | P1 | +| `media.request` | seerr (121) | заявка на фильм/сериал от имени пользователя | Overseerr/Jellyseerr `/api/v1/request`, API-key; ставит задачу, не качает напрямую | write | 🟢→🟡 (квота диска) | нет для «хочу», **да** при приоритете/4K | P1 | +| `media.search` | prowlarr (119) | поиск по индексаторам / состояние индексаторов | Prowlarr `/api/v1/search`, `/api/v1/indexerstatus` | read | 🟡 (приватность запросов, торренты) | нет | P2 | +| `media.grab` | radarr/sonarr/prowlarr | ручной grab релиза | `/api/v3/release` + POST | write | 🔴 (наружу, трафик, legal) | **да**, только по id из выдачи пользователя | не рекомендую (см. §4) | +| `media.library_stats` | jellyfin, navidrome (125) | размеры библиотек, новые по разделам | API read | read | 🟢 | нет | P2 | +| `media.playback` | jellyfin | кто сейчас смотрит, продолжения | `/Sessions`, read | read | 🟡 PII | нет | P2 | +| `books.status` | audiobookshelf (111), calibre-web (111), kavita (111), book-bot | прогресс/новинки/очередь бота | API read | read | 🟢 | нет | P2 | +| `podcasts.new` | podfetch (103), freshrss (111) | новые выпуски по подпискам | RSS/API read | read | 🟢 | нет | P2 | + +## 4. Календарь, заметки, знания + +| tool | сервис | назначение | API/аутентификация | R/W | риск | подтверждение | приоритет | +|---|---|---|---|---|---|---|---| +| `calendar.list` | внешний календарь / Nextcloud CalDAV | события на N дней | существующий | read | 🟡 | нет | P0 (есть) | +| `calendar.create` | то же | создать событие | существующий, CalDAV `PUT` с UID | write | 🟡 | **да** (показ черновика: время, участники, место) | P0 (есть) | +| `calendar.availability` | CalDAV | свободно/занято без раскрытия деталей | `freebusy` REPORT, read | read | 🟢 | нет | P1 | +| `notes.search` | memos (110) | поиск заметок по тексту | Memos `/api/v1/memos`, token | read | 🟡 (личные мысли) | нет | P1 | +| `notes.add` | memos (110) | добавить заметку/напоминание | Memos POST | write | 🟢 (своя песочница) | нет | P1 | +| `tasks.list` / `tasks.add` | vikunja (110) | задачи по проекту, создать задачу | Vikunja `/api/v1/tasks`, token | R/W | 🟢 write в свою доску | нет (add — только свой проект) | P1 | +| `docs.search` | docmost (103) | поиск по базе знаний | Docmost API search, token | read | 🟡 (внутренние регламенты) | нет | P2 | +| `bookmarks.search` | linkding (127) | поиск закладок/тегов | `/api/bookmarks`, token | read | 🟡 | нет | P2 | +| `files.search` | nextcloud (109) + files_db (109) | поиск файлов по имени в разрешённых папках | Nextcloud OCS `/remote.php/dav` search / WebDAV PROPFIND | read | 🟡 | нет | P2 | +| `print.preview` | stirling-pdf (110) | конвертация/предпросмотр PDF локально | `/api/v1/convert/*`, self-hosted | read (локально) | 🟢 | нет | P2 | + +## 5. Фото + +| tool | сервис | назначение | API/аутентификация | R/W | риск | подтверждение | приоритет | +|---|---|---|---|---|---|---|---| +| `photos.people` | immich (0/immich_database) | люди/лица, количество | существующий: Immich `/api/people`, API-key | read | 🟡 (биометрия!) | нет | P0 (есть) | +| `photos.albums` | immich | альбомы | существующий: `/api/albums` | read | 🟡 | нет | P0 (есть) | +| `photos.search` | immich | поиск по дате/месту/альбому (метаданные) | `/api/search/metadata`, read | read | 🟡 | нет | P1 | +| `photos.upload` | immich | загрузка одного файла | `/api/assets` POST | write | 🟡 | нет | P2 | +| `photos.comment` / `photos.album_edit` | immich | — | — | write | 🔴 (разрушение семейного архива) | — | не рекомендую | + +## 6. Дом/личное (средний риск, P1–P2) + +| tool | сервис | назначение | API/аутентификация | R/W | риск | подтверждение | приоритет | +|---|---|---|---|---|---|---|---| +| `pantry.expiring` | grocy (110) | что просрочено/скоро истекает | Grocy `/api/objects/*`, API-key | read | 🟢 | нет | P1 | +| `pantry.add` | grocy | добавить покупку на склад | POST | write | 🟢 | нет | P2 | +| `meals.plan` | mealie (110) | план питания, рецепт из URL | `/api/recipes`, `/api/mealplan`, token | R/W | 🟢 | нет | P2 | +| `inventory.search` | homebox (110) | поиск вещей/гарантий | `/api/v1/items`, token | read | 🟡 | нет | P2 | +| `contacts.bday` | monica (110) | ближайшие дни рождения/напоминания | Monica `/api/contacts`, token | read | 🟡 (PII) | нет | P2 | +| `finance.summary` | firefly (110) | агрегаты по категориям за месяц | Firefly `/api/v1/summary/*`, token read | read | 🔴 (финансы) | нет для агрегатов; сырые транзакции — нет | P2 | +| `expenses.add` | firefly | добавить расход из чата | POST `/api/v1/transactions` | write | 🔴 | **да** (показ категории/суммы) | не рекомендую в первой версии | + +## 7. Автоматизация и инфраструктура + +| tool | сервис | назначение | API/аутентификация | R/W | риск | подтверждение | приоритет | +|---|---|---|---|---|---|---|---| +| `n8n.workflows` | n8n (108) | список воркфлоу, последние запуски, ошибки | `/api/v1/workflows`, `/api/v1/executions`, API-key read | read | 🟡 (имена/схемы воркфлоу) | нет | P1 | +| `n8n.trigger` | n8n | запуск webhook-воркфлоу из allowlist | Webhook URL, HMAC | write | 🟡 | нет для allowlist; **да** для остальных | P1 | +| `node_red.status` | node_red (108) | состояние флоу, uptime | admin API read | read | 🟢 | нет | P2 | +| `gitea.repo_status` | gitea (140) | открытые PR/issues, состояние CI не через Actions API | `/api/v1/repos/...`, token read | read | 🟡 (структура репозиториев) | нет | P1 | +| `gitea.issues` | gitea | создать issue в allowlist репозиториев | POST `/api/v1/repos/{o}/{r}/issues` | write | 🟡 | нет (только в свой репо), **да** для чужих | P1 | +| `portainer.containers` | portainer (0) | список контейнеров/стеков и статус | `/api/endpoints/*/docker/containers/json`, token | read | 🟡 (карта инфраструктуры) | нет | P2 | +| `portainer.restart` | portainer | рестарт контейнера из allowlist | POST `/containers/{id}/restart` | write | 🔴 | **да**, двойное подтверждение, allowlist недеструктивных сервисов | P2 / по запросу | + +## 8. Оповещения + +| tool | сервис | назначение | API/аутентификация | R/W | риск | подтверждение | приоритет | +|---|---|---|---|---|---|---|---| +| `hub.notify` | hub-core / buryan-alert-webhook | уведомление владельцу в мессенджер | существующий: внутренний API хаба | write (наружу в канал) | 🟡 | нет (это и есть канал) | P0 (есть) | +| `alert.silence` | alertmanager (134) | заглушить алерт на 1–4 ч по метке | `/api/v2/silences` POST | write | 🔴 (можно скрыть реальную аварию) | **да**, max TTL, комментарий обязателен | P2 | + +## 9. Безопасность и identity — только наблюдение + +| tool | сервис | назначение | API/аутентификация | R/W | риск | подтверждение | приоритет | +|---|---|---|---|---|---|---|---| +| `authentik.sessions` | authentik (114) | активные сессии, неудачные логины (счётчики) | Authentik `/api/v3/core/users`, `/api/v3/events/events` read | read | 🔴 (identity) | нет для агрегатов; персональные данные — только владельцу локально | P1 (aggregates) | +| `vaultwarden.health` | vaultwarden (109) | только health/версия/размер БД, **без элементов хранилища** | `/alive`, `/api/…` health | read | 🟡 | нет | P1 | +| `netbox.lookup` | netbox (103) | «какой IP/устройство», поиск по инвентарю | `/api/ipam/`, `/api/dcim/`, token read | read | 🔴 (карта сети) | нет локально; в облако — только конкретная запись | P2 | + +## 10. Есть, но требует пересмотра + +| tool | замечание | +|---|---| +| `ha.call` | нужен allowlist доменов; `lock/alarm/cover/button` — отдельный режим с подтверждением. | +| `calendar.create` | фиксировать attendee allowlist; не давать создавать события в чужих календарях. | +| `hub.status` | добавить staleness-метку (данные старше N минут помечать). | +| `photos.people` | возвращать имена только по запросу, не в общий контекст; это биометрия. | + +--- + +## 1. Сценарии с максимумом пользы при минимуме риска + +1. **Утренний брифинг** — `hub.status` + `alerts.active` + `uptime.summary` + `backup.status` + + `calendar.list` + `media.queue`. Всё read, одна сводка, ноль записи. Самая высокая отдача. +2. **«Что сломалось?»** — `alerts.active` → `hub.service_detail` → `logs.recent` по одному сервису + (redacted, окно ≤15 мин). Диагностика без доступа к прод-консоли. +3. **Медиа-заявки** — `media.request` через seerr: пользователь просит фильм, инструмент создаёт + заявку с квотой; скачивание остаётся за существующей автоматикой radarr/sonarr. +4. **Безопасные бытовые действия** — `ha.call` только `light.*`, `scene.turn_on`, `media_player.*` + (громкость/пауза). Ощутимая польза, откат мгновенный. +5. **Личный органайзер** — `notes.add`/`tasks.add`/`pantry.expiring`/`contacts.bday`: + запись только в собственные «песочницы», чтение для напоминаний. +6. **Бэкап-контроль** — `backup.status` + `alerts.active`: «последний бэкап упал 2 дня назад» — + это тот алерт, который реально спасает. +7. **Календарное планирование** — `calendar.availability` + `calendar.list` → черновик события, + подтверждение человеком, затем `calendar.create`. + +Правило отбора: польза ежедневная, обратимость высокая, радиус поражения — один объект. + +--- + +## 2. Чего НЕ стоит делать инструментом + +- **Перезапуск/остановка критичных сервисов** (authentik, prometheus, gitea, matrix-synapse, + netbox-postgres, homeassistant, mosquitto) — через чат. Только человек у терминала. +- **Управление замками, сигнализацией, воротами/шторами, камерами** (frigate) — физическая + безопасность. Инструмент максимум читает статус. +- **Публикация в MQTT** произвольных топиков, особенно `homeassistant/*/config` и + `zigbee2mqtt/bridge/*` — один publish ломает всю автоматизацию дома. +- **Работа с секретами Vaultwarden** — никаких «покажи пароль», «найди элемент», «поделись». + Только health/метрики. +- **Управление пользователями/токенами Authentik**, сброс MFA, создание API-ключей. +- **Изменение ACL, DNS (adguard), firewall**, сетевых конфигураций — high blast radius. +- **Ручной grab торрентов/релизов** и любые действия, создающие внешний трафик или правовые риски. +- **Финансовые переводы/оплаты** (firefly только чтение агрегатов). +- **Удаление данных**: файлы, фото, заметки, записи БД, restore/rollback бэкапов, prune. +- **Выполнение произвольного shell/кода** на узлах, «универсальный `docker exec`», + произвольный SQL к PostgreSQL/MySQL/Redis. +- **Изменение конфигурации сервисов** (docker-compose, node_red flow deploy, n8n workflow edit, + gitea force-push, docmost удаление страниц). +- **Silence алертов без срока и причины** — только с TTL и обязательным комментарием. +- **Массовые операции** (`all`, `*`, диапазон id) — всегда один объект. + +--- + +## 3. Порядок реализации + +### P0 — «наблюдение + безопасная запись» (2–3 недели) +Цель: закрыть ежедневную пользу без риска. Всё read + 2 узких write. + +1. `hub.service_detail` (расширение уже имеющегося `hub.status`). +2. `alerts.active` — Alertmanager read. +3. `uptime.summary` — Uptime Kuma read. +4. `backup.status` — Duplicati read. **Важно: без restore.** +5. Расширить `media.queue` на lidarr; `media.recent` — фильтр по разделу. +6. `ha.call`: ввести allowlist доменов (light/scene/media_player/script) и подтверждение для + остального. +7. `notes.add` / `tasks.add` (свои песочницы). +8. `pantry.expiring`, `contacts.bday` (напоминания). +9. Единый контракт: `dryRun`, idempotency key, журнал write-вызовов, redaction логов. + +Критерий выхода: ни один P0-write не может изменить security/инфраструктуру; логи без секретов. + +### P1 — «контекст и автоматизация» (3–5 недель) +- `prometheus.query` (allowlist), `logs.recent` (redaction + окна). +- `beszel.system`, `zigbee.network`, `adguard.stats`. +- `media.wanted`, `media.request` (seerr, квота), `media.library_stats`. +- `calendar.availability`, `notes.search`, `tasks.list`, `docs.search`, `bookmarks.search`. +- `n8n.workflows`/`n8n.trigger` (allowlist), `n8n.workflows` read-only статус. +- `gitea.repo_status`, `gitea.issues` (свой репозиторий). +- `authentik.sessions` (только агрегаты), `vaultwarden.health`. +- `photos.search` (метаданные). + +### P2 — «по запросу и с усиленным контролем» +- `portainer.containers` → `portainer.restart` (allowlist, двойное подтверждение). +- `alert.silence` (TTL ≤4 ч, обязательный комментарий). +- `adguard.pause` (автовозврат). +- `finops`/`finance.summary` (только агрегаты, локально). +- `files.search`, `netbox.lookup`, `node_red.status`, `media.playback`, `podcasts.new`, `books.status`. +- `photos.upload`, `meals.plan`, `pantry.add`, `inventory.search`. +- Отдельная песочница для экспериментов; любые новые write — сначала dry-run 2 недели. + +Правило продвижения: инструмент пишется только после того, как его read-версия +использовалась ≥10 раз и ошибок интерпретации не было. + +--- + +## 4. Какие данные нельзя отдавать облачной LLM + +**Никогда (только локальная модель или вообще не в LLM):** +- секреты: токены, API-ключи, пароли, содержимое Vaultwarden, `.env`, приватные ключи SSH; +- содержимое бэкапов, дампы БД, конфиги Authentik/Matrix (ключи шифрования); +- полные логи (могут содержать токены, email, IP-адреса и тела запросов); +- биометрия: Immich `photos.people` — имена/лица/кластеры лиц; кадры с камер frigate; +- точные геолокации (GPS-метаданные фото, история HA `device_tracker`, геозоны); +- финансовые транзакции (firefly), суммы, контрагенты; +- медицинские/юридические документы (paperless, docmost), содержимое личных заметок (memos); +- содержимое чатов (mastrix-synapse, element-web, mautrix-telegram), e-mail; +- инвентарь инфраструктуры целиком (netbox: карта сети, IP, имена узлов) — можно отдельную запись; +- полный каталог сервисов с адресами и портами — только агрегаты вроде «N из M работают»; +- персональные данные из Authentik (список пользователей, логины, MFA-статус). + +**Можно, с минимизацией:** +- агрегированные статусы («12 из 72 сервисов лежат»), имена сервисов, метрики CPU/RAM/диска; +- имена алертов и severity без полного label-набора; +- названия фильмов/серий, задачи, свободные слоты календаря без заголовков встреч; +- погода, публичные URL, версии софта. + +**Правила:** +1. Redaction на стороне gateway: IP → `x.x.x.x`, email → `u***@d`, токены → `[redacted]`, + пути файлов → basename. +2. Минимизация: инструмент отдаёт уже сжатую сводку, не сырой ответ API. +3. Приватные домены (`.lan`, `*.local`) и внутренние IP не уходят наружу вообще. +4. Большие ответы (>8 КБ) режутся на стороне gateway, не «дополняются» моделью. +5. Явный признак в каждом инструменте: `sensitivity: public | internal | private`, gateway + блокирует `private` при выборе облачного провайдера. + +--- + +## Итог + +- Работающих инструментов: 10 → предлагается ~55, из них 20 в P0+P1 с реальной пользой. +- Опасная зона — write в identity, MQTT, restarts, secrets, silence алертов и удаление данных; + эти сценарии оставлены человеку у терминала. +- Ключевая ценность первой волны — **диагностика и сводки**, а не автоматическое управление. diff --git a/ops/automations/registry.yaml b/ops/automations/registry.yaml index 352307c..02049a4 100644 --- a/ops/automations/registry.yaml +++ b/ops/automations/registry.yaml @@ -1,5 +1,5 @@ # Реестр автоматизаций Buryans Hub -# Сгенерировано: 2026-11-17 16:19 (ops/scripts/build_automations_registry.py) +# Сгенерировано: 2026-11-17 16:22 (ops/scripts/build_automations_registry.py) total: 168 by_source: cron.d: 49