4.1 KiB
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.