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:
These are environment snapshots for authorized testing, not classifications or guarantees about a third-party service.
Installation
[]
= "0.9.1"
= "0.1.1"
= { = "1", = ["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:
[]
= "0.1.1"
= ["interceptor", "seeding"]
Quick start
Create a page, apply a profile while it is still blank, and then navigate:
use Result;
use ;
use StreamExt;
use ;
async
Apply the configuration before navigation so the first page scripts observe the selected values.
Profiles and patches
Built-in profiles are selected explicitly:
use ;
let linux = for_platform;
let macos = for_platform;
let windows = for_platform;
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 ;
let config = for_platform
.disable
.use_native
.timezone
.languages
.locale;
For an explicit opt-in configuration, start with no patches:
use ;
let config = none
.enable
.enable
.enable;
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 ;
let config = for_platform
.navigator_platform
.consistency_policy;
let issues = config.validation_issues;
assert!;
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 StreamExt;
use ;
# async
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 Page;
use NetworkAuditHandle;
# async
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 ;
use ;
let policy = new
.max_attempts
.max_elapsed;
let decision = policy.decide;
assert_eq!;
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:
[]
= { = "0.1.1", = ["seeding"] }
See examples/profile_seeding.rs for a complete
example.
Examples and tests
Runnable examples are included in the package:
Run the deterministic test suite with:
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