Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

fix(security): a bare "*" grants no private-IP override, narrowing the documented download SSRF bypass for operators (PIN-289)

Luigi Agostid2fb3db51b11
diff --git a/docs/endpoints.md b/docs/endpoints.md
index 1bb60fa9..95d5fe24 100644
--- a/docs/endpoints.md
+++ b/docs/endpoints.md
@@ -541,7 +541,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 and disables all private-IP protection on the download endpoint.
+- `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"]`.
- 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 60ddac50..b512c6eb 100644
--- a/docs/guides/security.md
+++ b/docs/guides/security.md
@@ -201,7 +201,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, listed domains bypass private-IP SSRF checks (intended for internal hosts such as Docker services). `["*"]` matches every host and disables all private-IP protection on the download endpoint.
+- `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.
- `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.
@@ -304,9 +304,13 @@ Important notes:
scanner found nothing suspicious" was read as "the operator allowed this host".)
- listing a private or internal host explicitly — `["10.0.0.5"]`, or the default
`["127.0.0.1", "localhost", "::1"]` — is what permits navigation to it. That is the
- only way the private-IP guard is relaxed, and it is a positive match against a
- non-empty list, never the absence of one.
-- if `allowedDomains` contains `"*"`, the whitelist effectively allows everything
+ only way the private-IP guard is relaxed, and it is a positive match by an entry
+ that **denotes a host**, never the absence of a list and never a bare `"*"`.
+- if `allowedDomains` contains `"*"`, the whitelist effectively allows everything: the
+ domain restriction is lifted for every host. It grants **no** private-IP override —
+ `"*"` names no host, which is the same intent as an empty list — so with `["*"]` the
+ SSRF guard still refuses private and internal addresses. To reach one, name it:
+ `["*", "10.0.0.5"]` keeps unrestricted navigation and permits that host.
- `security.allowedDomains` is the canonical config path. `security.idpi.allowedDomains` is still accepted when loading older config files, but new saves are normalized to `security.allowedDomains`
- `strictMode = true` blocks disallowed domains and suspicious content
- `strictMode = false` allows the request but emits warnings instead
diff --git a/internal/handlers/download_guard.go b/internal/handlers/download_guard.go
index 0f26590f..dbca2dfb 100644
--- a/internal/handlers/download_guard.go
+++ b/internal/handlers/download_guard.go
@@ -29,20 +29,22 @@ func newDownloadURLGuard(allowedDomains []string) *downloadURLGuard {
return &downloadURLGuard{allowedDomains: append([]string(nil), allowedDomains...)}
}
-func (g *downloadURLGuard) isHostAllowed(host string) bool {
- if len(g.allowedDomains) == 0 {
- return false
- }
+// explicitlyAllowsHost reports whether the operator named this host in
+// security.downloadAllowedDomains, which is what lets the dialler reach a private
+// address. It asks the one owner of that question rather than reading the
+// restriction predicate: "nothing blocked it" is not "the operator permitted it",
+// and under a bare "*" the two answers differ.
+func (g *downloadURLGuard) explicitlyAllowsHost(host string) bool {
host = netguard.NormalizeHost(host)
if host == "" {
return false
}
- return g.isDomainAllowed("https://" + host)
+ return idpi.DomainAllowed("https://"+host, config.IDPIConfig{Enabled: true}, g.allowedDomains)
}
-// isDomainAllowed reports whether rawURL's domain is on the configured
-// allowlist. Allowlisted domains bypass private-IP checks because they
-// are explicitly trusted by the operator (e.g. internal docker hosts).
+// isDomainAllowed reports whether rawURL passes the domain restriction. A bare "*"
+// passes every host here, unchanged: this answers what the download may fetch, not
+// what it may reach a private address for.
func (g *downloadURLGuard) isDomainAllowed(rawURL string) bool {
if len(g.allowedDomains) == 0 {
return false
diff --git a/internal/handlers/download_guard_test.go b/internal/handlers/download_guard_test.go
new file mode 100644
index 00000000..5f4e5d03
--- /dev/null
+++ b/internal/handlers/download_guard_test.go
@@ -0,0 +1,64 @@
+package handlers
+
+import (
+ "context"
+ "strings"
+ "testing"
+)
+
+// 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) {
+ const privateHost = "10.0.0.5"
+
+ for _, tc := range []struct {
+ name string
+ allowed []string
+ want bool
+ }{
+ {"a bare wildcard", []string{"*"}, false},
+ {"a wildcard beside an unrelated host", []string{"*", "example.com"}, false},
+ {"a wildcard beside the internal host", []string{"*", privateHost}, true},
+ {"the internal host alone", []string{privateHost}, true},
+ {"a wildcard subdomain", []string{"*.corp.example.com"}, false},
+ {"no list at all", nil, false},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ guard := newDownloadURLGuard(tc.allowed)
+ allowInternal := guard.explicitlyAllowsHost(privateHost)
+ if allowInternal != tc.want {
+ t.Fatalf("explicitlyAllowsHost(%v) = %v, want %v", tc.allowed, allowInternal, tc.want)
+ }
+
+ // The predicate matters only through the dialler that consumes it: a
+ // refused host must stop at the private-IP check, not at a connection.
+ _, err := resolveDownloadDialIPs(context.Background(), privateHost, allowInternal)
+ if tc.want {
+ if err != nil {
+ t.Errorf("the dialler refused a host the operator named: %v", err)
+ }
+ return
+ }
+ if err == nil || !strings.Contains(err.Error(), "blocked remote IP") {
+ t.Errorf("the dialler answered %v, want the private-IP refusal", err)
+ }
+ })
+ }
+}
+
+// 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"
+
+ if err := newDownloadURLGuard([]string{"*"}).Validate(unlisted); err != nil {
+ t.Errorf("a wildcard allowlist refused an unlisted public host: %v", err)
+ }
+ err := newDownloadURLGuard([]string{"listed.example"}).Validate(unlisted)
+ if err == nil || !strings.Contains(err.Error(), "downloadAllowedDomains") {
+ t.Errorf("a named allowlist admitted an unlisted host (%v); the row above would then prove nothing", err)
+ }
+}
diff --git a/internal/handlers/download_network.go b/internal/handlers/download_network.go
index 5e626457..9ce016b3 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.isHostAllowed(host)
+ allowInternal := validator != nil && validator.explicitlyAllowsHost(host)
ips, err := resolveDownloadDialIPs(ctx, host, allowInternal)
if err != nil {
return nil, err
diff --git a/internal/handlers/navigation_host_forms_test.go b/internal/handlers/navigation_host_forms_test.go
index 652a1792..4f63cc99 100644
--- a/internal/handlers/navigation_host_forms_test.go
+++ b/internal/handlers/navigation_host_forms_test.go
@@ -151,6 +151,9 @@ func TestAnEmptyAllowlistNeverGrantsThePrivateIPOverride(t *testing.T) {
{"idpi off, empty allowlist", false, nil, false},
{"idpi off, unrelated host listed", false, []string{"example.com"}, false},
{"idpi on, the internal host explicitly listed", true, []string{"10.0.0.5"}, true},
+ {"idpi on, a bare wildcard", true, []string{"*"}, false},
+ {"idpi on, a wildcard beside an unrelated host", true, []string{"*", "example.com"}, false},
+ {"idpi on, a wildcard beside the internal host", true, []string{"*", "10.0.0.5"}, true},
} {
t.Run(tc.name, func(t *testing.T) {
cfg := hostFormConfig(tc.allowed)
@@ -179,6 +182,31 @@ func TestAnEmptyAllowlistNeverGrantsThePrivateIPOverride(t *testing.T) {
}
}
+// Withdrawing the override from a bare "*" must not turn it into a restriction: its
+// documented meaning is that every host passes the domain check, and both paths that
+// consume the predicate still have to navigate anywhere. Without this, refusing "*"
+// outright would satisfy every row of the table above.
+func TestABareWildcardStillLiftsTheDomainRestriction(t *testing.T) {
+ h := New(&policyMockBridge{}, hostFormConfig([]string{"*"}), nil, nil, nil)
+
+ const publicTarget = "https://example.com/x"
+ w := httptest.NewRecorder()
+ if _, ok := h.validateNavigateTargets(w, httptest.NewRequest("GET", "/navigate", nil), "", publicTarget, h.Config); !ok {
+ t.Errorf("navigate refused a public host under a wildcard allowlist: %d %s", w.Code, w.Body.String())
+ }
+ if _, err := h.validateAuditTarget(publicTarget, h.Config); err != nil {
+ t.Errorf("audit-page refused a public host under a wildcard allowlist: %v", err)
+ }
+
+ // The control: a named list does restrict, so the rows above are the wildcard's
+ // doing rather than the domain check having stopped restricting anything.
+ restricted := New(&policyMockBridge{}, hostFormConfig([]string{"listed.example"}), nil, nil, nil)
+ w = httptest.NewRecorder()
+ if _, ok := restricted.validateNavigateTargets(w, httptest.NewRequest("GET", "/navigate", nil), "", publicTarget, restricted.Config); ok {
+ t.Error("navigate allowed an unlisted host under a named allowlist")
+ }
+}
+
// The spelling table above runs with IDPI off and no allowlist, deliberately, so it
// measures the spelling property rather than the allowlist override that used to sit
// in front of it. That leaves the configurations an operator actually runs
diff --git a/internal/idpi/domain.go b/internal/idpi/domain.go
index 7107390f..f95aaf61 100644
--- a/internal/idpi/domain.go
+++ b/internal/idpi/domain.go
@@ -2,6 +2,7 @@ package idpi
import (
"fmt"
+ "strings"
"github.com/pinchtab/pinchtab/internal/config"
"github.com/pinchtab/pinchtab/internal/security"
@@ -41,17 +42,40 @@ func CheckDomain(rawURL string, cfg config.IDPIConfig, allowedDomains []string)
}
// DomainAllowed reports whether rawURL's host matches an explicit allowedDomains
-// entry under an active IDPI domain allowlist. For an IDPI-independent check
-// callers should use security.HostAllowed directly.
+// entry under an active IDPI domain allowlist. Consumers feed it into navguard's
+// allowExplicitInternal, so it answers "did the operator name THIS host", never
+// "is this host permitted" — for the latter use security.HostAllowed.
+//
+// A bare "*" is dropped before matching: it denotes "anything", which is the same
+// intent as an empty list, and an empty list grants nothing. It stays a full match
+// for the domain RESTRICTION in CheckDomain — only the private-IP override is
+// withheld from it. "*.corp.example.com" still denotes a set of hosts and is kept.
func DomainAllowed(rawURL string, cfg config.IDPIConfig, allowedDomains []string) bool {
- if !cfg.Enabled || len(allowedDomains) == 0 || security.IsAllowedSpecialURL(rawURL) {
+ if !cfg.Enabled || security.IsAllowedSpecialURL(rawURL) {
+ return false
+ }
+ named := hostDenotingPatterns(allowedDomains)
+ if len(named) == 0 {
return false
}
host := security.ExtractHost(rawURL)
if host == "" {
return false
}
- return security.HostMatchesPatterns(host, allowedDomains)
+ return security.HostMatchesPatterns(host, named)
+}
+
+// hostDenotingPatterns drops the entries that name no host, so ["*", "example.com"]
+// still grants for example.com and grants nothing for anything else.
+func hostDenotingPatterns(allowedDomains []string) []string {
+ named := make([]string, 0, len(allowedDomains))
+ for _, pattern := range allowedDomains {
+ if strings.TrimSpace(pattern) == "*" {
+ continue
+ }
+ named = append(named, pattern)
+ }
+ return named
}
func makeResult(strictMode bool, reason string) CheckResult {
diff --git a/internal/idpi/domain_allowed_owner_test.go b/internal/idpi/domain_allowed_owner_test.go
index 7b598ce8..96fab00e 100644
--- a/internal/idpi/domain_allowed_owner_test.go
+++ b/internal/idpi/domain_allowed_owner_test.go
@@ -112,3 +112,55 @@ func TestTheShieldScanIsCalledOnlyWhereItAnswersItsOwnQuestion(t *testing.T) {
}
}
}
+
+// A bare "*" is a positive match against a non-empty list, so the empty-list rule
+// alone admits it — but it names no host. Written by an operator it means "do not
+// restrict me by domain", which is the intent an empty list expresses, and that
+// intent grants nothing. Two spellings of one intent must not get opposite answers
+// on private-IP protection.
+//
+// Two lists are deliberately NOT covered by this rule, and both exclusions are
+// properties of the key rather than of the code, so a later sweep should leave them
+// alone: security.attach.allowHosts (internal/bridge/runtime/cdp_url.go), whose only
+// purpose is to permit remote CDP attach — it has no restricting role, so "*" there
+// is unambiguous and documented as a full override — and RouteManager's
+// fulfillForgeryPermittedFor, which reads the allowlist to RESTRICT forgery and
+// grants no internal-address access at all.
+func TestABareWildcardGrantsNoExplicitAllowance(t *testing.T) {
+ const privateTarget = "https://10.0.0.5/x"
+ enabled := config.IDPIConfig{Enabled: true, StrictMode: true}
+
+ for _, tc := range []struct {
+ name string
+ allowed []string
+ want bool
+ }{
+ {"a bare wildcard", []string{"*"}, false},
+ {"a bare wildcard with whitespace", []string{" * "}, false},
+ {"a wildcard beside an unrelated host", []string{"*", "example.com"}, false},
+ {"a wildcard beside the target host", []string{"*", "10.0.0.5"}, true},
+ {"the target host alone", []string{"10.0.0.5"}, true},
+ {"a wildcard subdomain", []string{"*.corp.example.com"}, false},
+ {"no list at all", nil, false},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ if got := DomainAllowed(privateTarget, enabled, tc.allowed); got != tc.want {
+ t.Errorf("DomainAllowed(%v) = %v, want %v — this boolean is allowExplicitInternal, and only an entry that denotes a host may grant it", tc.allowed, got, tc.want)
+ }
+ if got := NewShieldGuard(enabled, tc.allowed).DomainAllowed(privateTarget); got != tc.want {
+ t.Errorf("the guard answers %v for %v; it must not keep a second answer to this question", got, tc.allowed)
+ }
+ })
+ }
+
+ // The withdrawal is scoped to the override. "*" still lifts the domain
+ // RESTRICTION for every host, which is the whole documented purpose of writing it.
+ for _, target := range []string{privateTarget, "https://anything.example/x"} {
+ if CheckDomain(target, enabled, []string{"*"}).Blocked {
+ t.Errorf("a bare wildcard blocked %s; the domain restriction it lifts is not this card's subject", target)
+ }
+ }
+ if !CheckDomain("https://unlisted.example/x", enabled, []string{"example.com"}).Blocked {
+ t.Error("the restriction admitted an unlisted host, so the row above proves nothing about the wildcard")
+ }
+}