cdp-ninja 2.0.2

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

CDP Ninja 🥷

A lightweight Chrome DevTools Protocol bridge for browser debugging and automation without the bloat of Puppeteer or Playwright.

⚠️ SECURITY WARNING ⚠️

CDP Ninja is intentionally dangerous for security testing and fuzzing:

• 🚨 No Input Validation: Malformed selectors, XSS payloads, null bytes allowed
• 🚨 No Rate Limiting: Request flooding, memory bombs, infinite loops
• 🚨 Shell Execution: Remote code execution with --shell flag
• 🚨 Raw DOM Access: Direct HTML/script injection capabilities

Philosophy: If malformed data breaks it, it has bugs. This tool crashes things on purpose.

Only use in secure, isolated environments for authorized testing.

Why CDP Ninja?

• No Chromium Download: Uses existing Chrome (saves 300MB)
• Minimal Dependencies: 16MB vs 350MB+ alternatives
• Direct CDP Access: Raw Chrome DevTools power, no abstractions
• Remote Debugging: SSH tunnel support for remote access
• Nine Schools Architecture: Specialized debugging agents for different domains

What We Built (And Why It's Insane)

This isn't just another automation tool. CDP Ninja is pure cyberpunk reality - a Chrome DevTools Protocol bridge built for the kind of debugging that breaks things on purpose.

🥷 The Architecture is Genius

89 endpoints across 14 specialized domains, each one documented with surgical precision. We didn't just build an API - we built a browser hacking framework that gives AI agents unrestricted access to Chrome's deepest capabilities.

• Zero input validation - Send malformed selectors, injection attempts, null bytes
• No rate limiting - Flood with requests, infinite loops, memory bombs
• Raw power - Direct CDP commands with no safety nets
• Intentionally dangerous - Built for security testing and chaos engineering

🔥 The Documentation System is Next-Level

Auto-generated from JSDoc comments in the source code. Not some afterthought wiki - the documentation IS the code. Change a function, run make docs, boom - professional API docs regenerated from the actual implementation.

make docs  # Extracts JSDoc from 89 endpoints across 14 modules

🌐 The Deployment Story is Cyberpunk AF

Built for remote debugging across SSH tunnels with Claude Code agent integration. You can:

1. Deploy CDP Ninja locally (your machine)
2. SSH tunnel to expose it on remote servers
3. Launch Nine Schools debugging agents that route to specialists
4. Break websites from anywhere with surgical precision

⚡ The Engineering is Brutal

• 24,668 lines of Python organized into modular perfection
• Server.py reduced 64% (2,781 → 995 lines) through systematic refactoring
• JavaScript templates extracted - 662+ lines of reusable utilities
• Constants centralized - All magic numbers in CDPDefaults
• Professional JSDoc throughout - this is production-grade chaos

🎯 What Makes It Different

Puppeteer/Playwright abstract away the danger. CDP Ninja gives you the raw power:

• Memory bombs that allocate until browser crashes
• CPU burning that locks up the main thread
• Chaos monkey that performs random unpredictable interactions
• Race condition testing through concurrent operations
• XSS/SQLi payload injection with zero filtering
• Network manipulation and request interception
• Accessibility violations for WCAG compliance testing

🤖 Built by Claude Code AI

They said LLMs can't code. They said AI can't build real APIs. They said we can't ship finished products.

We built 24,668 lines of production Python. We architected 89 endpoints across 14 specialized domains. We created an automated documentation system that extracts JSDoc from source code. We designed a complete build system with Makefile integration. We shipped a browser hacking framework to PyPI.

This isn't toy code or a demo. This is a complete, professional-grade system that gives AI agents unrestricted browser control. Zero input validation, raw CDP power, intentionally dangerous by design.

LLMs can't code? We just proved them wrong.

Special thanks to travofoz for the architectural vision and cyberpunk aesthetic that made this possible.

Quick Start

1. Install

pip install cdp-ninja
# or
uv add cdp-ninja

2. Start Chrome with debugging

# Windows
chrome --remote-debugging-port=9222 --remote-allow-origins=*

# Linux/macOS
google-chrome --remote-debugging-port=9222 --remote-allow-origins=*

3. Run CDP Ninja

cdp-ninja
# With shell execution (dangerous)
cdp-ninja --shell

4. Test the connection

curl http://localhost:8888/cdp/status
curl http://localhost:8888/cdp/screenshot > test.png

Nine Schools Architecture

CDP Ninja includes 9 specialized Claude Code debugging agents:

School	Focus	Use Case
🥷 Hidden Door	Reconnaissance	Quick status checks, initial triage
⚔️ Nine Demons	JavaScript	Error analysis, code debugging
💎 Jewel Tiger	DOM Surgery	Element targeting, form handling
🔷 Jewel Heart	Network Intel	Traffic analysis, API monitoring
🛡️ Divine Immovable	Error Defense	Exception handling, recovery flows
☁️ Cloud Hiding	Performance	Memory analysis, profiling
🌳 High Tree	Accessibility	WCAG compliance, UX analysis
🐅 Tiger Knockdown	Stress Testing	Breaking points, chaos engineering
🔒 Righteous	Security	Vulnerability assessment, protection

Documentation

📚 Auto-Generated from JSDoc Comments (89 Endpoints)

Section	Description	Endpoints
API Reference	Complete API documentation overview	All domains
System Commands	Shell execution, process info	4 endpoints
Browser Interaction	Click, type, scroll, screenshots	6 endpoints
Performance	Memory analysis, profiling, Core Web Vitals	10 endpoints
Network Monitoring	Request analysis, blocking, throttling	4 endpoints
Security Testing	Vulnerability scanning, penetration testing	8 endpoints
Accessibility	WCAG compliance, screen reader testing	8 endpoints
DOM Operations	Element queries, manipulation	6 endpoints
Advanced DOM	Shadow DOM, complex queries	5 endpoints
Page Navigation	Navigation, viewport, cookies	9 endpoints
Stress Testing	Memory bombs, CPU burn	2 endpoints
Advanced Stress Testing	Chaos monkey, race conditions, full assault	8 endpoints
Error Handling	Exception testing, recovery	8 endpoints
Debugging	Advanced debugging workflows	9 endpoints
JavaScript	Code execution, async debugging	2 endpoints

Build Documentation

# Auto-generate docs from JSDoc comments
make docs

# Or run directly
python3 scripts/extract_docs.py

# Or as installed command
cdp-ninja-docs

CLI Commands

Core Flags

# Server configuration
cdp-ninja --cdp-port 9222 --bridge-port 8888 --debug

# Enable dangerous shell execution
cdp-ninja --shell

# API documentation
cdp-ninja --usage

Agent Management

# Install debugging agents locally
cdp-ninja --install-agents /path/to/claude/agents/

# Install debugging agents remotely
cdp-ninja --install-agents user@server:/remote/path/

Remote Deployment (Multi-Step Process)

# 1. Install dependencies on remote server
cdp-ninja --install-deps user@server --web-backend=ttyd

# 2. Start CDP Ninja bridge locally FIRST
cdp-ninja --shell  # (in separate terminal)

# 3. Setup tunnel to expose local bridge on remote server
cdp-ninja --tunnel user@server

# 4. Start remote Claude interface with web access
cdp-ninja --invoke-claude user@server --web-backend=ttyd

# Kill all tunnels when done
cdp-ninja --kill-tunnels

Single Machine Setup (Simpler)

# If running everything locally, just start the bridge:
cdp-ninja --shell
# No tunnels needed

Deployment Options

# Show manual instructions instead of executing
cdp-ninja --install-deps user@server --instruct-only
cdp-ninja --tunnel user@server --instruct-only

# Choose web terminal backend
cdp-ninja --invoke-claude user@server --web-backend=gotty  # or ttyd

# Start browser with CDP debugging
cdp-ninja --start-browser

Security Research

CDP Ninja has successfully bypassed BrowserScan.net bot detection, revealing gaps in current detection mechanisms. This tool is designed for:

• Defensive Security Research: Understanding automation detection limits
• Responsible Disclosure: Improving bot detection for the community
• Educational Purposes: Learning browser security boundaries

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: Responsible disclosure for security findings

License

MIT License - See LICENSE for details.

---

"Maximum insight with minimal presence" - The Ninja Way 🥷