Skip to content

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.md
index 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.md
index 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.go
index 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.go
index 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, boo
return 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 downloadHostBlockedError
switch {
+ 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.go
index 5f4e5d03..43361440 100644
--- a/internal/handlers/download_guard_test.go
+++ b/internal/handlers/download_guard_test.go
@@ -2,8 +2,15 @@ package handlers
import (
"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)
+ }
+ }
+}