Configure a proxy

What this guide covers

Oobee sends its browser traffic through a proxy server when one is configured. It reads the standard proxy environment variables, and on Windows and macOS it can also read the system proxy settings. This guide shows how to set a proxy, limit which domains use it, and use the experimental Cloudflare Worker proxy. It does not cover proxy setup on your network.

Prerequisites

Oobee installed. Refer to Install the portable Oobee.
The address of your proxy server, and its credentials if it needs them.
A terminal where you can set environment variables before you run a scan.

How Oobee chooses a proxy

Oobee uses the first of these sources that is set:

CF_WORKER_PROXY, the experimental Cloudflare Worker proxy.
FAMILY_DNS, which starts a local filtering proxy. Refer to Enable Safe Browsing and family DNS.
The proxy environment variables HTTP_PROXY, HTTPS_PROXY and ALL_PROXY.
The system proxy settings: the Windows registry on Windows, or scutil --proxy on macOS. Linux uses environment variables only.

Variable names are accepted in upper case or lower case.

Step 1: Set the proxy variables

Set the variables for your proxy before you run the scan. Use ALL_PROXY for a SOCKS5 proxy.

export HTTP_PROXY="http://<PROXY_HOST>:<PORT>"
export HTTPS_PROXY="http://<PROXY_HOST>:<PORT>"
export NO_PROXY="localhost,127.0.0.1,.example.com"

On Windows PowerShell, use $env:HTTPS_PROXY = "http://<PROXY_HOST>:<PORT>".

Variable	Use
`HTTP_PROXY`	Proxy for HTTP requests, for example `http://proxy.example.com:8080`
`HTTPS_PROXY`	Proxy for HTTPS requests
`ALL_PROXY`	Proxy for all requests, usually a SOCKS5 proxy such as `socks5://proxy.example.com:1080`
`NO_PROXY`	Comma-separated domains that skip the proxy
`PROXY_USERNAME`, `PROXY_PASSWORD`	Proxy credentials, if the proxy URL does not contain them. `HTTP_PROXY_USERNAME` and `HTTP_PROXY_PASSWORD` are also read.

A proxy URL can contain credentials in the form http://<USERNAME>:<PASSWORD>@<PROXY_HOST>:<PORT>.

Step 2: Limit which domains use the proxy

To send only some domains through the proxy and everything else direct, set INCLUDE_PROXY to a list of domain patterns separated by commas or semicolons. Patterns can use * wildcards.

export INCLUDE_PROXY="*.example.com,intranet.example.org"

INCLUDE_PROXY needs HTTP_PROXY, HTTPS_PROXY or ALL_PROXY to be set to a proxy address. If it is set together with NO_PROXY, Oobee ignores NO_PROXY and prints a warning.

Step 3: Run the scan

Run the scan in the same terminal. Oobee finds the proxy settings itself, so no command-line option is needed.

npm run cli -- -c website -u <WEBSITE_URL> -k "<YOUR_NAME>:<YOUR_EMAIL>"

Use the Cloudflare Worker proxy

Experimental. The Cloudflare Worker proxy may help unblock sites that block scans from your network. It can change without notice.

The Cloudflare Worker proxy sends browser traffic through a Cloudflare Worker that you deploy. Oobee starts a local SOCKS5 proxy that tunnels each connection to the Worker over a WebSocket. The browser’s TLS connection stays end to end with the target site, and DNS lookups happen inside the Worker. The repository contains a reference Worker in examples/cf-worker-proxy.example.js.

Variable	Description	Default
`CF_WORKER_PROXY`	URL of your Worker, for example `https://<YOUR_WORKER>.workers.dev`. Overrides `HTTP_PROXY`, `HTTPS_PROXY` and `ALL_PROXY`.	None
`CF_WORKER_PROXY_AUTH_TOKEN`	Sent as the `Authorization` header when Oobee opens the WebSocket to the Worker	None
`CF_WORKER_PROXY_PORT`	Local port for the SOCKS5 proxy. If the port is in use, Oobee tries the next ports up to 20 times.	`8877`
`CF_WORKER_PROXY_FORCE_TUNNEL_HOSTS`	Host patterns, with `*` wildcards, separated by commas or semicolons. Matching hosts are always sent through the Worker.	None

The Worker’s ?bypass-ips=1 address lists IP ranges that Oobee connects to directly instead of through the Worker. Refer to the comments in the reference Worker for its settings.

Constraints and limitations

Constraint	Detail
Source order	`CF_WORKER_PROXY` and `FAMILY_DNS` take precedence over `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` and system settings.
`INCLUDE_PROXY` and `NO_PROXY`	They cannot be combined. `INCLUDE_PROXY` wins.
`INCLUDE_PROXY` address	Needs a direct proxy address from `HTTP_PROXY`, `HTTPS_PROXY` or `ALL_PROXY`. Otherwise Oobee ignores it.
SOCKS5 and IPv6	Chrome may still make direct IPv6 connections when a SOCKS5 proxy is set. Turn off IPv6 on the host to avoid this.
Credentials	Credentials in a proxy URL are visible in your shell history and process list.
macOS credentials	If `scutil` gives a proxy user name but no password, Oobee may read the password from the Keychain and prompt you to allow it.
Experimental	`CF_WORKER_PROXY` is experimental.

Enable Safe Browsing and family DNS — block unsafe sites.
CLI options, environment variables and error codes — every variable.
Troubleshooting — scans that fail behind a proxy.

Operations

Enable Safe Browsing and family DNS