# Security Policy

## Supported Versions

Security patches are published for supported release lines. We recommend always running the **latest** `0.5.x` release.

| Version   | Supported |
| --------- | --------- |
| **0.5.x** | :white_check_mark: Active (features + security fixes) |
| **0.4.x** | :warning: Security fixes only (best effort); upgrade to 0.5.x recommended |
| **< 0.4** | :x: Unsupported |

Pre-1.0 versions may include breaking changes between minors; treat upgrades as requiring release-note review.

## Reporting a Vulnerability

If you discover a security vulnerability in Browser DevTools MCP, please report it responsibly.

### How to Report

1. **DO NOT** create a public GitHub issue for security vulnerabilities
2. Report via one of these methods:
   - **GitHub Security Advisory** (preferred): [Create a security advisory](https://github.com/serkan-ozal/browser-devtools-mcp/security/advisories/new)
   - **Email**: serkanozal86@gmail.com
3. Include the following information:
   - Description of the vulnerability
   - Steps to reproduce
   - Potential impact
   - Suggested fix (if any)

### What to Expect

- **Acknowledgment**: You will receive an acknowledgment within 48 hours
- **Updates**: We will keep you informed of our progress
- **Resolution**: We aim to resolve critical issues within 7 days
- **Credit**: With your permission, we will credit you in the release notes

## Security Considerations

### Browser Automation Risks

Browser DevTools MCP provides powerful browser automation capabilities. Users should be aware of:

1. **Code Execution**: The `execute` tool runs arbitrary JavaScript in a VM; on the browser platform it receives `page` (Playwright Page) so code can also run script in the browser via `page.evaluate()`. The VM is not a security boundary — only use with trusted code inputs.

2. **Network Access**: The browser can make requests to any URL
   - HTTP requests from the browser inherit the page's cookies and session
   - Stubbing/mocking tools can intercept and modify requests or responses—use only in trusted environments and avoid pointing at production systems unless intentional
   - Observability tools can log URLs, headers, and (when enabled) bodies; treat captured traffic as potentially sensitive
   - Be cautious when automating authenticated sessions

3. **Persistent Context**: When `BROWSER_PERSISTENT_ENABLE=true`
   - Browser state (cookies, localStorage) persists across sessions
   - User data is stored in `BROWSER_PERSISTENT_USER_DATA_DIR`
   - Sensitive data may be stored locally
   - Restrict filesystem permissions on the user data directory

4. **Chrome DevTools Protocol (CDP) attach**: When `BROWSER_CDP_ENABLE=true` or `BROWSER_CDP_ENDPOINT_URL` is set (Chromium only)
   - The server may connect to an existing browser over CDP, which is equivalent to **full remote control** of that browser (navigation, JS, network, etc.)
   - **Never** expose a CDP endpoint to untrusted networks or the public internet without strict access controls (firewall, VPN, auth proxy)
   - Prefer **loopback** (`127.0.0.1`) for local debugging; treat any remote `BROWSER_CDP_ENDPOINT_URL` as highly sensitive configuration
   - Enabling remote debugging on Chrome (e.g. `--remote-debugging-port=`) increases attack surface—disable when not needed

5. **Screenshot/PDF Capture**: Content tools can capture sensitive information
   - Screenshots may contain PII or credentials visible on screen
   - Optional annotated screenshots overlay ref labels and return an annotations array (ref, role, name, box); when refs are empty, an ARIA snapshot is taken automatically to populate refs
   - PDFs preserve full page content
   - Be mindful of what pages are captured

6. **ARIA Snapshots and Ref Map**: Session context stores a ref map (e1, e2, ...) from the last ARIA snapshot
   - Refs map to element roles, names, and selectors; used by interaction tools (click, fill, hover, select, drag, scroll, press-key) and annotated screenshots
   - Ref map is session-scoped and not persisted; it is cleared on navigation or when a new snapshot is taken
   - Cursor-interactive refs (when cursorInteractive is enabled) may include generated CSS selectors for elements without ARIA roles

7. **Debug Tools**: Non-blocking debugging capabilities capture runtime state
   - Tracepoints capture call stack and local variables (may include sensitive data)
   - Logpoints evaluate expressions in page context
   - Exception snapshots capture error state and stack traces
   - Snapshots are stored in memory and cleared on session end

### API Keys and Secrets

The following environment variables may contain sensitive information:

| Variable | Sensitivity | Description |
|----------|-------------|-------------|
| `FIGMA_ACCESS_TOKEN` | High | Figma API access token |
| `OTEL_EXPORTER_HTTP_HEADERS` | High | May contain API keys for observability platforms |
| `COLLECTOR_API_KEY` | High | Authenticates tool-call event + artifact uploads to the collector |
| `AWS_PROFILE` | Medium | AWS credentials profile name |

### Collector Integration

When `COLLECTOR_URL` (and `COLLECTOR_API_KEY`) are configured, the server ships a `tool_call` event to the collector after every tool execution, and may upload artifacts (screenshots, videos) to the collector's S3 bucket via presigned URLs. The payload can contain sensitive data:

- `tool_input` may include typed form values (passwords, PII, card numbers via `interaction_fill`), URLs with query-string tokens, mock/stub bodies, or `execute`/scenario scripts.
- `tool_response` may include HTML/text extraction, ARIA snapshots, full HTTP request/response headers and bodies (`Authorization`, `Cookie`, auth tokens), console messages, and React component state.
- Artifacts (screenshots, videos) capture whatever is visible on screen — form content, OTPs, personal info.

Two opt-out knobs let operators limit exposure:

| Variable | Default | Effect |
|----------|---------|--------|
| `COLLECTOR_EVENTS_TOOL_DETAIL_ENABLE` | `true` | When `false`, strips `tool_input` and `tool_response` from collector events. IDs, `tool_name`, sizes, duration, and `error` are still sent. |
| `COLLECTOR_ARTIFACTS_ENABLE` | `true` | When `false`, skips all artifact (screenshot/video) uploads to the collector. The files stay on the local filesystem only. |

Both flags are server-side env vars; no caller on the tool-input `_metadata` path can override them. Use them together when the collector endpoint is outside your trust boundary or when sessions may contain regulated data.

**Best Practices:**
- Never commit secrets to version control
- Use environment variables or secret management tools
- Rotate API keys regularly
- Use minimal-permission API tokens

### Network Security

When using HTTP transport (`--transport=streamable-http`):

1. **Local Development**: The server binds to `localhost` by default
2. **Remote Deployment**: 
   - Always use HTTPS in production
   - Implement authentication/authorization
   - Consider network isolation
3. **CORS**: The server does not implement CORS restrictions by default

### Session Security

- Sessions are isolated per MCP client connection
- **Trust model**: Any client that can invoke the MCP server can use browser automation tools; lock down who can start the process and who can connect (stdio parent process, HTTP bind address, reverse proxy auth)
- Session data is stored in memory (not persisted by default)
- Idle sessions are automatically cleaned up (`SESSION_IDLE_SECONDS`)
- Setting `SESSION_CLOSE_ON_SOCKET_CLOSE=true` closes sessions immediately on disconnect

### Node Platform (`node-devtools-mcp`)

The Node entrypoint exposes the same **`execute`** tool pattern in a VM without an injected Playwright `page`. It remains **not** a security boundary: arbitrary JS in the sandbox can still be dangerous if the VM or allowed builtins change over time. Only run with trusted inputs and callers.

## Security Features

### Sandbox Isolation

The `execute` tool runs in a Node.js VM context with limited isolation:
- No access to `require`, `process`, `fs`, `Buffer`, `fetch`
- Limited built-in APIs available; on browser platform `page` (Playwright Page) is injected
- **Note**: This is NOT a security boundary — treat all input as trusted

### OpenTelemetry Security

When using OpenTelemetry integration:
- Trace data may contain sensitive URL paths and parameters
- Headers can be configured to authenticate with collectors
- Consider what data is being exported to observability platforms

## Responsible Disclosure

We kindly ask security researchers to:

1. Give us reasonable time to fix issues before public disclosure
2. Avoid accessing or modifying other users' data
3. Act in good faith to avoid privacy violations and service disruptions

We commit to:

1. Not pursuing legal action against researchers acting in good faith
2. Working with you to understand and resolve the issue
3. Acknowledging your contribution (with your permission)

## Security Updates

Security updates are released as patch versions. We recommend:

1. Always using the latest version
2. Subscribing to GitHub releases for notifications
3. Reviewing the changelog for security-related fixes

## Contact

For security-related inquiries:
- **GitHub Security Advisory**: [Report a vulnerability](https://github.com/serkan-ozal/browser-devtools-mcp/security/advisories/new)
- **Email**: serkanozal86@gmail.com
- **GitHub**: [@serkan-ozal](https://github.com/serkan-ozal)