Security
Claudezilla runs locally and communicates over a Unix socket. This guide covers the security controls available to restrict agent behavior and protect your browsing environment. ## Domain Allowlist Restrict which domains an agent can navigate to using `firefox_set_config`. When set, `firefox_navigate` and `firefox_create_window` block requests to unlisted domains. ```js // Only allow access to your staging environment firefox_set_config({ allowedDomains: ["staging.myapp.com", "*.myapp.com"] }) // This works firefox_create_window({ url: "https://staging.myapp.com/dashboard" }) // This is blocked firefox_create_window({ url: "https://google.com" }) // Error: DOMAIN_BLOCKED: Navigation to "google.com" not allowed. // Allowed: ["staging.myapp.com", "*.myapp.com"] ``` Wildcards match subdomains: `*.example.com` matches `app.example.com` and the bare `example.com`. The `about:` scheme is always allowed regardless of the allowlist. To clear the restriction: ```js firefox_set_config({ allowedDomains: [] }) ``` The allowlist is per-agent and per-session. It resets when the MCP server restarts. ## Private Mode By default, Claudezilla opens tabs in private (incognito) windows. This prevents cookies and browsing history from persisting. ```js // Disable private mode for sites that require login firefox_set_private_mode({ enabled: false }) // Re-enable private mode firefox_set_private_mode({ enabled: true }) ``` When the "Run in Private Windows" permission is enabled in Firefox (about:addons), `firefox_navigate` is automatically disabled to prevent accidentally creating non-private browsing contexts. ## Socket Security The Unix socket between the MCP server and native host is secured with: - **Restrictive permissions**: Socket file is `chmod 0600` (user-only access) - **Secure path**: Uses `XDG_RUNTIME_DIR` when available (per-user, tmpfs-backed), falls back to system temp directory - **Buffer limits**: 10MB maximum message size prevents memory exhaustion - **Auth token**: Shared secret written by the host on startup, required for MCP server connections On multi-user systems, the 0600 permission ensures other users cannot connect to your Claudezilla instance. ## URL Validation All URLs are validated before navigation: | Scheme | Status | |--------|--------| | `http:` | Allowed | | `https:` | Allowed | | `about:` | Allowed | | `file:` | Allowed (Claude Code runs locally) | | `javascript:` | Blocked | | `data:` | Blocked | | `chrome://` | Blocked | | `moz-extension://` | Blocked | This prevents XSS and code execution via URL injection. ## Input Validation ### CSS Selectors All selectors are validated before use: - Maximum length: 1000 characters - Syntax-checked via `document.querySelector()` in a try/catch - Invalid selectors return descriptive errors ### Expression Evaluation `firefox_evaluate` blocks dangerous patterns including `fetch`, `eval`, and cookie access, preventing data exfiltration through evaluated JavaScript. ## Content Security ### Structured Responses All tool responses are structured JSON. Page content is always returned as data in explicit fields (`result.text`, `result.html`), never mixed with instructions. This mitigates prompt injection from malicious page content. ### Network Monitoring The `firefox_get_network_requests` tool excludes sensitive data: - Request bodies are never captured (prevents credential leakage) - URL query parameters matching sensitive patterns are redacted - Debug logs are written with 0600 permissions ### Console Capture Console log capture is disabled by default and only activates on first call to `firefox_get_console`. This prevents inadvertent capture of sensitive data logged by page scripts. ## Multi-Agent Isolation Each agent gets a 128-bit entropy ID (`agent_<32-hex-chars>_<pid>`). Tab ownership is enforced on all content commands — agents cannot read from, write to, or close tabs they did not create. See the [Multi-Agent guide](/guides/multi-agent/) for details. ## Recommendations 1. **Use domain allowlists** when automating against specific sites to prevent unintended navigation. 2. **Keep private mode enabled** unless you specifically need persistent cookies. 3. **Do not automate login** to sensitive accounts — the extension uses your Firefox session. 4. **Review automation** — check `/tmp/claudezilla-debug.log` to see executed commands. 5. **Use Firefox containers** for sensitive browsing separate from Claudezilla tabs. Report security vulnerabilities to `security@boot.industries`.Claudezilla runs locally and communicates over a Unix socket. This guide covers the security controls available to restrict agent behavior and protect your browsing environment.
Domain Allowlist
Section titled “Domain Allowlist”Restrict which domains an agent can navigate to using firefox_set_config. When set, firefox_navigate and firefox_create_window block requests to unlisted domains.
// Only allow access to your staging environmentfirefox_set_config({ allowedDomains: ["staging.myapp.com", "*.myapp.com"]})
// This worksfirefox_create_window({ url: "https://staging.myapp.com/dashboard" })
// This is blockedfirefox_create_window({ url: "https://google.com" })// Error: DOMAIN_BLOCKED: Navigation to "google.com" not allowed.// Allowed: ["staging.myapp.com", "*.myapp.com"]Wildcards match subdomains: *.example.com matches app.example.com and the bare example.com. The about: scheme is always allowed regardless of the allowlist.
To clear the restriction:
firefox_set_config({ allowedDomains: [] })The allowlist is per-agent and per-session. It resets when the MCP server restarts.
Private Mode
Section titled “Private Mode”By default, Claudezilla opens tabs in private (incognito) windows. This prevents cookies and browsing history from persisting.
// Disable private mode for sites that require loginfirefox_set_private_mode({ enabled: false })
// Re-enable private modefirefox_set_private_mode({ enabled: true })When the “Run in Private Windows” permission is enabled in Firefox (about:addons), firefox_navigate is automatically disabled to prevent accidentally creating non-private browsing contexts.
Socket Security
Section titled “Socket Security”The Unix socket between the MCP server and native host is secured with:
- Restrictive permissions: Socket file is
chmod 0600(user-only access) - Secure path: Uses
XDG_RUNTIME_DIRwhen available (per-user, tmpfs-backed), falls back to system temp directory - Buffer limits: 10MB maximum message size prevents memory exhaustion
- Auth token: Shared secret written by the host on startup, required for MCP server connections
On multi-user systems, the 0600 permission ensures other users cannot connect to your Claudezilla instance.
URL Validation
Section titled “URL Validation”All URLs are validated before navigation:
| Scheme | Status |
|---|---|
http: | Allowed |
https: | Allowed |
about: | Allowed |
file: | Allowed (Claude Code runs locally) |
javascript: | Blocked |
data: | Blocked |
chrome:// | Blocked |
moz-extension:// | Blocked |
This prevents XSS and code execution via URL injection.
Input Validation
Section titled “Input Validation”CSS Selectors
Section titled “CSS Selectors”All selectors are validated before use:
- Maximum length: 1000 characters
- Syntax-checked via
document.querySelector()in a try/catch - Invalid selectors return descriptive errors
Expression Evaluation
Section titled “Expression Evaluation”firefox_evaluate blocks dangerous patterns including fetch, eval, and cookie access, preventing data exfiltration through evaluated JavaScript.
Content Security
Section titled “Content Security”Structured Responses
Section titled “Structured Responses”All tool responses are structured JSON. Page content is always returned as data in explicit fields (result.text, result.html), never mixed with instructions. This mitigates prompt injection from malicious page content.
Network Monitoring
Section titled “Network Monitoring”The firefox_get_network_requests tool excludes sensitive data:
- Request bodies are never captured (prevents credential leakage)
- URL query parameters matching sensitive patterns are redacted
- Debug logs are written with 0600 permissions
Console Capture
Section titled “Console Capture”Console log capture is disabled by default and only activates on first call to firefox_get_console. This prevents inadvertent capture of sensitive data logged by page scripts.
Multi-Agent Isolation
Section titled “Multi-Agent Isolation”Each agent gets a 128-bit entropy ID (agent_<32-hex-chars>_<pid>). Tab ownership is enforced on all content commands — agents cannot read from, write to, or close tabs they did not create. See the Multi-Agent guide for details.
Recommendations
Section titled “Recommendations”- Use domain allowlists when automating against specific sites to prevent unintended navigation.
- Keep private mode enabled unless you specifically need persistent cookies.
- Do not automate login to sensitive accounts — the extension uses your Firefox session.
- Review automation — check
/tmp/claudezilla-debug.logto see executed commands. - Use Firefox containers for sensitive browsing separate from Claudezilla tabs.
Report security vulnerabilities to security@boot.industries.