git init
Some checks failed
CI / containers (push) Has been cancelled
CI / agent (push) Has been cancelled
CI / backend (push) Has been cancelled
CI / frontend (push) Has been cancelled

This commit is contained in:
2026-09-19 19:31:36 +03:00
commit c4dc19cd41
78 changed files with 13045 additions and 0 deletions

87
docs/architecture.md Normal file
View File

@@ -0,0 +1,87 @@
# Architecture
## Components and trust boundaries
The Rust agent is a stateless, pull-oriented HTTP API. It stores no metrics or
log history and does no background polling. `/proc`, `/sys`, journald, and fixed
read-only utilities are queried only when the control plane asks. The Go backend
owns users, sessions, servers, metric/log samples, retention, and audit. React
is served behind nginx and only calls the backend.
Grafana also talks only to the backend. The backend implements the constrained
read portions of the Prometheus and Loki HTTP APIs, backed by PostgreSQL. There
is intentionally no Grafana-to-agent or Loki-to-agent path and no agent token is
ever provisioned into Grafana.
Agent transport is expected to be WireGuard plus a 256-bit application token,
or TLS plus that token. The listen address is loopback by default. Tokens live in
files outside configuration and are never returned by an API.
## Agent API v1
All `/v1` routes require `Authorization: Bearer …`; `/healthz` only returns
liveness. JSON bodies are capped at 64 KiB. Read traffic is capped at 10 rps,
writes at 2 rps, burst 20, with 32 concurrent requests and five-second timeouts.
| Method | Route | Purpose |
|---|---|---|
| GET | `/v1/system/status` | CPU, load, memory, swap, filesystems, uptime |
| GET | `/v1/network/interfaces` | interfaces, addresses and counters |
| GET | `/v1/network/routes` | kernel routes |
| GET | `/v1/network/listeners` | listening TCP/UDP sockets |
| GET | `/v1/network/connections` | current TCP/UDP sockets |
| GET | `/v1/firewall/rules` | backend and read-only ruleset |
| GET | `/v1/fail2ban/status` | installation and jail summary |
| GET | `/v1/fail2ban/jails/:jail` | validated jail detail |
| POST | `/v1/fail2ban/ban` | validated IP and jail ban |
| POST | `/v1/fail2ban/unban` | validated IP and jail unban |
| GET | `/v1/wireguard/status` | interface and peer dump |
| GET | `/v1/services` | allow-listed services only |
| POST | `/v1/services/:name/restart` | allow-listed restart only |
| GET | `/v1/logs` | cursor-paginated journald rows from allow-listed units |
No generic command route exists. Child processes receive a fixed executable and
fixed subcommand plus individually validated argv values.
## Data model
- `users(id, username, password_hash, role, disabled, timestamps)`
- `sessions(id_hash, user_id, csrf_hash, expires_at, source_ip)`
- `servers(id, name, hostname, agent_endpoint, credential_ref, tags, status,
last_seen, timestamps)`
- `metric_samples(server_id, sampled_at, cpu, memory, disk, rx, tx,
connections, bans)` with 30-day retention
- `agent_log_entries(server_id, journal_cursor, event_at, unit, priority,
message, boot_id, pid)` with configurable seven-day retention
- `audit_events(actor, server, action, target, before, after, result, source_ip,
created_at)`; secrets are excluded
Credentials are indirect references to Docker secrets or environment variables,
not database values. Database migrations are append-only and run on startup.
## Observability compatibility APIs
`/integrations/prometheus` accepts direct selectors for the fixed
`vps_control_*` metric set. `/integrations/loki` accepts bounded stream selectors
over `server_id`, `server_name`, `unit`, and `priority`. Full PromQL, arbitrary
LogQL pipelines, writes, remote-write, and Loki push APIs are deliberately not
implemented. Queries are bearer-authenticated with an independent secret,
rate-limited, range-limited to 31 days, and result-limited.
The data path is:
```text
Grafana ──Prometheus/Loki read APIs──> backend ──semantic polling──> VPS agent
│
PostgreSQL
```
## Privilege design
The agent has no ambient capabilities and runs as `vps-agent`. Linux usually
permits the read-only endpoints without elevation. Fail2Ban mutations and
service restarts need administrator-provided sudoers or polkit rules restricted
to each approved verb/name. The shipped service does not install such policy
automatically. Managed firewall mutation is out of v1 because giving the main
daemon `CAP_NET_ADMIN` violates least privilege; its future helper protocol must
provide prepare/apply/health/confirm/commit and persistent timed rollback.

