68 lines
4.1 KiB
Markdown
68 lines
4.1 KiB
Markdown
# 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.
|