Enable Safe Browsing and family DNS
What this guide covers
Oobee has two optional protections for scans of sites you do not control. Google Safe Browsing blocks pages that Google lists as phishing, malware or unwanted software. Family DNS refuses host names that a family-filtering DNS resolver blocks. Pages that Safe Browsing blocks appear in the report as “Blocked by Safe Browsing”. This guide shows how to turn on each protection. It does not cover scanning your own site.
| Protection | Blocks | Turned on by |
|---|---|---|
| Safe Browsing | Phishing, malware and unwanted software pages | GOOGLE_SAFE_BROWSING |
| Family DNS | Host names blocked by family-filtering DNS | FAMILY_DNS |
Prerequisites
- Oobee installed. Refer to Install the portable Oobee.
- For Safe Browsing: Google Chrome installed, not Chromium or Edge.
- For Safe Browsing in Docker: an
amd64orarm64image, built from the OobeeDockerfile. - Internet access for Chrome to download the Safe Browsing database on first use.
Step 1: Turn on Safe Browsing
Set GOOGLE_SAFE_BROWSING to any value before you run the scan. Oobee then uses Google Chrome with Safe Browsing’s standard protection.
export GOOGLE_SAFE_BROWSING=1
npm run cli -- -c intelligent -u <WEBSITE_URL> -b chrome -k "<YOUR_NAME>:<YOUR_EMAIL>"The first scan prepares a Safe Browsing database. Oobee copies one from your Chrome profile if it finds it. Otherwise it starts Chrome and waits for the download, for up to 300000 ms by default. Set SB_DB_TIMEOUT_MS to change this. Oobee keeps the prepared database in ~/.oobee/safe-browsing-profile and reuses it. Set SB_PROFILE_DIR to use another folder.
Step 2: Use Safe Browsing in Docker
The Oobee Dockerfile installs Google Chrome and prepares the Safe Browsing database while the image is built, in /data/chrome-profile. Scans in the container then start without waiting for a download. On architectures other than amd64 and arm64, the build skips both steps and Safe Browsing is not available. Set the variable when you run the container:
docker run -e GOOGLE_SAFE_BROWSING=1 <IMAGE_NAME> npm run cli -- -c intelligent -u <WEBSITE_URL> -k "<YOUR_NAME>:<YOUR_EMAIL>"To build an amd64 image on a machine with a different architecture, add --platform linux/amd64 to docker build.
Step 3: Turn on family DNS
Set FAMILY_DNS to 1, true or yes. Oobee starts a local SOCKS5 proxy on your machine and checks each host name against family-filtering DNS before the browser connects. Oobee refuses a host name that the resolver reports as blocked.
export FAMILY_DNS=1
npm run cli -- -c intelligent -u <WEBSITE_URL> -k "<YOUR_NAME>:<YOUR_EMAIL>"Oobee asks three resolvers in order and moves to the next one only if the one before it gives no answer:
- Cloudflare Families,
family.cloudflare-dns.com - ControlD Family,
freedns.controld.com/family - AdGuard Family,
family.adguard-dns.com
An answer from a resolver ends the search, so a later resolver cannot overrule an earlier one. The older variable CF_FAMILY_DNS still works but is deprecated. Oobee ignores it when FAMILY_DNS is set, so FAMILY_DNS=0 turns the filter off even if CF_FAMILY_DNS=1 is set.
Constraints and limitations
| Constraint | Detail |
|---|---|
| Browser | Safe Browsing needs Google Chrome. Chromium and Edge do not support it. |
| Safe Browsing platforms | On macOS and Windows, Oobee copies the database from your Chrome profile. In Docker on Linux, it uses a pre-warmed Chrome. |
| First scan | The first scan can wait several minutes for the database download. |
| Proxy | Family DNS does not work with HTTP_PROXY, HTTPS_PROXY or ALL_PROXY. It uses its own local proxy. It can be combined with CF_WORKER_PROXY. |
| Family DNS caching | Oobee caches a resolver answer for 60 seconds. It caches a host name that no resolver answered for 5 seconds. |
| Blocked pages | A blocked page is listed under Pages Not Scanned with the reason “Blocked by Safe Browsing”. Refer to Scan report files. |
Related content
- Configure a proxy — proxy sources and the Cloudflare Worker proxy.
- CLI options, environment variables and error codes —
GOOGLE_SAFE_BROWSING,FAMILY_DNS,SB_*variables. - Run Oobee in CI/CD — the Docker image.
