ochenstarik/server-monitor-manager
1
0
Fork 0
Code Issues Pull requests 6 Projects Releases 17 Packages Wiki Activity Actions

Define standalone Server Monitor Manager roadmap

Browse source 
* Remove unrelated repository references

* Define standalone provisioning and VPN roadmap

---------

Co-authored-by: Ochenstarik <ochenstarik@inbox.ru>
This commit is contained in:
ochenstarik-ui 2026-07-19 12:59:27 +07:00 committed by GitHub
parent 266900115c
commit 95c919ecbe
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
16 changed files with 695 additions and 182 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
README.md
View file

@ -9,7 +9,7 @@ The current alpha combines a packaged WinUI 3 desktop client, an ASP.NET Core co
## What it does ## What it does
- monitors CPU/load, memory, swap, disks, inodes, network activity, uptime, latency, SSH, and WireGuard; - monitors CPU/load, memory, swap, disks, inodes, network activity, uptime, latency, SSH, and WireGuard;
- keeps several server profiles, groups, tags, favorites, alerts, and short local metric history; - keeps several server profiles, local health warnings, and short metric history;
- generates a dedicated Ed25519 SSH key and stores private material only on the Windows device; - generates a dedicated Ed25519 SSH key and stores private material only on the Windows device;
- opens direct SSH terminals without sending a private terminal key to the Hub; - opens direct SSH terminals without sending a private terminal key to the Hub;
- exports support diagnostics with hashed endpoint identities and without hosts, users, keys, certificates, or tokens; - exports support diagnostics with hashed endpoint identities and without hosts, users, keys, certificates, or tokens;
@ -40,7 +40,7 @@ The control plane and data plane are separated:
- **Desktop:** packaged WinUI 3 client with DPAPI-protected operator certificate and SSH identity. - **Desktop:** packaged WinUI 3 client with DPAPI-protected operator certificate and SSH identity.
- **Agent:** self-contained Linux binary for `amd64` and `arm64`; it only creates outbound mTLS sessions. - **Agent:** self-contained Linux binary for `amd64` and `arm64`; it only creates outbound mTLS sessions.
See [architecture](docs/architecture.md), [security model](docs/security-model.md), [roadmap](docs/roadmap.md), and [installer contract](docs/installer-contract.md). See [architecture](docs/architecture.md), [security model](docs/security-model.md), [roadmap](docs/roadmap.md), [Linux bootstrap contract](docs/installer-contract.md), and the [Provisioning and Xray specification](docs/provisioning-vpn-requirements.md).
Operational procedures are documented in [Control backup and recovery](docs/control-backup.md) and the [three-server acceptance test](docs/three-server-acceptance.md). Operational procedures are documented in [Control backup and recovery](docs/control-backup.md) and the [three-server acceptance test](docs/three-server-acceptance.md).
@ -55,39 +55,11 @@ tests/ Control-plane tests
docs/ Architecture, security, roadmap, translations docs/ Architecture, security, roadmap, translations
``` ```
The Linux installer is maintained in [`ochenstarik-ui/lightweight-server`](https://github.com/ochenstarik-ui/lightweight-server) as `ochenstarik-server-monitor-manager.sh`. Release binaries are attached to [Server Monitor Manager releases](https://github.com/ochenstarik-ui/server-monitor-manager/releases). Self-contained Control and Agent binaries are published with [Server Monitor Manager releases](https://github.com/ochenstarik-ui/server-monitor-manager/releases). The project-owned Linux bootstrap is specified but is not yet included in the current alpha release. Until it is implemented, checksummed, and tested, the project does not publish a one-command Hub/Node installation instruction.
## Quick start: Hub and two Nodes The planned bootstrap, helper, schemas, and compatibility manifest will be maintained and released only from this repository. See the [Linux bootstrap contract](docs/installer-contract.md). Do not use an installer from another project as a Server Monitor Manager component.
Use a fresh Debian or Ubuntu server with a public IP as the Hub. Download and inspect the installer before running it: The `SMMDEV1` flow enrolls the Windows application: the app creates its operator key locally, confirms the Hub CA fingerprint, obtains a separate certificate, and protects it with Windows DPAPI.
```bash
curl -fLO https://raw.githubusercontent.com/ochenstarik-ui/lightweight-server/main/ochenstarik-server-monitor-manager.sh
chmod 700 ochenstarik-server-monitor-manager.sh
bash -n ochenstarik-server-monitor-manager.sh
sudo ./ochenstarik-server-monitor-manager.sh hub
```
Open the selected WireGuard UDP port (default `51820`) and Control Hub TCP port `7443`. Create enrollment codes on the Hub:
```bash
sudo ochenstarik-smm node-code home
sudo ochenstarik-smm node-code ai-agent
```
On each secondary server, use the same installer and select the Node role. Paste the code for that Node. The private WireGuard key is created locally and never leaves the Node. Then install the persistent control layer:
```bash
# Hub
sudo ./ochenstarik-server-monitor-manager.sh install-control-hub
sudo ./ochenstarik-server-monitor-manager.sh control-code home
sudo ./ochenstarik-server-monitor-manager.sh control-device-code windows-pc
# Node: paste the corresponding SMMCTL1 code when prompted
sudo ./ochenstarik-server-monitor-manager.sh install-control-agent
```
The installer selects the `amd64` or `arm64` archive and verifies its SHA-256 checksum. The `SMMDEV1` code enrolls the Windows application: the app creates its operator key locally, confirms the Hub CA fingerprint, obtains a separate certificate, and protects it with Windows DPAPI.
An Operator can issue a ten-minute Automation enrollment token for exactly one source Node through `POST /api/v1/control/automations/token` or the local `automation-token-create AUTOMATION_ID SOURCE_NODE_ID` command. The automation process creates its private key and CSR locally, enrolls through `/api/v1/automation-enroll`, and can then read only `/api/v1/automation/links`. Link mutations remain Operator-only. An Operator can issue a ten-minute Automation enrollment token for exactly one source Node through `POST /api/v1/control/automations/token` or the local `automation-token-create AUTOMATION_ID SOURCE_NODE_ID` command. The automation process creates its private key and CSR locally, enrolls through `/api/v1/automation-enroll`, and can then read only `/api/v1/automation/links`. Link mutations remain Operator-only.
@ -124,11 +96,11 @@ In the application, generate or copy the monitoring SSH key, add the Hub profile
## Current status ## Current status
`v0.1.0-alpha.5` is an early testing release, not a production security appliance. Windows and Linux builds, control-plane tests, Bash syntax checks, signed x64 MSIX packaging, self-contained `linux-x64`/`linux-arm64` artifacts, and SHA-256 checksums are automated in GitHub Actions. `v0.1.0-alpha.5` is an early testing release, not a production security appliance. Windows and Linux builds, control-plane tests, a test-signed x64 MSIX, self-contained `linux-x64`/`linux-arm64` artifacts, and SHA-256 checksums are automated in GitHub Actions.
The current development branch implements dedicated Windows pages for Servers, Links, Sessions, and Settings; SSH monitoring; the Hub/Node WireGuard installer; directional Links; one-time enrollment; separate mTLS Agent, Operator, and source-scoped Automation identities; certificate revocation/re-enrollment; SQLite control state; audit; authenticated event streaming; Windows Control API integration; and a bounded durable Agent buffer with downsampling. The current development branch implements dedicated Windows pages for Servers, Links, Sessions, and Settings; SSH monitoring; directional Links; one-time enrollment; separate mTLS Agent, Operator, and source-scoped Automation identities; certificate revocation/re-enrollment; SQLite control state; audit; authenticated event streaming; Windows Control API integration; and a bounded durable Agent buffer with downsampling.
Reconnect reconciliation is implemented with a durable SQLite marker: after a Node returns, the Hub reapplies the latest effective disabled policies and clears the marker only after the firewall confirms success. Control also expires TTL Links through the firewall helper, prunes bounded operational data, versions its SQLite schema, and creates verified backups of SQLite state and the Control CA. Linux CI exercises the real Control-to-helper process boundary, repeated installation and a systemd reboot, a real WireGuard data path with directional nftables policies, HTTP authorization boundaries, and a 100-Node concurrent heartbeat and replay scenario. The Windows release pipeline produces a signed MSIX and publishes its SHA-256 checksum. Still planned: trusted public code signing and desktop/mobile clients for additional platforms. Reconnect reconciliation is implemented with a durable SQLite marker: after a Node returns, the Hub reapplies the latest effective disabled policies and clears the marker only after the firewall confirms success. Control also expires TTL Links through the firewall helper, prunes bounded operational data, versions its SQLite schema, and creates verified backups of SQLite state and the Control CA. CI exercises the Control-to-helper process boundary, HTTP authorization, Agent parsing, Desktop contracts, and a 100-Node concurrent heartbeat/replay scenario. Still required are the project-owned bootstrap, physical WireGuard/nftables/reboot acceptance, trusted public code signing, Provisioning/Xray, and clients for additional platforms.
## License and project policy ## License and project policy

2
docs/i18n/README.ar.md
View file

@ -20,7 +20,7 @@ Server Monitor Manager هو تطبيق خفيف يبدأ بمنصة Windows لم
يتصل عميل Windows عبر mTLS/HTTPS بـ Control Hub مبني على ASP.NET Core 10 وSQLite. ينشئ Linux Agent جلسات صادرة فقط. ينقل WireGuard البيانات وتمنع nftables العبور افتراضياً. الرابط أحادي الاتجاه، ولا يحتاج الخادم المنزلي خلف NAT إلى IP عام. يتصل عميل Windows عبر mTLS/HTTPS بـ Control Hub مبني على ASP.NET Core 10 وSQLite. ينشئ Linux Agent جلسات صادرة فقط. ينقل WireGuard البيانات وتمنع nftables العبور افتراضياً. الرابط أحادي الاتجاه، ولا يحتاج الخادم المنزلي خلف NAT إلى IP عام.
```bash ```bash
curl -fLO https://raw.githubusercontent.com/ochenstarik-ui/lightweight-server/main/ochenstarik-server-monitor-manager.sh # نزّل ochenstarik-server-monitor-manager.sh أولاً من ملفات الإصدار.
chmod 700 ochenstarik-server-monitor-manager.sh chmod 700 ochenstarik-server-monitor-manager.sh
bash -n ochenstarik-server-monitor-manager.sh bash -n ochenstarik-server-monitor-manager.sh
sudo ./ochenstarik-server-monitor-manager.sh hub sudo ./ochenstarik-server-monitor-manager.sh hub

2
docs/i18n/README.de.md
View file

@ -20,7 +20,7 @@ Server Monitor Manager ist eine schlanke, zunächst für Windows entwickelte Anw
Der Windows-Client kommuniziert per mTLS/HTTPS mit einem ASP.NET Core 10 Control Hub und SQLite. Der Linux Agent baut nur ausgehende Sitzungen auf. WireGuard transportiert Daten, nftables sperrt Transit standardmäßig. Ein Link öffnet keine Gegenrichtung; ein Server hinter NAT benötigt keine öffentliche IP. Der Windows-Client kommuniziert per mTLS/HTTPS mit einem ASP.NET Core 10 Control Hub und SQLite. Der Linux Agent baut nur ausgehende Sitzungen auf. WireGuard transportiert Daten, nftables sperrt Transit standardmäßig. Ein Link öffnet keine Gegenrichtung; ein Server hinter NAT benötigt keine öffentliche IP.
```bash ```bash
curl -fLO https://raw.githubusercontent.com/ochenstarik-ui/lightweight-server/main/ochenstarik-server-monitor-manager.sh # Laden Sie ochenstarik-server-monitor-manager.sh zuerst aus den Release-Dateien herunter.
chmod 700 ochenstarik-server-monitor-manager.sh chmod 700 ochenstarik-server-monitor-manager.sh
bash -n ochenstarik-server-monitor-manager.sh bash -n ochenstarik-server-monitor-manager.sh
sudo ./ochenstarik-server-monitor-manager.sh hub sudo ./ochenstarik-server-monitor-manager.sh hub

2
docs/i18n/README.es.md
View file

@ -22,7 +22,7 @@ El cliente Windows usa mTLS/HTTPS con un Control Hub ASP.NET Core 10 y SQLite. E
## Instalación rápida ## Instalación rápida
```bash ```bash
curl -fLO https://raw.githubusercontent.com/ochenstarik-ui/lightweight-server/main/ochenstarik-server-monitor-manager.sh # Descargue primero ochenstarik-server-monitor-manager.sh desde los archivos de la versión.
chmod 700 ochenstarik-server-monitor-manager.sh chmod 700 ochenstarik-server-monitor-manager.sh
bash -n ochenstarik-server-monitor-manager.sh bash -n ochenstarik-server-monitor-manager.sh
sudo ./ochenstarik-server-monitor-manager.sh hub sudo ./ochenstarik-server-monitor-manager.sh hub

2
docs/i18n/README.fr.md
View file

@ -20,7 +20,7 @@ Server Monitor Manager est une application légère, d'abord conçue pour Window
Le client Windows communique en mTLS/HTTPS avec un Control Hub ASP.NET Core 10 et SQLite. L'Agent Linux ne crée que des sessions sortantes. WireGuard transporte les données et nftables bloque le transit par défaut. Un Link n'ouvre pas le sens inverse ; un serveur derrière NAT n'a pas besoin d'IP publique. Le client Windows communique en mTLS/HTTPS avec un Control Hub ASP.NET Core 10 et SQLite. L'Agent Linux ne crée que des sessions sortantes. WireGuard transporte les données et nftables bloque le transit par défaut. Un Link n'ouvre pas le sens inverse ; un serveur derrière NAT n'a pas besoin d'IP publique.
```bash ```bash
curl -fLO https://raw.githubusercontent.com/ochenstarik-ui/lightweight-server/main/ochenstarik-server-monitor-manager.sh # Téléchargez d’abord ochenstarik-server-monitor-manager.sh depuis les fichiers de la version.
chmod 700 ochenstarik-server-monitor-manager.sh chmod 700 ochenstarik-server-monitor-manager.sh
bash -n ochenstarik-server-monitor-manager.sh bash -n ochenstarik-server-monitor-manager.sh
sudo ./ochenstarik-server-monitor-manager.sh hub sudo ./ochenstarik-server-monitor-manager.sh hub

2
docs/i18n/README.hi.md
View file

@ -20,7 +20,7 @@ Server Monitor Manager एक हल्का, Windows-first अनुप्र
Windows client mTLS/HTTPS से ASP.NET Core 10 और SQLite Control Hub से जुड़ता है। Linux Agent केवल outbound session बनाता है। WireGuard data ले जाता है और Hub का nftables default रूप से transit रोकता है। Link केवल एक दिशा खोलता है; NAT के पीछे Home server को public IP नहीं चाहिए। Windows client mTLS/HTTPS से ASP.NET Core 10 और SQLite Control Hub से जुड़ता है। Linux Agent केवल outbound session बनाता है। WireGuard data ले जाता है और Hub का nftables default रूप से transit रोकता है। Link केवल एक दिशा खोलता है; NAT के पीछे Home server को public IP नहीं चाहिए।
```bash ```bash
curl -fLO https://raw.githubusercontent.com/ochenstarik-ui/lightweight-server/main/ochenstarik-server-monitor-manager.sh # पहले release files से ochenstarik-server-monitor-manager.sh डाउनलोड करें।
chmod 700 ochenstarik-server-monitor-manager.sh chmod 700 ochenstarik-server-monitor-manager.sh
bash -n ochenstarik-server-monitor-manager.sh bash -n ochenstarik-server-monitor-manager.sh
sudo ./ochenstarik-server-monitor-manager.sh hub sudo ./ochenstarik-server-monitor-manager.sh hub

2
docs/i18n/README.ja.md
View file

@ -20,7 +20,7 @@ Server Monitor Manager は、Linux サーバーの監視、直接 SSH セッシ
Windows クライアントは mTLS/HTTPS で ASP.NET Core 10 + SQLite Control Hub に接続します。Linux Agent は外向きセッションだけを作成します。WireGuard がデータを運び、Hub の nftables は転送を既定で拒否します。Link は一方向で、NAT 内の家庭サーバーに公開 IP は不要です。 Windows クライアントは mTLS/HTTPS で ASP.NET Core 10 + SQLite Control Hub に接続します。Linux Agent は外向きセッションだけを作成します。WireGuard がデータを運び、Hub の nftables は転送を既定で拒否します。Link は一方向で、NAT 内の家庭サーバーに公開 IP は不要です。
```bash ```bash
curl -fLO https://raw.githubusercontent.com/ochenstarik-ui/lightweight-server/main/ochenstarik-server-monitor-manager.sh # 先にリリースファイルから ochenstarik-server-monitor-manager.sh をダウンロードしてください。
chmod 700 ochenstarik-server-monitor-manager.sh chmod 700 ochenstarik-server-monitor-manager.sh
bash -n ochenstarik-server-monitor-manager.sh bash -n ochenstarik-server-monitor-manager.sh
sudo ./ochenstarik-server-monitor-manager.sh hub sudo ./ochenstarik-server-monitor-manager.sh hub

2
docs/i18n/README.ko.md
View file

@ -20,7 +20,7 @@ Server Monitor Manager는 Linux 서버 모니터링, 직접 SSH 세션, 서버
Windows client는 mTLS/HTTPS로 ASP.NET Core 10 및 SQLite Control Hub에 연결합니다. Linux Agent는 outbound session만 만듭니다. WireGuard가 데이터를 전달하고 Hub의 nftables는 기본적으로 transit을 거부합니다. Link는 단방향이며 NAT 뒤의 홈 서버에는 공개 IP가 필요 없습니다. Windows client는 mTLS/HTTPS로 ASP.NET Core 10 및 SQLite Control Hub에 연결합니다. Linux Agent는 outbound session만 만듭니다. WireGuard가 데이터를 전달하고 Hub의 nftables는 기본적으로 transit을 거부합니다. Link는 단방향이며 NAT 뒤의 홈 서버에는 공개 IP가 필요 없습니다.
```bash ```bash
curl -fLO https://raw.githubusercontent.com/ochenstarik-ui/lightweight-server/main/ochenstarik-server-monitor-manager.sh # 먼저 릴리스 파일에서 ochenstarik-server-monitor-manager.sh를 다운로드하세요.
chmod 700 ochenstarik-server-monitor-manager.sh chmod 700 ochenstarik-server-monitor-manager.sh
bash -n ochenstarik-server-monitor-manager.sh bash -n ochenstarik-server-monitor-manager.sh
sudo ./ochenstarik-server-monitor-manager.sh hub sudo ./ochenstarik-server-monitor-manager.sh hub

2
docs/i18n/README.pt-BR.md
View file

@ -20,7 +20,7 @@ Server Monitor Manager é um aplicativo leve, inicialmente para Windows, que mon
O cliente Windows usa mTLS/HTTPS com um Control Hub ASP.NET Core 10 e SQLite. O Linux Agent inicia somente sessões de saída. WireGuard transporta dados e nftables bloqueia trânsito por padrão. Um Link não abre o sentido inverso; um servidor doméstico atrás de NAT não precisa de IP público. O cliente Windows usa mTLS/HTTPS com um Control Hub ASP.NET Core 10 e SQLite. O Linux Agent inicia somente sessões de saída. WireGuard transporta dados e nftables bloqueia trânsito por padrão. Um Link não abre o sentido inverso; um servidor doméstico atrás de NAT não precisa de IP público.
```bash ```bash
curl -fLO https://raw.githubusercontent.com/ochenstarik-ui/lightweight-server/main/ochenstarik-server-monitor-manager.sh # Baixe primeiro ochenstarik-server-monitor-manager.sh nos arquivos da versão.
chmod 700 ochenstarik-server-monitor-manager.sh chmod 700 ochenstarik-server-monitor-manager.sh
bash -n ochenstarik-server-monitor-manager.sh bash -n ochenstarik-server-monitor-manager.sh
sudo ./ochenstarik-server-monitor-manager.sh hub sudo ./ochenstarik-server-monitor-manager.sh hub

4
docs/i18n/README.ru.md
View file

@ -23,10 +23,10 @@ Control plane хранит inventory, метрики, политики, исто
## Быстрая установка ## Быстрая установка
Установщик находится в [`ochenstarik-ui/lightweight-server`](https://github.com/ochenstarik-ui/lightweight-server): Установщик публикуется в [релизах Server Monitor Manager](https://github.com/ochenstarik-ui/server-monitor-manager/releases):
```bash ```bash
curl -fLO https://raw.githubusercontent.com/ochenstarik-ui/lightweight-server/main/ochenstarik-server-monitor-manager.sh # Сначала скачайте ochenstarik-server-monitor-manager.sh из файлов релиза.
chmod 700 ochenstarik-server-monitor-manager.sh chmod 700 ochenstarik-server-monitor-manager.sh
bash -n ochenstarik-server-monitor-manager.sh bash -n ochenstarik-server-monitor-manager.sh
sudo ./ochenstarik-server-monitor-manager.sh hub sudo ./ochenstarik-server-monitor-manager.sh hub

2
docs/i18n/README.tr.md
View file

@ -20,7 +20,7 @@ Server Monitor Manager, Linux sunucularını izleyen, doğrudan SSH oturumları
Windows istemcisi mTLS/HTTPS ile ASP.NET Core 10 ve SQLite Control Hub'a bağlanır. Linux Agent yalnızca dış oturum açar. WireGuard veriyi taşır, Hub üzerindeki nftables varsayılan olarak geçişi engeller. Link tek yönlüdür; NAT arkasındaki ev sunucusunun genel IP'ye ihtiyacı yoktur. Windows istemcisi mTLS/HTTPS ile ASP.NET Core 10 ve SQLite Control Hub'a bağlanır. Linux Agent yalnızca dış oturum açar. WireGuard veriyi taşır, Hub üzerindeki nftables varsayılan olarak geçişi engeller. Link tek yönlüdür; NAT arkasındaki ev sunucusunun genel IP'ye ihtiyacı yoktur.
```bash ```bash
curl -fLO https://raw.githubusercontent.com/ochenstarik-ui/lightweight-server/main/ochenstarik-server-monitor-manager.sh # Önce sürüm dosyalarından ochenstarik-server-monitor-manager.sh dosyasını indirin.
chmod 700 ochenstarik-server-monitor-manager.sh chmod 700 ochenstarik-server-monitor-manager.sh
bash -n ochenstarik-server-monitor-manager.sh bash -n ochenstarik-server-monitor-manager.sh
sudo ./ochenstarik-server-monitor-manager.sh hub sudo ./ochenstarik-server-monitor-manager.sh hub

2
docs/i18n/README.zh-CN.md
View file

@ -22,7 +22,7 @@ Windows 客户端通过 mTLS/HTTPS 连接 ASP.NET Core 10 + SQLite Control Hub
## 快速安装 ## 快速安装
```bash ```bash
curl -fLO https://raw.githubusercontent.com/ochenstarik-ui/lightweight-server/main/ochenstarik-server-monitor-manager.sh # 请先从发布文件中下载 ochenstarik-server-monitor-manager.sh。
chmod 700 ochenstarik-server-monitor-manager.sh chmod 700 ochenstarik-server-monitor-manager.sh
bash -n ochenstarik-server-monitor-manager.sh bash -n ochenstarik-server-monitor-manager.sh
sudo ./ochenstarik-server-monitor-manager.sh hub sudo ./ochenstarik-server-monitor-manager.sh hub

159
docs/installer-contract.md
View file

@ -1,93 +1,110 @@
# Контракт Linux-установщика # Контракт собственного Linux bootstrap
Единственный исходный файл `ochenstarik-server-monitor-manager.sh` хранится в `ochenstarik-ui/lightweight-server`. В репозитории desktop client не должна находиться устаревающая копия. ## 1. Владение и поставка
## Поддерживаемые роли Bootstrap, helper, systemd units, JSON schemas и manifests являются компонентами Server Monitor Manager и хранятся только в этом репозитории. Они публикуются одним совместимым release вместе с Desktop, Control и Agent.
### Monitor only Bootstrap не скачивает и не запускает исходники других проектов. Production-установка использует закреплённый release/tag, проверяет signed compatibility manifest и SHA-256 каждого artifact. Mutable `main` не является источником production-установки.
Режим `install` устанавливает SSH monitoring endpoint без WireGuard: Пока bootstrap не опубликован в release, документация не должна предлагать несуществующую команду его скачивания.
## 2. Поддерживаемые роли
### Monitor
- Ubuntu/Debian с systemd; - Ubuntu/Debian с systemd;
- публичный ключ `ssh-ed25519` из Windows-клиента; - отдельный `ochenstarik-monitor` без пароля;
- отдельный системный пользователь `ochenstarik-monitor` без пароля; - публичный Ed25519 key из Desktop;
- root-owned forced-command; - root-owned forced command;
- сохранение существующего SSH-порта; - сохранение существующего SSH-порта;
- отсутствие нового публичного API. - запрет shell, PTY и forwarding.
### Hub ### Control Hub
Режим `hub` дополнительно: - ASP.NET Core Control service и SQLite;
- локальный Control CA и HTTPS certificate;
- устанавливает WireGuard и nftables; - TCP `7443` по умолчанию;
- запрашивает публичный IPv4/домен и UDP-порт; - WireGuard interface и root-owned nftables policy helper;
- создаёт `smm0` с адресом `10.77.0.1/24`; - systemd units и root-only state directories;
- включает IPv4 forwarding; - транзит только по explicit directional Link.
- устанавливает минимальный root helper и systemd restore unit;
- хранит публичные identities Node и политики Links;
- разрешает транзит только по явной политике.
### Node ### Node
Режим `node`: - локальная генерация Agent и WireGuard private keys;
- CSR-based enrollment по одноразовому коду;
- только исходящие mTLS/WireGuard sessions;
- отсутствие требования публичного IP и входящего порта;
- restricted provisioning helper без общего root shell.
- локально генерирует WireGuard keypair; ## 3. Enrollment
- принимает одноразовый enrollment token;
- отправляет Hub только публичный ключ;
- получает внутренний адрес и аутентифицированное подтверждение конфигурации;
- создаёт только исходящее WireGuard-соединение;
- не требует белого IP или входящего публичного порта.
## Постоянный control layer (alpha) 1. Пользователь скачивает bootstrap и checksum из release Server Monitor Manager.
2. Запускает bootstrap локально через `sudo`.
3. Сверяет fingerprint Control CA.
4. Вводит одноразовый enrollment code.
5. Node локально создаёт key и CSR.
6. Control выдаёт role-scoped certificate.
7. Bootstrap устанавливает совместимые Agent/helper units.
8. Enrollment code атомарно погашается.
После установки существующих ролей отдельные действия добавляют постоянные сервисы: Sudo-пароль не передаётся в Desktop, Control или audit. Приватные Node keys не покидают Node. Приватный Control CA key не включается в enrollment code.
- `install-control-hub` скачивает release-архив под amd64/arm64, проверяет SHA-256, создаёт локальный CA, HTTPS-сертификат Hub, SQLite-каталог и изолированный systemd service; ## 4. Root helper
- `control-code NAME` создаёт десятиминутный token и код `SMMCTL1`, содержащий URL Hub и только публичный CA;
- `control-device-code DEVICE` создаёт отдельный код `SMMDEV1` для operator identity Windows-клиента;
- `install-control-agent` проверяет CA, локально создаёт ключ и CSR, регистрирует сертификат и запускает исходящий mTLS Agent через systemd.
Приватный ключ Control CA не включается в `SMMCTL1`, а приватный ключ Agent не покидает Node. По умолчанию Control Hub слушает TCP `7443`. Helper доступен только через root-owned Unix socket или фиксированный non-interactive privilege wrapper. Он принимает:
Control service не получает общий доступ к root helper. Отдельный root-owned wrapper принимает только проверенные `link-connect` и `link-disconnect`; команды регистрации, удаления Node и произвольные аргументы ему недоступны. - известный action id;
- schema version;
- JSON, соответствующий строгой схеме;
- job id и module hash.
Репозиторий Control проверяет границу запуска helper отдельным Linux integration test: реальный дочерний процесс, обязательный non-interactive privilege wrapper, сохранение `Disabled/Partial` в SQLite и восстановление после пересоздания Control process. Проверка настоящих nftables ruleset и reboot хоста выполняется вместе с исходным установщиком, без его копирования в этот репозиторий. Helper не принимает shell text, произвольные paths, environment или неизвестные поля, способные изменить смысл операции. Username, UID, port, protocol, CIDR, timezone, package id и управляемые пути валидируются повторно.
## Команды жизненного цикла Каждая mutation:
Целевой интерфейс: 1. выполняет preflight;
2. создаёт root-only backup;
3. отклоняет symlink в managed path;
4. проверяет синтаксис новой конфигурации;
5. применяет изменение атомарно;
6. проверяет factual state;
7. при ошибке выполняет rollback.
## 5. Целевой CLI
```text ```text
install-monitor bootstrap enroll
install-hub bootstrap status
install-node bootstrap update
install-control-hub bootstrap rollback BACKUP_ID
install-control-agent bootstrap uninstall ROLE
control-code NAME control device-code DEVICE_ID
control-device-code DEVICE control node-code NODE_ID
status control automation-token AUTOMATION_ID SOURCE_NODE_ID
update emergency status
rollback emergency vpn-disable
uninstall-monitor emergency ssh-restore BACKUP_ID
uninstall-node emergency firewall-restore BACKUP_ID
uninstall-hub
``` ```
Каждая установка и обновление должны быть идемпотентными. Перед изменением рабочей конфигурации создаётся root-only backup. Ошибка проверки или запуска автоматически восстанавливает последнюю рабочую версию. CLI является non-interactive, кроме локального ввода enrollment code и явных подтверждений опасного удаления. Машиночитаемый режим возвращает versioned JSON и стабильные exit codes.
Удаление роли должно убрать только принадлежащие ей файлы, units, интерфейсы и правила. Удаление Hub требует отдельного подтверждения и не должно молча оставлять включённый forwarding или nftables ACL. ## 6. Идемпотентность и обновление
## Forced-command - повторная установка не дублирует users, keys, units, routes или firewall rules;
- несовместимая версия Control/Agent/helper блокирует provisioning job;
- update загружает artifacts только из release этого репозитория;
- checksum проверяется до остановки service;
- бинарники и units заменяются атомарно;
- неуспешный health check восстанавливает предыдущую версию;
- uninstall удаляет только принадлежащие выбранной роли files, users, interfaces и rules;
- удаление Hub требует отдельного подтверждения и не оставляет forwarding/ACL.
Ключ мониторинга допускает только: ## 7. Forced command monitoring
- `metrics`; Monitoring key допускает только versioned metrics snapshot и read-only mesh status. Полный SSH-терминал использует отдельную пользовательскую identity.
- read-only `mesh nodes`, `mesh links`, `mesh status` на Hub;
- строго типизированные изменения Link с проверкой параметров.
Он не должен позволять shell, PTY, agent forwarding, TCP forwarding или произвольную команду. Полный SSH-терминал использует отдельную identity. Минимальный snapshot:
## Минимальный metrics snapshot
```text ```text
PROTOCOL=1 PROTOCOL=1
@ -108,12 +125,18 @@ NETWORK_TX_BYTES=...
KERNEL=... KERNEL=...
``` ```
## Проверки перед применением ## 8. Обязательные проверки
- `bash -n` и ShellCheck; - ShellCheck и `bash -n` для bootstrap scripts;
- проверка SSH-ключа через `ssh-keygen`; - `ssh-keygen` для public keys;
- `sshd -t` перед reload; - `sshd -t` и `sshd -T` до reload;
- `wg-quick strip` и пробный запуск конфигурации; - `wg-quick strip` для WireGuard configuration;
- `nft --check` перед заменой таблицы; - `nft --check` до замены managed rules;
- проверка systemd unit; - проверка systemd units;
- сохранение активной SSH-сессии до подтверждения нового доступа. - проверка active session до миграции SSH;
- checksum, permissions и ownership release artifacts;
- repeated install/update/rollback/uninstall;
- reboot на поддерживаемой VM matrix;
- сохранение management-доступа при helper/VPN failure.
Полные требования к заданиям, настройке ОС, пользователям и Xray приведены в [ТЗ Provisioning и Xray VPN](provisioning-vpn-requirements.md).

424
docs/provisioning-vpn-requirements.md Normal file
View file

@ -0,0 +1,424 @@
# Техническое задание: Provisioning серверов и Xray VPN
## 1. Статус и граница проекта
Этот документ является частью технического задания **Server Monitor Manager**. Все описанные здесь исходники, bootstrap-компоненты, схемы, manifests, helper-модули, тесты и release artifacts принадлежат только репозиторию `ochenstarik-ui/server-monitor-manager`.
Проект не использует исходники, установщики, releases или runtime-компоненты других репозиториев. Совместное версионирование и межрепозиторные зависимости запрещены. Source of truth для каждой поддерживаемой операции находится в этом репозитории и публикуется в одном релизе с совместимыми Control, Agent и Desktop.
## 2. Назначение
Добавить управляемую первоначальную настройку Ubuntu/Debian из Windows-приложения. Пользователь один раз запускает собственный bootstrap Server Monitor Manager на новом сервере, привязывает Node к Control Hub одноразовым кодом, а последующие операции выполняет через типизированные задания с проверкой результата, журналом, аудитом и безопасным откатом.
Функциональность включает:
- первичную проверку совместимости сервера;
- базовую настройку ОС;
- безопасное управление firewall и миграцию SSH-порта;
- управление Unix-пользователями и публичными SSH-ключами;
- установку и обслуживание Xray;
- VPN для всего сервера или одного Unix-пользователя;
- reconciliation фактического и желаемого состояния после reconnect/reboot.
## 3. Цели безопасности
- не передавать произвольные root-команды через Control API;
- не хранить root/sudo-пароли, приватные Node-ключи и открытые VPN subscription URL на Hub;
- выполнять root-операции только через локальный helper с фиксированными action id и JSON Schema;
- не закрывать действующий SSH-доступ до подтверждения нового подключения;
- предварительно проверять опасную конфигурацию и создавать root-only backup;
- обеспечивать idempotency, аудит, verification и rollback каждой mutation;
- не позволять компрометации одного Node запускать задания на другом.
## 4. Не входит в первую версию
- системы без systemd и APT;
- CentOS, Fedora, Alpine, Arch Linux и производные;
- автоматическое изменение cloud firewall/security groups;
- выполнение произвольного Bash или terminal input через Provisioning API;
- хранение root/sudo-пароля в Desktop, Control или Agent;
- VPN для отдельных процессов одного пользователя;
- несколько одновременных VPN-профилей у одного пользователя;
- установка пакетов вне утверждённого versioned manifest;
- удалённый bootstrap с передачей sudo-пароля из Desktop;
- macOS/Linux Desktop и мобильные клиенты в рамках provisioning alpha.
## 5. Поддерживаемые платформы
- Ubuntu Server 22.04 и 24.04;
- последующая Ubuntu LTS только после включения в CI matrix;
- Debian 12 и 13;
- `amd64` и `arm64`;
- systemd, OpenSSH и APT;
- UFW с nftables backend либо root-owned nftables-таблицы проекта.
Preflight определяет ОС, версию, архитектуру, init system, текущий SSH-порт, host key, активный firewall, IPv4/IPv6, права bootstrap-пользователя, APT и совместимость Agent/helper.
## 6. Целевая архитектура
```text
Windows Desktop
|
| mTLS/HTTPS, Operator identity
v
Control Hub + SQLite
|
| desired state, typed jobs, events
v
Outbound Agent session
|
| local Unix socket, action id + strict JSON
v
root-owned provisioning helper
|
+-- base-setup
+-- firewall-apply
+-- ssh-migrate
+-- user-create/update/delete
+-- vpn-install/apply/disable
+-- verify
+-- rollback
```
Control Hub хранит desired state, безопасные метаданные и аудит. Agent получает только задания собственного `node_id`. Helper повторно валидирует payload, использует фиксированный `PATH`, очищенный environment и никогда не принимает shell text или произвольный путь.
Monitoring Agent и Provisioning Agent могут поставляться одним бинарником, но используют разные API scopes, очереди, разрешения и журналы. Monitoring не получает root-доступ автоматически.
## 7. Собственный bootstrap
### 7.1. Поставка
Bootstrap Server Monitor Manager хранится в этом репозитории и прикладывается к release вместе с:
- SHA-256 checksum;
- подписанным version manifest;
- версиями совместимых Desktop, Control, Agent и helper;
- JSON schemas поддерживаемых действий;
- self-contained binaries для `linux-x64` и `linux-arm64`.
Production-установка использует только закреплённый tag/release, а не mutable `main`. Checksum и manifest проверяются до запуска. Обновление выполняется атомарно с root-only backup.
### 7.2. Регистрация
1. Пользователь скачивает bootstrap из release Server Monitor Manager.
2. Проверяет checksum и запускает его один раз через локальный `sudo`.
3. Bootstrap показывает fingerprint Control CA и запрашивает одноразовый enrollment-код.
4. На Node локально создаются приватный ключ и CSR.
5. После регистрации устанавливаются Agent, ограниченный helper и systemd units.
6. Enrollment закрывается после успешной регистрации.
7. Приватный Node key никогда не покидает сервер.
Sudo-пароль вводится только в локальном терминале сервера. Удалённый ввод пароля из Desktop не входит в первую версию.
## 8. ProvisioningJob
### 8.1. Состояния
```text
Queued -> Preflight -> AwaitingConfirmation -> Running -> Verifying -> Completed
| | |
+-> Cancelled +-> Failed +-> NeedsReconciliation
|
+-> RollingBack -> RolledBack
-> RollbackFailed
```
После потери связи результат не считается автоматически успешным или неуспешным. Состояние `NeedsReconciliation` требует сверки системы после reconnect.
### 8.2. Поля
- `job_id`, `node_id`, action type и schema version;
- обязательный `idempotency_key`;
- hash нормализованного запроса;
- версия и SHA-256 helper module;
- инициатор, audit reason и timestamps;
- безопасные параметры без секретов;
- текущий шаг, процент и длительность;
- структурированные redacted events;
- preflight и confirmation records;
- backup/rollback identifier;
- desired state и verification result;
- безопасный error code;
- TTL задания.
Повтор с тем же idempotency key и телом возвращает исходное задание. Повтор с другим телом отклоняется. На одном Node одновременно выполняется только одно несовместимое опасное задание.
После перезапуска Agent сначала проверяет фактическое состояние и только затем продолжает шаг либо выполняет rollback. Отзыв или повторная регистрация Node инвалидирует незавершённые опасные задания.
## 9. Базовая настройка
Desktop-мастер предоставляет:
- timezone;
- locale для новых сессий;
- `apt update` и опциональный `apt upgrade`;
- versioned package groups с раскрываемым точным списком;
- swap: выключен, автоматически рассчитан или задан явно;
- `vm.swappiness`;
- unattended upgrades;
- предварительный план;
- отдельное подтверждение перезагрузки.
Требования:
- операции идемпотентны;
- неизвестные package id отклоняются;
- APT lock отображается как ожидание;
- перед изменением locale, fstab, sysctl и APT создаётся root-only backup;
- существующий swap не заменяется без отдельного подтверждения;
- symlink в управляемом пути отклоняется;
- APT output проходит secret redaction;
- после выполнения проверяются timezone, locale, swap, packages и reboot requirement.
## 10. Firewall и безопасная миграция SSH
Пользователь задаёт IPv4/IPv6 policy, новый SSH-порт, правила port/protocol, необязательный source CIDR, описание и судьбу ранее управляемых правил. Никакие прикладные порты не открываются автоматически. UI отдельно предупреждает, что локальный firewall не изменяет cloud firewall провайдера.
Миграция SSH выполняется двухфазно:
1. Определить текущую сессию, effective port и host key.
2. Проверить диапазон и отсутствие конфликта через `ss -lnt`.
3. Открыть новый TCP-порт в managed firewall rules.
4. Создать отдельный managed `sshd_config.d` drop-in.
5. Выполнить `sshd -t` и проверить `sshd -T`.
6. Выполнить reload, но не stop SSH.
7. Desktop открывает второе тестовое соединение.
8. Проверяются host key, authentication и безопасная probe-команда.
9. При успехе Desktop обновляет профиль на новый порт.
10. Отдельным подтверждением пользователь закрывает порт 22.
11. Desktop повторно проверяет новый доступ и отсутствие публичного порта 22.
До успешного шага 8 запрещено удалять старое правило. При ошибке новый drop-in и firewall rule откатываются, активная SSH-сессия сохраняется.
## 11. Управление пользователями
Страница **Пользователи** поддерживает:
- список обычных и административных аккаунтов;
- отдельный фильтр системных аккаунтов;
- создание валидированного login и home;
- добавление/удаление SSH public key и показ fingerprint;
- password authentication policy;
- назначение/отзыв sudo;
- отдельное опасное подтверждение passwordless sudo;
- блокировку/разблокировку;
- активные процессы и systemd user services;
- завершение сессий перед удалением;
- удаление с сохранением либо удалением home;
- назначение одного VPN-профиля.
Новый пользователь по умолчанию не получает sudo. Приватные SSH-ключи не загружаются на Hub. Helper проверяет owner/group и режимы `0700/0600`.
Запрещено удалять `root`, пользователей Control/Agent/monitoring и текущего bootstrap-администратора, пока административный доступ не передан другому аккаунту.
## 12. Xray VPN
### 12.1. Профиль и секреты
VPN-профиль содержит название, источник HTTPS subscription или одну VLESS-ссылку, endpoint, DNS mode, IPv6 policy, kill switch, исключаемые CIDR, время проверки, внешний IP до/после и состояния Xray/routing.
Subscription URL является секретом. Desktop шифрует его на публичный encryption key конкретного Node. Control хранит ciphertext и минимальные маскированные metadata, но не может расшифровать URL. Node decrypt key не покидает Node. Диагностика и аудит показывают только scheme, host и masked path.
### 12.2. VPN для сервера
- весь исходящий трафик направляется через Xray;
- исключаются loopback, private/link-local, Mesh WireGuard, Control Hub, SSH/control traffic и VPN endpoint;
- конфигурация Xray проверяется до переключения маршрутов;
- запускается automatic rollback timer;
- verification проверяет внешний IP, TCP, UDP, DNS и IPv6 policy;
- при ошибке маршруты автоматически снимаются;
- kill switch блокирует прямой публичный выход, сохраняя management exceptions;
- профиль можно включать, отключать, проверять и обновлять без переустановки Xray.
### 12.3. VPN для Unix-пользователя
```text
process UID -> nftables meta skuid/cgroup -> fwmark -> policy route -> Xray TPROXY
```
- назначение хранится по UID с проверкой username;
- одному пользователю назначается не более одного активного профиля;
- root и служебные пользователи требуют отдельного опасного подтверждения;
- Xray и management traffic исключаются из перехвата;
- поддерживаются TCP, UDP и DNS;
- прямой IPv6 блокируется, если профиль не обеспечивает защищённый IPv6;
- kill switch блокирует пользователя при неактивном Xray/routing unit;
- остальные пользователи и службы сохраняют обычный маршрут;
- смена UID или удаление пользователя отключает assignment и создаёт audit warning;
- probes запускаются именно от назначенного UID.
## 13. Desktop UI
В карточке сервера добавляются разделы:
- **Подготовка** — bootstrap, capabilities и этапы;
- **Базовая настройка** — locale, timezone, packages и swap;
- **Firewall и SSH** — rules, migration и probes;
- **Пользователи** — accounts, keys, sudo и VPN assignment;
- **VPN** — profiles, modes, external IP и diagnostics;
- **Задания** — progress, logs, retry и rollback;
- **Конфигурация** — desired/factual state и drift.
Статус определяется probes, а не локальными галочками:
```text
Подключён -> Базово настроен -> Firewall применён -> Новый SSH проверен
-> Администратор создан -> Agent активен -> VPN проверен
```
Закрытие текущего SSH-порта, удаление администратора, системный VPN и kill switch требуют отдельных подтверждений и не объединяются в одну mutation.
## 14. API
Минимальные Operator endpoints:
```text
GET /api/v1/nodes/{nodeId}/capabilities
GET /api/v1/nodes/{nodeId}/configuration
POST /api/v1/nodes/{nodeId}/provisioning/preflight
POST /api/v1/nodes/{nodeId}/provisioning/jobs
GET /api/v1/provisioning/jobs/{jobId}
POST /api/v1/provisioning/jobs/{jobId}/confirm
POST /api/v1/provisioning/jobs/{jobId}/cancel
POST /api/v1/provisioning/jobs/{jobId}/rollback
GET /api/v1/provisioning/jobs/{jobId}/events
GET /api/v1/nodes/{nodeId}/users
GET /api/v1/nodes/{nodeId}/vpn-profiles
```
Agent получает только задания своего Node. Automation identity не создаёт provisioning jobs, не читает VPN secrets и не управляет пользователями. Mutation требует Operator certificate, idempotency key и audit reason.
Каждый action type имеет отдельную versioned JSON Schema. Неизвестные смысловые поля отклоняются на Control, Agent и helper.
## 15. Хранение и аудит
Control SQLite хранит job metadata, безопасные параметры, состояния, errors, desired/factual snapshots, user metadata без password hashes, encrypted VPN profiles, assignments, confirmations и audit records.
Не хранятся sudo/root-пароли, приватные Node keys, plaintext subscription URL, `/etc/shadow` и terminal input.
Аудит содержит инициатора, Node, action, before/after, idempotency key, reason, module hash, verification и rollback result. Срок хранения журналов и событий ограничивается настройками retention.
## 16. Наблюдаемость и восстановление
UI показывает текущий шаг и длительность, APT lock, ожидание confirmation/reconnect, последние redacted stdout/stderr, error code, состояние старого SSH-доступа, rollback result, внешний IP, leak-test и configuration drift.
На каждом Node устанавливается локальная аварийная команда, работающая без Control Hub и способная:
- отключить managed VPN и kill switch;
- восстановить последний рабочий SSH drop-in;
- восстановить только принадлежащие проекту firewall rules;
- показать последние backup identifiers и verification results.
Аварийная команда не предоставляет удалённый root shell.
## 17. Тестирование
### Unit
- validation всех action schemas;
- idempotency и конфликт request body;
- state machine и TTL;
- secret redaction;
- package allowlist;
- username/UID, port, protocol, CIDR и timezone validation;
- role isolation;
- блокировка параллельных опасных заданий.
### Integration
- Control -> Agent -> helper boundary;
- рестарт Control/Agent в каждом состоянии;
- token expiration и certificate revocation;
- повторная доставка action;
- helper failure, rollback и rollback failure;
- неверный module checksum;
- Node-specific encryption и невозможность decrypt на Hub;
- reconciliation после reconnect.
### VM end-to-end
Матрица включает Ubuntu/Debian, `amd64` и минимум один `arm64` образ:
- чистый bootstrap, повторная установка и update;
- timezone, locale, packages и swap;
- SSH migration с активной старой сессией;
- неуспешный новый порт с сохранением порта 22;
- успешный новый порт и отдельное закрытие 22;
- reboot после каждого опасного этапа;
- user lifecycle, SSH login и sudo policy;
- system VPN, rollback и kill switch;
- два пользователя: VPN и direct;
- TCP, UDP, DNS и IPv6 leak tests;
- сохранение management-доступа при недоступном VPN endpoint.
## 18. Критерии приёмки
Функция готова, если:
1. Чистый поддерживаемый сервер регистрируется одним bootstrap-кодом без передачи приватных ключей.
2. Повторная базовая настройка не повреждает систему.
3. Порт 22 невозможно закрыть до успешного второго SSH-подключения.
4. Ошибка SSH/firewall сохраняет доступ либо завершает rollback.
5. Новый пользователь создаётся без sudo, permissions SSH проходят проверку.
6. System VPN меняет внешний IP и откатывается при ошибке probes.
7. Трафик назначенного UID идёт через VPN, контрольный UID — напрямую.
8. Kill switch не допускает прямой выход после остановки Xray.
9. TCP, UDP, DNS и IPv6 probes соответствуют выбранной policy.
10. Пароли, plaintext subscription URL и private keys отсутствуют в SQLite, logs и diagnostics.
11. Все опасные операции имеют audit, idempotency, verification и rollback result.
12. После reboot factual state соответствует последнему подтверждённому desired state.
13. Bootstrap, helper, schemas и manifest получены только из release этого репозитория.
## 19. Этапы реализации
### A — собственный bootstrap и release contract
- bootstrap в этом репозитории;
- pinned release manifest, checksums и compatibility matrix;
- non-interactive helper actions и JSON schemas;
- install/update/rollback/uninstall;
- CI для Ubuntu/Debian и supported architectures.
### B — Provisioning control plane
- models и SQLite migrations;
- API, state machine, confirmations и events;
- Agent job channel и reconciliation;
- restricted Unix-socket helper;
- retention и diagnostics.
### C — базовая настройка и пользователи
- Desktop wizard;
- base setup;
- user lifecycle;
- logs, retry, verification и rollback.
### D — firewall и SSH
- firewall editor;
- two-phase SSH migration;
- Desktop connectivity probe;
- отдельное закрытие старого порта.
### E — системный Xray VPN
- Node-encrypted profiles;
- Xray lifecycle;
- routing exclusions, rollback timer и leak tests;
- management emergency recovery.
### F — VPN для пользователя
- UID/cgroup routing;
- TCP/UDP/DNS/IPv6 policy;
- per-user kill switch;
- assignment UI и reconciliation.
### G — hardening и alpha release
- полная VM matrix;
- update/rollback/reboot tests;
- threat-model review;
- локализация UI и документации;
- физическая приёмка на тестовых серверах.

208
docs/roadmap.md
View file

@ -1,92 +1,168 @@
# План разработки # План разработки
## Этап 0 — репозиторий и контракт Подробные требования к собственному bootstrap, управляемой настройке Linux и Xray находятся в [ТЗ Provisioning и Xray VPN](provisioning-vpn-requirements.md). Все компоненты Server Monitor Manager разрабатываются, версионируются и выпускаются только в этом репозитории.
## Этап 0 — граница и базовая архитектура
- [x] переименовать проект в Server Monitor Manager; - [x] переименовать проект в Server Monitor Manager;
- [x] зафиксировать самостоятельность репозитория и отсутствие межрепозиторных runtime-зависимостей;
- [x] выбрать звёздную архитектуру Hub/Node для первого Mesh; - [x] выбрать звёздную архитектуру Hub/Node для первого Mesh;
- [x] разделить monitoring identity, terminal identity и AI-agent identity; - [x] разделить monitoring, terminal, Agent, Operator и AI-automation identities;
- [x] описать направленные Links и kill switch; - [x] описать направленные Links и kill switch;
- [x] выбрать лицензию; - [x] выбрать Apache License 2.0;
- [x] добавить CI, форматирование, тесты и release checksum; - [x] добавить CI, форматирование, тесты и release checksums.
- [ ] объединить PR приложения и установщика в `main`.
## Этап 1 — Windows SSH MVP ## Этап 1 — Windows SSH MVP
- [x] создать packaged WinUI 3 приложение; - [x] создать packaged WinUI 3 приложение;
- [x] добавить адаптивный Overview и профили нескольких серверов; - [x] добавить адаптивный Overview и профили нескольких серверов;
- [x] генерировать отдельный Ed25519 SSH-ключ; - [x] генерировать отдельный Ed25519 monitoring SSH key;
- [x] защищать monitoring key и Operator certificate через DPAPI;
- [x] сохранять профили локально без паролей; - [x] сохранять профили локально без паролей;
- [x] получать CPU/load, RAM, disk, uptime и latency; - [x] получать CPU/load, RAM, disk, uptime и latency;
- [x] собрать и реально запустить x64-приложение; - [x] редактировать и удалять серверы;
- [x] редактирование и удаление серверов; - [x] поддерживать единственный изменяемый Mesh Hub;
- [x] единственный изменяемый Hub; - [x] добавить страницы Servers, Links, Sessions и Settings;
- [x] настоящие страницы Servers, Links, Sessions и Settings. - [x] собирать и запускать x64-приложение;
- [ ] добавить группы, теги и избранные серверы;
- [ ] добавить настраиваемые alert rules и журнал уведомлений;
- [ ] добавить управляемую отдельную terminal key identity вместо зависимости только от обычных пользовательских SSH-ключей.
## Этап 2 — установщик Hub/Node ## Этап 2 — постоянный Control и Agent
- [x] SSH forced-command для Ubuntu/Debian; - [x] ASP.NET Core Control Hub и SQLite;
- [x] роли `hub` и `node`; - [x] self-contained Agent/Control binaries для `linux-x64` и `linux-arm64`;
- [x] WireGuard Hub и исходящие Node-соединения; - [x] исходящие mTLS Agent sessions;
- [x] постоянный nftables ACL на Hub; - [x] одноразовые enrollment tokens не более чем на 10 минут;
- [x] список узлов и handshake-состояние; - [x] локальная генерация Agent private key и CSR;
- [x] явные зависимости `sudo`, `visudo` и `ping` для минимального Debian; - [x] отдельные Agent, Operator и source-scoped Automation certificates;
- [x] безопасные `update` и `rollback` с root-only backup; - [x] отзыв и повторная регистрация Node/Operator;
- [x] полный `uninstall-monitor`, `uninstall-node` и `uninstall-hub`; - [x] подтверждение SHA-256 fingerprint Control CA;
- [x] интеграционный тест повторной установки и reboot. - [x] защищённый event stream для Desktop;
- [x] ограниченный offline buffer Agent и downsampling;
- [x] idempotency и replay protection;
- [x] SQLite schema version, retention и backup/restore Control DB + CA;
- [ ] добавить Desktop UI управления Automation identities и токенами.
## Этап 3 — безопасная регистрация ## Этап 3 — управляемые Links
- [x] локальная генерация WireGuard-ключа на Node; - [x] направленные пары source -> destination;
- [x] одноразовый enrollment token; - [x] управление Links из Windows-клиента;
- [x] срок действия не более 10 минут; - [x] политики по destination `/32`, TCP/UDP и порту;
- [x] атомарное погашение token; - [x] TTL и фоновое автоматическое истечение;
- [x] отзыв и повторная регистрация Node;
- [x] подтверждение SHA-256 fingerprint Control CA Hub;
- [x] защита desktop SSH-ключа через DPAPI.
## Этап 4 — управляемые Links
- [x] направленные пары source → destination;
- [x] ручное добавление и удаление nftables ACL из Windows-клиента;
- [x] политики по целевому `/32`, TCP/UDP и порту;
- [x] TTL и автоматическое истечение;
- [x] состояния Connecting, Active, Disconnecting, Partial, Disabled и Failed; - [x] состояния Connecting, Active, Disconnecting, Partial, Disabled и Failed;
- [x] версия политики и подтверждение применения на Hub; - [x] версия политики и подтверждение применения helper;
- [x] обязательное отключение после reconnect; - [x] обязательное восстановление disabled policy после reconnect;
- [x] локальный append-only JSONL-аудит операций Link; - [x] append-only audit операций Link;
- [x] интеграционные тесты Control kill switch, перезапуска процесса и частичного отказа helper; - [x] интеграционные тесты kill switch, process restart и helper failure;
- [x] end-to-end тесты nftables и реального reboot вместе с Linux-установщиком. - [ ] выполнить физический acceptance Hub + source Node + два destination Node с WireGuard/nftables/reboot.
## Этап 5 — мониторинг и терминал ## Этап 4 — мониторинг и терминал
- [x] swap, inode, network и состояние SSH/WireGuard; - [x] CPU/load, RAM, swap, disk, inode, network и uptime;
- [x] предупреждения по диску, памяти, inode и недоступности; - [x] состояния SSH/WireGuard и latency;
- [x] локальные предупреждения по ресурсам и доступности;
- [x] автоматическое обновление каждые 30 секунд; - [x] автоматическое обновление каждые 30 секунд;
- [x] короткая локальная история до 240 точек на сервер; - [x] локальная история до 240 точек на сервер;
- [x] встроенный график CPU, RAM и диска; - [x] графики CPU, RAM и диска;
- [x] экспорт диагностики без секретов; - [x] экспорт redacted diagnostics;
- [x] отдельный прямой SSH-терминал; - [x] прямой SSH-терминал с явным выбором пользователя;
- [x] отдельная terminal identity и подтверждение пользователя; - [x] source-scoped Automation API для AI-агента.
- [x] отдельная automation identity для AI-агента.
## Этап 6 — постоянный control layer ## Этап 5 — качество и нагрузка
- [x] самодостаточный single-file Linux agent для amd64/arm64; - [x] HTTP authorization/integration tests;
- [x] SQLite inventory, policies, history и audit; - [x] Linux Agent parser tests;
- [x] исходящие mTLS agent sessions; - [x] Windows Desktop contract tests;
- [x] защищённый Hub event stream для desktop client; - [x] тест 100 Node: concurrent heartbeat, inventory и replay;
- [x] ограниченный локальный буфер и downsampling; - [x] проверка TTL, retention, schema и backup/restore;
- [x] idempotency key и защита от replay; - [x] CI Windows/Linux и проверка форматирования;
- [x] тест нагрузки 100 Node на одном Hub (конкурентные heartbeat, inventory и replay в CI). - [ ] выполнить полную физическую приёмку по `docs/three-server-acceptance.md`;
- [x] фоновое истечение TTL с подтверждением удаления firewall policy; - [ ] добавить долговременный soak test и измеримые performance budgets.
- [x] retention метрик, replay и audit, версия SQLite schema, backup/restore Control DB и CA;
- [x] HTTP integration tests, Linux Agent parser tests и Windows desktop contract tests;
- [ ] выполнить acceptance test на физическом Hub и двух Node по `docs/three-server-acceptance.md`.
## Этап 7 — релиз и другие платформы ## Этап 6 — releases
- [x] подписанный Windows installer и GitHub Release; - [x] GitHub prerelease с test-signed Windows MSIX;
- [x] checksum Linux-установщика и бинарников; - [x] SHA-256 для Windows package и Linux binaries;
- [ ] macOS и Linux desktop после стабилизации Core/API; - [x] self-contained Control/Agent release artifacts;
- [ ] настроить постоянную доверенную Windows code-signing identity;
- [ ] синхронизировать все переводы README с текущим release status.
## Этап 7 — собственный bootstrap Server Monitor Manager
- [ ] добавить bootstrap source в этот репозиторий;
- [ ] публиковать bootstrap, checksum и signed compatibility manifest в release;
- [ ] поддержать Ubuntu 22.04/24.04 и Debian 12/13, `amd64`/`arm64`;
- [ ] добавить non-interactive install/update/rollback/uninstall;
- [ ] устанавливать Agent, restricted helper и systemd units;
- [ ] локально создавать Node keys/CSR и погашать bootstrap enrollment;
- [ ] добавить VM CI matrix, повторную установку и reboot;
- [ ] добавить локальную emergency recovery command.
## Этап 8 — Provisioning control plane
- [ ] модели и SQLite migrations для ProvisioningJob;
- [ ] state machine, confirmations, cancellation, retry и rollback;
- [ ] обязательные idempotency key, audit reason и job TTL;
- [ ] Agent job channel только для собственного `node_id`;
- [ ] versioned JSON schemas для каждого action type;
- [ ] restricted root helper через Unix socket;
- [ ] structured redacted events и progress;
- [ ] `NeedsReconciliation` после неопределённого результата;
- [ ] desired/factual configuration и drift;
- [ ] запрет параллельных несовместимых опасных заданий.
## Этап 9 — базовая настройка и пользователи
- [ ] preflight ОС, архитектуры, SSH, firewall, APT и capabilities;
- [ ] Desktop wizard timezone/locale/packages/swap/unattended upgrades;
- [ ] versioned package allowlist;
- [ ] root-only backups и symlink protection;
- [ ] user lifecycle без sudo по умолчанию;
- [ ] SSH public keys, fingerprints и permissions;
- [ ] sudo/passwordless sudo с отдельным подтверждением;
- [ ] block/unblock, sessions, services и безопасное удаление;
- [ ] verification и rollback для каждого action.
## Этап 10 — firewall и безопасная миграция SSH
- [ ] редактор managed firewall rules IPv4/IPv6/CIDR;
- [ ] preflight port conflict и effective sshd config;
- [ ] managed `sshd_config.d` drop-in;
- [ ] `sshd -t`, `sshd -T` и firewall dry-run;
- [ ] второе SSH-подключение Desktop на новом порту;
- [ ] сохранение host key fingerprint;
- [ ] запрет закрытия порта 22 до успешной проверки;
- [ ] отдельное подтверждение закрытия старого порта;
- [ ] автоматический rollback без разрыва активной сессии.
## Этап 11 — системный Xray VPN
- [ ] Node-specific encryption VPN subscription secrets;
- [ ] установка, update, disable и verification Xray;
- [ ] routing exclusions для Mesh, Control, SSH и VPN endpoint;
- [ ] automatic rollback timer;
- [ ] TCP/UDP/DNS/IPv6 probes и внешний IP до/после;
- [ ] system-wide kill switch с management exceptions;
- [ ] emergency disable без Control Hub;
- [ ] reboot/reconciliation tests.
## Этап 12 — Xray VPN для пользователя
- [ ] UID/cgroup marking, fwmark, policy route и TPROXY;
- [ ] один активный VPN profile на UID;
- [ ] TCP, UDP, DNS и IPv6 policy;
- [ ] per-user kill switch;
- [ ] probes от назначенного UID;
- [ ] исключение Xray, Mesh и management traffic;
- [ ] отключение assignment при смене UID/удалении пользователя;
- [ ] UI assignment и audit;
- [ ] VM test: один пользователь через VPN, второй напрямую.
## Этап 13 — hardening и дополнительные платформы
- [ ] threat-model review Provisioning и VPN;
- [ ] полная VM matrix и physical alpha acceptance;
- [ ] macOS и Linux Desktop после стабилизации Core/API;
- [ ] Android/iOS companion clients; - [ ] Android/iOS companion clients;
- [ ] push-уведомления без административных секретов у push-провайдера. - [ ] push-уведомления без административных secrets у push provider.

18
docs/security-model.md
View file

@ -63,6 +63,24 @@ Windows-клиент получает отдельный код `SMMDEV1`, по
5. показывать `Partial`, если подтверждение одного из узлов отсутствует; 5. показывать `Partial`, если подтверждение одного из узлов отсутствует;
6. сохранить обязательную операцию для временно недоступного Node. 6. сохранить обязательную операцию для временно недоступного Node.
## Provisioning и VPN
Provisioning расширяет существующую модель ролей, но не предоставляет удалённый root shell:
- mutation создаёт только Operator и только для явно выбранного `node_id`;
- Agent получает задания исключительно своего Node;
- Automation identity не управляет ОС, пользователями, firewall или VPN;
- root helper принимает фиксированный action id и JSON строгой versioned schema через локальный Unix socket;
- helper повторно валидирует параметры, использует фиксированный `PATH` и отклоняет shell text, неизвестные поля, произвольные paths и symlinks;
- опасное задание имеет TTL, idempotency key, audit reason, отдельное подтверждение, verification и rollback;
- одновременно на Node не выполняются несовместимые опасные задания;
- неопределённый результат после disconnect получает `NeedsReconciliation`;
- повторная регистрация Node инвалидирует незавершённые опасные задания;
- VPN subscription secret шифруется на публичный ключ конкретного Node, а Control хранит только ciphertext и маскированные metadata;
- локальная emergency recovery может отключить managed VPN и восстановить SSH/firewall без Control Hub, но не запускает произвольную команду.
Подробный контракт приведён в [ТЗ Provisioning и Xray VPN](provisioning-vpn-requirements.md).
## Не входит в первый MVP ## Не входит в первый MVP
- выполнение произвольных root-команд; - выполнение произвольных root-команд;