71
docs/deployment.md Normal file
View File

@@ -0,0 +1,71 @@
# Deployment
## Network
Place each agent and the backend in a WireGuard network. Bind the agent to its
WireGuard address only and allow TCP/9105 solely from the control-plane peer.
Alternatively bind to loopback and expose it through an authenticated tunnel.
TLS termination at the agent is supported when certificate paths are configured.
## Control plane
```bash
cp control-plane/.env.example control-plane/.env
mkdir -p control-plane/secrets
openssl rand -hex 32 > control-plane/secrets/db_password
openssl rand -base64 24 > control-plane/secrets/admin_password
openssl rand -hex 32 > control-plane/secrets/integration_token
openssl rand -base64 24 > control-plane/secrets/grafana_admin_password
openssl rand -hex 32 > control-plane/secrets/grafana_secret_key
# Securely copy the exact token installed on the agent:
install -m 600 /secure/source/control-plane.token control-plane/secrets/agent_token
chmod 600 control-plane/secrets/*
docker compose -f control-plane/docker-compose.yml up -d --build
docker compose -f control-plane/docker-compose.yml ps
```
Terminate public TLS at a maintained reverse proxy and forward only to the
frontend container. Set `COOKIE_SECURE=true`. Restrict PostgreSQL to its Compose
network; it has no published host port.
## Backups and upgrades
Back up PostgreSQL with `pg_dump -Fc`, the `.env` file via a secret manager, TLS
key material, and Docker secret files. Test restores periodically. Agent backup
needs only `/etc/vps-agent/`. For upgrades, pin image tags, back up, pull/build,
run `docker compose up -d`, then inspect health and audit events. Database
migrations are forward-only; restore the database backup for rollback.
Metric samples are retained for 30 days and collected logs for seven days by
the backend cleanup loop. `METRICS_RETENTION` and `LOGS_RETENTION` control these
windows; log retention is constrained to one hour through 90 days. Configure
database-level backups independently of retention.
## Grafana and journald collection
Enable log collection explicitly on each agent:
```toml
[logs]
enabled = true
allowed_units = ["vps-agent.service", "nginx.service", "ssh.service"]
max_entries_per_request = 200
max_message_bytes = 16384
```
The service user also needs read access to journald. On Debian/Ubuntu this is
usually granted with `sudo usermod -aG systemd-journal vps-agent`, followed by an
agent restart. Membership permits the process to read the host journal even
though the API returns only configured units, so enable it only after the host
security review. The installer deliberately does not grant this access.
Start the provisioned Grafana profile with:
```bash
docker compose -f control-plane/docker-compose.yml --profile observability up -d --build
```
Grafana is bound to `127.0.0.1:3000`, requires the password from
`secrets/grafana_admin_password`, and comes with Prometheus/Loki datasources plus
a starter dashboard. For public access, place it behind TLS, set
`GRAFANA_ROOT_URL`, and set `GRAFANA_COOKIE_SECURE=true`.

19
docs/development.md Normal file
View File

@@ -0,0 +1,19 @@
# Development
Requirements: Rust 1.80+, Go 1.22+ (the container build uses 1.24), Node 22+,
Docker with Compose v2, and PostgreSQL 16 for backend integration.
```bash
cargo test --manifest-path agent/Cargo.toml
cd control-plane/backend && go test ./...
cd ../frontend && npm ci && npm test -- --run && npm run build
docker compose -f ../docker-compose.yml config
```
Copy example configuration; never commit live tokens. Parser tests use fixtures
and ordinary suites must work on macOS/Linux without root. Host integration is a
separate manual pass on a disposable supported VM.
When adding an endpoint, update the agent route, control-plane proxy allow-list,
RBAC policy, audit behavior (for writes), docs, and tests together. Prefer small
dependencies and measure agent RSS before accepting runtime-heavy crates.

