Network & SSRF Protections
Relevant source files
The following files were used as context for generating this wiki page:
Zephyr implements a multi-layered security architecture to protect users from network-level threats, specifically Server-Side Request Forgery (SSRF) and DNS leaks. The system treats all external inputs, such as subscription URLs and rule downloads, as untrusted. By enforcing DNS validation and IP pinning, Zephyr prevents attackers from using the client as a proxy to attack local network services or sensitive infrastructure.
These protections are integrated into the core network stack, ensuring that every remote fetch operation undergoes security scrutiny before execution. The defense-in-depth strategy extends from the Rust backend's network logic to the system-level TUN mode configurations.
Sources: SECURITY.md, FEATURES.md:204-206, landing.html:314-325
SSRF Prevention Mechanism
Zephyr prevents SSRF attacks during the download of subscriptions and remote rules. The system performs DNS validation before initiating any connection to a remote URL. If a request is redirected to a private or internal IP address, the network handler blocks the request immediately.
Key SSRF Features
- DNS Validation: The client validates the resolved IP address of a target host before completing the connection.
- Private Address Blocking: Redirects to private IP ranges (e.g., 127.0.0.1, 192.168.x.x) are strictly blocked.
- IP Pinning: Zephyr uses IP pinning to mitigate DNS Rebinding attacks, ensuring the connection stays bound to the validated IP.
- User-Initiated Exceptions: While automated redirects to private IPs are blocked, the system allows explicit, user-initiated private address inputs for local testing.
Sources: SECURITY.md, README_en.md:104-105, FEATURES.md:205-207, landing.html:318-325
Connection Security Flow
The following diagram illustrates the validation process when the application attempts to fetch a remote resource.
The diagram shows the iterative DNS validation and IP pinning process used to prevent SSRF and Rebinding.
Sources: FEATURES.md:205-207, landing.html:318-325
DNS Leak Prevention and TUN Mode
Zephyr protects user privacy by preventing DNS leaks through automated configuration of the TUN (Virtual Network Interface) mode. When TUN mode is active, the system injects dns-hijack parameters into the Mihomo core configuration.
Protection Capabilities
- Traffic Capture: The TUN mode captures all system-level traffic, including DNS queries.
- DNS Hijacking: All captured DNS traffic is forcibly routed through the Mihomo core, ensuring queries follow the defined proxy rules rather than leaking through the native OS DNS handler.
- UWP Loopback Exemption: On Windows, Zephyr manages loopback exemptions to allow Store apps to communicate with the local proxy without triggering network blocks.
Sources: README_en.md:106-107, README.md:126-127, FEATURES.md:208-209, landing.html:370-375
Network Security Summary Table
| Layer | Protection | Implementation Detail |
|---|---|---|
| SSRF | DNS Validation | Validates host IP before subscription/rule downloads. |
| SSRF | Redirect Blocking | Blocks redirects targeting private/local network addresses. |
| DNS | DNS Hijacking | Forcibly routes DNS traffic to Mihomo core in TUN mode. |
| DNS | DNS Pinning | Prevents Rebinding attacks during remote fetches. |
| Windows | UWP Exemption | Manages loopback for Windows Store applications. |
| Network | IPC Validation | Validates length and UTF-8 safety of network-related IPC commands. |
Sources: SECURITY.md, FEATURES.md:205-212, landing.html:62-68
Filename and Path Security
Network operations often involve saving remote data to the local disk. Zephyr implements strict sanitization for filenames derived from network sources to prevent path traversal attacks.
Sanitization Rules
The sanitize_filename function enforces the following security constraints:
- Stripping Disallowed Characters: Removes control characters, null bytes, and shell metacharacters (e.g.,
$,`,|,&). - Path Traversal Prevention: Removes forward slashes (
/) and backslashes (\) to prevent attackers from writing files outside the intended directory. - Component Validation: Rejects inputs consisting solely of
.or... - Length Constraints: Limits filenames to exactly 255 characters.
Sources: apps/desktop/src-tauri/src/prism_tests.rs:56-235, FEATURES.md:223-225
The sequence shows how malicious filenames from network headers are flattened to prevent traversal.
Sources: apps/desktop/src-tauri/src/prism_tests.rs:114-142, FEATURES.md:223-225
Conclusion
Network and SSRF protections in Zephyr prioritize a "Safe by Default" approach. By combining backend DNS validation, IP pinning, and system-level DNS hijacking, the project mitigates common vulnerabilities associated with proxy clients and remote configuration management.
Sources: SECURITY.md, README_en.md:102-114