cdp-ninja 1.0.5

🥷 Lightweight Chrome DevTools Protocol bridge for browser debugging and security testing

CDP Ninja 🥷

A lightweight Chrome DevTools Protocol bridge that gives you powerful browser debugging capabilities without the bloat of Puppeteer or Playwright.

⚠️ SECURITY WARNING ⚠️

CDP Ninja is intentionally dangerous for security testing and fuzzing. It allows:

• 🚨 No Input Validation: Send malformed selectors, injection attempts, null bytes, XSS payloads
• 🚨 No Rate Limiting: Flood with requests, infinite loops, memory bombs
• 🚨 PowerShell Execution: Remote code execution when ENABLE_POWERSHELL=true
• 🚨 Any URL Navigation: javascript:, data:, file:// protocols allowed
• 🚨 Raw DOM Manipulation: HTML injection, script injection, attribute modification

Philosophy: If we can break it with malformed data, it has bugs. This tool crashes things on purpose.

Only use CDP Ninja in secure, isolated environments for testing purposes.

Why CDP Ninja?

• No Chromium Download: Uses your existing Chrome installation (saves 300MB)
• Minimal Dependencies: Only 16MB of Python packages vs 350MB+ for alternatives
• Direct CDP Access: No abstraction layers, just raw Chrome DevTools power
• Remote Debugging: SSH tunnel support for debugging from anywhere
• Claude Code Integration: Works as a specialized debugging agent

Architecture

Your Chrome → CDP WebSocket → Python Bridge → HTTP API → SSH Tunnel → Claude/Tools
     ↑             ↑              ↑             ↑           ↑
Already      Built-in        16MB deps    REST API    Remote access
installed    protocol

Features

• 🖱️ Full Browser Control: Click, type, scroll, hover, drag and drop
• 🌐 Network Monitoring: Capture all requests, responses, and timing
• 📊 Performance Profiling: Memory, CPU, rendering metrics
• 🐛 Console Access: Capture logs, errors, warnings
• 📸 Screenshots: Full page or viewport captures
• 🔍 DOM Inspection: Query, modify, and analyze page structure
• ⚡ JavaScript Execution: Run code in page context
• 📝 Form Handling: Fill, submit, and extract form data
• 🎯 Bug Reproduction: Automated workflows for reproducing issues

Quick Start

Prerequisites

1. Chrome installed
2. Python 3.8+ installed

Installation

# Install CDP Ninja
pip install git+https://github.com/travofoz/cdp-ninja.git

# Start Chrome with debugging enabled
# Windows PowerShell:
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --remote-allow-origins=* --user-data-dir="C:\temp\chrome-debug"

# Linux/macOS:
google-chrome --remote-debugging-port=9222 --remote-allow-origins=* --user-data-dir=/tmp/chrome-debug

# Start CDP Ninja
cdp-ninja

Test it works:

curl http://localhost:8888/cdp/status

Custom Settings

# Use different ports
cdp-ninja --bridge-port 9999 --cdp-port 9222

# Enable debug mode
cdp-ninja --debug

# Set timeout (for heavy analytics, pingtrees, etc.)
cdp-ninja --timeout 1200

# Environment variables
export CHROME_TIMEOUT=600
cdp-ninja

SSH Tunnel Setup

To expose your local CDP Ninja to a remote server:

# From your local machine (where CDP Ninja runs)
ssh -R 8888:localhost:8888 user@your-server

# Now on the remote server:
curl http://localhost:8888/cdp/status

Usage Examples

Click a Button

import requests

# Click by CSS selector
response = requests.post("http://localhost:8888/cdp/click",
                        json={"selector": "#submit-button"})

# Click by coordinates
response = requests.post("http://localhost:8888/cdp/click",
                        json={"x": 100, "y": 200})

Drag and Drop

# Drag by coordinates
response = requests.post("http://localhost:8888/cdp/drag",
                        json={"startX": 100, "startY": 100, "endX": 300, "endY": 300})

# Drag by selectors
response = requests.post("http://localhost:8888/cdp/drag",
                        json={"startSelector": "#drag-handle", "endSelector": "#drop-zone"})

