High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
fix(handlers): consult the download allowlist before the loopback rejection so a named loopback host is reachable, and refuse a blocked host with code download_host_blocked plus the config set remedy (PIN-280)
Luigi Agostie643c70f0f30
diff --git a/docs/endpoints.md b/docs/endpoints.mdindex b5ddd511..2afaf83e 100644--- a/docs/endpoints.md+++ b/docs/endpoints.md@@ -574,7 +574,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"]`.+- `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.- 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 dd4243f2..82a2cc1a 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.+- `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`.- `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.go b/internal/handlers/download.goindex fa797d2d..6de05d03 100644--- a/internal/handlers/download.go+++ b/internal/handlers/download.go@@ -45,7 +45,7 @@ func (h *Handlers) HandleDownload(w http.ResponseWriter, r *http.Request) {}validator := newDownloadURLGuard(allowed)if err := validator.Validate(dlURL); err != nil {- httpx.Error(w, 400, fmt.Errorf("unsafe URL: %w", err))+ writeDownloadGuardError(w, fmt.Errorf("unsafe URL: %w", err), maxDownloadBytes)return}diff --git a/internal/handlers/download_guard.go b/internal/handlers/download_guard.goindex dbca2dfb..a7f3c567 100644--- a/internal/handlers/download_guard.go+++ b/internal/handlers/download_guard.go@@ -16,11 +16,24 @@ import ("github.com/pinchtab/pinchtab/internal/httpx""github.com/pinchtab/pinchtab/internal/idpi""github.com/pinchtab/pinchtab/internal/netguard"+ "github.com/pinchtab/pinchtab/internal/remedy")// Aliased to the bridge sentinel so errors from either layer classify identically.var errDownloadTooLarge = bridge.ErrDownloadTooLarge+const codeDownloadHostBlocked = "download_host_blocked"++var errDownloadHostBlocked = errors.New("internal or blocked host")++var downloadHostGrant = remedy.Declare(+ `pinchtab config set security.downloadAllowedDomains "$(pinchtab config get security.downloadAllowedDomains),<host>" && pinchtab server restart`)++type downloadHostBlockedError struct{ host string }++func (e downloadHostBlockedError) Error() string { return errDownloadHostBlocked.Error() }+func (e downloadHostBlockedError) Unwrap() error { return errDownloadHostBlocked }+type downloadURLGuard struct {allowedDomains []string}@@ -29,11 +42,6 @@ func newDownloadURLGuard(allowedDomains []string) *downloadURLGuard {return &downloadURLGuard{allowedDomains: append([]string(nil), allowedDomains...)}}-// 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 == "" {@@ -42,9 +50,6 @@ func (g *downloadURLGuard) explicitlyAllowsHost(host string) bool {return idpi.DomainAllowed("https://"+host, config.IDPIConfig{Enabled: true}, g.allowedDomains)}-// 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@@ -67,8 +72,14 @@ func (g *downloadURLGuard) Validate(rawURL string) error {}host := netguard.NormalizeHost(parsed.Hostname())- if host == "" || netguard.IsLocalHost(host) {- return fmt.Errorf("internal or blocked host")+ if host == "" {+ return downloadHostBlockedError{}+ }+ if g.explicitlyAllowsHost(host) {+ return nil+ }+ if netguard.IsLocalHost(host) {+ return downloadHostBlockedError{host: host}}if len(g.allowedDomains) > 0 {@@ -204,11 +215,27 @@ func parseContentLengthHeaderGeneric(headers map[string]interface{}) (int64, booreturn parseContentLengthHeader(headers)}+func downloadHostBlockedDetails(host string) map[string]any {+ if host == "" {+ return nil+ }+ details := remedy.Details(+ "Name the host in security.downloadAllowedDomains to let the download endpoint reach it; a loopback entry exposes services on the server's own machine.",+ downloadHostGrant.Fill(host))+ details["host"] = host+ details["setting"] = "security.downloadAllowedDomains"+ return details+}+func writeDownloadGuardError(w http.ResponseWriter, err error, maxBytes int) bool {if err == nil {return false}+ var blocked downloadHostBlockedErrorswitch {+ case errors.As(err, &blocked):+ httpx.ErrorCode(w, http.StatusBadRequest, codeDownloadHostBlocked, err.Error(), false,+ downloadHostBlockedDetails(blocked.host))case errors.Is(err, bridge.ErrTooManyRedirects):httpx.Error(w, 422, fmt.Errorf("download: %w", err))case errors.Is(err, errDownloadTooLarge):diff --git a/internal/handlers/download_guard_test.go b/internal/handlers/download_guard_test.goindex 5f4e5d03..43361440 100644--- a/internal/handlers/download_guard_test.go+++ b/internal/handlers/download_guard_test.go@@ -2,8 +2,15 @@ package handlersimport ("context"+ "encoding/json"+ "errors"+ "net"+ "net/http"+ "net/http/httptest""strings""testing"++ "github.com/pinchtab/pinchtab/internal/config")// The download dialler asks the guard whether the operator named this host, and a@@ -62,3 +69,80 @@ func TestABareWildcardStillLiftsTheDownloadDomainRestriction(t *testing.T) {t.Errorf("a named allowlist admitted an unlisted host (%v); the row above would then prove nothing", err)}}++func TestAnAllowlistedLoopbackHostGetsTheSameVerdictFromValidateAndTheDialler(t *testing.T) {+ stubDownloadHostResolution(t, func(ctx context.Context, network, host string) ([]net.IP, error) {+ if host == "localhost" {+ return []net.IP{net.ParseIP("127.0.0.1")}, nil+ }+ return nil, errors.New("not found")+ })++ for _, tc := range []struct {+ name string+ allowed []string+ host string+ wantAllowed bool+ wantBlocked bool+ }{+ {"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 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},+ {"private host absent from a named list", []string{"example.com"}, "10.0.0.5", false, false},+ } {+ t.Run(tc.name, func(t *testing.T) {+ guard := newDownloadURLGuard(tc.allowed)+ err := guard.Validate("http://" + tc.host + ":18791/dl.html")+ if (err == nil) != tc.wantAllowed {+ t.Fatalf("Validate answered %v, want allowed=%v", err, tc.wantAllowed)+ }+ 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))+ if (dialErr == nil) != tc.wantAllowed {+ t.Fatalf("the dialler answered %v while Validate answered %v; the two layers must agree", dialErr, err)+ }+ })+ }+}++func TestABlockedDownloadHostRefusalNamesTheSettingAndTheRemedy(t *testing.T) {+ h := New(&mockBridge{}, &config.RuntimeConfig{AllowDownload: true}, nil, nil, nil)+ req := httptest.NewRequest("GET", "/download?url=http://127.0.0.1:18791/dl.html", nil)+ w := httptest.NewRecorder()+ h.HandleDownload(w, req)+ if w.Code != http.StatusBadRequest {+ t.Fatalf("status %d, want 400: %s", w.Code, w.Body.String())+ }+ var body struct {+ Code string `json:"code"`+ Error string `json:"error"`+ Details struct {+ Host string `json:"host"`+ Setting string `json:"setting"`+ Remedy string `json:"remedy"`+ } `json:"details"`+ }+ if err := json.Unmarshal(w.Body.Bytes(), &body); err != nil {+ t.Fatalf("decode: %v: %s", err, w.Body.String())+ }+ if body.Code != codeDownloadHostBlocked {+ t.Errorf("code %q, want %q", body.Code, codeDownloadHostBlocked)+ }+ if !strings.Contains(body.Error, "internal or blocked host") {+ t.Errorf("error %q lost the refusal", body.Error)+ }+ if body.Details.Host != "127.0.0.1" || body.Details.Setting != "security.downloadAllowedDomains" {+ t.Errorf("details name host %q setting %q", body.Details.Host, body.Details.Setting)+ }+ for _, want := range []string{"config set security.downloadAllowedDomains", "127.0.0.1", "server restart"} {+ if !strings.Contains(body.Details.Remedy, want) {+ t.Errorf("remedy %q lacks %q", body.Details.Remedy, want)+ }+ }+}