Ghost Puppet

> Undetectable browser automation library for Node.js with advanced Cloudflare bypass and bot detection evasion. Built on Chrome DevTools Protocol (CDP) for stealth automation that bypasses anti-bot systems, fingerprinting detection, and automated browser detection.

Perfect for: Web scraping, automated testing, Cloudflare bypass, undetected automation, bot detection evasion, and stealth browser automation.


Features

$3

- Cloudflare Bypass - Advanced techniques to bypass Cloudflare protection and bot detection
- Undetectable Automation - Evades browser fingerprinting, automation detection, and anti-bot systems
- Bot Detection Evasion - Built-in stealth features to avoid detection by automated browser detection systems
- Fingerprinting Protection - Masks automation signals and browser automation indicators
- Undetected Browser Automation - Operates like a real user, bypassing common detection methods

$3

- Zero Dependencies - No runtime dependencies (only ws for WebSocket communication)
- TypeScript First - Full type definitions and excellent IDE support
- Chrome CDP Native - Direct Chrome DevTools Protocol integration for maximum performance. Compatible with any Chromium-based browser (Chrome, Brave, Edge, Opera, etc.)
- Firefox Support (Beta) - Firefox/Marionette support is available in beta. Some features may be limited compared to Chrome.
- Lightweight & Fast - Minimal footprint with optimized performance
- Modern API - Promise-based, async/await ready with intuitive API design

Installation

Ghost Puppet is available on npm and can be installed using any Node.js package manager:

``bash


npm

npm install ghost-puppet

bun

bun add ghost-puppet

yarn

yarn add ghost-puppet

pnpm

pnpm add ghost-puppet
`

Quick Start

$3

`typescript
import { launch } from 'ghost-puppet';

// Launch Chrome with stealth mode enabled (default)
const browser = await launch({ headless: false });
const page = await browser.newPage('https://example.com');
await page.waitForLoadState('load');

console.log(await page.title);
await browser.close();

// Launch Firefox (beta)
const firefoxBrowser = await launch({ browser: 'firefox', headless: false });
const firefoxPage = await firefoxBrowser.newPage('https://example.com');
await firefoxPage.waitForLoadState('load');
await firefoxBrowser.close();
`

$3

`typescript
import { launch } from 'ghost-puppet';

// Configure for maximum stealth and Cloudflare bypass
const browser = await launch({
headless: false,
args: [
'--disable-blink-features=AutomationControlled',
'--disable-dev-shm-usage',
'--no-sandbox',
'--disable-setuid-sandbox'
]
});

const page = await browser.newPage();
await page.goto('https://protected-site.com'); // Bypasses Cloudflare protection
await page.waitForLoadState('networkidle');

// Your automation code here
await browser.close();
`

Usage

$3

Ghost Puppet is designed for undetected browser automation and Cloudflare bypass. The library automatically configures Chrome with stealth settings to evade:

- Browser Automation Detection - Removes automation indicators
- Cloudflare Protection - Bypasses Cloudflare bot detection
- Fingerprinting - Masks browser fingerprinting attempts
- Bot Detection Systems - Evades common anti-bot measures
- Automated Browser Detection - Appears as a real user browser

$3

`typescript
const browser = await launch({
headless: true, // Run in headless mode (less detectable)
browser: 'chrome', // Browser type: 'chrome' (default) or 'firefox' (beta)
executablePath: '/path/to/chrome', // Custom browser path (Chrome, Brave, Edge, etc.)
args: [
'--disable-blink-features=AutomationControlled', // Essential for stealth
'--disable-dev-shm-usage',
'--no-sandbox',
'--disable-setuid-sandbox',
'--disable-web-security' // Additional stealth options
],
port: 9222, // Custom debugging port
sandbox: true // Enable sandbox (default: true)
});
`

$3

`typescript
const page = await browser.newPage();
await page.goto('https://example.com');
await page.waitForLoadState('load');

// Navigation history
await page.goBack();
await page.goForward();
await page.reload();
`

$3

`typescript
// Locate elements
const input = page.locator('input[name="search"]');
const button = page.locator('button[type="submit"]');

// Interact with elements
await input.fill('search query');
await button.click();
await button.press('Enter');
`

$3

`typescript
// Evaluate JavaScript in page context
const title = await page.evaluate(() => document.title);
const data = await page.evaluate((a, b) => a + b, 5, 10);

