Documentation
¶
Overview ¶
Package fleetnet validates the URL of a remote CashPilot worker before the desktop (master) makes an authenticated request to it.
The master attaches the shared fleet bearer token to every worker request, so an unvalidated worker URL — which arrives either in a worker's own heartbeat body (attacker-influenceable) or is typed by the operator — is a classic SSRF confused-deputy hazard: it could steer authenticated requests at cloud-metadata endpoints (169.254.169.254), the master's own loopback services, or otherwise unreachable internal hosts.
This is a straight port of the CashPilot server's SSRF guard (CashPilot/app/main.py:792-918). The always-blocked address sets, the IPv4-mapped-IPv6 normalization, and the DNS-rebinding guard (resolve the host and check EVERY resolved IP) are reproduced faithfully; the three policy modes (strict/private/public) are the Desktop's adaptation of the original's permissive/strict pair. See docs/REMOTE-DEPLOY-DESIGN.md §4.
The package is pure and has no callers yet — Phase 2 of the remote-deploy plan wires it into the outbound fleet client.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ValidateWorkerURL ¶
ValidateWorkerURL parses rawURL and returns nil if it is a safe worker target under p, or a descriptive error naming why it was rejected.
Precedence, highest first (documented so the allowlist-vs-metadata question is unambiguous — see docs/REMOTE-DEPLOY-DESIGN.md §4):
- Structural — the scheme must be http/https and the URL must have a host.
- Metadata — a metadata IP (or the GCP metadata hostname) is rejected whenever AllowMetadata is false. This is NOT overridable by AllowedHosts, faithful to the original whose metadata block runs unconditionally; AllowMetadata=true is the only lift and then treats those endpoints as explicitly allowed.
- Explicit allowlist — an exact IP/CIDR entry in AllowedHosts allows that IP, overriding the loopback/link-local/unspecified block AND the policy range check. A name/suffix entry overrides the range check (and a resolution failure) but never the metadata (2) or loopback/link-local (4) block on a RESOLVED IP, matching the original where _assert_ip_not_blocked always runs.
- Always-blocked — loopback, link-local and unspecified addresses are rejected.
- Policy range check — strict/private/public as described on Policy.
For a hostname the host is resolved and EVERY resolved IP must pass steps 2-5 — the DNS-rebinding guard: a name that resolves to any blocked/disallowed IP is rejected, and the resolution is done at call time (never cached) so a name that later flips to a blocked address is still caught.
A URL may legitimately carry userinfo ("user:pass@host"); like the original it is not rejected, because url.Hostname() (as with Python's urlparse().hostname) extracts exactly the authority host the HTTP client will dial, so userinfo cannot smuggle a different target past the check.
Types ¶
type Policy ¶
Policy selects how ValidateWorkerURL classifies a worker endpoint. It mirrors the Phase 0 config surface (config.AppConfig.WorkerURLPolicy / WorkerAllowedHosts / WorkerAllowMetadata).
Mode:
- "strict": allow ONLY hosts/IPs matched by AllowedHosts.
- "private": allow RFC1918 + CGNAT/Tailscale 100.64.0.0/10 + IPv6 ULA fc00::/7, plus AllowedHosts; public addresses are rejected. This is the homelab default and the value an empty Mode is treated as.
- "public": allow any address that is not loopback / link-local / metadata / unspecified.
AllowedHosts entries may be an exact hostname, a "*.suffix" DNS-name suffix (e.g. "*.mango-alpha.ts.net" for Tailscale MagicDNS), a CIDR, or a literal IP — a port of the original's allowlist parsing (main.py:823-839).
AllowMetadata, when false (the default), blocks the cloud-metadata endpoints unconditionally: no AllowedHosts entry overrides that. Setting it true is the only way to reach a metadata address.