Understanding the Security Model and Sandboxing in Clash Verge Rev

Clash Verge Rev implements a layered security architecture using Tauri 2's capability-based permission system, asset protocol isolation, and platform-specific entitlements to sandbox the web-based UI from native system access.

The security model in Clash Verge Rev leverages Tauri 2's runtime to isolate the frontend webview from the Rust backend, ensuring that only explicitly declared capabilities can access native APIs. This approach combines configuration-driven permissions in tauri.conf.json with platform-specific sandboxing rules to protect against unauthorized system access while maintaining functionality for proxy management and system integration.

Tauri 2 Security Architecture Overview

Clash Verge Rev is built on Tauri 2, which provides a process-separated architecture where the UI runs in a system webview while native functionality executes in a Rust backend process. Security is enforced through capabilities—declarative permissions that whitelist specific Tauri APIs and custom commands the frontend may invoke.

Unlike Electron, which grants the renderer broad Node.js access, Tauri's model requires explicit capability declarations in src-tauri/tauri.conf.json before any native API can be called from the frontend.

Core Security Configuration in tauri.conf.json

The primary security settings reside in src-tauri/tauri.conf.json, which defines the global security posture, asset handling, and API permissions.

Capability-Based Permissions

The app.security.capabilities array declares which Tauri capabilities the application possesses:

{
  "app": {
    "security": {
      "capabilities": [
        "desktop-capability",
        "desktop-windows-capability",
        "migrated"
      ]
    }
  }
}

Key capabilities:

• desktop-capability: Grants access to desktop APIs including system tray, notifications, and window management
• desktop-windows-capability: Adds Windows-specific desktop features
• migrated: Indicates the app was upgraded from an older Tauri version, retaining backward-compatible permissions

