StealthSession

mimic::stealth_session::StealthSession joins the pieces. It presents one StealthIdentity (the fingerprint, the measured browser it belongs to, the cookies it earned and the egress they were earned through) in one of two modes and moves between them by the policies:

• Mode::Http: an HttpSession sends the requests. It is fast and cheap, with the measured handshake and headers.
• Mode::Browser: a real Chrome sends them, behind a MitmProxy that replays each request with the same measured handshake. A clearance earned here is valid in the other mode.

use seleniumbase_rs_mimic::StealthSession;use seleniumbase_rs_scrape::CountryCode;# async fn demo() -> Result<(), Box<dyn std::error::Error>> {let mut session = StealthSession::builder()    .with_geo_proxies([("http://user:pass@de.proxy.example:8080", CountryCode::new("DE")?)])?    .build()    .await?;let page = session.fetch("https://example.com/").await?;println!("{} bytes, {:?} mode", page.body.len(), page.mode);session.close().await?;# Ok(())# }

The loop#

A session starts in the mode its SessionPolicy prefers (HTTP by default). fetch(url) asks the policies three questions:

Every change of mode emits ScraperEvent::ModeChanged with its reason. The browser is closed when the session goes back to HTTP and started again, with the same identity and egress, when it is needed. The MITM proxy is started the first time a browser is needed (at build() when the policy prefers the browser) and lives until close(), so its port and its certificate stay the same across browsers.

A site in cooldown is not requested at all. The state of the site (successes, challenges, cooldown) is read before the first load and saved after the last, whether the fetch worked or not. The attempts per fetch default to 4 (DEFAULT_ATTEMPTS, one more than a browser-only scraper): one load meets the challenge over HTTP, one in the browser solves it, and one over HTTP uses the clearance.

fetch returns a StealthFetch: url after redirects, status, headers, the body (the response body over HTTP, the rendered page in the browser), the detection, the mode it was got in, how many loads it took (attempts), the challenge solved on the way, and the egress. A page that took a challenge to reach is usually an HTTP page: the browser earned the clearance and the session went back to HTTP to use it. A body that is not UTF-8 is read lossily.

In short, the two modes and what moves a session between them:

The two modes, and what moves a session between them

What adapts, and what it presents#

Nothing in a session guesses. It adapts because each decision reads state that the earlier fetches wrote:

• Per site: the ledger counts successes and challenges for each site. A site whose history says plain requests fail is fetched in the browser first (EscalateReason::SiteNeedsBrowser), and a blocked or rate-limited site gets a cooldown, so it is not asked again until the cooldown ends.
• Per identity: the identity holds the clearances it earned. A clearance that ends within clearance_margin (120 seconds by default) sends the next fetch back to the browser to renew it (EscalateReason::ClearanceExpiring); a valid one keeps the session on plain HTTP.
• Per answer: the mitigation policy reads each response. A challenge met over HTTP escalates; a challenge solved in the browser demotes once the identity holds the clearance (demote_after_solve, on by default); repeated blocks rotate the egress and then the profile.

SessionPolicy holds four switches:

The fingerprint a session presents is drawn once from its seed: Fingerprint::randomized_with_major(os, seed, major) gives a coherent persona for this machine’s operating system that claims the measured Chrome major, and it is then moved to the language and time zone of the egress country. Like every randomized identity it carries StealthPolicy::balanced(): the WebRTC leak policy DisableNonProxiedUdp, seeded canvas and audio noise, the window.chrome stubs and the headless fixes (see the fingerprint tutorial). The fingerprint only changes when you rotate the profile or the egress, or pass your own with fingerprint(..), which must claim the measured Chrome.

Building one#

StealthSession::builder() has a default for everything: Chrome with the platform’s launch options, no proxy, state in memory, events written to tracing, HTTP preferred, and a profile drawn from a random seed.

build() fails with StealthError::Impersonate when this machine’s system has no measured Chrome or the profile claims another version, StealthError::Scrape for an egress whose country has no locale, an identity that belongs to another egress or no browser to start, StealthError::Http and StealthError::Mitm for the legs.

Moving by hand#

On an error from a rotation, an import or a change of mode the session is as it was.

When to move by hand#

The policies move a session when a site answers with a challenge. Move it yourself when you know more than the answers show:

• escalate() before a step that needs a real page: a login form, a page that renders its content with JavaScript, a button that must be clicked. The cookies HTTP collected go with it.
• demote() after that step, once the browser holds what you came for (the login cookie, a clearance): the following fetches are plain HTTP again, much faster, and carry the browser’s cookies.
• Leave both alone for ordinary fetching; fetch escalates and demotes on its own.

use seleniumbase_rs_mimic::StealthSession;# async fn login_then_scrape(password: &str) -> Result<(), Box<dyn std::error::Error>> {let mut session = StealthSession::builder().build().await?;// Log in where a real browser is needed.session.escalate().await?;let page = session.page().expect("a session in browser mode has a page");page.goto("https://shop.example/login").await?;page.locator("#user").type_text("me@example.com").await?;page.locator("#password").type_text(password).await?;page.locator("button[type=submit]").click().await?;// Back to plain HTTP: the browser's cookies, the login among them, move into the// identity and the browser closes.session.demote().await?;for n in 1..=20 {    let orders = session.fetch(&format!("https://shop.example/orders?page={n}")).await?;    println!("page {n}: {} bytes over {:?}", orders.body.len(), orders.mode);}session.close().await?;# Ok(())# }

Errors#

StealthError has one variant per layer: Scrape (the browser leg, the site state, an identity or the mitigation policy; Unsolved, GaveUp and CoolingDown come as this variant), Http, Mitm and Impersonate. Each already keeps URLs redacted and credentials out of its text. At the crate boundary it maps to SeleniumBaseError.

What to know#

What was run#