Skip to main content

Crate stealth_oxide

Crate stealth_oxide 

Source
Expand description

stealth-oxide logo

§stealth-oxide

Typed Chromium profiles and Chrome DevTools Protocol configuration for Rust.

stealth-oxide gives applications explicit, configurable control over the browser-visible values that Chromium exposes to a page. It works with chromiumoxide and applies CDP configuration to an existing page before navigation.

Use it for authorized browser automation, compatibility testing, diagnostics, and reproducible QA environments.

Testing only: Use stealth-oxide only for authorized browser automation, research, and quality assurance. Do not use it to evade access controls or security systems, or against sites and systems without permission.

§What you can do

  • Start from coherent Linux, macOS, or Windows Chrome profiles.
  • Apply identity, locale, timezone, screen, media-feature, and touch settings.
  • Override only the surfaces your application needs while preserving native Chromium values everywhere else.
  • Build and validate custom browser profiles with typed values.
  • Detect contradictions before sending CDP commands.
  • Coordinate configuration across new pages, iframes, popups, and workers.
  • Observe and redact transmitted network identity without intercepting requests.
  • Validate User-Agent, language, and Client Hint consistency at the network boundary.
  • Add validated request headers with the optional interceptor feature.
  • Make bounded, application-controlled decisions for retryable top-level navigations.
  • Seed reproducible cookies, local storage, and IndexedDB state with the optional seeding feature.

The application remains in control of Chromium launch, browser lifetime, navigation, proxies, authentication, storage, and shutdown.

§Diagnostic snapshots

These representative browser diagnostics show the kind of environment output the package helps applications collect and compare:

CreepJS Sannysoft
CreepJS diagnostic snapshot Sannysoft diagnostic snapshot

These are environment snapshots for authorized testing, not classifications or guarantees about a third-party service.

§Installation

[dependencies]
chromiumoxide = "0.9.1"
stealth-oxide = "0.1.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

The crate currently models Chrome 151.0.7922.138 and requires Rust 1.86 or newer.

Optional capabilities are feature-gated:

[dependencies.stealth-oxide]
version = "0.1.1"
features = ["interceptor", "seeding"]

§Quick start

Create a page, apply a profile while it is still blank, and then navigate:

use anyhow::Result;
use chromiumoxide::{Browser, BrowserConfig};
use futures::StreamExt;
use stealth_oxide::{ChromeLanguageConfig, PlatformProfile, StealthConfig};

#[tokio::main]
async fn main() -> Result<()> {
    let profile = PlatformProfile::Linux.profile();
    let language = ChromeLanguageConfig::from_profile(&profile);
    let browser_config = BrowserConfig::builder()
        .hide()
        .arg(language.chrome_argument())
        .build()
        .map_err(anyhow::Error::msg)?;

    let (mut browser, mut handler) = Browser::launch(browser_config).await?;
    tokio::spawn(async move {
        while let Some(event) = handler.next().await {
            if let Err(error) = event {
                eprintln!("chromiumoxide handler error: {error:?}");
            }
        }
    });

    let page = browser.new_page("about:blank").await?;
    let report = StealthConfig::from_profile(profile).apply(&page).await?;
    page.goto("https://example.com").await?;

    println!("applied patches: {:?}", report.applied());
    browser.close().await?;
    Ok(())
}

Apply the configuration before navigation so the first page scripts observe the selected values.

§Profiles and patches

Built-in profiles are selected explicitly:

use stealth_oxide::{PlatformProfile, StealthConfig};

let linux = StealthConfig::for_platform(PlatformProfile::Linux);
let macos = StealthConfig::for_platform(PlatformProfile::MacOS);
let windows = StealthConfig::for_platform(PlatformProfile::Windows);

Each profile supplies typed values for:

AreaExamples
IdentityUser-Agent, navigator platform, languages, User-Agent Client Hints
LocaleIntl locale and language configuration
TimezoneIANA timezone
ScreenDimensions, available area, scale factor, orientation
Media featuresColor scheme, reduced motion, forced colors, gamut, monochrome
TouchTouch availability and maximum touch points

Patches can be enabled, disabled, or kept native independently:

