PAC-Like Request Callback

Use standard PAC routing plus BotBrowser’s trusted request callback for enterprise network policy workflows.

Prerequisites

• BotBrowser ENT Tier3 license for trusted request callback workflows.
• BotBrowser binary with a valid profile loaded via --bot-profile.
• A trusted PAC source that you control, such as a local file or controlled loopback service.

Quick Start

Configure PAC through the standard --proxy-pac-url flag:

chromium-browser \
  --bot-profile="path/to/profile.enc" \
  --proxy-pac-url=file:///absolute/path/to/proxy.pac \
  --user-data-dir="$(mktemp -d)"

For local development, a controlled loopback PAC server is also supported:

chromium-browser \
  --bot-profile="path/to/profile.enc" \
  --proxy-pac-url=http://127.0.0.1:8080/proxy.pac \
  --user-data-dir="$(mktemp -d)"

Standard PAC Routing

Standard PAC scripts continue to use the normal FindProxyForURL(url, host) function:

function FindProxyForURL(url, host) {
  if (dnsDomainIs(host, "example.internal")) {
    return "DIRECT";
  }
  return "SOCKS5 proxy.example.com:1080";
}

Use standard PAC routing when you only need proxy selection by URL or hostname.

BotBrowser Request Callback

Approved ENT Tier3 profiles can also define a BotBrowser callback in the same trusted PAC script:

function BotBrowserFindProxyForRequest(url, host, method, headersB64, bodyB64, bodyState) {
  if (method === "POST" && dnsDomainIs(host, "api.example.test")) {
    return "CAPTURE; CAPTURE_FILE /var/botbrowser/captures/api.jsonl; CAPTURE_TAG api-post; CONTINUE";
  }
  if (shExpMatch(url, "https://media.example.test/*")) {
    return "SOCKS5 media-user:media-pass@media-proxy.example.net:1080";
  }
  if (dnsDomainIs(host, "static.example.test")) {
    return "HTTPS static-proxy.example.net:8443";
  }
  return "CONTINUE";
}

This callback is BotBrowser-specific. It does not replace standard PAC routing. FindProxyForURL(url, host) continues to handle normal proxy selection. When the BotBrowser callback returns CONTINUE or no valid routing result, routing falls back to standard PAC behavior. A valid standard PAC route or synthetic response applies to the current request.

Use this workflow when request policy should stay in the browser network path. CDP-level request interception can interrupt HTTP/2 connection and stream continuity in some automation workflows. A trusted PAC callback keeps policy decisions with PAC routing, helping selected requests continue, stop, capture, or use different PAC routes without pausing every request in the automation layer.

Return values can be combined with semicolons:

Capture records are written only when CAPTURE and CAPTURE_FILE <path> are returned together. CAPTURE_FILE <path> without CAPTURE does not write a capture record. BLOCK can be used by itself. CAPTURE; CAPTURE_FILE <path>; BLOCK writes the capture record and then blocks the request.

Standard PAC routes may include proxy credentials, for example SOCKS5 user:pass@proxy.example.com:1080. Credentials remain part of the proxy route and are not sent to the destination server.

When commands are combined, capture is written first. RESPONSE or RESPONSE_FILE then completes the request and takes priority over BLOCK and proxy routing. Without a response, BLOCK takes priority over a proxy result. Invalid response input fails closed and is not sent to the destination or proxy.

Synthetic Responses

RESPONSE accepts a complete raw HTTP response encoded as base64. The response must include a status line, headers, a blank line, and an optional body. This is useful for controlled health endpoints, local fixtures, and request policy workflows that should remain inside the browser network path.

function BotBrowserFindProxyForRequest(url, host, method, headersB64, bodyB64, bodyState) {
  if (shExpMatch(url, "https://status.example.test/browser-ready")) {
    return "RESPONSE SFRUUC8xLjEgMjAwIE9LDQpDb250ZW50LVR5cGU6IHRleHQvcGxhaW4NCg0Kb2s=";
  }
  return "CONTINUE";
}

RESPONSE_FILE reads the same raw HTTP response format from an approved absolute local path:

function BotBrowserFindProxyForRequest(url, host, method, headersB64, bodyB64, bodyState) {
  if (shExpMatch(url, "https://fixtures.example.test/*")) {
    return "RESPONSE_FILE /var/botbrowser/responses/fixture.http";
  }
  return "CONTINUE";
}