// Wait for conditions (function or string)
await page.waitForFunction(() => window.myAppReady === true);
`

$3

`typescript
// Network interception
page.onRequest((request) => {
if (request.url.includes('ads')) {
request.abort();
} else {
request.continue();
}
});

// Screenshots
await page.screenshot({ path: 'screenshot.png' });

// PDF generation
await page.pdf({ path: 'document.pdf' });
`

API Reference

$3

Launches a new browser instance.

Options:
- headless?: boolean - Run in headless mode (default: false)
- browser?: 'chrome' | 'firefox' - Browser type: 'chrome' (default) or 'firefox' (beta)
- executablePath?: string - Path to Chrome/Chromium/Firefox executable (auto-detected if not provided). Supports any Chromium-based browser (Brave, Edge, Opera, etc.) or Firefox
- args?: string[] - Additional browser arguments
- port?: number - Custom debugging port
- sandbox?: boolean - Enable sandbox mode (default: true, Chrome only)

$3

Connects to an existing Chrome instance.

$3

- newPage(url?: string): Promise - Create a new page
- pages(): Page[] - Get all open pages
- close(): Promise - Close the browser

$3

- goto(url: string): Promise - Navigate to URL
- locator(selector: string): Locator - Create element locator
- evaluate(fn: Function, ...args: any[]): Promise - Evaluate JavaScript
- screenshot(options?: ScreenshotOptions): Promise - Take screenshot
- waitForLoadState(state: 'load' | 'domcontentloaded' | 'networkidle'): Promise - Wait for page state

Use Cases

- Web Scraping - Undetected data extraction from protected websites
- Cloudflare Bypass - Access Cloudflare-protected sites without detection
- Automated Testing - Browser automation for testing web applications
- Bot Detection Evasion - Bypass anti-bot systems and CAPTCHA challenges
- Stealth Automation - Automated tasks that require appearing as a real user
- Browser Fingerprinting Evasion - Avoid detection through browser fingerprinting
- Undetected Automation - Perform automated actions without triggering security measures

Requirements

- Node.js >= 18.0.0
- Chrome/Chromium or any Chromium-based browser (Brave, Edge, Opera, etc.) installed on your system (recommended for production)
- Firefox (optional, beta support) - Firefox support is available in beta. Some features may be limited.

The library automatically detects Chrome/Chromium installation. For custom browser paths (including Brave, Edge, or other Chromium-based browsers), use the executablePath option. For Firefox, set browser: 'firefox' in launch options.

Note: Firefox support via Marionette protocol is available in beta. Some features may be limited compared to Chrome. For production use, Chrome/Chromium is recommended.

Why Ghost Puppet?

Ghost Puppet is specifically designed for undetected browser automation and Cloudflare bypass. Unlike other automation libraries, Ghost Puppet focuses on:

- Stealth First - Built-in anti-detection features from the ground up
- Cloudflare Bypass - Advanced techniques to bypass Cloudflare protection
- Bot Detection Evasion - Evades common automated browser detection systems
- Lightweight - Minimal dependencies, maximum performance
- TypeScript Native - Full type safety and excellent developer experience
- CDP Native - Direct Chrome DevTools Protocol for better control and stealth

Keywords & Search Terms

This library is optimized for searches related to:
- Cloudflare bypass - Bypass Cloudflare protection and bot detection
- Undetectable automation - Browser automation that evades detection
- Undetected browser automation - Automated browsing without triggering security
- Bot detection bypass - Evade anti-bot systems and detection
- Stealth automation - Stealthy browser automation for web scraping
- Browser fingerprinting evasion - Avoid detection through fingerprinting
- Anti-bot bypass - Bypass anti-bot measures and CAPTCHA
- Automated browser detection bypass - Evade automated browser detection
- Puppeteer alternative - Lightweight alternative to Puppeteer with stealth features
- Undetected web scraping - Web scraping without detection

License

Non-Commercial Attribution License - See LICENSE for details.

This software is provided for non-commercial use only. Commercial licensing inquiries should be directed to the author.

Author

KLXYinc

---

Note: This package requires Chrome, Chromium, or any Chromium-based browser (Brave, Edge, Opera, etc.) to be installed on your system for production use. Firefox support is available in beta - set browser: 'firefox' in launch options. The library will automatically detect the installation path on macOS, Windows, and Linux. For custom browser paths, specify the executablePath` option when launching.

Disclaimer: This library is designed for legitimate automation and testing purposes. Users are responsible for complying with website terms of service and applicable laws when using this software.