# Pantheon-Security/chrome-mcp-secure [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/Pantheon-Security/chrome-mcp-secure  
**GitHub Stars:** 8  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/pantheon-security-chrome-mcp-secure

## Description
Security-hardened Chrome automation with post-quantum encryption (ML-KEM-768 + ChaCha20-Poly1305), secure credential vault, memory scrubbing, and audit logging. 22 tools for browser automation and secure logins.

## Tools
Capabilities this server exposes over MCP:

- **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
- **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

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "chrome-mcp-secure": {
    "command": "npx",
    "args": ["-y","pantheon-security-chrome-mcp-secure"],
    "env": {
      "COMPLIANCE_LOG_FORMAT": "",
      "COMPLIANCE_LOG_DIR": "",
      "SYSLOG_HOST": "",
      "SYSLOG_PORT": ""
    }
  }
}
```

**Requires environment variables:** `COMPLIANCE_LOG_FORMAT`, `COMPLIANCE_LOG_DIR`, `SYSLOG_HOST`, `SYSLOG_PORT` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation & README

<div align="center">

# Chrome MCP Server (Security Hardened)

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

[![Version](https://img.shields.io/badge/Version-2.3.0-brightgreen.svg)](./CHANGELOG.md)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-2025-green.svg)](https://modelcontextprotocol.io/)
[![Security](https://img.shields.io/badge/Security-Hardened-red.svg)](./SECURITY.md)
[![Post-Quantum](https://img.shields.io/badge/Encryption-Post--Quantum-purple.svg)](./SECURITY.md#post-quantum-encryption)
[![SOC2](https://img.shields.io/badge/SOC_2-Compatible-blue.svg)](#compliance-logging)
[![CEF](https://img.shields.io/badge/CEF-SIEM_Ready-orange.svg)](#compliance-logging)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

[Enterprise Features](#enterprise-ready) • [Compliance Logging](#compliance-logging) • [Security Features](#security-features) • [Quick Start](#quick-start) • [Docker Deploy](#docker-deployment)

</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

```bash
# 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](https://github.com/lxe/chrome-mcp)
> Maintained by [Pantheon Security](https://github.com/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.**

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

### Production Configuration

```bash
# Copy example config
cp env.example .env

# Edit for your environment
vim .env

# Start with custom config
docker-compose up -d
```

### Key Environment Variables

```bash
# 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:

```bash
# 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](https://github.com/Pantheon-Security/chrome-mcp-secure/blob/HEAD/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:
1. Install dependencies and build the project
2. Register the MCP server with Claude Code
3. Start Chrome with remote debugging
4. Create an isolated Chrome profile

### Manual Setup

```bash
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
```bash
./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

```bash
# 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

```bash
openssl rand -base64 32
```

See [SECURITY.md](https://github.com/Pantheon-Security/chrome-mcp-secure/blob/HEAD/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

```bash
# 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](https://github.com/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:

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

See [CHANGELOG.md](https://github.com/Pantheon-Security/chrome-mcp-secure/blob/HEAD/CHANGELOG.md) for full version history.

---

## Troubleshooting

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

### Credential decryption fails
1. Check if you changed machines (machine-derived key won't work)
2. Set `CHROME_MCP_ENCRYPTION_KEY` to the same key used to encrypt
3. 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

```bash
# 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](https://github.com/lxe) - [chrome-mcp](https://github.com/lxe/chrome-mcp)
- **Security Hardening**: [Pantheon Security](https://github.com/Pantheon-Security)
- **Security Patterns**: Adapted from [notebooklm-mcp-secure](https://github.com/Pantheon-Security/notebooklm-mcp-secure)
- **Post-Quantum Crypto**: [@noble/post-quantum](https://www.npmjs.com/package/@noble/post-quantum)

## License

MIT - Same as original.

---

<div align="center">

**Security hardened by [Pantheon Security](https://github.com/Pantheon-Security)**

[Full Security Documentation](https://github.com/Pantheon-Security/chrome-mcp-secure/blob/HEAD/SECURITY.md) • [Report Vulnerability](mailto:support@pantheonsecurity.io)

</div>