High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
fix(handlers): honor wildcard download allowlist for private hosts (PIN-280)
Luigi Agostid44a9861d3f6
diff --git a/docs/endpoints.md b/docs/endpoints.mdindex e979ecf4..b235eae2 100644--- a/docs/endpoints.md+++ b/docs/endpoints.md@@ -588,7 +588,7 @@ Notes:- download and upload endpoints are gated by `security.allowDownload` and `security.allowUpload`- cookie endpoints (`GET/POST/DELETE /cookies`, plus tab-scoped variants) are gated by `security.allowCookies`- download automatically decompresses `.gz` files and returns the decompressed content-- `security.downloadAllowedDomains` can whitelist specific domains (bypasses SSRF checks for those domains). Setting `["*"]` matches every host for the domain restriction, but grants no SSRF bypass — private-IP protection stays on. Name the internal host to reach it: `["docker-registry.internal"]`, `["10.0.0.5"]`, or `["*", "10.0.0.5"]`. Naming a loopback host (`127.0.0.1`, `localhost`) lets the download endpoint reach services on the server's own machine, including PinchTab's own local endpoints. A host that is neither named nor public is refused with code `download_host_blocked`, and the response carries the `config set` line that names it.+- `security.downloadAllowedDomains` can whitelist specific domains (bypasses SSRF checks for matching domains). Setting `["*"]` matches every host and disables private-IP protection for this endpoint, including loopback. Naming a loopback host (`127.0.0.1`, `localhost`) or using `"*"` lets the download endpoint reach services on the server's own machine, including PinchTab's own local endpoints. A host that is neither matched nor public is refused with code `download_host_blocked`, and the response carries the `config set` line that names it.- clipboard endpoints are gated by `security.allowClipboard`- upload uses a JSON body with `selector`, `files`, and optional `fileNames`- `fileNames` is index-aligned with `files` and sets the name the page sees in `file.name` — send it, or every upload arrives as `upload-<i>.bin` and forms gating on `accept=".csv"` or `file.name.endsWith(...)` reject it. Without a name the extension is sniffed from content, which cannot identify text formats (`.csv`, `.json`, `.txt`, `.md`, `.html`) because they have no magic bytes. A supplied name wins over the sniffed type even when the two disagree, matching what a browser sends. Only the basename is used: any directory part is dropped.diff --git a/docs/guides/security.md b/docs/guides/security.mdindex 82a2cc1a..21659a6e 100644--- a/docs/guides/security.md+++ b/docs/guides/security.md@@ -202,7 +202,7 @@ Why they are considered dangerous:- `evaluate` can execute JavaScript in page context- `macro` can trigger higher-level automation flows- `screencast` can stream live page contents-- `download` can fetch and persist remote content. When `security.downloadAllowedDomains` is set, explicitly listed domains bypass private-IP SSRF checks (intended for internal hosts such as Docker services). A bare `"*"` matches every host for the domain restriction but grants no such bypass: private-IP protection stays on. Name the internal host to reach it — `["docker-registry.internal"]`, `["10.0.0.5"]`, or `["*", "10.0.0.5"]` to keep every other host reachable too. Naming a loopback host (`127.0.0.1`, `localhost`) lets the download endpoint reach services on the server's own machine, including PinchTab's own local endpoints, so treat such an entry the way you treat `allowFileScheme`.+- `download` can fetch and persist remote content. When `security.downloadAllowedDomains` is set, matching domains bypass private-IP SSRF checks (intended for internal hosts such as Docker services). A bare `"*"` matches every host and therefore disables private-IP protection for this endpoint, including loopback. Naming a loopback host (`127.0.0.1`, `localhost`) or using `"*"` lets the download endpoint reach services on the server's own machine, including PinchTab's own local endpoints, so treat either configuration the way you treat `allowFileScheme`.- `cookies` can read, write, or clear browser session tokens for the current page- `upload` can push local files into browser flows- `allowFileScheme` permits navigation to `file://` URLs. Because a `file://` URL has no host, it is **not** subject to `allowedDomains` or the SSRF/private-IP guard, so enabling it grants read access (via snapshot/screenshot/scrape) to any local file the server process can read. It stays blocked when a strict-mode `allowedDomains` allowlist is active. Enable only on trusted, single-tenant hosts. `javascript:`, `chrome://`, and `data:` remain rejected regardless.diff --git a/internal/handlers/download_guard.go b/internal/handlers/download_guard.goindex a7f3c567..15140e8e 100644--- a/internal/handlers/download_guard.go+++ b/internal/handlers/download_guard.go@@ -42,12 +42,12 @@ func newDownloadURLGuard(allowedDomains []string) *downloadURLGuard {return &downloadURLGuard{allowedDomains: append([]string(nil), allowedDomains...)}}-func (g *downloadURLGuard) explicitlyAllowsHost(host string) bool {+func (g *downloadURLGuard) allowsHost(host string) bool {host = netguard.NormalizeHost(host)if host == "" {return false}- return idpi.DomainAllowed("https://"+host, config.IDPIConfig{Enabled: true}, g.allowedDomains)+ return g.isDomainAllowed("https://" + host)}func (g *downloadURLGuard) isDomainAllowed(rawURL string) bool {@@ -75,7 +75,7 @@ func (g *downloadURLGuard) Validate(rawURL string) error {if host == "" {return downloadHostBlockedError{}}- if g.explicitlyAllowsHost(host) {+ if g.allowsHost(host) {return nil}if netguard.IsLocalHost(host) {diff --git a/internal/handlers/download_guard_test.go b/internal/handlers/download_guard_test.goindex 43361440..c7d3f018 100644--- a/internal/handlers/download_guard_test.go+++ b/internal/handlers/download_guard_test.go@@ -13,11 +13,7 @@ import ("github.com/pinchtab/pinchtab/internal/config")-// The download dialler asks the guard whether the operator named this host, and a-// bare "*" names none. It used to derive that grant from the RESTRICTION predicate-// — "nothing blocked it" read as "the operator permitted it" — which is why a-// wildcard, whose whole purpose is to block nothing, dialled every private address.-func TestABareWildcardGrantsNoPrivateIPOverrideOnTheDownloadDialler(t *testing.T) {+func TestTheDownloadAllowlistControlsTheDomainAndPrivateIPChecksTogether(t *testing.T) {const privateHost = "10.0.0.5"for _, tc := range []struct {@@ -25,8 +21,8 @@ func TestABareWildcardGrantsNoPrivateIPOverrideOnTheDownloadDialler(t *testing.Tallowed []stringwant bool}{- {"a bare wildcard", []string{"*"}, false},- {"a wildcard beside an unrelated host", []string{"*", "example.com"}, false},+ {"a bare wildcard", []string{"*"}, true},+ {"a wildcard beside an unrelated host", []string{"*", "example.com"}, true},{"a wildcard beside the internal host", []string{"*", privateHost}, true},{"the internal host alone", []string{privateHost}, true},{"a wildcard subdomain", []string{"*.corp.example.com"}, false},@@ -34,9 +30,9 @@ func TestABareWildcardGrantsNoPrivateIPOverrideOnTheDownloadDialler(t *testing.T} {t.Run(tc.name, func(t *testing.T) {guard := newDownloadURLGuard(tc.allowed)- allowInternal := guard.explicitlyAllowsHost(privateHost)+ allowInternal := guard.allowsHost(privateHost)if allowInternal != tc.want {- t.Fatalf("explicitlyAllowsHost(%v) = %v, want %v", tc.allowed, allowInternal, tc.want)+ t.Fatalf("allowsHost(%v) = %v, want %v", tc.allowed, allowInternal, tc.want)}// The predicate matters only through the dialler that consumes it: a@@ -55,9 +51,6 @@ func TestABareWildcardGrantsNoPrivateIPOverrideOnTheDownloadDialler(t *testing.T}}-// The withdrawal is scoped to the override: "*" still lifts the domain restriction-// for every host, which is what an operator writes it for. Without this, refusing-// the wildcard outright would satisfy every row above.func TestABareWildcardStillLiftsTheDownloadDomainRestriction(t *testing.T) {const unlisted = "https://unlisted.example/file.bin"@@ -88,7 +81,7 @@ func TestAnAllowlistedLoopbackHostGetsTheSameVerdictFromValidateAndTheDialler(t{"loopback literal named", []string{"127.0.0.1"}, "127.0.0.1", true, false},{"localhost named", []string{"localhost"}, "localhost", true, false},{"loopback beside a wildcard", []string{"*", "127.0.0.1"}, "127.0.0.1", true, false},- {"loopback under a bare wildcard", []string{"*"}, "127.0.0.1", false, true},+ {"loopback under a bare wildcard", []string{"*"}, "127.0.0.1", true, false},{"loopback absent from a named list", []string{"example.com"}, "127.0.0.1", false, true},{"loopback with no list", nil, "127.0.0.1", false, true},{"private host named", []string{"10.0.0.5"}, "10.0.0.5", true, false},@@ -103,7 +96,7 @@ func TestAnAllowlistedLoopbackHostGetsTheSameVerdictFromValidateAndTheDialler(tif errors.Is(err, errDownloadHostBlocked) != tc.wantBlocked {t.Fatalf("Validate answered %v, want the blocked-host refusal=%v", err, tc.wantBlocked)}- _, dialErr := resolveDownloadDialIPs(context.Background(), tc.host, guard.explicitlyAllowsHost(tc.host))+ _, dialErr := resolveDownloadDialIPs(context.Background(), tc.host, guard.allowsHost(tc.host))if (dialErr == nil) != tc.wantAllowed {t.Fatalf("the dialler answered %v while Validate answered %v; the two layers must agree", dialErr, err)}diff --git a/internal/handlers/download_network.go b/internal/handlers/download_network.goindex 9ce016b3..5902f71e 100644--- a/internal/handlers/download_network.go+++ b/internal/handlers/download_network.go@@ -55,7 +55,7 @@ func dialGuardedDownloadAddress(ctx context.Context, network, addr string, validreturn nil, err}- allowInternal := validator != nil && validator.explicitlyAllowsHost(host)+ allowInternal := validator != nil && validator.allowsHost(host)ips, err := resolveDownloadDialIPs(ctx, host, allowInternal)if err != nil {return nil, err