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.