use stealth_oxide::{Patch, PlatformProfile, StealthConfig};

let config = StealthConfig::for_platform(PlatformProfile::Windows)
    .disable(Patch::Screen)
    .use_native(Patch::Touch)
    .timezone("America/Toronto")
    .languages(["en-CA", "en"])
    .locale("en-CA");

For an explicit opt-in configuration, start with no patches:

use stealth_oxide::{Patch, StealthConfig};

let config = StealthConfig::none()
    .enable(Patch::Identity)
    .enable(Patch::Locale)
    .enable(Patch::Timezone);

§Custom profiles and validation

BrowserProfileBuilder lets applications create a reusable profile with the same typed fields as the built-in presets. StealthConfig validates known contradictions by default before issuing CDP commands.

use stealth_oxide::{ConsistencyPolicy, PlatformProfile, StealthConfig};

let config = StealthConfig::for_platform(PlatformProfile::Linux)
    .navigator_platform("Win32")
    .consistency_policy(ConsistencyPolicy::Warn);

let issues = config.validation_issues();
assert!(!issues.is_empty());

Choose the validation policy that matches the workflow:

  • Strict rejects known contradictions before applying patches.
  • Warn applies valid values and returns consistency issues in the report.
  • Permissive applies requested values subject to CDP and Chromium rules.

The returned ApplyReport records applied, native, skipped, and warning states, making configuration behavior observable to the caller.

§New-target coordination

Configuration is applied to a specific CDP target. Use TargetCoordinator when a page can create workers, popups, related pages, or other targets that need the same configuration:

use futures::StreamExt;
use stealth_oxide::{PlatformProfile, StealthConfig, TargetCoordinator};

let config = StealthConfig::for_platform(PlatformProfile::Linux);
config.apply(&page).await?;

let coordinator = TargetCoordinator::new(&config)?;
let mut events = coordinator.enable(&page).await?;
let target_page = page.clone();

tokio::spawn(async move {
    while let Some(event) = events.next().await {
        if let Err(error) = coordinator.apply(&target_page, &event).await {
            eprintln!("target configuration failed: {error}");
        }
    }
});

page.goto("https://example.com").await?;

The application must keep driving the event stream. This makes target coverage explicit instead of hiding a runtime task inside the library.

§Network observation

NetworkAudit is a passive, bounded observer for Chromium network events. It can summarize requests, redirects, failures, cache behavior, and transmitted identity without pausing or rewriting ordinary requests:

use chromiumoxide::Page;
use stealth_oxide::NetworkAuditHandle;

let audit = NetworkAuditHandle::attach(page).await?;
page.goto("https://example.com").await?;
let report = audit.stop().await;

println!("observed requests: {}", report.summary().requests);

Reports are redacted and bounded. They omit request bodies, credentials, cookies, remote addresses, URL query strings, and fragments. The audit can also validate transmitted User-Agent, language, and Client Hint values against the selected profile.

For applications that need explicit request-header additions, enable the optional interceptor feature and use its validated HeaderPolicy builder.

§Controlled navigation retries

NavigationRetryPolicy makes a decision for a completed top-level navigation; it does not perform the retry itself:

use std::time::{Duration, SystemTime};
use stealth_oxide::{NavigationMethod, NavigationRetryPolicy, RetryDecision};

let policy = NavigationRetryPolicy::new()
    .max_attempts(3)
    .max_elapsed(Duration::from_secs(120));

let decision = policy.decide(
    429,
    NavigationMethod::Get,
    Some("15"),
    1,
    Duration::from_secs(2),
    SystemTime::now(),
    0.5,
);

assert_eq!(decision, RetryDecision::RetryAfter(Duration::from_secs(15)));

Applications decide whether and how to act on RetryDecision, preserving ownership of browser state, cookies, proxies, and navigation lifecycle.

§Reproducible browser state

Enable the seeding feature to install test cookies, local storage, and IndexedDB records through typed seed definitions:

[dependencies]
stealth-oxide = { version = "0.1.1", features = ["seeding"] }

See examples/profile_seeding.rs for a complete example.

§Examples and tests

Runnable examples are included in the package:

cargo run --example example
cargo run --example custom_configuration
cargo run --example custom_profile
cargo run --features seeding --example profile_seeding

