slice 8A (agent half): local-API server + provisioning back-half (v0.10.0)

internal/localapi: per-guest local-API server (doc 03 §6) — 7 self-scoped endpoints, hashed per-guest token store, persisted self-signed leaf with stable SHA-256 pin, optional 6th daemon goroutine. internal/provision: back-half — mint token, render bootstrap.json (no registry cred), write 0600, chown 100000:100000, attach pct-set bind mount (host-side, F3, no pct exec). --selftest=provision. build-golden.sh bakes the controller image + bootstrap unit. sudoers FELHOM_PROVISION; firewall narrowing artifact. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-10 09:47:42 +02:00
parent fae11020a5
commit 3fecf4c713
18 changed files with 2203 additions and 11 deletions
@@ -0,0 +1,40 @@
+# felhom-agent local API — host firewall narrowing (doc 03 §6, slice 8A)
+#
+# Defense-in-depth for the per-guest local API (the controller→agent channel on the host
+# bridge). The PER-GUEST BEARER TOKEN is the authorization gate; this firewall rule is an
+# ADDITIONAL layer that limits who can even reach the port. The slice-8A spike found no rule
+# was needed for reachability on the demo (PVE firewall off) — this narrows exposure so that
+# only guests on the bridge subnet (not arbitrary LAN hosts) can open a connection.
+#
+# The agent already binds the listener to the host BRIDGE IP (local_api.listen_addr), not
+# 0.0.0.0. This file adds the subnet restriction. Apply it at HOST SETUP (it is a host-level
+# packet-filter change, intentionally OUTSIDE the agent's 3-exception privileged fence — the
+# agent never mutates the host firewall at runtime).
+#
+# Replace the bridge IP (192.168.0.162), port (8443), and the guest bridge subnet
+# (192.168.0.0/24) with this host's values.
+#
+# ---------------------------------------------------------------------------------------------
+# Option A — nftables (recommended on PVE 8/9; inet filter table). Insert ABOVE any accept:
+#
+#   nft add rule inet filter input ip daddr 192.168.0.162 tcp dport 8443 \
+#       ip saddr != 192.168.0.0/24 drop
+#   nft add rule inet filter input ip daddr 192.168.0.162 tcp dport 8443 \
+#       ip saddr 192.168.0.0/24 accept
+#
+# ---------------------------------------------------------------------------------------------
+# Option B — iptables:
+#
+#   iptables -A INPUT -d 192.168.0.162 -p tcp --dport 8443 -s 192.168.0.0/24 -j ACCEPT
+#   iptables -A INPUT -d 192.168.0.162 -p tcp --dport 8443 -j DROP
+#
+# ---------------------------------------------------------------------------------------------
+# Option C — PVE host firewall (/etc/pve/nodes/<node>/host.fw), if the PVE firewall is enabled.
+# Add under [RULES] (and ensure the firewall is enabled in cluster.fw / host.fw):
+#
+#   [RULES]
+#   IN ACCEPT -source 192.168.0.0/24 -dport 8443 -proto tcp -log nolog
+#   IN DROP   -dport 8443 -proto tcp -log nolog
+#
+# Verify after applying: from a guest ON the bridge, a TLS connect to <bridge-ip>:8443 succeeds;
+# from an OFF-bridge host it is refused/dropped. (The token + leaf-pin still gate the request.)