update
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user