Run the deterministic test suite with:

cargo test --all-targets --all-features

Browser diagnostics are ignored by default because they require a local Chromium process. See tests/README.md for trigger commands.

§Scope

stealth-oxide configures Chromium through CDP; it does not replace Chromiumoxide or manage the browser lifecycle. The selected profile describes browser-visible values, while the host operating system still supplies native fonts, graphics, voices, and other platform resources.

Use the library only for systems and destinations you are authorized to test.

§License

MIT

Re-exports§

pub use compatibility::CompatibilityStatus;
pub use compatibility::compare_browser_versions;
pub use environment::Finding;
pub use environment::FindingSeverity;
pub use environment::Observation;
pub use environment::check_device_memory;
pub use environment::compare_page_worker;
pub use environment::compare_voice_language;
pub use environment::valid_device_memory_bucket;
pub use launch::ChromeLanguageConfig;
pub use network::FailureCategory;
pub use network::NetworkAudit;
pub use network::NetworkAuditHandle;
pub use network::NetworkAuditSummary;
pub use network::NetworkRequestAudit;
pub use network::RedirectHop;
pub use network::classify_failure;
pub use network::increment_failure_count;
pub use network::sanitize_error_name;
pub use network::validate_client_hint_negotiation;
pub use network::validate_request_identity;
pub use profiles::BUILT_IN_CHROME_MAJOR;
pub use profiles::BUILT_IN_CHROME_VERSION;
pub use profiles::BrowserProfile;
pub use profiles::BrowserProfileBuilder;
pub use profiles::ColorGamut;
pub use profiles::ColorScheme;
pub use profiles::ForcedColors;
pub use profiles::IdentityConfig;
pub use profiles::MediaFeaturesConfig;
pub use profiles::ProfileVersion;
pub use profiles::ReducedMotion;
pub use profiles::ScreenConfig;
pub use profiles::TouchConfig;
pub use retry::NavigationMethod;
pub use retry::NavigationRetryPolicy;
pub use retry::NoRetryReason;
pub use retry::ResponseDisposition;
pub use retry::RetryDecision;
pub use retry::classify_response;
pub use retry::parse_retry_after;
pub use targets::TargetApplyReport;
pub use targets::TargetCoordinator;
pub use topology::Coverage;
pub use topology::ResourceScope;
pub use topology::classify_resource;
pub use topology::sanitize_initiator_origin;

Modules§

compatibility
Browser runtime and profile-version compatibility inspection. Browser runtime and profile-version compatibility inspection.
environment
Read-only environment observations and consistency checks. Read-only host/browser environment observations and consistency checks.
launch
Browser-native startup configuration derived from a browser profile. Chrome startup values that must be configured before CDP is available.
network
Typed categories for observed Chromium network failures. Passive, redacted Chromium network diagnostics and failure classification.
profiles
Browser profile types, builders, and built-in platform presets.
redaction
Shared privacy and diagnostic redaction helpers. Shared privacy rules for diagnostic reports.
retry
Safe decisions for opt-in top-level navigation retries. Safe, opt-in decisions for retrying top-level browser navigations.
targets
Coordination for workers, popups, iframes, and other new CDP targets. Runtime-neutral coordination for CDP targets created after a page is configured.
topology
Read-only frame and target topology classification helpers. Read-only classification helpers for network/frame topology diagnostics.

Structs§

ApplyReport
Result of applying a stealth configuration.
PatchPlan
Deterministic patch order and validation result prepared without a browser.
StealthConfig
Fully configurable patch selection and override values.
ValidationErrors
Collection of consistency issues rejected by strict validation.

Enums§

ConsistencyPolicy
Controls how cross-surface contradictions are handled.
Error
Error returned while validating a profile or applying a CDP patch.
Patch
An independently selectable CDP patch.
PatchMode
Controls how one patch obtains its value.
PatchState
Non-generic state of a configured patch.
PlatformProfile
Built-in desktop profile selection.
ValidationIssue
A known consistency or configuration problem.

Functions§

validate_profile
Validates all relationships in an editable browser profile.

Type Aliases§

Result
Result type returned by stealth-oxide.