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:
1 parent
3f35fd5b47
commit
72c48ded12
1 file changed
+38
@@ -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].
|
||||
Reference in new issue
Block a user