# VPS Control

Ориентированная на production-среду система мониторинга и ограниченного управления VPS-хостами на Debian и Ubuntu.

Небольшой демон на Rust предоставляет семантические системные API через приватную сеть WireGuard или TLS. Отдельно размещаемая управляющая часть на Go + React предоставляет инвентаризацию серверов, историю, RBAC и неизменяемый журнал аудита.

```text
Браузер ──HTTPS──> React/nginx ──> Go API ──приватная сеть──> Rust agent
                                         │
                                     PostgreSQL
                                         ▲
                            Grafana (Prometheus/Loki APIs)
```

В проекте намеренно отсутствует удалённый shell-доступ.

По умолчанию агент слушает `127.0.0.1:9105`, считывает учётные данные из файлов, управляемых `root`, запускается от имени непривилегированного системного пользователя и ограничивается средствами управления ресурсами `systemd`.

## Быстрый старт

Управляющая часть:

```bash
cp control-plane/.env.example control-plane/.env
# Заполните все значения CHANGE_ME и создайте файлы с секретами, описанные ниже.
docker compose -f control-plane/docker-compose.yml up -d --build
```

Сборка агента для разработки:

```bash
cargo build --manifest-path agent/Cargo.toml --release
sudo install -m 0755 agent/target/release/vps-agent /usr/local/bin/vps-agent
sudo install -m 0640 examples/agent-config.toml /etc/vps-agent/config.toml
```

Для установки релизной версии скачайте скрипт управления жизненным циклом и файл контрольной суммы как отдельные файлы, проверьте их с помощью `sha256sum -c`, после чего выполните:

```bash
sudo ./scripts/vps-agentctl.sh install --version v0.1.0
```

См. документацию по [развёртыванию](docs/deployment.md), [безопасности](docs/security.md), а также руководства по [агенту](agent/README.md) и [управляющей части](control-plane/README.md).

## Структура репозитория

```text
agent/                 VPS-демон на Rust и файлы для упаковки systemd-службы
control-plane/backend/ Go API, хранение данных в PostgreSQL, аутентификация/RBAC/аудит
control-plane/frontend Панель управления на React/Vite
docs/                  архитектура, модель угроз, эксплуатация, разработка
scripts/               безопасная утилита управления жизненным циклом агента
examples/              примеры конфигураций, готовых к развёртыванию
```

## Безопасность и совместимость

Поддерживаемые системы:

- Debian 12+
- Ubuntu 22.04
- Ubuntu 24.04

Требуется `systemd`.

Держите агент за WireGuard либо привязывайте его только к localhost/reverse tunnel.

Никогда не привязывайте агент к публичному сетевому интерфейсу без:

- TLS;
- настроенной политики firewall на хосте;
- явной оценки связанных с этим рисков.

Перед включением операций, изменяющих состояние системы, прочитайте [docs/security.md](docs/security.md).

Текущий объём функциональности v1 поддерживает операции только для чтения для:

- системной информации;
- сетевой конфигурации;
- сетевых сокетов;
- firewall;
- Fail2Ban;
- WireGuard;
- сервисов из явно разрешённого списка.

Также поддерживаются ручные операции Fail2Ban `ban`/`unban` и перезапуск разрешённых сервисов. Все такие действия записываются в журнал аудита.

Управляемое изменение правил firewall и настройка L7 rate limit намеренно отложены до появления отдельного привилегированного helper-процесса, который сможет гарантировать безопасный откат изменений даже при сбое или аварийном завершении.

Дополнительные observability-endpoint'ы позволяют backend-компоненту выступать в роли ограниченного источника метрик, совместимого с Prometheus, и источника логов, совместимого с Loki, для Grafana.

Grafana никогда не получает адрес агента или его учётные данные.

## Разработка

См. [docs/development.md](docs/development.md).

Команды, совместимые с CI, также перечислены в [AGENTS.md](AGENTS.md).

Репозиторий распространяется по лицензии Apache-2.0.