Expand description
§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-oxideonly 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
interceptorfeature. - Make bounded, application-controlled decisions for retryable top-level navigations.
- Seed reproducible cookies, local storage, and IndexedDB state with the
optional
seedingfeature.
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 |
|---|---|
|
|
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:
| Area | Examples |
|---|---|
| Identity | User-Agent, navigator platform, languages, User-Agent Client Hints |
| Locale | Intl locale and language configuration |
| Timezone | IANA timezone |
| Screen | Dimensions, available area, scale factor, orientation |
| Media features | Color scheme, reduced motion, forced colors, gamut, monochrome |
| Touch | Touch 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:
Strictrejects known contradictions before applying patches.Warnapplies valid values and returns consistency issues in the report.Permissiveapplies 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_seedingRun the deterministic test suite with:
cargo test --all-targets --all-featuresBrowser 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::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§
- Apply
Report - Result of applying a stealth configuration.
- Patch
Plan - Deterministic patch order and validation result prepared without a browser.
- Stealth
Config - Fully configurable patch selection and override values.
- Validation
Errors - Collection of consistency issues rejected by strict validation.
Enums§
- Consistency
Policy - 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.
- Patch
Mode - Controls how one patch obtains its value.
- Patch
State - Non-generic state of a configured patch.
- Platform
Profile - Built-in desktop profile selection.
- Validation
Issue - 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.