git init
This commit is contained in:
87
docs/architecture.md
Normal file
87
docs/architecture.md
Normal 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
71
docs/deployment.md
Normal 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
19
docs/development.md
Normal 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
67
docs/security.md
Normal 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.
|
||||
Reference in New Issue
Block a user