DOCSEARCHbyAlgolia
Submit Docs

ProxyBridge Documentation

repository·master·Indexed 26 days ago

https://github.com/interceptsuite/proxybridge

A lightweight, open-source universal proxy client for Windows, macOS, and Linux that provides transparent proxy routing. It allows users to redirect TCP and UDP traffic from specific processes through SOCKS5 or HTTP proxies, enabling compatibility with proxy-unaware applications. Features include a CLI and GUI for rule management, support for process-based routing, and the ability to block or direct traffic.

Tokens
8.7K
Snippets
21
Records
56
Agent score
87%

What's inside ProxyBridge

  1. Overview of ProxyBridge features

    master
    ProxyBridge is a lightweight, open-source universal proxy client that provides transparent proxy routing for applications on Windows, macOS, and Linux. It redirects TCP and UDP traffic from specific processes through SOCKS5 or HTTP proxies without requiring application-level configuration.

  2. Overview of ProxyBridge for macOS

    master

    ProxyBridge is a transparent proxy application for macOS that routes network traffic through HTTP or SOCKS5 proxies. It uses the macOS Network Extension framework to intercept TCP/UDP traffic system-wide and applies granular routing rules based on:

    • Package name (Bundle ID)
    • Destination IP/hostname (TCP only)
    • Destination port (TCP only)
    • Protocol (TCP, UDP, or Both)

  3. Build ProxyBridge from Source

    master

    Requirements

    • macOS 13.0 or later
    • Xcode 14.0 or later
    • Swift 5.7 or later
    • Valid Apple Developer account for code signing

    Build Steps

    1. Clone the repository:
    git clone https://github.com/InterceptSuite/ProxyBridge.git
cd ProxyBridge/MacOS/ProxyBridge
    1. Open the project in Xcode:
    open ProxyBridge.xcodeproj
    1. Configure code signing: Select the ProxyBridge target, go to Signing & Capabilities, and select your development team.
    2. Build the project using xcodebuild:
    xcodebuild -project ProxyBridge.xcodeproj -scheme ProxyBridge -configuration Release build
    1. The built .app will be located in your Xcode DerivedData folder under Build/Products/Release/.
    git clone https://github.com/InterceptSuite/ProxyBridge.git
cd ProxyBridge/MacOS/ProxyBridge
open ProxyBridge.xcodeproj
xcodebuild -project ProxyBridge.xcodeproj -scheme ProxyBridge -configuration Release build

  4. Use the ProxyBridge GUI

    master

    If GTK3 is installed, you can launch the graphical interface to manage proxy configurations and rules visually. The GUI supports:

    • Proxy configuration (SOCKS5/HTTP with authentication)
    • Visual rule management with process selection
    • Real-time connection monitoring
    • Import/Export rules in JSON format
    • Toggling DNS via Proxy
    sudo ProxyBridgeGUI

  5. Use the ProxyBridge CLI

    master

    The CLI allows for automated traffic routing using rules. Note: ProxyBridge requires root privileges to use nfqueue.

    Common CLI Commands

    Route a specific process through a SOCKS5 proxy:

    sudo ProxyBridge --proxy socks5://127.0.0.1:1080 --rule "curl:*:*:TCP:PROXY"

    Route multiple processes in a single rule (semicolon-separated):

    sudo ProxyBridge --proxy http://127.0.0.1:8080 --rule "curl;wget;firefox:*:*:TCP:PROXY"

    Block a specific application from internet access:

    sudo ProxyBridge --rule "malware:*:*:BOTH:BLOCK"

    Route all traffic through proxy except a specific app:

    sudo ProxyBridge --proxy socks5://127.0.0.1:1080 \
    --rule "*:*:*:TCP:PROXY" \
    --rule "burpsuite:*:*:TCP:DIRECT"

    Cleanup after a crash: If ProxyBridge crashes without cleaning up iptables rules, run:

    sudo ProxyBridge --cleanup
    # Example: Route curl and wget through a specific HTTP proxy with verbose logging
