Localhost proxy + Chromium DNS overrides for local-dev scans against apps using Auth0 / Firebase / Clerk / Supabase

[VicenteSotoArmijo]

Problem

When I run Shannon against an app that's running on my dev machine, the auth layer breaks before the pentest even starts:

1. Auth SDKs hard-fail on non-localhost origins. Auth0, Firebase, Clerk, and Supabase all enforce a secure-origin check (HTTPS or localhost). Shannon's containerized browser visiting http://host.docker.internal:8888 triggers the check and the web-app crashes before the login form renders.
2. Subdomain-based API routing breaks too. When the web-app's API lives on api.localhost:3000, Chromium hardcodes the .localhost TLD to 127.0.0.1 and never consults /etc/hosts. Inside the worker container that resolves to nothing.

The current host.docker.internal workaround documented in the README only works for apps without these constraints. For everything else (most modern stacks), the workaround doesn't help.

Related: open issue #284 asks for the same kind of in-container DNS routing from a different angle (Traefik reverse-proxy setup).

Proposed solution

An opt-in network section in the YAML config that does three things:

1. In-container reverse proxy. Bind 127.0.0.1:<local_port> inside the worker container, forward to host.docker.internal:<remote_port>, rewrite the outgoing Host header. The browser sees a localhost origin (passing the secure-origin check); the dev server sees whatever host header you want (incl. subdomains).
2. Chromium DNS overrides. Write .playwright/cli.config.json into a per-workspace overlay that injects --host-resolver-rules=MAP api.localhost 127.0.0.1 so .localhost subdomains route through the proxy instead of Chromium's hardcoded 127.0.0.1.
3. --add-host plumbing. Pass each dns_overrides hostname as --add-host <host>:host-gateway so non-browser tools in the container (curl, fetch, the worker's own HTTP client) resolve them too.

Backward-compatible but disabled by default. Config-driven, no Docker image rebuild needed between scans. WebSocket upgrades (Vite HMR, webpack-dev-server) are forwarded transparently.

Example config:

network:
  localhost_proxy:
    enabled: "true"
    mappings:
      - local_port: "8888"
        remote_port: "8888"
        host_header: "localhost:8888"
      - local_port: "3000"
        remote_port: "3000"
        host_header: "api.localhost:3000"
  browser:
    dns_overrides:
      api.localhost: "127.0.0.1"

Hardening

Config validation rejects CRLF/NUL in host_header and remote_host (HTTP header smuggling), enforces 1-65535 port ranges, and warns when dns_overrides points to a loopback IP without any proxy mappings (Chromium would ECONNREFUSED).

Implementation status

I have a working branch with:

• ProxyManager (HTTP + WebSocket, real-socket tested with Vite HMR)
• writePlaywrightConfig (per-workspace overlay, doesn't touch user's repo)
• Config schema + validation + types
• CLI --add-host plumbing
• 42 unit tests + a real-Chromium integration test that guards against the cwd-vs-repo-path bug
• README section + commented example-config.yaml
• Validated end-to-end against a multi-port host stack inside the worker container ([PROXY] log lines visible in workflow.log, browser successfully reaches localhost:8888, upstream sees the rewritten Host header).

The diff is one commit: 26 files, +2674 / -55. No Fintoc-internal references; no formatting churn against main.

Question for maintainers

The README says external PRs aren't being accepted right now. I respect that, so I wanted to raise this here. Have you already thought about implementing something in this line?

Either way, would love to hear your thoughts on the approach.

[keygraphVarun]

I believe this fixes your issue:
#346
Please kindly open an issue if it doesn't work yet. Thanks for your feedback!