Security Architecture & Threat Model
Relevant source files
The following files were used as context for generating this wiki page:
Zephyr utilizes a Defense in Depth strategy to protect users from malicious configurations, network-based attacks, and unauthorized data access. The architecture enforces security across multiple layers, including network request filtering, configuration sanitization, and cryptographic verification of updates.
The system assumes all external inputs—such as subscription URLs, YAML configurations, and deep links—are untrusted. By implementing machine-bound encryption and strict resource limits on script execution, Zephyr isolates the core system from potential exploitation via third-party content.
Core Security Principles
Zephyr operates under four primary security pillars that govern the implementation of all features.
| Principle | Description |
|---|---|
| Defense in Depth | Multiple overlapping layers of protection across network boundaries and execution environments. |
| Least Privilege | Untrusted scripts and plugins run in constrained sandboxes with enforced resource limits. |
| Secure by Default | Cryptographic verification and atomic file operations are enabled for all critical updates. |
| Automated Verification | Continuous CI scanning using CodeQL, Semgrep, and dependency audits. |
Sources: SECURITY.md:215-230, FEATURES.md:120-155
Encryption and Data Protection
Zephyr protects sensitive user data, specifically subscription metadata, using machine-bound encryption. This ensures that even if a configuration file is stolen, it cannot be decrypted on a different device.
Machine-Bound Encryption
The system uses hardware fingerprint-derived keys to perform AES-256-GCM encryption on metadata.json. This file stores subscription URLs and traffic information. Proxy configurations also support optional encryption using a v2: base64 prefix.
Sources: FEATURES.md:92-95, README_en.md:125-130
File System Security
Zephyr enforces strict file permissions to prevent unauthorized local access:
- Unix: Sets
0600permissions. - Windows: Applies specific DACLs (Discretionary Access Control Lists).
- Atomic Operations: Uses UUID temporary files for downloads to prevent partial file writes or race conditions.
Sources: FEATURES.md:112-115, FEATURES.md:122-124
Network Security and SSRF Protection
Zephyr implements a multi-stage validation process for network requests to prevent Server-Side Request Forgery (SSRF) and DNS leakage.
SSRF Mitigation
Before downloading subscription or rule URLs, the system performs DNS validation. While users can manually input private addresses, the system blocks any redirects that point to private IP ranges to prevent attackers from probing the local network.
The diagram above shows the validation flow for preventing SSRF and DNS rebinding attacks.
Sources: FEATURES.md:97-101, SECURITY.md:180-185
DNS Leak Prevention
When running in TUN Mode, Zephyr automatically injects a dns-hijack rule. This captures all system DNS traffic and routes it through the Mihomo core, ensuring that no DNS queries bypass the proxy and leak the user's IP address.
Sources: FEATURES.md:103-105, README_en.md:133-135
Configuration and Script Sandboxing
Zephyr protects the host system from malicious YAML configurations and embedded scripts through sanitization and resource-constrained execution.
YAML Sanitization
The Config Sanitizer recursively removes dangerous YAML keys that could lead to unauthorized system access.
- Removes
scriptandscript-pathkeys. - Blocks 6 legacy Clash for Windows keys.
- Prevents path traversal in providers.
- Limits YAML depth to 100 to prevent "Billion Laughs" denial-of-service attacks.
Sources: FEATURES.md:107-110, README_en.md:137-140
Prism Engine Sandbox
Prism scripts run within a QuickJS sandbox. The engine enforces nine distinct resource limits to prevent resource exhaustion or sandbox escape.
| Limit Category | Enforcement Range |
|---|---|
| Execution Time | 100ms – 300s |
| Memory | 1MB – 512MB |
| Recursion Depth | 8 – 512 |
| Loop Iterations | 1K – 10M |
Sources: FEATURES.md:83-88, SECURITY.md:218-222
Update Integrity and Code Signing
The software ensures that only verified binaries are executed through cryptographic signatures and authorized build pipelines.
Binary Verification
Zephyr verifies all updates using a two-step process:
- SHA256: Validates the integrity of the downloaded asset.
- Minisign Ed25519: Verifies the digital signature against a hardcoded public key to ensure authenticity.
Sources: FEATURES.md:117-120, SECURITY.md:224-226
Windows Code Signing
Official Windows release artifacts (NSIS installers and MSI packages) are digitally signed by SignPath Foundation. This prevents tampered binaries from being installed and provides users with a verifiable signer identity.
Sources: CODE_SIGNING_POLICY.md:1-15, README_en.md:255-265
Threat Model & Scope
The security model classifies threats based on their impact on the sandbox and user data.
In-Scope Threats
- Sandbox Escapes: Attempts to break out of the QuickJS environment.
- SSRF Bypasses: Circumventing IP filters during subscription downloads.
- Configuration Injection: Unsafe YAML deserialization leading to system compromise.
- Update Tampering: Bypassing signature verification in the auto-updater.
Out-of-Scope Threats
- Attacks requiring pre-existing root/admin access on the target machine.
- UI anomalies that remain contained within the WebView sandbox.
- Denial of Service (DoS) caused by manual modification of local configuration files.
Sources: SECURITY.md:175-200, SECURITY.md:100-115
Path and Filename Sanitization
Zephyr prevents path traversal attacks during file operations by sanitizing all user-provided filenames. This is critical for preventing malicious servers from overwriting system files.
// Example of path traversal mitigation in prism_tests.rs
#[test]
fn rejects_path_traversal_dotdot() {
// "../../etc/passwd" is stripped to "....etcpasswd"
// This creates a safe flat filename.
let result = sanitize_filename("../../etc/passwd");
assert_eq!(result.unwrap(), "....etcpasswd");
}
Sources: apps/desktop/src-tauri/src/prism_tests.rs:115-122, FEATURES.md:122-125
The system strips control characters, null bytes, and shell metacharacters (e.g., $, `) while allowing safe characters like CJK characters, hyphens, and parentheses.
Sources: apps/desktop/src-tauri/src/prism_tests.rs:70-100, FEATURES.md:122-124