ProxyBridge is a transparent proxy application for macOS that allows you to route network traffic through HTTP or SOCKS5 proxies with granular control using rules based on application, destination, and protocol.
ProxyBridge leverages macOS Network Extension framework to intercept and route network traffic. It provides a GUI application for configuration and uses a system extension to handle traffic routing based on user-defined rules.
ProxyBridge Main Window
┌─────────────┐
│ │ (1) TCP/UDP packet
│ Application │ ↓
│ │
└─────────────┘
│
│
[user mode]───────────────────────────────────────────────────────────────────────
│
│ (2) Packet intercepted via Network Extension
↓
┌──────────────────────┐
│ │
│ ProxyBridge │
│ Extension │
│ (System Extension) │
│ │
└──────────────────────┘
│
│ (3) Rule matching
↓
┌───────────────────────────────────────┐
│ │
│ Match rules: │
│ - Package name (bundle ID) │
│ - Destination IP/hostname (TCP only) │
│ - Destination port (TCP only) │
│ - Protocol (TCP/UDP/Both) │
│ │
└───────────────────────────────────────┘
│
│
├──────(4a) Rule matched: PROXY────────────────────────┐
│ │
├──────(4b) Rule matched: DIRECT───────────────────┐ │
│ │ │
├──────(4c) Rule matched: BLOCK──────────┐ │ │
│ │ │ │
└──────(4d) No rule matched─────────┐ │ │ │
│ │ │ │
↓ ↓ ↓ ↓
┌────────────────────────────┐
│ ProxyBridge Network │
│ Manager │
│ (4e) Store original │
│ dest IP/port │
│ (4f) Log connection │
└────────────────────────────┘
│
┌─────────────────────────────┼─────────────────────┐
│ │ │
│ │ │
(5) BLOCK │ (6) DIRECT │ (7) PROXY │
│ │ │ │ │ │
↓ │ ↓ │ ↓ │
Connection │ Pass to OS │ ┌─────────────────────────┐
Dropped │ (Direct) │ │ Extension creates │
│ │ │ │ NWTCPConnection or │
│ ↓ │ │ NWUDPSession to proxy │
│ ┌────────────┐ │ └─────────────────────────┘
│ │ Remote │ │ │
│ │ Server │ │ │
│ └────────────┘ │ ↓
│ │ ┌─────────────────────────┐
│ │ │ Proxy Server │
│ │ │ - HTTP Proxy, or │
│ │ │ - SOCKS5 Proxy │
│ │ │ │
│ │ │ (8) Extension handles │
│ │ │ proxy handshake & │
│ │ │ data relay │
│ │ └─────────────────────────┘
│ │ │
│ │ ↓
│ │ ┌─────────────────────────┐
│ │ │ Remote Server │
│ │ │ (Final destination) │
│ │ └─────────────────────────┘
│ │
└─────────────────────────────┴─────────────────────────────
│
│ (9) Response flows back through
│ extension to application
↓
[Application]
-
GUI Application (User Mode)
- Configuration interface for proxy settings
- Rule management (add, delete, enable/disable)
- Connection log viewer
- Stored in UserDefaults and shared with extension
-
Network Extension (System Extension)
- Runs as a system extension
- Intercepts all TCP/UDP traffic system-wide
- Evaluates traffic against configured rules
- Routes traffic based on rule actions
- Creates NWTCPConnection for TCP proxy connections
- Creates NWUDPSession for SOCKS5 UDP associations
- Handles proxy protocol handshakes (HTTP CONNECT, SOCKS5)
- Relays data between application and proxy server
- Supports both HTTP and SOCKS5 proxies with authentication
-
Network Manager
- Stores original destination details
- Logs all connection attempts
- Tracks active connections
- Handles authentication when credentials provided
- Application initiates connection - Any application on the system makes a network request
- Network Extension intercepts - ProxyBridge extension receives the connection request via NETransparentProxyProvider
- Rule evaluation - Extension checks configured rules against:
- Application bundle identifier (package name)
- Destination IP/hostname (TCP only)
- Destination port (TCP only)
- Protocol (TCP/UDP/Both)
- Action execution:
- (4a) PROXY - Extension creates NWTCPConnection/NWUDPSession to proxy server
- (4b) DIRECT - Allows direct connection bypassing proxy
- (4c) BLOCK - Blocks the connection entirely
- (4d) No Match - Passes to OS (Direct for TCP, logged with "unknown" for UDP)
- Logging - Connection details are logged and sent to GUI
- Proxy handling - For PROXY action, extension handles proxy handshake and relays data
- Final destination - Traffic reaches remote server either directly or through proxy
- Logging - Connection details are logged and visible in the GUI
- Proxy handling - For PROXY action, establishes connection to configured proxy server
- Final destination - Traffic reaches remote server either directly or through proxy
- Download the latest release from the releases page
- Open the downloaded
.pkgfile - Follow the installation wizard
- Grant System Extension permissions when prompted
- Launch ProxyBridge from Applications folder
Note: ProxyBridge requires system extension permissions. You need to allow the extension in System Settings → General → Login Items & Extensions → Network Extension on first launch.
Access proxy settings from Menu Bar → Proxy → Proxy Settings.
Proxy Settings Window
- HTTP - Standard HTTP/HTTPS proxy
- SOCKS5 - SOCKS5 proxy with optional UDP support
| Field | Description | Required | Format |
|---|---|---|---|
| Proxy Type | Select HTTP or SOCKS5 | Yes | Dropdown selection |
| Proxy Host | Proxy server IP address, hostname, or domain | Yes | IPv4, IPv6, or domain name |
| Proxy Port | Proxy server port number | Yes | 1-65535 |
| Username | Proxy authentication username | No | Text |
| Password | Proxy authentication password | No | Text |
HTTP Proxy
Type: HTTP
Host: proxy.example.com
Port: 8080
Username: myuser
Password: mypass
SOCKS5 Proxy
Type: SOCKS5
Host: 127.0.0.1
Port: 1080
Username: (optional)
Password: (optional)
Access proxy rules from Menu Bar → Proxy → Proxy Rules.
Proxy Rules Window
Rules determine how network traffic is handled. Multiple rules can be created, and they are evaluated in order until a match is found.
| Component | Description | Supports TCP | Supports UDP |
|---|---|---|---|
| Package Name | Application bundle identifier | Yes | Yes |
| IP/Hostname | Destination IP address or domain | Yes | No* |
| Port | Destination port number | Yes | No* |
| Protocol | TCP, UDP, or Both | Yes | Yes |
| Action | PROXY, DIRECT, or BLOCK | Yes | Yes |
Note: UDP rules only match on package name due to Apple API limitations. IP and port-based filtering is not available for UDP traffic.
- PROXY - Route traffic through the configured proxy server
- DIRECT - Allow direct connection bypassing the proxy
- BLOCK - Block the connection entirely
- Add Rule - Create a new rule with specified criteria
- Enable/Disable - Toggle rules on/off without deleting them
- Delete - Remove rules permanently
- List All - View all configured rules and their status
Add/Edit Rule Window
Block all traffic from specific app
Package Name: com.example.app
IP/Hostname: (empty)
Port: (empty)
Protocol: Both
Action: BLOCK
Route browser through proxy
Package Name: com.google.Chrome
IP/Hostname: (empty)
Port: (empty)
Protocol: TCP
Action: PROXY
Direct connection for specific domain
Package Name: (empty)
IP/Hostname: trusted.example.com
Port: 443
Protocol: TCP
Action: DIRECT
UDP traffic from specific app through SOCKS5
Package Name: com.example.voipapp
IP/Hostname: (ignored for UDP)
Port: (ignored for UDP)
Protocol: UDP
Action: PROXY
ProxyBridge allows you to export selected rules to a JSON file and import rules from previously exported files.
Export Rules:
- Select one or more rules using the checkboxes
- Click the Select All button to select all rules (optional)
- Click the Export button
- Choose a location and save the JSON file
Import Rules:
- Click the Import button
- Select a previously exported JSON file
- Rules will be imported and added to your existing rules
JSON Format Example:
[
{
"action" : "DIRECT",
"enabled" : true,
"processNames" : "curl",
"protocol" : "BOTH",
"targetHosts" : "*",
"targetPorts" : "*"
}
]- Launch ProxyBridge from Applications
- The app runs in the menu bar
- Configure proxy settings and rules as needed
- Enable the system extension when prompted
- Traffic will be routed according to your rules
Connection logs are available in the main window, showing:
- Protocol (TCP/UDP)
- Application package name
- Destination IP/hostname
- Destination port
- Action taken (PROXY/DIRECT/BLOCK)
- Proxy Settings - Configure proxy server details
- Proxy Rules - Manage traffic routing rules
- Help - Check for updates and about information
- Quit - Exit ProxyBridge
-
Package Name vs Process Name
- Rules use application bundle identifier (package name), not process name
- Apple's Network Extension API does not provide access to process names
- Use
com.example.appformat instead of executable names
-
UDP Traffic Limitations
- UDP rules can only match on package name
- Destination IP and port are not available for UDP traffic when not handled by the extension
- This is an Apple API limitation in the Network Extension framework
- UDP traffic that doesn't match a rule is passed to the OS directly and logged with "unknown" IP/port
-
System Traffic
- Some system processes may bypass the extension
- Critical macOS services are not intercepted for system stability
- TCP - Full support with all rule matching criteria
- UDP - Limited to package name matching only
- SOCKS5 UDP - Supported when rules match and proxy through SOCKS5
- macOS 13.0 or later
- Xcode 14.0 or later
- Swift 5.7 or later
- Valid Apple Developer account for code signing
-
Clone the repository:
git clone https://github.com/InterceptSuite/ProxyBridge.git cd ProxyBridge/MacOS/ProxyBridge -
Open the project:
open ProxyBridge.xcodeproj
-
Configure code signing in Xcode:
- Select the ProxyBridge target
- Go to Signing & Capabilities
- Select your development team
-
Build the project:
xcodebuild -project ProxyBridge.xcodeproj -scheme ProxyBridge -configuration Release build
-
The built application will be in:
~/Library/Developer/Xcode/DerivedData/ProxyBridge-*/Build/Products/Release/ProxyBridge.app
To create a .pkg installer, additional packaging steps are required using pkgbuild or a similar tool. See the packaging documentation for details.
See the LICENSE file for details.