sudo ProxyBridge --proxy http://127.0.0.1:8080 \
    --rule "curl:*:*:TCP:PROXY" \
    --rule "wget:*:*:TCP:PROXY" \
    --verbose 2

  6. Install ProxyBridge on macOS

    master

    To install ProxyBridge on macOS, follow these steps:

    1. Download the latest release .pkg file from the official releases page.
    2. Open the downloaded .pkg file and follow the installation wizard.
    3. Grant Permissions: On first launch, you must grant System Extension permissions. Navigate to System Settings → General → Login Items & Extensions → Network Extension to allow the extension.
    4. Launch ProxyBridge from your Applications folder.

  7. Manage Proxy Rules on macOS

    master

    Proxy rules determine how network traffic is handled. Rules are evaluated in order until a match is found. Access them via Menu Bar → Proxy → Proxy Rules.

    Rule Components

    • Package Name: Application bundle identifier (e.g., com.google.Chrome). Note: Use bundle identifiers, not process names, due to Apple API limitations.
    • IP/Hostname: Destination IP or domain. (Note: Not supported for UDP rules).
    • Port: Destination port. (Note: Not supported for UDP rules).
    • Protocol: TCP, UDP, or Both.
    • Action:
      • PROXY: Route through the configured proxy.
      • DIRECT: Bypass the proxy.
      • BLOCK: Block the connection.

    UDP Limitations

    Due to Apple Network Extension API constraints, UDP rules can only match on the Package Name. IP and port-based filtering is unavailable for UDP traffic.

    // Example Rule JSON Format
[
  {
    "action" : "DIRECT",
    "enabled" : true,
    "processNames" : "curl",
    "protocol" : "BOTH",
    "targetHosts" : "*",
    "targetPorts" : "*"
  }
]

  8. Build ProxyBridge from source on Windows

    master

    Prerequisites

    • Windows 7 or later (64-bit)
    • Administrator privileges (required for the WinDivert driver)
    • Visual Studio 2019+ (MSVC recommended) or MinGW-w64 (GCC)
    • WinDivert 2.2.2-A or later

    Recommended Build (PowerShell)

    Use the provided script to compile the DLL, CLI, and GUI application automatically.

    cd Windows
.\compile.ps1

    Outputs will be located in Windows\output\.

  9. Configure Localhost via Proxy

    master

    By default, all localhost traffic (127.0.0.0/8 and ::1) uses a direct connection to prevent security risks (SSRF) and compatibility issues with local services (e.g., DevTools, NVIDIA GeForce Experience, or local web servers).

    To intercept localhost traffic (e.g., for security testing in Burp Suite or InterceptSuite), you must enable the Localhost via Proxy option in the Proxy menu.

    Warning: Only enable this if your proxy server is running on the same machine (127.0.0.1:1080). Do not enable it if the proxy is on a different IP address.

  10. Install build dependencies for Linux

    master

    Before building from source, install the required development libraries based on your distribution:

    Debian/Ubuntu/Mint:

    sudo apt-get update
sudo apt-get install build-essential gcc make \
    libnetfilter-queue-dev libnfnetlink-dev \
    libgtk-3-dev pkg-config

    Fedora:

    sudo dnf install gcc make \
    libnetfilter_queue-devel libnfnetlink-devel \
    gtk3-devel pkg-config

    Arch/Manjaro:

    sudo pacman -S base-devel gcc make \
    libnetfilter_queue libnfnetlink \
    gtk3 pkg-config
    sudo apt-get update
sudo apt-get install build-essential gcc make \
    libnetfilter-queue-dev libnfnetlink-dev \
    libgtk-3-dev pkg-config

  11. Install ProxyBridge on Windows

    master

    For Windows 10+ (64-bit), you can use the winget package manager. Note that the winget package is community-maintained and may not always be the latest verified build. For the most recent verified builds, use the official installer from the InterceptSuite website.

    winget install InterceptSuite.ProxyBridge

  12. Uninstall ProxyBridge from Linux

    master

    To completely remove ProxyBridge from a Linux system, remove the binaries, the shared library, the configuration directory, and update the library cache. If a configuration file was added to ld.so.conf.d, it should also be removed.

    # Remove binaries
sudo rm -f /usr/local/bin/ProxyBridge
sudo rm -f /usr/local/bin/ProxyBridgeGUI

# Remove library
sudo rm -f /usr/local/lib/libproxybridge.so

# Remove configuration
sudo rm -rf /etc/proxybridge

# Update library cache
sudo ldconfig

# Remove ld.so.conf entry (if exists)
sudo rm -f /etc/ld.so.conf.d/proxybridge.conf
sudo ldconfig