67
docs/security.md Normal file
View File

@@ -0,0 +1,67 @@
# Security model
## Assumptions
The agent host, control-plane host, private transport, and browser are distinct
trust zones. Root compromise is out of scope; reducing the blast radius of an
application compromise is in scope. WireGuard/TLS protects transport while the
application token authenticates the control plane. Control-plane cookies are
HttpOnly, Secure in production, SameSite=Strict, short-lived, and paired with a
CSRF header on mutations. Passwords use Argon2id.
## Threats and mitigations
| Threat | Mitigation |
|---|---|
| Public scanning | loopback default, documented WireGuard-only binding, no unauthenticated metadata beyond liveness |
| Stolen agent token | file permissions, independent per-server credential refs, rotation without config secrets, TLS/WireGuard |
| Malicious API input | typed JSON, size limits, IP/jail/service validation, fixed argv, no shell |
| Request flooding | request timeouts, concurrency semaphore, token buckets, reverse-proxy limits |
| Command injection | no command strings; executable and subcommands are constants; service names are allow-listed |
| Privilege escalation | unprivileged user, systemd sandbox, no capabilities, write privileges opt-in and narrow |
| Accidental firewall lockout | v1 is read-only; future mutations require local, crash-safe confirm-or-rollback |
| Disk/log exhaustion | journald only, no metric spool, PostgreSQL retention, bounded body/audit fields |
| Observability token theft | independent file secret, constant-time verification, per-source limiting, no agent credentials in Grafana |
| Expensive dashboard queries | fixed metric set, restricted selectors, 31-day ranges, point/row/result caps |
| Compromised browser | RBAC, CSRF, Secure cookies, no agent access, audit; administrators still must use a trusted endpoint |
| Compromised control plane | semantic agent API and allow-lists limit actions; unique rotatable tokens reduce lateral movement |
| Authentication brute force | generic errors, Argon2id, per-IP login limiter, login audit |
| Suspicious traffic misclassification | display factual events and counts; no ungrounded “security score” |
## Credential rotation
Generate at least 32 random bytes (`openssl rand -hex 32`). Write the new value
to `/etc/vps-agent/credentials/control-plane.token`, owned by `vps-agent`, mode
0600, atomically replace
the file, restart the agent, then update its control-plane Docker secret and
restart the backend. Keep the overlap window short; the agent intentionally
accepts one token. Never pass the token on a command line.
## Firewall safety design (future helper)
The future root helper owns only `table inet vps_control`. It writes a bounded
snapshot (maximum five), fsyncs a pending transaction with a monotonic deadline,
applies a complete validated table, and starts an independent rollback timer.
Only an authenticated confirmation commits. On restart it rolls back any pending
transaction before accepting a new one. Unknown tables/chains remain read-only.
## Operational logging
The agent logs startup/shutdown, invalid configuration, auth failures (without
tokens), mutations, and unexpected errors. Successful metric polls are silent.
Bound journald globally only after reviewing other services, for example with
`SystemMaxUse=500M`, `RuntimeMaxUse=100M`, and `MaxRetentionSec=1month`.
Agent log export is off by default. When enabled, unit names are configuration
allow-listed, journal cursors and timestamps are validated, message/page sizes
are capped, subprocess time and output are bounded, and backlog ingestion is
limited per poll. Common `Authorization`, password, token, secret, and API-key
shapes are redacted on the agent and again before database insertion. This is a
defense in depth measure, not a substitute for applications avoiding secrets in
logs. PostgreSQL is the durable log store. The Loki-compatible API is read-only
and cannot be used to inject logs.
Treat the integration bearer token like a password. Keep it distinct from all
agent tokens, mount it from a secret file, rotate it by replacing the file and
restarting backend/Grafana, and restrict `/integrations/` at the outer reverse
proxy to Grafana source addresses where possible.