DNS Leak Prevention

Prevent DNS leak scenarios by controlling whether domain resolution uses local DNS or the proxy path.

Prerequisites

• BotBrowser binary with a valid profile loaded via --bot-profile.
• A proxy server configured via --proxy-server.

Quick Start

Enable BotBrowser’s built-in DNS resolver with the --bot-local-dns flag. This keeps DNS resolution local and independent of the proxy provider’s DNS behavior:

import { chromium } from "playwright-core";
 
const browser = await chromium.launch({
  executablePath: process.env.BOTBROWSER_EXEC_PATH,
  headless: true,
  args: [
    `--bot-profile=${process.env.BOT_PROFILE_PATH}`,
    "--proxy-server=socks5://user:pass@proxy.example.com:1080",
    "--bot-local-dns",
  ],
});
 
const page = await browser.newPage();
await page.goto("https://example.com");
await browser.close();

How It Works

How BotBrowser Prevents DNS Leaks

When using a proxy, DNS queries can leak outside the tunnel and expose browsing activity. BotBrowser prevents this across all DNS resolution paths, including prefetch queries.

BotBrowser provides two layers of DNS leak protection:

SOCKS5H protocol. When you use socks5h:// as the proxy protocol, all DNS resolution happens on the proxy server side. The hostname is sent through the tunnel and resolved remotely. This is the simplest way to prevent DNS leaks:

--proxy-server=socks5h://user:pass@proxy.example.com:1080

Local DNS resolver (--bot-local-dns, ENT Tier1). This flag enables BotBrowser’s built-in DNS resolver that keeps DNS resolution local instead of relying on the proxy provider’s DNS behavior. This is useful when:

• The proxy provider blocks or rewrites DNS lookups.
• You want to control DNS resolution behavior independently from the proxy.
• You need consistent DNS behavior across different proxy providers.

--bot-local-dns

DNS prefetch protection. BotBrowser routes DNS prefetch queries through the same proxy tunnel to prevent leaking outside the configured path.

Common Scenarios

Using SOCKS5H for remote DNS resolution

The simplest approach. Switch from socks5:// to socks5h://:

# DNS resolved locally (potential leak)
--proxy-server=socks5://user:pass@proxy.example.com:1080
 
# DNS resolved through the proxy tunnel (protected)
--proxy-server=socks5h://user:pass@proxy.example.com:1080

With socks5h, the target hostname is never visible to your local DNS resolver. The proxy server handles all name resolution.

Combining with local DNS resolver

For maximum control, combine socks5h with --bot-local-dns:

--proxy-server=socks5h://user:pass@proxy.example.com:1080 --bot-local-dns

This gives you local DNS resolution behavior while keeping queries within the proxy tunnel.

HTTP proxy DNS behavior

HTTP and HTTPS proxies use the CONNECT method for tunneling. DNS resolution for the target host is performed by the proxy server, not locally. DNS leaks with HTTP proxies are less common, but DNS prefetch can still cause leaks for link targets found on pages:

--proxy-server=http://user:pass@proxy.example.com:8080

Verifying DNS Protection

To verify protection is active, visit BrowserLeaks DNS test  or DNS Leak Test  and confirm that all reported DNS servers match your proxy region, not your local ISP.

Troubleshooting / FAQ

Next Steps

• Proxy Configuration. Supported protocols including SOCKS5H.
• WebRTC Leak Prevention. Prevent real IP disclosure through WebRTC.
• Port Protection. Protect local service ports from being scanned.
• UDP over SOCKS5. Tunnel UDP traffic through the proxy.
• CLI Flags Reference. Complete list of all available flags.

Related documentation: Advanced Features: Network Fingerprint Control | CLI Flags Reference

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