From 72c48ded12720f3017a107959ac639b8b2c6bc11 Mon Sep 17 00:00:00 2001 From: Roman Buryan Date: Wed, 7 Oct 2026 20:14:52 +0300 Subject: [PATCH] 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 --- ops/F2-3-REMEDIATION-API-REPORT.md | 38 ++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 ops/F2-3-REMEDIATION-API-REPORT.md diff --git a/ops/F2-3-REMEDIATION-API-REPORT.md b/ops/F2-3-REMEDIATION-API-REPORT.md new file mode 100644 index 0000000..a24592e --- /dev/null +++ b/ops/F2-3-REMEDIATION-API-REPORT.md @@ -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 -- systemctl reboot` ΠΈΠ»ΠΈ ΠΊΠΎΡ€Ρ€Π΅ΠΊΡ‚Π½ΡƒΡŽ остановку Docker-Π΄Π΅ΠΌΠΎΠ½Π° ΠΏΠ΅Ρ€Π΅Π΄ остановкой ΠΊΠΎΠ½Ρ‚Π΅ΠΉΠ½Π΅Ρ€Π°. + +## 6. Π‘Π»Π΅Π΄ΡƒΡŽΡ‰ΠΈΠ΅ шаги +1. **Π’Π°Ρ€ΠΈΠ°Π½Ρ‚ Π‘**: Π˜ΡΠΏΡ€Π°Π²Π»Π΅Π½ΠΈΠ΅ ΠΌΠ΅Ρ…Π°Π½ΠΈΠ·ΠΌΠ° пСрСзапуска для LXC с Docker Π²Π½ΡƒΡ‚Ρ€ΠΈ. +2. **F2-5**: [Π£Ρ‚ΠΎΡ‡Π½ΠΈΡ‚ΡŒ ΠΈΠ· Master Plan, Π½Π°ΠΏΡ€ΠΈΠΌΠ΅Ρ€: Π Π°ΡΡˆΠΈΡ€Π΅Π½ΠΈΠ΅ возмоТностСй Π°Π³Π΅Π½Ρ‚ΠΎΠ² / Π˜Π½Ρ‚Π΅Π³Ρ€Π°Ρ†ΠΈΡ с Observability].