This commit is contained in:
2026-09-22 23:37:05 +03:00
parent cf1c31eb2a
commit 0fc35589e6
25 changed files with 2616 additions and 245 deletions

View File

@@ -30,14 +30,18 @@ writes at 2 rps, burst 20, with 32 concurrent requests and five-second timeouts.
| 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/POST | `/v1/firewall/rules` | structured iptables inventory / add managed rule |
| DELETE | `/v1/firewall/rules/:id` | delete a managed rule |
| GET/POST | `/v1/rate-limits` | list / add managed L4 policies |
| DELETE | `/v1/rate-limits/:id` | delete a managed L4 policy |
| 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 |
| POST | `/v1/fail2ban/configure` | write and validate an allow-listed jail drop-in |
| 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/services` | bounded inventory of all systemd services |
| POST | `/v1/services/:name/:operation` | allow-listed action or catalog installation |
| GET | `/v1/logs` | cursor-paginated journald rows from allow-listed units |
No generic command route exists. Child processes receive a fixed executable and
@@ -53,6 +57,8 @@ fixed subcommand plus individually validated argv values.
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
- `connection_samples(...)` with current source/destination/process aggregates
- `fail2ban_events(...)` and `fail2ban_ban_state(...)` for ban history
- `audit_events(actor, server, action, target, before, after, result, source_ip,
created_at)`; secrets are excluded
@@ -78,10 +84,8 @@ Grafana ──Prometheus/Loki read APIs──> backend ──semantic polling─
## 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.
The HTTP agent has no ambient capabilities and runs as `vps-agent`. Linux
usually permits the read-only endpoints without elevation. Mutations go over a
0600 Unix socket to a root, socket-activated helper. The helper accepts typed
JSON only, validates local allow-lists, uses fixed argv, snapshots iptables,
rolls back failures and never mutates rules outside its two reserved chains.

View File

@@ -7,6 +7,49 @@ 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.
## Agent write features
On Debian/Ubuntu install the firewall userspace and persistence provider before
enabling managed writes:
```bash
sudo apt-get update
sudo apt-get install -y iptables iptables-persistent fail2ban
sudo systemctl enable --now netfilter-persistent vps-agent-helper.socket
```
Then edit `/etc/vps-agent/config.toml`. All write targets must be explicitly
allow-listed; use the real tunnel interface, management network and service
ports for the host:
```toml
[services]
allowed = ["nginx.service", "fail2ban.service"]
inventory_limit = 512
install_enabled = true
install_timeout_seconds = 300
packages = { "nginx.service" = "nginx", "fail2ban.service" = "fail2ban" }
[firewall]
management_enabled = true
persistence_enabled = true
allowed_interfaces = ["wg0"]
allowed_sources = ["192.168.50.0/24"]
allowed_ports = [22, 80, 443, 9105]
rollback_timeout_seconds = 60
max_snapshots = 5
[fail2ban]
management_enabled = true
allowed_jails = ["sshd", "nginx-http-auth"]
```
Restart the daemon after editing. The UI shows every iptables rule but only
rules in `VPS_CONTROL_INPUT` and `VPS_CONTROL_RATE` can be deleted. Successful
changes are saved through `netfilter-persistent`; failed changes restore the
last snapshot. Keep the control-panel port and source network in the allow-list
before adding restrictive rules.
## Control plane
```bash
@@ -36,7 +79,8 @@ 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
Metric and connection samples are retained for 30 days and collected logs and
Fail2Ban history 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.

View File

@@ -19,7 +19,7 @@ CSRF header on mutations. Passwords use Argon2id.
| 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 |
| Accidental firewall damage | only dedicated chains are mutable; every change snapshots, restores on error, and persists only after success |
| 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 |
@@ -37,13 +37,18 @@ 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)
## Privileged helper and firewall safety
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.
The HTTP daemon remains unprivileged. A socket-activated, one-request root helper
accepts only typed operations from the `vps-agent` Unix account. Firewall writes
are restricted to `VPS_CONTROL_INPUT` and `VPS_CONTROL_RATE`; external rules are
always read-only. Before a mutation the helper stores a bounded `iptables-save`
snapshot and arms an independent systemd rollback timer. The backend confirms
the transaction only after reconnecting to the agent; without confirmation the
snapshot is restored and persisted. Immediate command failures also restore it.
Interfaces, source CIDRs, ports, services, packages and Fail2Ban jails must all
match local configuration allow-lists. Service installation uses a fixed
`apt-get` argv in a time-bounded transient systemd unit.
## Operational logging