Soenneker.Playwrights.Extensions.Stealth 4.0.106

Soenneker.Playwrights.Extensions.Stealth

A .NET extension library for Microsoft Playwright that makes browser automation harder to detect. It applies launch-argument hardening, context shaping, and init-script evasions so Chromium sessions look more like normal user sessions.

Related Repos

You might also be interested in:

• soenneker.playwrights.crawler for crawling and mirroring sites to disk with Playwright.
• soenneker.playwrights.installation for ensuring Playwright browsers are installed before first use.

Installation

dotnet add package Soenneker.Playwrights.Extensions.Stealth

Quick start

1. Launch Chromium with stealth defaults: Playwright.LaunchStealthChromium().
2. Create a stealth browser context: browser.CreateStealthContext().
3. Use the context as usual to create pages and run automation.

using Microsoft.Playwright;
using Soenneker.Playwrights.Extensions.Stealth;

using var playwright = await Playwright.CreateAsync();
await using var browser = await playwright.LaunchStealthChromium(new BrowserTypeLaunchOptions
{
    Headless = true,
    Channel = "chromium"
});

var browserContext = await browser.CreateStealthContext();
var page = await browserContext.NewPageAsync();

Connecting to a remote Playwright sidecar

If Chromium is already running remotely, for example in a Docker sidecar, connect with the endpoint overload:

using Microsoft.Playwright;
using Soenneker.Playwrights.Extensions.Stealth;

using var playwright = await Playwright.CreateAsync();
await using var browser = await playwright.LaunchStealthChromium(
    "ws://playwright:3000/",
    new BrowserTypeConnectOptions());

var context = await browser.CreateStealthContext();
var page = await context.NewPageAsync();

In endpoint mode, stealth launch arguments are not applied because the remote browser is already running. Stealth still applies at the browser-context level via CreateStealthContext().

With proxy

Pass an optional proxy into CreateStealthContext:

var context = await browser.CreateStealthContext(new Proxy
{
    Server = "http://proxy.example.com:8080",
    Username = "user",
    Password = "secret"
});

Customizing launch and context

The defaults are recommended, but if you want to tune options further:

using Microsoft.Playwright;
using Soenneker.Playwrights.Extensions.Stealth;
using Soenneker.Playwrights.Extensions.Stealth.Options;

using var playwright = await Playwright.CreateAsync();
await using var browser = await playwright.LaunchStealthChromium(
    new BrowserTypeLaunchOptions { Headless = true },
    new StealthLaunchOptions
    {
        Channel = "chrome",
        IncludeNoSandboxArgument = false,
        IgnoreDetectableDefaultArguments = true,
        AdditionalIgnoredDefaultArguments = ["--disable-features=DialMediaRouteProvider"],
        AdditionalArguments = ["--disable-features=Translate"]
    });

var context = await browser.CreateStealthContext(
    new BrowserNewContextOptions
    {
        // Optionally specify a UserAgent
        UserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36"
    },
    new StealthContextOptions
    {
        NormalizeDocumentHeaders = true,
        InjectClientHintHeaders = true,
        WarmupSpeechVoices = true,
        PatchFunctionToString = false,
        EnableCdpDomainHardening = true,
        DisableConsoleDomain = true,
        DisableRuntimeDomain = false,
        Surfaces = new StealthSurfaceOptions
        {
            NavigatorProfile = StealthSurfaceMode.Native,
            NavigatorPlugins = StealthSurfaceMode.Native,
            Screen = StealthSurfaceMode.Native,
            Battery = StealthSurfaceMode.Native,
            UserAgentData = StealthSurfaceMode.Native,
            PermissionsQuery = StealthSurfaceMode.Native,
            DocumentFonts = StealthSurfaceMode.Native,
            Canvas = StealthSurfaceMode.Native,
            MediaDevices = StealthSurfaceMode.Native
        },
        AdditionalHttpHeaders = new Dictionary<string, string>
        {
            ["DNT"] = "1"
        }
    });

Applying stealth to an existing context

You can apply the same stealth behavior to a context you already created:

var context = await browser.NewContextAsync();
await context.ApplyStealthAsync();

Features

Options reference

• StealthLaunchOptions — Controls how launch arguments are normalized (Channel, RemoveDetectableArguments, IncludeNoSandboxArgument, IgnoreDetectableDefaultArguments, AdditionalArguments, AdditionalIgnoredDefaultArguments).
• StealthContextOptions — Controls context and request behavior (Proxy, AdditionalHttpHeaders, InjectClientHintHeaders, NormalizeDocumentHeaders, AlignColorScheme, RandomizeGeolocation, WarmupSpeechVoices, PatchFunctionToString, Surfaces, EnableCdpDomainHardening, DisableConsoleDomain, DisableRuntimeDomain).
• StealthSurfaceOptions — Controls per-surface behavior with StealthSurfaceMode (Native, Spoofed, Disabled) for NavigatorProfile, NavigatorPlugins, Screen, Battery, UserAgentData, PermissionsQuery, DocumentFonts, Canvas, MediaDevices, and WebGl.