Skip to content

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.md
index 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.md
index 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.go
index 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.go
index 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.T
allowed []string
want 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(t
if 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.go
index 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, valid
return 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