DOM Manipulation

# Set element attribute
response = requests.post("http://localhost:8888/cdp/dom/set_attribute",
                        json={"selector": "#element", "name": "data-test", "value": "modified"})

# Set element HTML content
response = requests.post("http://localhost:8888/cdp/dom/set_html",
                        json={"selector": "#content", "html": "<h1>New Content</h1>"})

# Query DOM elements
response = requests.post("http://localhost:8888/cdp/dom/query",
                        json={"selector": ".item"})

Capture Screenshot

# Take screenshot
response = requests.get("http://localhost:8888/cdp/screenshot")
with open("screenshot.png", "wb") as f:
    f.write(response.content)

# Full page screenshot
response = requests.get("http://localhost:8888/cdp/screenshot?full_page=true")

Execute JavaScript (⚠️ No Validation)

# Normal JavaScript execution
response = requests.post("http://localhost:8888/cdp/execute",
                         json={"code": "document.querySelector('#result').innerText"})
result = response.json()

# ⚠️ Security Testing Examples (will attempt execution):
# Infinite loop test
requests.post("http://localhost:8888/cdp/execute",
              json={"code": "while(true) { console.log('crash test'); }"})

# Memory bomb test
requests.post("http://localhost:8888/cdp/execute",
              json={"code": "let a = []; while(true) a.push('x'.repeat(1000000));"})

# XSS injection test
requests.post("http://localhost:8888/cdp/execute",
              json={"code": "alert('XSS test: ' + document.cookie)"})

Monitor Network Traffic

# Get all recent network requests
response = requests.get("http://localhost:8888/cdp/network/requests")
for request in response.json():
    print(f"{request['method']} {request['url']} - Status: {request.get('response', {}).get('status')}")

# Block specific URLs
requests.post("http://localhost:8888/cdp/network/block",
              json={"patterns": ["*://*.doubleclick.net/*", "*://analytics.google.com/*"]})

Fill Forms (⚠️ No Sanitization)

# Normal form filling
requests.post("http://localhost:8888/cdp/form/fill", json={
    "fields": {
        "#email": "[e-mail]",
        "#password": "secret123",
        "#username": "testuser"
    }
})

# ⚠️ Security Testing Examples:
# Malformed selectors and values with null bytes
requests.post("http://localhost:8888/cdp/form/fill", json={
    "fields": {
        ">>>invalid_selector<<<": "test\0null\nbytes",
        "#input": "x" * 1000000,  # Huge value test
        "#other": "'; DROP TABLE users; --"  # SQL injection attempt
    }
})

# Test malformed form submission
requests.post("http://localhost:8888/cdp/form/submit",
              json={"selector": ">>>invalid<<<"})

Bug Reproduction Workflow

# Automated bug reproduction with screenshots
response = requests.post("http://localhost:8888/debug/reproduce", json={
    "steps": [
        {"action": "navigate", "url": "http://localhost:3000"},
        {"action": "click", "selector": "#login-btn"},
        {"action": "type", "selector": "#email", "text": "[e-mail]"},
        {"action": "click", "selector": "#submit"},
        {"action": "wait", "duration": 2},
        {"action": "click", "selector": "#submit"},  # Double-click bug
        {"action": "click", "selector": "#submit"}   # Triple-click bug
    ],
    "screenshots": True,
    "capture_console": True
})

print(f"Bug reproduced: {response.json()['completed']}")

Claude Code Integration

Add to your Claude Code agent configuration:

cdp-debugger: Browser debugging specialist using Chrome DevTools Protocol.
Captures network requests, console logs, executes JavaScript, takes screenshots,
clicks elements, fills forms. Use PROACTIVELY for debugging client-side issues,
reproducing bugs, and automated browser interaction. (Tools: WebFetch to CDP bridge)

Usage:

from tools import Task

# Use the debugging agent
Task(
    subagent_type="cdp-debugger",
    description="Debug login form",
    prompt="Click login button 5 times rapidly and capture any console errors or network failures"
)

Timeout Configuration

CDP Ninja uses configurable timeouts to handle different use cases:

Default Timeout

