- Description
Introduce a new routing rule item (e.g., gateway_mac_address or lan_mac_address) that allows sing-box to determine the current network environment by checking the MAC address of the default router or a specified local IP address via the system's ARP table.
This would function similarly to the existing wifi_bssid rule, but operates at the OSI Layer 2/3 level rather than relying on OS-specific Wi-Fi APIs.
- Motivation & Use Cases
Currently, sing-box relies on wifi_ssid and wifi_bssid to identify the local network environment and trigger specific outbound profiles. While effective for mobile environments, this approach has several significant limitations that ARP-based detection solves natively:
Full Ethernet Support: Desktop machines, homelabs, and servers connected via Ethernet cannot use wifi_bssid. An ARP check allows a hardwired machine to seamlessly switch routing profiles when moved between a home network, an office, or a datacenter.
Bypassing OS Location Permissions: On desktop and mobile OSs, querying Wi-Fi SSIDs often requires the user to grant the application broad "Location" permissions, which is an unnecessary friction point for users who only want to route traffic.
Spoof-Resistance: SSIDs are easily duplicated. Validating the actual hardware MAC address of the default gateway ensures the rule only triggers on the genuinely trusted home/work network.
Router & Gateway Deployments: When sing-box is deployed as a transparent proxy on OpenWrt or Linux gateways, checking the MAC of a specific upstream gateway or adjacent smart-home device allows for highly dynamic, environment-aware routing.
- Proposed Implementation
Add a new rule item to the route object. When this rule is evaluated, sing-box queries the OS ARP cache to find the MAC address of the default route or a user-defined local IP.
Example config.json structure:
JSON
{
"route": {
"rules": [
{
"gateway_mac_address": [
"00:11:22:33:44:55",
"AA:BB:CC:DD:EE:FF"
],
"outbound": "home-proxy-node"
},
{
"lan_mac_address": {
"ip": "192.168.1.100",
"mac": "11:22:33:44:55:66"
},
"outbound": "direct"
}
]
}
}
4. Cross-Platform Viability
Reading the ARP table is well-supported across the core operating systems sing-box targets:
Linux / OpenWrt / Android: Straightforward to implement by parsing /proc/net/arp.
Windows: Natively supported and well-documented via the iphlpapi.h library (GetIpNetTable).
macOS / iOS: Can be cleanly implemented using sysctl routing queries (NET_RT_FLAGS + RTF_LLINFO). Crucially, testing confirms that reading the ARP table operates successfully even inside the strict macOS App Sandbox, provided the app is signed with the standard com.apple.security.network.client entitlement. (A Proof of Concept .tgz demonstrating this sandboxed behavior on macOS is attached to this issue).
Implementing this feature bridges a major gap for desktop power users and physical gateway deployments, providing a rock-solid, OS-agnostic method for environment detection.
Introduce a new routing rule item (e.g., gateway_mac_address or lan_mac_address) that allows sing-box to determine the current network environment by checking the MAC address of the default router or a specified local IP address via the system's ARP table.
This would function similarly to the existing wifi_bssid rule, but operates at the OSI Layer 2/3 level rather than relying on OS-specific Wi-Fi APIs.
Currently, sing-box relies on wifi_ssid and wifi_bssid to identify the local network environment and trigger specific outbound profiles. While effective for mobile environments, this approach has several significant limitations that ARP-based detection solves natively:
Full Ethernet Support: Desktop machines, homelabs, and servers connected via Ethernet cannot use wifi_bssid. An ARP check allows a hardwired machine to seamlessly switch routing profiles when moved between a home network, an office, or a datacenter.
Bypassing OS Location Permissions: On desktop and mobile OSs, querying Wi-Fi SSIDs often requires the user to grant the application broad "Location" permissions, which is an unnecessary friction point for users who only want to route traffic.
Spoof-Resistance: SSIDs are easily duplicated. Validating the actual hardware MAC address of the default gateway ensures the rule only triggers on the genuinely trusted home/work network.
Router & Gateway Deployments: When sing-box is deployed as a transparent proxy on OpenWrt or Linux gateways, checking the MAC of a specific upstream gateway or adjacent smart-home device allows for highly dynamic, environment-aware routing.
Add a new rule item to the route object. When this rule is evaluated, sing-box queries the OS ARP cache to find the MAC address of the default route or a user-defined local IP.
Example config.json structure:
JSON
{
"route": {
"rules": [
{
"gateway_mac_address": [
"00:11:22:33:44:55",
"AA:BB:CC:DD:EE:FF"
],
"outbound": "home-proxy-node"
},
{
"lan_mac_address": {
"ip": "192.168.1.100",
"mac": "11:22:33:44:55:66"
},
"outbound": "direct"
}
]
}
}
4. Cross-Platform Viability
Reading the ARP table is well-supported across the core operating systems sing-box targets:
Linux / OpenWrt / Android: Straightforward to implement by parsing /proc/net/arp.
Windows: Natively supported and well-documented via the iphlpapi.h library (GetIpNetTable).
macOS / iOS: Can be cleanly implemented using sysctl routing queries (NET_RT_FLAGS + RTF_LLINFO). Crucially, testing confirms that reading the ARP table operates successfully even inside the strict macOS App Sandbox, provided the app is signed with the standard com.apple.security.network.client entitlement. (A Proof of Concept .tgz demonstrating this sandboxed behavior on macOS is attached to this issue).
Implementing this feature bridges a major gap for desktop power users and physical gateway deployments, providing a rock-solid, OS-agnostic method for environment detection.