Synthetic responses are restricted to approved profiles using file: or data: PAC sources. HTTP(S) PAC sources can continue to route, capture, and block requests, but cannot return RESPONSE or RESPONSE_FILE. Malformed, oversized, unsafe, redirect, or otherwise unsupported response inputs fail closed. RESPONSE_FILE requires an approved absolute local path.

Trusted Sources

The request callback is available only for approved profiles and explicit PAC sources:

• file:// PAC files.
• data: PAC URLs.
• Loopback HTTP(S) PAC services.
• Explicit remote HTTP(S) PAC services that your team controls.

PAC auto-detect and WPAD should be used only for standard PAC routing. They do not receive the BotBrowser request callback.

Synthetic responses have a narrower source policy than the callback itself: use file: or data: PAC sources for RESPONSE and RESPONSE_FILE.

Enterprise Request Policy

ENT Tier3 profiles can enable trusted request callback workflows for approved deployments. Standard PAC routing remains unchanged; the BotBrowser callback adds request-aware policy handling for explicit PAC sources.

Recommended operating model:

• Use only PAC files or PAC services that your team controls.
• Prefer file:// or loopback PAC URLs for local automation workers.
• Use HTTPS when the PAC source is remote.
• Keep PAC deployment tied to the same profile, proxy, and user data directory policy as the browser session.
• Avoid PAC auto-detect/WPAD for request callback workflows.

For setup templates and profile enablement, use the enterprise support channel.

Common Scenarios

Keep a fixed proxy for most traffic

function FindProxyForURL(url, host) {
  return "SOCKS5 proxy.example.com:1080";
}

Bypass known internal hosts

function FindProxyForURL(url, host) {
  if (shExpMatch(host, "*.internal.example")) {
    return "DIRECT";
  }
  return "HTTPS proxy.example.com:8443";
}

Route selected requests by URL

function FindProxyForURL(url, host) {
  return "SOCKS5 default-proxy.example.net:1080";
}
 
function BotBrowserFindProxyForRequest(url, host, method, headersB64, bodyB64, bodyState) {
  if (shExpMatch(url, "https://media.example.test/*")) {
    return "SOCKS5 media-user:media-pass@media-proxy.example.net:1080";
  }
  if (dnsDomainIs(host, "static.example.test")) {
    return "HTTPS static-user:static-pass@static-proxy.example.net:8443";
  }
  return "CONTINUE";
}

CONTINUE keeps the default FindProxyForURL route. Returning a standard PAC route from the BotBrowser callback applies that route only to the current request.

Return a controlled response by URL

function FindProxyForURL(url, host) {
  return "SOCKS5 default-user:default-pass@proxy.example.net:1080";
}
 
function BotBrowserFindProxyForRequest(url, host, method, headersB64, bodyB64, bodyState) {
  if (shExpMatch(url, "https://status.example.test/browser-ready")) {
    return "RESPONSE SFRUUC8xLjEgMjAwIE9LDQpDb250ZW50LVR5cGU6IHRleHQvcGxhaW4NCg0Kb2s=";
  }
  if (shExpMatch(url, "https://fixtures.example.test/*")) {
    return "RESPONSE_FILE /var/botbrowser/responses/fixture.http";
  }
  return "CONTINUE";
}

Combine PAC with SOCKS5 UDP policy

PAC can select SOCKS5 routes for TCP traffic. QUIC/STUN UDP behavior still follows BotBrowser’s UDP-over-SOCKS5 support and standard browser flags. If the deployment should avoid QUIC/HTTP/3, add --disable-quic:

--proxy-pac-url=file:///absolute/path/to/proxy.pac
--disable-quic

Troubleshooting / FAQ

Next Steps

• Proxy Configuration. Basic proxy setup and supported protocols.
• UDP over SOCKS5. QUIC/STUN tunneling behavior and --disable-quic.
• Proxy Selective Routing. Regex-based bypass rules.
• Per-Context Proxy. Assign different proxies to different contexts.
• CLI Flags Reference. Complete list of all available flags.

Related documentation: Advanced Features: Network Fingerprint Control

Legal Disclaimer & Terms of Use | Responsible Use Guidelines. BotBrowser is for authorized fingerprint protection and privacy research only.