Source: [src-tauri/tauri.conf.json](https://github.com/clash-verge-rev/clash-verge-rev/blob/dev/src-tauri/tauri.conf.json#L49-L53)

Asset Protocol Isolation

The asset protocol (asset://) ensures the webview loads only compiled application assets without exposing the full filesystem:

{
  "app": {
    "security": {
      "assetProtocol": {
        "enable": true,
        "scope": {
          "allow": ["**"],
          "requireLiteralLeadingDot": false
        }
      }
    }
  }
}

This configuration:

• Enables the asset:// protocol for loading bundled resources
• Allows access to all bundled assets via the ["**"] scope
• Disables the literal leading dot requirement for simpler asset referencing

By using asset:// instead of file://, the application prevents directory traversal attacks that could allow the webview to access arbitrary files on the host system.

Source: [src-tauri/tauri.conf.json](https://github.com/clash-verge-rev/clash-verge-rev/blob/dev/src-tauri/tauri.conf.json#L50-L57)

Content Security Policy

The Content Security Policy (CSP) header controls resource loading in the webview:

{
  "app": {
    "security": {
      "csp": null
    }
  }
}

Setting csp to null instructs Tauri to use its default CSP, which:

• Blocks inline scripts and styles unless explicitly allowed
• Restricts script-src and style-src to self-origin
• Prevents the execution of remote code

This default policy provides robust protection against cross-site scripting (XSS) attacks while allowing the application to function normally.

Source: [src-tauri/tauri.conf.json](https://github.com/clash-verge-rev/clash-verge-rev/blob/dev/src-tauri/tauri.conf.json#L58-L60)

Deep Link Validation

Custom URL schemes are registered for deep linking:

{
  "plugins": {
    "deep-link": {
      "desktop": {
        "schemes": ["clash", "clash-verge"]
      }
    }
  }
}

Tauri validates these schemes before invoking backend handlers, preventing arbitrary protocol handling that could be exploited through malicious links.

Source: [src-tauri/tauri.conf.json](https://github.com/clash-verge-rev/clash-verge-rev/blob/dev/src-tauri/tauri.conf.json#L43-L47)

Platform-Specific Sandboxing Implementation

While Tauri provides the primary security boundary, platform-specific configurations add additional sandboxing layers.

macOS Entitlements and Sandbox Configuration

The macOS entitlements file at src-tauri/packages/macos/entitlements.plist defines the macOS sandbox behavior:

<key>com.apple.security.app-sandbox</key>
<false/>

Critical security note: The application explicitly disables the macOS app sandbox (<false/>). This is intentional because:

• Tauri's process isolation already separates the webview from native code
• The application requires access to system proxy settings and network configuration that would be restricted by the macOS sandbox
• The entitlements file still declares an application group (io.github.clash-verge-rev.clash-verge-rev) with inherit set to true, allowing future extensions to share data

Source: src-tauri/packages/macos/entitlements.plist

Windows Capability Model

Windows lacks a system-wide sandbox comparable to macOS, so Clash Verge Rev relies entirely on Tauri's declared capabilities. The Windows-specific configuration in src-tauri/tauri.windows.conf.json reinforces the security model:

{
  "app": {
    "security": {
      "capabilities": [
        "desktop-capability",
        "desktop-windows-capability",
        "migrated"
      ]
    }
  }
}

This ensures that Windows-specific APIs (such as window management and system integration) are only accessible when explicitly declared, preventing unauthorized access to the Windows registry or system APIs from the frontend.

Source: [src-tauri/tauri.windows.conf.json](https://github.com/clash-verge-rev/clash-verge-rev/blob/dev/src-tauri/tauri.windows.conf.json#L24-L31)

How the Security Layers Interact

The security model in Clash Verge Rev operates through five distinct layers that work sequentially to protect the system:

1. Process Isolation: Tauri core runs the Rust backend in a separate process from the webview frontend. The webview cannot access the filesystem or network directly; all operations must go through Tauri's IPC bridge.

2. Capability Enforcement: Declared capabilities in tauri.conf.json whitelist specific APIs. Any attempt to invoke an undeclared native API results in a runtime permission error, preventing privilege escalation from the frontend.

3. Asset Protocol Restrictions: The asset:// protocol ensures the webview loads only bundled resources. Unlike file:// URLs, asset:// cannot traverse outside the application bundle, eliminating directory traversal vulnerabilities.

4. Content Security Policy: The default CSP blocks inline scripts and restricts resource loading to same-origin content. This prevents XSS attacks where malicious scripts could execute in the context of the application.

5. Platform Controls: On macOS, entitlements control sandbox behavior (intentionally disabled in favor of Tauri's isolation), while Windows relies entirely on Tauri's capability model. These platform-specific settings provide the final gate for system-level operations.

Practical Security Configuration Examples

Enabling the Asset Protocol

The default configuration in src-tauri/tauri.conf.json enables secure asset loading:

{
  "app": {
    "security": {
      "assetProtocol": {
        "enable": true,
        "scope": {
          "allow": ["**"],
          "requireLiteralLeadingDot": false
        }
      }
    }
  }
}

This configuration allows the webview to access all bundled assets via asset://index.html while preventing access to arbitrary filesystem paths.

Implementing a Strict Content Security Policy

To tighten security beyond Tauri's defaults, modify the CSP in tauri.conf.json:

{
  "app": {
    "security": {
      "csp": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:;"
    }
  }
}

This policy restricts scripts to same-origin only, allows inline styles (often required by UI frameworks), and permits images from the app bundle or data URIs.

Registering Deep Link Schemes

To handle custom URL schemes securely, configure the deep-link plugin:

{
  "plugins": {
    "deep-link": {
      "desktop": {
        "schemes": ["clash", "clash-verge"]
      }
    }
  }
}

Frontend implementation (TypeScript):

import { register } from '@tauri-apps/api/event';

// Register deep link handler
register('tauri://deep-link', (event) => {
  const url = event.payload as string;
  // Validate URL before processing
  if (url.startsWith('clash://') || url.startsWith('clash-verge://')) {
    handleDeepLink(url);
  }
});

Modifying Capability Permissions

To restrict application capabilities on Windows, edit src-tauri/tauri.windows.conf.json:

{
  "app": {
    "security": {
      "capabilities": [
        "desktop-capability",
        "migrated"
      ]
    }
  }
}

Removing desktop-windows-capability prevents access to Windows-specific APIs, demonstrating how Tauri's capability model enforces least-privilege access.

Summary

• Tauri 2 Foundation: Clash Verge Rev builds on Tauri 2's process isolation, separating the webview frontend from the Rust backend to prevent direct system access from JavaScript.

• Capability-Based Security: The application uses declared capabilities in tauri.conf.json to whitelist specific native APIs, ensuring only authorized operations (system tray, notifications, deep links) are accessible from the frontend.

• Asset Protocol Protection: The asset:// protocol configuration prevents directory traversal attacks by restricting the webview to bundled resources only, eliminating risks associated with file:// URL handling.

• Cross-Platform Sandboxing: macOS uses entitlements to disable the OS sandbox (relying on Tauri's isolation), while Windows depends entirely on Tauri's capability model, providing consistent security across platforms without OS-level sandbox complexity.

Frequently Asked Questions

How does Clash Verge Rev prevent the frontend from accessing arbitrary files?

Clash Verge Rev uses Tauri's asset protocol (asset://) configured in src-tauri/tauri.conf.json to restrict resource loading. Unlike file:// URLs, the asset protocol cannot traverse outside the application bundle, ensuring the webview accesses only compiled assets like index.html, JavaScript, and CSS. This prevents directory traversal attacks while allowing the frontend to load necessary resources.

Why is the macOS app sandbox disabled in Clash Verge Rev?

The macOS entitlements file (src-tauri/packages/macos/entitlements.plist) explicitly sets com.apple.security.app-sandbox to false because Tauri's process isolation already provides sufficient security between the webview and native code. Disabling the OS sandbox allows the application to modify system proxy settings and network configurations required for its core functionality, while the Tauri runtime prevents the frontend from accessing raw filesystem APIs directly.

What is the difference between desktop-capability and desktop-windows-capability?

desktop-capability is a cross-platform Tauri capability that grants access to universal desktop APIs such as system tray integration, notifications, and window management across all supported operating systems. desktop-windows-capability is Windows-specific and enables additional APIs tailored for Windows environments, such as specific window behaviors or platform integrations. Clash Verge Rev declares both in tauri.conf.json and tauri.windows.conf.json to ensure full functionality on Windows while maintaining cross-platform compatibility.

How does the Content Security Policy protect against XSS attacks?

The Content Security Policy (CSP) in Clash Verge Rev is set to null in tauri.conf.json, which instructs Tauri to apply its default strict CSP. This default policy blocks inline scripts, restricts script-src and style-src to same-origin content only, and prevents the execution of remote code. By preventing the webview from loading external scripts or executing injected code, the CSP effectively mitigates cross-site scripting (XSS) attacks even if malicious content reaches the frontend.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}