docs: add F2-3 Remediation API post-mortem and audit report

- Documented architecture, artifacts, and success metrics
- Noted LXC+Docker cgroup locking behavior for future fix (Variant B)
- Formalized the completion of the secure agent control channel
This commit is contained in:
root committed 2026-10-07 20:14:52 +03:00
1 parent 3f35fd5b47
commit 72c48ded12
1 file changed
+38
+38
View File
@@ -0,0 +1,38 @@
# 📋 Отчет по задаче: F2-3 Remediation API & Agent Control
**Статус:** ✅ **DONE**
**Дата завершения:** 2026-10-07
**Ответственный:** Admin-Buryans (Roman)
## 1. Цель задачи
Создать безопасный, контролируемый канал для выполнения административных действий (перезапуск сервисов) через Telegram-бота без предоставления прямого root-доступа агентам.
## 2. Реализованная архитектура
1. **Telegram Bot (`comms-agent`)**: Принимает команду от администратора, проверяет права (`is_admin`), формирует JSON-запрос.
2. **Remediation API (FastAPI на PVE, порт 5000)**:
- Принимает запросы только с валидным `X-API-Key`.
- Строгий `allowlist` действий (пока реализовано только `restart_service`).
- Динамически читает карту сервисов из `services_map.json`.
3. **Proxmox VE (Hyperwisor)**: Выполняет команды `pct` от имени root, возвращая реальный статус операции.
## 3. Ключевые артефакты
| Артефакт | Путь | Описание |
|---|---|---|
| `api.py` | `/opt/remediation-api/api.py` | Ядро API на FastAPI с валидацией и выполнением команд. |
| `services_map.json` | `/opt/remediation-api/services_map.json` | Динамическая карта соответствия "Имя сервиса → ID контейнера". |
| `discover_services.sh` | `/opt/remediation-api/discover_services.sh` | Скрипт автообнаружения сервисов (Service Discovery). |
| `bot.py` | `services/comms/telegram-admin-bot/bot.py` | Обновленный код бота с поддержкой Inline-кнопок и динамических запросов. |
| Runbooks | `services/*/runbook.md` | 29 автоматически сгенерированных runbook'ов для всех сервисов. |
## 4. Метрики успеха
- ✅ Полностью исключен хардкод ID контейнеров в коде бота.
- ✅ Успешная сквозная проверка: Telegram → Bot → API → Proxmox → Выполнение команды.
- ✅ Реализована ролевая модель (только `ADMIN_ID` может нажимать кнопки).
## 5. Известные особенности и ограничения (To-Do для Варианта Б)
- **Нюанс LXC + Docker**: При попытке выполнить `pct stop` или `pct reboot` на контейнерах, внутри которых запущен Docker (например, CT 155 Matrix, CT 118 Radarr), Proxmox может вернуть ошибку `unable to get PID`. Это связано с тем, что демоны Docker/containerd удерживают блокировки cgroups.
- **План решения**: Заменить жесткий `pct stop/start` на мягкий перезапуск через `pct exec <vmid> -- systemctl reboot` или корректную остановку Docker-демона перед остановкой контейнера.
## 6. Следующие шаги
1. **Вариант Б**: Исправление механизма перезапуска для LXC с Docker внутри.
2. **F2-5**: [Уточнить из Master Plan, например: Расширение возможностей агентов / Интеграция с Observability].