guise 0.1.2

Canonical browser fingerprint bundles, human-behavior timing, and TLS profile re-exports for the Santh fleet
Documentation

stealth

status: alpha

Canonical browser fingerprint bundles, human keystroke timing, and TLS profile re-exports for the Santh fleet.

What it does

stealth provides five orthogonal stealth primitives that work together:

  1. Fingerprint bundles (fingerprint feature, default) - Tier-A ProfileBundle values pair a StealthProfile (JS property overrides for navigator, WebGL, screen, etc.) with the matching TLS ImpersonateProfile. profile_js renders overrides into a CDP-injectable IIFE. validate_overrides / validate_browser_coherence detect UA/platform/brands mismatches before they reach a WAF.

  2. Human keystroke timing (human feature, default) - plan_keystrokes produces a Vec<Keystroke> (char, hold_ms, gap_ms_before, is_correction) drawn from per-bigram timing envelopes calibrated on real human typing data. Supports typo injection with backspace correction and random thinking pauses. All timing is deterministic given a seeded Rng.

  3. TLS profile re-exports (http feature, default) - thin re-exports of scanclient::tls_impersonate::{ImpersonateProfile, supported_profiles}. The heavier StealthClient (rquest + BoringSSL) is gated behind tls-impersonate.

  4. HTTP browser headers (http + fingerprint + rotation, default) - ordered User-Agent, Accept-*, Client Hint, and Sec-Fetch-* templates derived from the same StealthProfile that drives browser JS overrides.

  5. Pacing and rotation (pacing + rotation, default) - deterministic profile cycling, named profile resolution, exclusive-upper-bound jitter, and shared exponential backoff policy.

Optional extras: CDP injection (browser feature) via apply_stealth / apply_cdp_mask for a chromiumoxide::Page, Tier-B community TOML profiles (tier-b-toml), and a stealth-probe scoring engine (probe module, browser feature).

Quick start

Add to Cargo.toml:

stealth = { path = "libs/runtime/stealth" }

Generate a Chrome 131/Windows fingerprint + type "hello" with realistic timing:

use stealth::{ProfileBundle, plan_keystrokes, TypingPlan};
use rand::{rngs::StdRng, SeedableRng};

let bundle = ProfileBundle::chrome_131_windows();
bundle.validate_browser_coherence().unwrap();

let mut rng = StdRng::seed_from_u64(0);
let keys = plan_keystrokes("hello", TypingPlan::default(), &mut rng);
assert_eq!(keys.len(), 5);

Inject the bundle into a chromiumoxide page (requires the browser feature):

use stealth::cdp::apply_stealth;

apply_stealth(&page).await?;  // call once, before goto()

When to use / When not

Use when:

  • You need a coherent UA + platform + brands + TLS fingerprint tuple (not just a UA string).
  • You need human-realistic keystroke timing for CDP input dispatch.
  • You want type-safe profile selection with compile-time coherence checking.

Do not use when:

  • You need live browser fingerprint data (this crate ships static profiles; update them manually).
  • You need full TLS impersonation without enabling the tls-impersonate feature - that feature pulls BoringSSL via scanclient and lengthens compile time significantly.
  • You are working outside the Santh fleet and have no scanclient workspace dependency - the http feature will not resolve.

Compared to alternatives

Capability stealth playwright-stealth puppeteer-extra-stealth
Typed, validated profile bundles yes no no
TLS ClientHello matching yes (tls-impersonate) no no
Bigram keystroke timing yes no partial
Zero outbound network yes yes yes
Rust compile-time safety yes N/A (JS) N/A (JS)
Live profile update manual community community

Unlike JS stealth libraries, this crate exposes typed Rust structs so the compiler catches UA/platform mismatches before deployment.

How it fits in Santh

stealth is a runtime substrate consumed by the scanner and behavior layers:

libs/runtime/stealth      ← this crate (fingerprint + timing data)
      ↑
libs/scanner/scanclient   ← HTTP client (uses ImpersonateProfile + StealthClient)
      ↑
libs/runtime/behavior/*   ← orchestration (uses ProfileBundle + plan_keystrokes)
      ↑
bin/santh                 ← operator entry point

Profile bundles flow outward via scanclient for TLS impersonation. Keystroke timing is consumed directly by behavior orchestration that drives CDP input events. The probe module (browser feature) runs in-page JS to score how detectable the active session is.

Contributing

  1. Pure profile data lives in ../stealth-profiles/src/lib.rs. Add a new StealthProfile variant, fill the profile facts, hardware tuple, navigator vendor, and Client Hint brand catalog entries there, then add a ProfileBundle constructor and extend validate_tls_family if the new browser family needs cross-checking.
  2. Timing data lives in src/human/keystroke.rs in the HOT_BIGRAMS table and the hold_envelope match arms. Constants are named and documented; do not hardcode new values without a citation.
  3. All new public items require a doc comment and at least one test in the appropriate tests/ file (unit/ for happy path, adversarial.rs for hostile input, gap.rs for pinned limitations, property.rs for proptest invariants, integration.rs for pipelines).
  4. cargo +nightly test -p stealth must pass before merging. Run santh-conform check libs/runtime/stealth and resolve any fail-level findings.

License

Licensed under either of Apache-2.0 or MIT at your option.