Chrome MCP Server (Security Hardened)

Enterprise-grade Chrome automation for AI agents with compliance-ready logging

![Version](./CHANGELOG.md) ![TypeScript](https://www.typescriptlang.org/) ![MCP](https://modelcontextprotocol.io/) ![Security](./SECURITY.md) ![Post-Quantum](./SECURITY.md#post-quantum-encryption) ![SOC2](#compliance-logging) ![CEF](#compliance-logging) ![License](./LICENSE)

Enterprise Features • Compliance Logging • Security Features • Quick Start • Docker Deploy

</div>

---

Enterprise Ready

Built for corporate environments where security, compliance, and auditability are non-negotiable.

| Requirement | Solution | |-------------|----------| | Audit Trails | Hash-chained audit logs with tamper detection | | SIEM Integration | CEF (Splunk, ArcSight, QRadar) + Syslog (RFC 5424) | | Credential Security | Post-quantum encryption (ML-KEM-768 + ChaCha20-Poly1305) | | Data Protection | Auto-redaction of PII in screenshots and logs | | Session Control | Configurable timeouts, auto-expiry, inactivity lockout | | Access Control | Token-based authentication with brute-force protection | | Compliance Logging | OWASP-compliant event categories, correlation IDs |

Compliance Standards Support

| Standard | Coverage | |----------|----------| | SOC 2 Type II | Audit logging, access controls, encryption at rest | | GDPR | Data minimization, right to erasure, audit trails | | PCI DSS | Credential protection, access logging, encryption | | HIPAA | Audit controls, access management, encryption |

---

Compliance Logging

SIEM-ready logging in industry-standard formats. Every tool execution, credential access, and security event is logged.

Output Formats

| Format | Use Case | Example | |--------|----------|---------| | CEF | Splunk, ArcSight, QRadar | CEF:0\|Pantheon-Security\|Chrome-MCP-Secure\|2.3.0\|... | | Syslog | Centralized logging (RFC 5424) | <134>1 2025-12-16T10:30:00Z ... | | JSONL | Elastic, custom pipelines | {"timestamp":"...","category":"audit",...} |

Event Categories (OWASP-Compliant)

authentication - Login attempts, session creation
authorization - Access control decisions
credential - Vault operations (store, retrieve, delete)
audit - Tool executions with timing
security - Rate limits, injection attempts, anomalies
data_access - Sensitive data retrieval

Quick Configuration

# Enable CEF logging for Splunk
COMPLIANCE_LOG_FORMAT=cef
COMPLIANCE_LOG_DIR=./logs/compliance

# Forward to remote syslog
SYSLOG_HOST=siem.company.com
SYSLOG_PORT=514

Example CEF Output

CEF:0|Pantheon-Security|Chrome-MCP-Secure|2.3.0|audit:tool:navigate|tool:navigate|3|rt=1702732800000 outcome=success msg=Tool navigate executed: success request=https://internal.company.com cn1=1702732800-abc123 cn1Label=correlationId

---

Security-hardened fork of lxe/chrome-mcp Maintained by Pantheon Security

---

Real-World Results

"We used this MCP for hours building out our security dashboard - the reliability was incredible. The amount of work we produced was huge compared to manual browser interaction." — Pantheon Security team

Production Tested

| Metric | Result | |--------|--------| | Session Duration | 4+ hours continuous use | | Stability | Zero crashes or disconnects | | Credential Security | All logins encrypted, auto-wiped | | Productivity Gain | 10x faster than manual browser work |

This isn't just a security enhancement - it's a reliable workhorse for AI-assisted browser automation. When you need Claude to interact with web apps for extended sessions, this MCP delivers.

---

Security Features

Core Security (v2.1.0)

| Feature | Description | |---------|-------------| | Post-Quantum Encryption | ML-KEM-768 + ChaCha20-Poly1305 hybrid | | Secure Credential Vault | Encrypted at rest, auto-wiped from memory | | Memory Scrubbing | Zeros sensitive data after use | | Audit Logging | Tamper-evident logs with hash chains | | Profile Isolation | Dedicated Chrome profile for secure sessions | | Log Sanitization | Credentials masked in all output | | Rate Limiting | 100 requests per minute per operation | | Input Validation | CSS selector sanitization, URL validation |

Advanced Security Modules (v2.2.0+)

| Module | Description | |--------|-------------| | Secrets Scanner | Detects 25+ credential patterns (AWS, GitHub, Slack, OpenAI keys, private keys, JWTs, credit cards, SSNs) | | Response Validator | Prompt injection detection (15 patterns), suspicious URL blocking, encoded payload detection | | Session Manager | Credential session lifecycle with 8h max lifetime and 30min inactivity timeout | | MCP Authentication | Token-based auth with auto-generation, SHA256 hashing, brute-force lockout | | Certificate Pinning | SPKI-style pinning for Google, GitHub, Microsoft, Anthropic, OpenAI domains | | Screenshot Redaction | Auto-redacts password fields, credit cards, CVV, SSN, API keys in screenshots | | Cross-Platform Permissions | Secure file permissions on Linux, macOS, and Windows (icacls) |

Post-Quantum Ready

Traditional encryption will be broken by quantum computers. This fork uses hybrid encryption:

ML-KEM-768 (Kyber) + ChaCha20-Poly1305

ML-KEM-768: NIST-standardized post-quantum key encapsulation
ChaCha20-Poly1305: Modern stream cipher (immune to timing attacks)

Even if one algorithm is broken, the other remains secure.

Why Post-Quantum Now?

| Timeline | Threat | |----------|--------| | 2024-2030 | "Harvest now, decrypt later" attacks - adversaries collecting encrypted data today | | 2030-2035 | Early cryptographically-relevant quantum computers expected | | 2035+ | Current RSA/ECC encryption potentially broken |

Your browser credentials stored today could be decrypted in 10 years. This fork protects against that future threat now.

---

Docker Deployment

Recommended for production environments.

# Clone and start
git clone https://github.com/Pantheon-Security/chrome-mcp-secure.git
cd chrome-mcp-secure
docker-compose up -d

Production Configuration

# Copy example config
cp env.example .env

# Edit for your environment
vim .env

# Start with custom config
docker-compose up -d

Key Environment Variables

# SIEM Integration
COMPLIANCE_LOG_FORMAT=cef              # cef, syslog, jsonl, json
SYSLOG_HOST=siem.company.com           # Remote syslog server
SYSLOG_PORT=514

# Encryption (REQUIRED for production)
CHROME_MCP_ENCRYPTION_KEY=$(openssl rand -base64 32)

# Session Security
CHROME_MCP_SESSION_MAX_LIFETIME=28800000   # 8 hours
CHROME_MCP_SESSION_INACTIVITY=1800000      # 30 minutes

Log Collection

Logs are written to ./logs/compliance/ in your chosen format:

# View compliance logs
tail -f logs/compliance/compliance-2025-12-16.cef

# Forward to Splunk via syslog
docker-compose logs chrome-mcp | nc -u siem.company.com 514

See env.example for all configuration options.

---

Installation

One-Command Setup (Recommended)

Linux / macOS: ``bash git clone https://github.com/Pantheon-Security/chrome-mcp-secure.git cd chrome-mcp-secure ./setup.sh ``

Windows (PowerShell): ``powershell git clone https://github.com/Pantheon-Security/chrome-mcp-secure.git cd chrome-mcp-secure .\setup.ps1 ``

This will:

Install dependencies and build the project
Register the MCP server with Claude Code
Start Chrome with remote debugging
Create an isolated Chrome profile

Manual Setup

npm install && npm run build
claude mcp add chrome-mcp-secure --scope user -- node /path/to/chrome-mcp-secure/dist/index.js
google-chrome --remote-debugging-port=9222 --user-data-dir=~/.chrome-mcp-profile

Platform-Specific Notes

| Platform | Setup Script | Chrome Profile Location | |----------|--------------|------------------------| | Linux | ./setup.sh | ~/.chrome-mcp-profile | | macOS | ./setup.sh | ~/.chrome-mcp-profile | | Windows | .\setup.ps1 | %USERPROFILE%\.chrome-mcp-profile |

---

Quick Start

1. Start Chrome with debugging

./setup.sh --start-chrome

2. Use in Claude Code

"Check Chrome connection with health tool"
"Navigate to https://example.com"
"Take a screenshot"

3. Secure Login Flow

"Store a credential for my GitHub account"
"Navigate to github.com/login"
"Use secure_login with the stored credential"

---

Available Tools

Browser Automation (15 tools)

| Tool | Description | |------|-------------| | health | Check Chrome connection and version | | navigate | Navigate to URL | | get_tabs | List all Chrome tabs | | click_element | Click element by CSS selector | | click | Click at coordinates | | type | Type text at cursor | | get_text | Extract text from element | | get_page_info | Get URL, title, interactive elements | | get_page_state | Get scroll position, viewport size | | scroll | Scroll to coordinates | | screenshot | Capture page screenshot | | wait_for_element | Wait for element to appear | | evaluate | Execute JavaScript | | fill | Fill form field | | bypass_cert_and_navigate | Navigate with HTTPS cert bypass |

Secure Credential Tools (7 tools)

| Tool | Description | |------|-------------| | store_credential | Store encrypted login credentials | | list_credentials | List stored credentials (no passwords shown) | | get_credential | Get credential metadata | | delete_credential | Remove a stored credential | | update_credential | Update an existing credential | | secure_login | Auto-fill login forms using stored credentials | | get_vault_status | Check vault encryption status |

---

Secure Credential Usage

Storing Credentials

Store a credential for my Google account:
- Name: "Google Work"
- Type: google
- Email: me@example.com
- Password: mypassword123
- Domain: google.com

Using Credentials for Login

1. Navigate to https://accounts.google.com
2. Use secure_login with the credential ID from list_credentials

The secure_login tool will:

Retrieve and decrypt the credential from the vault
Auto-fill the username/email field
Auto-fill the password field
Click the submit button
Wipe credentials from memory after use

---

What Gets Protected

| Data | Protection | |------|------------| | Login credentials | Post-quantum encrypted at rest | | Passwords in memory | Auto-wiped after 5 min TTL | | Log output | Credentials auto-masked | | Chrome profile | Isolated from default browser | | Audit trail | Hash-chained for tamper detection |

---

Configuration

Environment Variables

# Chrome connection
CHROME_HOST=localhost
CHROME_PORT=9222
CHROME_PROFILE_DIR=~/.chrome-mcp-profile

# Encryption (recommended for production)
CHROME_MCP_ENCRYPTION_KEY=<base64-32-bytes>
CHROME_MCP_USE_POST_QUANTUM=true

# Credential vault
CHROME_MCP_CONFIG_DIR=~/.chrome-mcp
CHROME_MCP_CREDENTIAL_TTL=300000  # 5 minutes

# Logging
LOG_LEVEL=info
AUDIT_LOGGING=true

Generate Strong Encryption Key

openssl rand -base64 32

See SECURITY.md for complete configuration reference.

---

Security Architecture

Encryption

                    ┌─────────────────────────────────────┐
                    │      ML-KEM-768 Key Pair            │
                    │   (Post-Quantum Key Encapsulation)  │
                    └─────────────────┬───────────────────┘
                                      │
                    ┌─────────────────┴───────────────────┐
                    │      ChaCha20-Poly1305              │
                    │   (Symmetric AEAD Encryption)       │
                    └─────────────────┬───────────────────┘
                                      │
                    ┌─────────────────┴───────────────────┐
                    │      Encrypted Credential Files     │
                    │   ~/.chrome-mcp/credentials/*.pqenc │
                    └─────────────────────────────────────┘

Memory Protection

SecureCredential class: Auto-wipes credentials after TTL (5 min default)
Zero-fill buffers: Random overwrite + zero fill prevents memory dumps
No credential logging: Automatic masking of sensitive field names

Why ChaCha20-Poly1305 over AES-GCM?

| Property | ChaCha20-Poly1305 | AES-GCM | |----------|-------------------|---------| | Timing attacks | Immune (constant-time) | Vulnerable without AES-NI | | Software speed | Fast everywhere | Slow without hardware | | Complexity | Simple | Complex (GCM mode) | | Adoption | Google, Cloudflare TLS | Legacy systems |

---

Management Commands

# Full setup
./setup.sh

# Check status
./setup.sh --check

# Uninstall from Claude Code
./setup.sh --uninstall

# Start/stop Chrome
./setup.sh --start-chrome
./setup.sh --stop-chrome

---

Architecture

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│ Claude/     │────▶│  MCP Server      │────▶│   Chrome    │
│ AI Agent    │     │  (This Fork)     │     │   (CDP)     │
└─────────────┘     └──────────────────┘     └─────────────┘
                           │
                    ┌──────┴──────┐
                    │  Security   │
                    │   Layers    │
                    └─────────────┘
                    • PQ Encryption
                    • Credential Vault
                    • Memory Wipe
                    • Audit Logs
                    • Rate Limits
                    • Input Validation

---

File Structure

chrome-mcp-secure/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── cdp-client.ts         # Persistent CDP WebSocket client
│   ├── tools.ts              # Browser automation tools
│   │
│   │── # Core Security (v2.1.0)
│   ├── credential-vault.ts   # Encrypted credential storage
│   ├── credential-tools.ts   # Credential MCP tools
│   ├── crypto.ts             # Post-quantum encryption (ML-KEM-768 + ChaCha20)
│   ├── secure-memory.ts      # Memory protection utilities
│   ├── security.ts           # Input validation, rate limiting
│   ├── logger.ts             # Logging with auto-masking
│   ├── errors.ts             # Typed error classes
│   │
│   │── # Advanced Security Modules (v2.2.0+)
│   ├── secrets-scanner.ts    # Credential leak detection (25+ patterns)
│   ├── response-validator.ts # Prompt injection detection
│   ├── session-manager.ts    # Session lifecycle management
│   ├── mcp-auth.ts           # Token-based MCP authentication
│   ├── cert-pinning.ts       # Certificate pinning for sensitive domains
│   ├── screenshot-redaction.ts # Auto-redact sensitive fields
│   └── file-permissions.ts   # Cross-platform secure file permissions
│
├── dist/                     # Compiled JavaScript
├── setup.sh                  # Linux/macOS setup
├── setup.ps1                 # Windows setup
├── SECURITY.md               # Security documentation
├── CHANGELOG.md              # Version history
├── CLAUDE.md                 # Claude Code integration guide
└── README.md

---

Comparison with Original

| Feature | lxe/chrome-mcp | This Fork | |---------|----------|-----------| | Chrome automation | ✅ | ✅ | | Persistent WebSocket | ✅ | ✅ | | Cross-platform | ✅ | ✅ | | Post-quantum encryption | ❌ | ✅ | | Secure credential vault | ❌ | ✅ | | Memory scrubbing | ❌ | ✅ | | Audit logging | ❌ | ✅ | | Auto log masking | ❌ | ✅ | | Profile isolation | ❌ | ✅ | | Secrets scanner | ❌ | ✅ | | Prompt injection detection | ❌ | ✅ | | Session management | ❌ | ✅ | | MCP authentication | ❌ | ✅ | | Certificate pinning | ❌ | ✅ | | Screenshot redaction | ❌ | ✅ |

---

What's New in v2.2.x

v2.2.1 - Cross-Platform File Permissions

All file operations use centralized file-permissions.ts
Proper Windows ACL support via icacls
Consistent 0o700/0o600 permissions on Unix

v2.2.0 - Advanced Security Modules

Six new security modules totaling 3,000+ lines of security hardening:

Secrets Scanner - Detects leaked credentials in page content using patterns from TruffleHog, GitLeaks, and MEDUSA
Response Validator - Blocks prompt injection attacks in scraped content
Session Manager - Auto-expires credential sessions after configurable timeouts
MCP Authentication - Protects the MCP server itself with token-based auth
Certificate Pinning - Validates TLS certificates for sensitive domains
Screenshot Redaction - Overlays sensitive fields before screenshots

See CHANGELOG.md for full version history.

---

Troubleshooting

Chrome not accessible

curl http://localhost:9222/json
# If no response, start Chrome:
./setup.sh --start-chrome

Credential decryption fails

Check if you changed machines (machine-derived key won't work)
Set CHROME_MCP_ENCRYPTION_KEY to the same key used to encrypt
Credentials may need to be re-stored if key is lost

Element not found

Use get_page_info to see available elements
Use wait_for_element for dynamic content

---

Development

# Install dependencies
npm install

# Development mode (auto-reload)
npm run dev

# Type checking
npm run typecheck

# Build for production
npm run build

# Run built version
npm start

---

Reporting Vulnerabilities

Found a security issue? Do not open a public GitHub issue.

Email: support@pantheonsecurity.io

---

Credits

Original Chrome MCP: lxe - chrome-mcp
Security Hardening: Pantheon Security
Security Patterns: Adapted from notebooklm-mcp-secure
Post-Quantum Crypto: @noble/post-quantum

License

MIT - Same as original.

---

Security hardened by Pantheon Security

Full Security Documentation • Report Vulnerability