Config Cleansing & XSS Prevention

Relevant source files

The following files were used as context for generating this wiki page:

• crates/core/src/config/sanitizer.rs
• SECURITY.md
• FEATURES.md
• crates/core/src/config/prism_types.rs
• apps/desktop/src-tauri/src/prism_tests.rs
• apps/desktop/src/ui/advanced.js

Config Cleansing and XSS Prevention represent the core defensive layers of the Zephyr security architecture. The project implements a "Security First" philosophy, enforcing strict boundaries on untrusted inputs from subscriptions, configuration files, and deep links. These systems protect the application from Remote Code Execution (RCE), path traversal, and Cross-Site Scripting (XSS) by sanitizing YAML structures and validating UI rendering logic.

Sources: SECURITY.md:158-164, FEATURES.md:108-112

YAML Config Sanitization

Zephyr sanitizes all YAML configurations to remove dangerous keys that could lead to unauthorized code execution or unmanaged control surfaces. The sanitizer recursively traverses YAML mappings and removes specific identifiers before they reach the core proxy engine.

Defensive Mechanisms

The sanitization process employs several strategies to neutralize threats:

• Dangerous Key Removal: The system strips script and script-path keys to prevent arbitrary JavaScript execution.
• Control Plane Protection: It removes keys that open unauthenticated controller surfaces, such as external-ui or external-controller-unix.
• Billion Laughs Defense: The sanitizer limits YAML recursion depth to 100 to prevent stack overflow or memory exhaustion attacks.
• Path Traversal Prevention: It removes the path key specifically within provider contexts to prevent access to sensitive system files.

Sources: crates/core/src/config/sanitizer.rs:8-12, crates/core/src/config/sanitizer.rs:114-124, crates/core/src/config/sanitizer.rs:136-140

Sanitization Flow

This diagram illustrates how the backend processes a YAML configuration string to produce a safe output.

Prohibited Configuration Keys

Category	Prohibited Keys	Reason
Scripting	script, script-path	Prevents arbitrary code execution via JavaScript.
Control Plane	external-ui, external-doh-server, external-controller-tls	Prevents unauthenticated access to the proxy controller.
Legacy CFW	cfw-bypass, cfw-profiles-path, append-proxy-groups	Removes non-functional keys that could be used for injection.
Providers	path (inside provider context)	Prevents path traversal attacks.

Sources: crates/core/src/config/sanitizer.rs:24-34, crates/core/src/config/sanitizer.rs:118-132

Path and Filename Sanitization

Zephyr enforces strict filename validation to prevent path traversal and ensure compatibility across different operating systems. This applies to profile imports, rule files, and subscription management.

Sanitization Logic

The sanitize_base_filename function performs the following steps:

1. URL Decoding: Completely decodes the input string up to 5 times to catch double-encoded traversal patterns like %252e%252e%252f.
2. Trailing Cleanup: Trims trailing spaces and dots to prevent Windows canonicalization bypasses.
3. Separator Rejection: Rejects any input containing / or \ characters.
4. Reserved Name Check: Rejects Windows reserved names such as CON, PRN, AUX, and NUL.

Sources: crates/core/src/config/sanitizer.rs:175-180, crates/core/src/config/sanitizer.rs:206-215, crates/core/src/config/sanitizer.rs:260-265

Sanitization Requirements

Rule	Implementation
Max Length	255 characters.
Prohibited Chars	Null bytes (\0) and control characters.
Traversal	Bare .. and . are explicitly rejected.
Allowed Chars (Prism)	Alphanumeric, -, _, ., , (, ), and CJK characters.

Sources: crates/core/src/config/sanitizer.rs:219-235, crates/core/src/config/prism_types.rs:82-95

XSS Prevention & UI Security

The frontend implements defense-in-depth measures to prevent Cross-Site Scripting (XSS) and Prototype Pollution when handling dynamic configuration data.

Frontend Data Flow

The Advanced Settings module uses a recursive rendering engine to display and edit configurations. It prevents Prototype Pollution during object merging and UI construction.

Security Constraints in JavaScript

• Prototype Pollution Guard: The deepMerge and buildNestedPayload functions explicitly check for and skip __proto__, constructor, and prototype keys.
• Safe Property Definition: The application uses Object.defineProperty instead of direct assignment to avoid triggering setters on the prototype chain.
• Content Security Policy (CSP): The project enforces a strict CSP that limits script and connection sources, preventing the execution of external malicious scripts.

Sources: apps/desktop/src/ui/advanced.js:46-52, FEATURES.md:113-115, SECURITY.md:164

HTML Sanitization Utilities

Function	Purpose
escapeHtml	Escapes & < > " ' via string replacement for safe text rendering.
sanitizeHtml	Uses a whitelist and <template> parsing to strip dangerous content tags.
check_input_size	Limits user text inputs to 10 MB to prevent resource exhaustion.

Sources: FEATURES.md:112, crates/core/src/config/prism_types.rs:43-48

Conclusion

The Config Cleansing and XSS Prevention systems provide a robust security boundary between untrusted remote data and the local system. By combining backend YAML sanitization with frontend prototype protection and strict filename validation, Zephyr mitigates the most common attack vectors associated with proxy configuration management.

Sources: SECURITY.md:158-164, FEATURES.md:108-112