Anti-detection evasions, fingerprint randomization, and human-like behavior for browser automation.

Overview

Many websites detect and block automated browsers. The stealth system counters this with browser fingerprint evasions, user agent rotation, and human-like input simulation.

Enable stealth with stealth: true for defaults, or pass a StealthConfig for fine-grained control.

import { BrowserSession, browserTools } from '@cogitator-ai/browser';

const session = new BrowserSession({
  headless: true,
  stealth: true,
});

await session.start();

StealthConfig

interface StealthConfig {
  humanLikeTyping?: boolean;         // default: true
  humanLikeMouse?: boolean;          // default: true
  fingerprintRandomization?: boolean; // default: true
  blockWebDriver?: boolean;          // default: true
  evasionScripts?: string[];         // custom init scripts
}

When stealth: true is passed, all boolean options default to true. You can disable specific features:

const session = new BrowserSession({
  stealth: {
    humanLikeTyping: true,
    humanLikeMouse: false,
    fingerprintRandomization: true,
    blockWebDriver: true,
  },
});

Evasion Scripts

When stealth is enabled, the following evasion scripts run automatically on every new page via context.addInitScript:

Evasion	What it does
WebDriver	Sets `navigator.webdriver` to `false`
Plugins	Fakes `navigator.plugins` with Chrome PDF Plugin, PDF Viewer, Native Client
Languages	Sets `navigator.languages` to `['en-US', 'en']`
Canvas	Adds subtle noise to canvas fingerprinting by XOR-ing pixel data
WebGL	Overrides WebGL vendor/renderer to report Intel Iris OpenGL Engine
Chrome	Adds `window.chrome` object with `runtime`, `loadTimes`, `csi` stubs
Permissions	Overrides `Permissions.query` to return `denied` for notifications

Custom Evasion Scripts

Add your own init scripts that run before any page content:

const session = new BrowserSession({
  stealth: {
    evasionScripts: [
      `Object.defineProperty(navigator, 'hardwareConcurrency', { get: () => 8 });`,
      `Object.defineProperty(navigator, 'deviceMemory', { get: () => 8 });`,
    ],
  },
});

Human-Like Behavior

When stealth is enabled, the browser_type and browser_fill_form tools automatically add random delays between keystrokes (50-150ms) to simulate human typing.

For direct use without tools, the package exports three human-like action helpers:

`humanLikeType(page, selector, text)`

Clicks the element, then types each character with a random delay between 50-150ms.

import { humanLikeType } from '@cogitator-ai/browser';

await humanLikeType(page, '#search', 'cogitator ai');

`humanLikeClick(page, selector)`

Moves the mouse to the element along a Bezier curve with random control points, then clicks at the element center with slight random offset.

import { humanLikeClick } from '@cogitator-ai/browser';

await humanLikeClick(page, '#submit-button');

`humanLikeScroll(page, direction, amount)`

Scrolls in multiple small increments with random pauses and slight variation in scroll distance per step.

import { humanLikeScroll } from '@cogitator-ai/browser';

await humanLikeScroll(page, 'down', 500);

When stealth is enabled and no custom userAgent is set, a random user agent is selected from a curated pool that matches the browser type. The pool includes recent Chrome, Edge, Firefox, and Safari user agents across Windows, macOS, Linux, iOS, and iPad.

import { getRandomUserAgent, getAllUserAgents } from '@cogitator-ai/browser';

const ua = getRandomUserAgent('chromium');
const all = getAllUserAgents(); // { chromium: [...], firefox: [...], webkit: [...] }

Full Stealth Example

import { Cogitator, Agent } from '@cogitator-ai/core';
import { BrowserSession, browserTools } from '@cogitator-ai/browser';

const session = new BrowserSession({
  headless: true,
  browser: 'chromium',
  stealth: {
    humanLikeTyping: true,
    humanLikeMouse: true,
    fingerprintRandomization: true,
    blockWebDriver: true,
  },
  viewport: { width: 1920, height: 1080 },
  locale: 'en-US',
  timezone: 'America/New_York',
});

await session.start();

const agent = new Agent({
  name: 'stealth-scraper',
  model: 'openai/gpt-4o',
  tools: browserTools(session),
  instructions: 'Browse websites naturally. Extract the requested data.',
});

const cogitator = new Cogitator({
  llm: {
    defaultModel: 'openai/gpt-4o',
    providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } },
  },
});

const result = await cogitator.run(agent, {
  input: 'Search for "AI agent frameworks" and summarize the top results',
});

console.log(result.output);
await session.close();

Next Steps

BrowserSession — session configuration reference
Vision — screenshot and accessibility-based tools

Stealth