• 900 seconds (15 minutes) - Suitable for heavy analytics, pingtrees, and business reporting

Configuration Options

CLI Flag:

# Quick testing (30 seconds)
cdp-ninja --timeout 30

# Heavy analytics (20 minutes)
cdp-ninja --timeout 1200

# Pingtree debugging (30 minutes)
cdp-ninja --timeout 1800

Environment Variable:

# Set via environment
export CHROME_TIMEOUT=600
cdp-ninja

# Or inline
CHROME_TIMEOUT=300 cdp-ninja

Use Cases

• CI/CD Testing: 30-60 seconds for fast feedback
• Development: 900 seconds (default) for complex applications
• Analytics/Reporting: 1200+ seconds for heavy database queries
• Pingtree Debugging: 1800+ seconds for multi-channel operations

Note: HTTP clients (curl, WebFetch) can set their own timeouts independently. CDP Ninja's timeout only prevents internal hangs.

API Reference

Core Operations

• GET /health - Health check
• GET /cdp/status - CDP connection status
• POST /cdp/command - Execute raw CDP command

Browser Interaction

• POST /cdp/click - Click element (selector or coordinates)
• POST /cdp/type - Type text into element
• POST /cdp/scroll - Scroll page
• POST /cdp/hover - Hover over element
• POST /cdp/drag - Drag from start to end (coordinates or selectors)
• GET /cdp/screenshot - Capture screenshot

Debugging Operations

• GET /cdp/console/logs - Get console output
• GET /cdp/network/requests - Get network activity
• POST /cdp/execute - Execute JavaScript
• GET /cdp/dom/snapshot - Get DOM tree
• POST /cdp/dom/query - Query DOM elements
• POST /cdp/dom/set_attribute - Set element attributes
• POST /cdp/dom/set_html - Set element innerHTML

Form Operations

• POST /cdp/form/fill - Fill form fields
• POST /cdp/form/submit - Submit form
• GET /cdp/form/values - Get form field values

Page Navigation

• POST /cdp/page/navigate - Navigate to URL
• GET /cdp/page/reload - Reload page
• GET /cdp/page/back - Go back
• GET /cdp/page/forward - Go forward

Network Control

• POST /cdp/network/block - Block URLs
• POST /cdp/network/throttle - Simulate slow network
• GET /cdp/network/clear - Clear network cache

System Integration (⚠️ DANGEROUS)

• POST /system/execute - Execute RAW PowerShell/CMD/Bash commands (requires ENABLE_POWERSHELL=true)
• GET /system/info - System information and capabilities
• GET /system/processes - Browser process information
• GET /system/chrome/info - Chrome debugging information

⚠️ PowerShell/Command Execution Setup:

# Enable dangerous system commands (REQUIRED for /system/execute)
export ENABLE_POWERSHELL=true  # Linux/macOS
# OR
set ENABLE_POWERSHELL=true     # Windows CMD
# OR
$env:ENABLE_POWERSHELL="true"  # PowerShell

Advanced Debugging

• POST /debug/reproduce - Automated bug reproduction
• GET /debug/performance - Performance metrics
• GET /debug/memory - Memory usage analysis

Testing Philosophy

CDP Ninja is designed for security testing and fuzzing:

• No Input Validation: All endpoints accept ANY data to test application limits
• Intentional Code Injection: JavaScript string interpolation allows arbitrary code execution for testing
• Crash Reporting: When malformed data crashes Chrome, that's valuable debugging data
• Raw Pass-Through: Commands are sent exactly as provided to Chrome DevTools
• Edge Case Testing: Null bytes, huge values, malformed selectors are encouraged
• Security Research: XSS, injection attempts, protocol violations are allowed
• Browser Vulnerability Discovery: Test how browsers handle malformed CSS selectors and JavaScript

The "vulnerabilities" in CDP Ninja are features, not bugs.

If CDP Ninja can break your application with malformed data, your application has bugs.

This tool is intentionally permissive to help find vulnerabilities and edge cases through aggressive testing.

Project Structure

