QuickJS Script Sandboxing
Relevant source files
The following files were used as context for generating this wiki page:
QuickJS Script Sandboxing provides a secure execution environment for untrusted JavaScript within the Prism Engine. The system enforces strict resource boundaries and permission controls to prevent script escapes, resource exhaustion, and unauthorized system access. This sandboxing is a core component of Zephyr's "Security First" design, ensuring that user-provided scripts, overrides, and plugins operate under the principle of least privilege.
Sources: SECURITY.md:162-164, README_en.md:92-93, FEATURES.md:94-98
Sandbox Architecture and Resource Management
The sandboxing mechanism utilizes the QuickJS engine to isolate script execution from the main application process. It implements nine distinct resource limits and four primary permission controls. The backend enforces strict validation on these limits to prevent privilege escalation.
Resource Limits and Constraints
The system validates limit configurations against hardcoded boundaries during the script_set_limits call.
| Limit Category | Minimum | Maximum | Default/Note |
|---|---|---|---|
| Execution Time | 100ms | 300s | Prevents CPU-bound DoS |
| Memory Usage | 1MB | 512MB | Caps memory allocation |
| Loop Iterations | 1,000 | 10,000,000 | Prevents infinite loops |
| Recursion Depth | 8 | 512 | Prevents stack overflow |
| String Length | - | - | Enforced by Prism |
Sources: FEATURES.md:94-98, apps/desktop/src/ui/plugins-smart.js:315-325
Permission Control Flow
The frontend UI monitors for elevation of privileges. When a user attempts to enable sensitive permissions like filesystem access, the system triggers a confirmation workflow.
The system generates audit logs for every permission change, recording a WARN level for elevations and INFO for revocations.
Sources: FEATURES.md:94-100, apps/desktop/src/ui/plugins-smart.js:284-308
Security Safeguards
Zephyr implements a multi-layered defense to protect the host system from sandboxed scripts.
Permission Capabilities
Scripts operate under four specific permission flags:
- Network Access: Controls the ability to make external requests.
- Filesystem Access: Restricts reading or writing to local storage.
- Child Process: Prevents the execution of external binaries.
- Worker Threads: Limits the creation of parallel execution contexts.
Sources: FEATURES.md:94-98, apps/desktop/src/ui/plugins-smart.js:287-290
Execution Validation and Monitoring
Before execution, the system performs a safety check to determine if the current sandbox configuration is considered "Safe" according to predefined security heuristics.
Plugin and Override Integration
The sandboxing system extends to the Plugin and Override modules. Plugins are discovered in the prism/plugins/ directory and run within the sandbox when loaded.
Plugin Lifecycle
- Discovery: Scans the filesystem for valid plugin folders.
- Loading: Initializes the script within the sandbox with specific permission sets.
- Execution: Runs entry scripts or specific lifecycle hooks (e.g., high-frequency hooks).
- Audit: Tracks duration in microseconds (µs) and records success/failure status.
Sources: apps/desktop/src/ui/plugins-smart.js:68-150, FEATURES.md:100-101
Configuration Data Structures
The smart scoring and failover policies are managed via the KV (Key-Value) store, which sandboxed scripts can access if permitted.
| Endpoint / Method | Description | Data Type |
|---|---|---|
scriptSetLimits | Sets CPU/Memory constraints | ScriptLimits Object |
scriptSetSandbox | Sets permission flags | SandboxConfig Object |
kvSet | Stores persistent script data | JSON-serializable |
pluginExecuteHook | Triggers script hooks | (name, context) |
Sources: apps/desktop/src/ui/plugins-smart.js:192-215, apps/desktop/src/ui/plugins-smart.js:315-330
Testing and Verification
The sandboxing engine is verified through integration tests that simulate rule extraction and safety boundaries. Tests ensure that even if a rule is extracted from a profile, it remains disabled by default using the __when__: enabled: false flag to prevent unauthorized execution.
Sources: apps/desktop/src-tauri/src/prism_tests.rs:595-605, CONTRIBUTING.md:100-110
QuickJS Script Sandboxing ensures that Zephyr remains lightweight and secure by providing high-performance JavaScript execution while strictly enforcing resource and permission boundaries. This architecture mitigates risks associated with malicious configurations and automated script execution.