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

Anti-Detection & Stealth Capabilities

• 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

Technical Features

• 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:

# npm
npm install ghost-puppet

# bun
bun add ghost-puppet

# yarn
yarn add ghost-puppet

# pnpm
pnpm add ghost-puppet

Quick Start

Basic Undetected Automation

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();

Cloudflare Bypass Example

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

Stealth Mode & Anti-Detection

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

Launch Options

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)
});

Page Navigation

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();

Element Interaction

// 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');

JavaScript Evaluation

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

Advanced Features

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

launch(options?: LaunchOptions): Promise<Browser>

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)

connect(options: { host: string; port: number }): Promise<Browser>

Connects to an existing Chrome instance.

Browser

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

Page

• goto(url: string): Promise<void> - Navigate to URL
• locator(selector: string): Locator - Create element locator
• evaluate(fn: Function, ...args: any[]): Promise<any> - Evaluate JavaScript
• screenshot(options?: ScreenshotOptions): Promise<Buffer> - Take screenshot
• waitForLoadState(state: 'load' | 'domcontentloaded' | 'networkidle'): Promise<void> - 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.