cdp-ninja/
├── core/
│   ├── __init__.py
│   ├── cdp_client.py        # WebSocket CDP client with auto-reconnect
│   └── cdp_pool.py          # Connection pooling for performance
├── api/
│   ├── __init__.py
│   ├── server.py            # Main Flask application
│   ├── config.py            # Configuration with PowerShell toggle
│   ├── routes/
│   │   ├── __init__.py
│   │   ├── browser.py       # RAW browser interaction (click, type, screenshot)
│   │   ├── debugging.py     # RAW JavaScript execution and console access
│   │   ├── navigation.py    # RAW navigation (any URL, any protocol)
│   │   ├── dom.py           # RAW DOM manipulation (no sanitization)
│   │   └── system.py        # RAW system commands (PowerShell/Bash)
│   └── utils/
│       └── error_reporter.py # Crash telemetry (not prevention)
├── setup/
│   ├── setup_windows.ps1   # Windows PowerShell installer
│   └── setup_unix.sh       # Linux/macOS bash installer
├── agent/
│   └── claude_agent.md     # Claude Code agent specification
├── examples/
│   ├── basic_usage.py      # Getting started examples
│   └── debug_nextjs.py     # Next.js debugging workflows
├── requirements.txt        # Python dependencies (16MB total)
├── README.md
├── LICENSE
└── setup.py

Comparison with Alternatives

Feature	CDP Ninja	Playwright	Puppeteer	Selenium
Browser Download	0 MB (uses your Chrome)	300MB	170MB	0 MB
Python Package	16MB	50MB	N/A	15MB
Memory Usage	~50MB	~500MB	~400MB	~200MB
Setup Time	<1 minute	5+ minutes	3+ minutes	2+ minutes
Direct CDP Access	✅	❌ (abstracted)	❌ (abstracted)	❌ (WebDriver)
Remote Debugging	✅ SSH tunnel	❌ Complex	❌ Complex	✅ Grid
Learning Curve	Low (REST API)	High	High	Medium

Common Issues & Solutions

Installation Issues

Problem: ModuleNotFoundError when running cdp-ninja

# Solution: Force reinstall with no cache
pip install --force-reinstall --no-cache-dir git+https://github.com/travofoz/cdp-ninja.git

Problem: ImportError: cannot import name 'config'

# Solution: You have an old version, update to latest
pip uninstall cdp-ninja -y
pip install git+https://github.com/travofoz/cdp-ninja.git

Connection Issues

Problem: Chrome DevTools connection failed (403 Forbidden)

# Solution: Chrome requires --remote-allow-origins flag
# Kill all Chrome processes first
Get-Process chrome | Stop-Process -Force  # Windows PowerShell
pkill chrome  # Linux/macOS

# Start Chrome with correct flags
chrome --remote-debugging-port=9222 --remote-allow-origins=*

# Windows PowerShell:
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --remote-allow-origins=* --user-data-dir="C:\temp\chrome-debug"

Problem: Connection timeout on Windows

# Chrome can be slow to respond on Windows
# This is fixed in v1.0.1+ (timeout increased to 30s)
pip install --upgrade git+https://github.com/travofoz/cdp-ninja.git

Problem: Bridge server won't start on port 8888

# Solution: Use a different port
cdp-ninja --bridge-port 9999

Windows-Specific Issues

Problem: PowerShell script execution disabled

# Solution: Enable script execution (run as Administrator)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Problem: Python not in PATH

# Solution: Use full path to Python
C:\Users\YourName\AppData\Local\Programs\Python\Python311\python.exe -m pip install git+https://github.com/travofoz/cdp-ninja.git

Verification Steps

# 1. Verify Chrome is accessible
curl http://localhost:9222/json
# Should return JSON with browser tabs

# 2. Verify CDP Ninja is running
curl http://localhost:8888/health
# Should return {"status": "ok"}

# 3. Test CDP connection
curl http://localhost:8888/cdp/status
# Should return connection details

Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

License

MIT License - see LICENSE file for details.

Credits

Built with ❤️ by developers who believe debugging should be simple, not bloated.

Special thanks to Claude (Anthropic) for architectural insights and implementation guidance.

Support

• 📚 API Documentation - Complete usage guide with examples
• 🐛 Issues
• 💬 Discussions