fleetnet

package
v0.23.11 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: GPL-3.0 Imports: 5 Imported by: 0

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

func ValidateWorkerURL(rawURL string, p Policy) error

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):

  1. Structural — the scheme must be http/https and the URL must have a host.
  2. 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.
  3. 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.
  4. Always-blocked — loopback, link-local and unspecified addresses are rejected.
  5. 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

type Policy struct {
	Mode          string
	AllowedHosts  []string
	AllowMetadata bool
}

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL