GProxy: PAC File for Automatic Proxy Configuration

A Proxy Auto-Configuration (PAC) file is a JavaScript file that web browsers and other user agents execute to determine which proxy server, if any, to use for a given URL. This mechanism allows for dynamic and granular control over how client traffic is routed through a proxy infrastructure.

Understanding PAC Files

A PAC file centralizes proxy configuration logic on a web server, eliminating the need for manual client-side proxy settings. When a client is configured to use a PAC file, it downloads and executes the script before each HTTP/HTTPS request. The script's primary function, FindProxyForURL(url, host), returns a string indicating whether to connect directly, use a specific proxy, or use a SOCKS proxy.

Benefits of Using PAC Files

Implementing PAC files offers several operational advantages:

Granular Control: Define specific routing rules based on URL patterns, hostnames, IP addresses, time of day, or network location.
Load Balancing: Distribute traffic across multiple proxy servers to prevent overload.
Failover: Specify alternative proxy servers in case the primary one is unavailable, enhancing reliability.
Bypass Specific Traffic: Direct certain internal or trusted domains to bypass the proxy entirely, reducing latency and resource consumption.
Simplified Client Configuration: Clients only need the URL of the PAC file, simplifying deployment and updates. Changes to proxy logic are made once on the server, not on each client.

PAC File Structure and Syntax

A PAC file is a plain text file written in JavaScript, typically named proxy.pac or wpad.dat. The core of a PAC file is the FindProxyForURL(url, host) function, which must be present.

`FindProxyForURL(url, host)` Function

This function takes two arguments:
* url: The full URL of the object being requested (e.g., http://www.example.com/index.html).
* host: The hostname extracted from the URL (e.g., www.example.com).

The function must return a string value:

DIRECT: Connect directly to the destination without using a proxy.
PROXY <host>:<port>: Use the specified HTTP proxy server.
SOCKS <host>:<port>: Use the specified SOCKS proxy server.
Multiple options: Separate multiple proxy servers or a proxy and direct connection with semicolons (e.g., PROXY proxy1.example.com:8080; PROXY proxy2.example.com:8080; DIRECT). The client attempts connections in the order specified.

Common JavaScript Functions within PAC Files

Standard JavaScript functions are available, alongside several browser-specific functions designed for proxy auto-configuration:

isPlainHostName(host): Returns true if host does not contain a domain name (e.g., localhost, intranet-server).
dnsDomainIs(host, domain): Returns true if host belongs to domain (e.g., dnsDomainIs("www.example.com", ".example.com")).
shExpMatch(str, pattern): Returns true if str matches pattern using shell expression matching (e.g., shExpMatch("http://www.example.com/index.html", "http://*.example.com/*")).
isInNet(host, pattern, mask): Returns true if the IP address of host is within the specified IP network pattern and mask (e.g., isInNet(host, "192.168.1.0", "255.255.255.0")). host can be a hostname or IP address.
myIpAddress(): Returns the IP address of the machine running the browser. Useful for location-based proxy decisions.
dnsResolve(host): Resolves the hostname host to an IP address. Returns an empty string if resolution fails.
weekdayRange(wd1, wd2, gmt): Returns true if the current weekday is in the specified range. wd1, wd2 are abbreviations (e.g., "MON", "FRI"). gmt is optional for GMT time.
dateRange(day1, month1, year1, day2, month2, year2, gmt): Returns true if the current date is in the specified range.
timeRange(hour1, min1, sec1, hour2, min2, sec2, gmt): Returns true if the current time is in the specified range.

Example PAC File

This example demonstrates bypassing internal domains, routing specific traffic, and implementing failover.

function FindProxyForURL(url, host) {
    // Define your proxy servers
    var PRIMARY_PROXY = "PROXY proxy.example.com:8080";
    var SECONDARY_PROXY = "PROXY backup-proxy.example.com:8080";
    var SOCKS_PROXY = "SOCKS socks.example.com:1080";

    // 1. Direct connection for local hosts and internal domains
    // Bypass proxy for plain hostnames (e.g., "localhost", "intranet-server")
    if (isPlainHostName(host)) {
        return "DIRECT";
    }

    // Bypass proxy for specific internal domain
    if (dnsDomainIs(host, ".internal-domain.com")) {
        return "DIRECT";
    }

    // Bypass proxy for specific internal IP ranges
    // Note: myIpAddress() returns the client's IP. This checks if the *destination* is internal.
    // For checking client's IP, use myIpAddress() and isInNet.
    if (isInNet(dnsResolve(host), "10.0.0.0", "255.0.0.0") ||
        isInNet(dnsResolve(host), "172.16.0.0", "255.240.0.0") ||
        isInNet(dnsResolve(host), "192.168.0.0", "255.255.0.0")) {
        return "DIRECT";
    }

    // 2. Use SOCKS proxy for specific applications or protocols
    // Example: Route all FTP traffic through a SOCKS proxy
    if (url.substring(0, 4) == "ftp:") {
        return SOCKS_PROXY;
    }

    // 3. Route specific external domains through a primary proxy with failover
    // Example: Route traffic to partner-site.com through the primary proxy,
    // with a fallback to a secondary proxy.
    if (dnsDomainIs(host, ".partner-site.com")) {
        return PRIMARY_PROXY + "; " + SECONDARY_PROXY;
    }

    // 4. Block specific URLs (by returning a non-existent proxy or an error)
    // Note: Some browsers might treat "PROXY 0.0.0.0:0" as a block.
    // A more robust blocking mechanism is typically handled by the proxy itself.
    if (shExpMatch(url, "*bad-site.com*")) {
        // Return a non-existent proxy to effectively block, or use a specific blocking proxy
        return "PROXY 127.0.0.1:1"; // Or a dedicated blocking proxy
    }

    // 5. Default rule: All other traffic goes through the primary proxy with failover
    return PRIMARY_PROXY + "; " + SECONDARY_PROXY + "; DIRECT";
}

Deployment and Distribution

For clients to use a PAC file, they must be configured to retrieve it.

Via HTTP/HTTPS Server

The most common method is to host the PAC file on a standard web server (Apache, Nginx, IIS) and configure client browsers or operating systems with its URL.
* Server Configuration: Ensure the server serves the PAC file with the correct MIME type: application/x-ns-proxy-autoconfig.
* Client Configuration: In browser settings (or OS network settings), specify the "Use automatic proxy configuration script" option and provide the full URL (e.g., http://proxyconfig.example.com/proxy.pac).

Web Proxy Auto-Discovery Protocol (WPAD)

WPAD allows clients to automatically discover the PAC file URL without manual configuration. This typically involves:
1. DNS: Creating a DNS entry for wpad.<domain> that points to the web server hosting wpad.dat.
2. DHCP: Configuring a DHCP option (option 252) to provide the PAC file URL.

While convenient, WPAD has security implications (e.g., potential for malicious WPAD servers) and is often disabled or used cautiously. Direct URL configuration is generally preferred for security and explicit control.

Group Policy Objects (GPO) for Windows

In Windows domains, PAC file URLs can be centrally distributed to client machines using Group Policy:
* Navigate to User Configuration > Policies > Windows Settings > Internet Explorer Maintenance > Connection > Proxy Settings.
* Enable "Automatic configuration" and provide the PAC file URL.

Troubleshooting PAC Files

Issues with PAC files often stem from syntax errors, caching, or network problems.

Syntax Errors: Even minor JavaScript errors can prevent the PAC file from functioning. Use a JavaScript linter or a dedicated PAC file validator. Browsers may log errors in their developer console (e.g., F12 in Chrome/Firefox).
Incorrect MIME Type: If the web server serves the PAC file with an incorrect MIME type, clients may not process it correctly. Verify application/x-ns-proxy-autoconfig.
Caching Issues: Browsers aggressively cache PAC files. When making changes, clear browser cache or force a refresh (e.g., Ctrl+F5). Some browsers offer an option to disable PAC file caching for debugging.
Network Accessibility: Ensure the client can reach the web server hosting the PAC file. Verify DNS resolution and firewall rules.
FindProxyForURL Function: Confirm the function FindProxyForURL(url, host) is correctly defined and returns valid proxy strings.
Testing Tools: Browser developer tools (Network tab) can show which proxy was used for a request. Online PAC file testers can simulate requests against your script.

PAC File vs. Other Proxy Configuration Methods

Feature	PAC File	Direct Proxy Settings	WPAD
Configuration Method	JavaScript script URL	Manual IP/Port entry	Auto-discovery via DNS/DHCP
Granular Control	High (logic-based)	Low (all traffic goes to one proxy or direct)	High (uses PAC file)
Failover/Load Balancing	Yes (built into script logic)	No (single proxy)	Yes (built into PAC file logic)
Bypass Rules	Yes (built into script logic)	Manual exclusions list	Yes (built into PAC file logic)
Deployment Complexity	Moderate (host file on web server, configure URL)	Low (manual per client)	High (DNS/DHCP configuration, web server)
Maintenance	Centralized (edit script on server)	Decentralized (manual per client)	Centralized (edit script on server, DNS/DHCP)
Security Considerations	Script injection, unencrypted distribution	Basic	DNS/DHCP spoofing (higher risk), script injection

Security Considerations

Integrity: PAC files contain sensitive routing information. Ensure the PAC file is hosted on a secure, trusted web server and delivered over HTTPS to prevent tampering or interception during download.
Malicious Scripts: A compromised PAC file can redirect client traffic to malicious proxies, facilitating man-in-the-middle attacks, credential harvesting, or data exfiltration. Only use PAC files from trusted sources.
Information Disclosure: Avoid including sensitive internal network details in PAC files that are publicly accessible. While the file itself is code, its logic can reveal network topology.
WPAD Vulnerabilities: The automatic discovery mechanism of WPAD can be exploited if an attacker can control DNS or DHCP responses, directing clients to a malicious WPAD server. Use WPAD with caution and appropriate security measures.

Analysis & Check

Security & Network

Generators

9 tools

PAC File