ming-iv8-rs 0.8.12

High-fidelity browser runtime for Python, powered by V8 (import as iv8_rs)

iv8-rs

High-fidelity browser-like JS runtime for Python (V8 + Rust + PyO3).
Built for Web JS reverse engineering, controlled re-execution, anti-bot / fingerprint host simulation, and ChaosVM-class instrumentation / analysis.

Current: milestone continuum through v0.8.102 · package 0.8.12 (D-151 dual-track) — CHANGELOG
PyPI: ming_iv8_rs · import: import iv8_rs · package track: 0.8.12 (D-151; not the same number as continuum tags v0.8.10x)
中文版：README.zh-CN.md · API contracts：docs/api/ · Coverage audit：docs/api/COVERAGE.md

Origin: why iv8-rs exists

We first met iv8 (the PyPI iv8 0.1.x line): V8 inside Python, environment-driven browser surface — a shape that fits Web reverse work. We wanted the same product category, dug one layer deeper:

• Sturdier host surface — not only “can eval”, but brand checks, getters, Workers, Intl, DOM collections under high-signal probes;
• Reproducible runs — offline ResourceBundle, deterministic seeds, logical clocks for CI and dual-engine compare;
• Execution + observation together — run the script in a host while instrument_source / CDP / unified traces open ChaosVM / TDC-style paths. A bit “left foot on right foot”, but the intent is real: runtime host + analysis plane on one stack.

Product intuition borrows from iv8 (Python-friendly, injectable environment, offline-first). The kernel choice is Rust + PyO3 + large codegen/native browser surface for performance, type boundaries, and long-term maintenance.
No need to dunk on peers. This repo and PyPI iv8 0.1.x are related lineage / dual-engine oracle. The product name here is iv8-rs — not “replace X”, but “same spark, deeper dig”.

Design philosophy: two branches, one loop

iv8-rs is not “only a browser stub” and not “only a decompiler”. The core bet is a dual-branch product:

Branch	Name	Question it answers
A	Runtime host	Can this script run under a controlled, browser-like host?
B	Runtime analysis	Can we observe, structure, and reason about what that run did?

They are meant to feed each other: a better host produces cleaner traces and fewer Illegal-invocation lies; better analysis points back at missing host surface, wrong brands, or incomplete network. Informally: left foot on right foot — host fidelity and analysis depth climb together, not as two disconnected tools.

What ships today is a strong Branch A plus a usable Branch B spine (instrumentation, unified trace, entry plane, diagnostics). Deeper IR / SSA / full decompile pipelines are an explicit desired state on Branch B — not vaporware branding, not “everything unfinished,” but a north-star map of where analysis is going while Branch A remains the production weight.

Branch A — runtime environment (host)

The script must believe it lives in something like a page: same-thread V8 isolate, large browser surface, offline-first I/O, deterministic knobs for CI.

Layer	Includes (illustrative, not exhaustive)
Kernel	V8 isolate, stack/thread affinity, ICU/Intl + timezone redetect, logical vs system time, seeds
Browser surface	Window / Navigator / Screen / Location / DOM parse & query, events, collections, Workers
Media & crypto	Canvas, WebGL params, Audio paths, SubtleCrypto
Network	ResourceBundle → optional Python handler → error (no silent open crawl)
Identity	Profiles, flat environment overrides, storage, cookies/headers helpers
Anti-detect building blocks	wrap/hook natives, chrome object, toString / brand hygiene (fidelity, not “pass all detectors”)
Product honesty	Explicit non-goals: not full Chromium, not layout luxury, not one-click bypass

Branch A is what makes controlled re-execution possible: same inputs, same seeds, offline chunks, dual-engine compare.

Branch B — runtime analysis (observe & structure)

Once the host can run the payload, Branch B turns the run into evidence: traces, diffs, entry plans, diagnostic reports — and, as the desired state deepens, richer intermediate forms.

Layer	Today (shipping spine)	Desired state (north star, not a claim of full completion)
Instrumentation	instrument_source / ChaosVM path A, global instrument_chaosvm, env Proxies	Broader VM families, lower false Illegal-invocation, optional expose_handlers policies
Trace plane	Unified D/R/C/W lines, VM trace, trace_diff, recording / profiler / coverage	Stable schemas, streaming, multi-run corpora as first-class
Debugger / CDP	DevTools attach, breakpoints, step, Debugger helpers	Deeper scope/object UX, CI-friendly programmatic sessions
Entry / bundlers	prepare_entry / run_with_entry / multi-entry plans; caller-owned chunks	Richer bundler graphs without silent network fetch
Structure & reasoning	CFG / taint / pattern / crypto detectors, report models, environment plane (diagnostic)	IR / SSA-style views, opcode/handler IR, string-array & deobf reports as a coherent pipeline, cross-version VM diff as default workflow
Formats & adapters	Schema-versioned reports, corpus manifests	More intermediate formats, dual-oracle packs, export for external RE tools

Branch B must stay honest: default environment toolchain is report-only; analysis is not a “site bypass kit.” Deeper IR/SSA language in the table is design intent — pieces exist or are scaffolded; the full pipeline remains the climb, not a checkbox of “already done.”

How A and B reinforce each other

        +------------------+
        |  JS under test   |
        +--------+---------+
                 |
        +--------v---------+
        |  Branch A: host  |  run / freeze / offline / brand
        +--------+---------+
                 |  traces, events, gaps
        +--------v---------+
        |  Branch B: analyze |  instrument, CFG, plan, report
        +--------+---------+
                 |  missing surface, wrong values, entry fixes
                 +-----> back into Branch A (profiles, shims, network)

1. A → B: Without a faithful host, traces are noise and Illegal invocation masks real logic.
2. B → A: Diffs and probes show which getters, plugins, or network edges still lie.
3. Loop: Each milestone should either harden the host, deepen observation, or tighten the contract between them.

That is the product thesis: one Python process, two complementary branches, not a pile of unrelated scripts.

Why this technical path

Approach	Common gap
Pure Node / pure Python	Thin browser surface; instanceof, getters, workers, Intl often wrong
Full CDP browser only	Heavy, hard to instrument VMs offline, non-deterministic for CI
Thin stubs	Fail brand checks, canvas/WebGL/crypto fingerprints, DOM collections

iv8-rs embeds V8 with a large native browser surface, offline ResourceBundle networking, deterministic seeds, ChaosVM / instrument_source path A, multi-bundler entry plane, and a diagnostic environment toolchain — one Python process, same-thread isolate, honest bounds (not full Chrome).

Capabilities

Organized by domain, not version waterfall. Version deltas live in CHANGELOG. Contracts: docs/api/.

Runtime host

• JSContext factory with environment / profile / defaults merge; context manager; close / dispose
• Same-thread isolate affinity; 128MB Python thread stack at import (mixin-scale templates)
• time_mode logical | system; random_seed / crypto_seed / time_freeze
• config: timezone, locale, storage_path; TZ → process TZ + V8 Redetect (ICU 77 data)
• Dual-track versioning: milestone tags vs package number (docs/api/versioning.md)

Browser surface & DOM

• Window / Navigator / Screen / Location / History / Performance / document APIs (codegen + native)
• html5ever parse, ego-tree, CSS Level 4 selectors, EventTarget 3-phase dispatch
• page_load / page_load_with_headers; NodeList iterable; getElementsByTagName('*')
• Collections / plugins / HTMLAll / Options structure; Worker + WorkerNavigator paths
• Profile-driven identity (Chrome-line default profile; flat dot-path environment)

Crypto / Canvas / WebGL / Audio

• SubtleCrypto: AES-GCM/CBC/CTR, RSA-OAEP/PSS, ECDSA/ECDH, HMAC, HKDF, PBKDF2, X25519/AES-KW paths
• Canvas 2D (tiny-skia + deterministic noise / fixed fingerprint modes)
• WebGL parameter surface + environment UNMASKED_* / call log hooks
• AudioContext / OfflineAudio completion paths; font metrics from profile where wired

Network & event loop

• 3-layer network: ResourceBundle → Python set_network_handler → error (no silent open-web crawl)
• add_resource offline bodies; XHR / fetch / WebSocket lifecycle surfaces
• Logical vs system timers; advance / sleep / tick / drain patterns (see GUIDE)
• Cookie / Headers / storage persist-load helpers on context

Anti-detection primitives

• wrapNative / hookNative / window.chrome / MarkAsUndetectable paths
• Function toString / toStringTag / prototype brand hygiene (ongoing fidelity work)
• High-signal Illegal invocation fixes on brand-sensitive APIs
• Not a “pass every detector” product guarantee — host fidelity + explicit bounds

Instrumentation & observability

• Module instrument_source (ChaosVM path A, closure-scoped handlers, e.g. TDC)
• Instance instrument_chaosvm for global handler tables only
• Unified / VM traces; trace_diff; trace points; recording / profiler / coverage
• CDP Inspector: with_devtools, breakpoints, step, scope, programmatic API
• Debugger class: trace_api, watch_property, eval_traced, snapshots

Entry / multi-bundler

• prepare_entry / run_with_entry / plan_multi_entry
• Webpack / Parcel / Browserify / Vite-adjacent bridges; chunk supply is caller-owned
• Corpus runner CLI helpers for offline multi-case runs

Environment toolchain (diagnostic plane)

• Probe / gap / candidate / pressure / MAPE-K-style reports
• Report-only / no automatic apply / no silent profile write by default
• Not a one-click site bypass kit; sample adapters are separate and non-API

Workers

• Dedicated isolate + OS thread + structured clone (方案 A)
• WorkerNavigator / import static+dynamic paths; residual gaps in residual ledgers

Non-goals / honest bounds

Not claimed	Reality
Full Chromium / Blink	Large IDL + intentional stubs; parity is continuous work
Auto-fetch all bundler chunks	Offline-first; you supply chunk text
Silent live network product	ResourceBundle-first
Environment toolchain auto-fixes hosts	Diagnostic reports only unless you authorize mutation elsewhere
Identity with PyPI package iv8 0.1.x	Related lineage / dual-engine oracle; this product is iv8-rs
Full layout engine / deep fingerprint luxury	Deferred (v0.9+ / residual)

Global bounds: docs/api/overview.md.

Install

Requires Python 3.13+. ICU 77 data ships as icudtl.dat (override with IV8_ICUDTL_PATH).

Prebuilt wheels (PyPI / GitHub Release)

When published, install from PyPI:

pip install ming_iv8_rs
python -c "import iv8_rs; c=iv8_rs.JSContext(); print(c.eval('1+1')); c.close()"

Supported wheel platforms (package track 0.8.12):

Platform	Wheel tag (typical)	Notes
Windows x86_64	win_amd64	Primary desktop
Linux x86_64	manylinux_2_34_x86_64	Prebuilt V8 150+ (cdylib TLS-safe)
macOS Apple Silicon	macosx_*_arm64	arm64 only

Not shipped in 0.8.12: macOS Intel (x86_64), Linux aarch64. Build from source if needed.

GitHub Release tag for binaries (when cut): pkg-0.8.12 (package release; not continuum milestone v0.8.12).

Build from source

Requires Rust toolchain (see rust-version in workspace) in addition to Python 3.13+.

git clone https://github.com/lgnorant-lu/ming_iv8_rs
cd ming_iv8_rs

# Local development (fast iteration)
uv run maturin develop --target-dir target-maturin --strip --profile dev

# Distribution build (LTO, slow)
uv run maturin develop --release

Stack: create JSContext after import iv8_rs (module sets threading.stack_size(128MB)). Full-kernel Rust tests: RUST_MIN_STACK=134217728.

Optional: cargo/maturin --target-dir on a fast local cache path to avoid IDE contention on target/.

Quick start

import iv8_rs

with iv8_rs.JSContext() as ctx:
    print(ctx.eval("navigator.userAgent"))

# Profile + overrides (environment wins over profile)
ctx = iv8_rs.JSContext(
    profile="default",
    environment={
        "timezone": "Asia/Shanghai",
        "navigator.userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...",
        "screen.width": 1920,
        "screen.height": 1080,
    },
    time_mode="system",
    config={"timezone": "Asia/Shanghai"},
)
print(ctx.eval("Intl.DateTimeFormat().resolvedOptions().timeZone"))
ctx.close()

# Offline resource + eval
ctx = iv8_rs.JSContext()
ctx.add_resource("https://example.com/app.js", "window.__ok = 1", status=200)
ctx.page_load("<html><body></body></html>", base_url="https://example.com/")
# ChaosVM / TDC-style: prefer instrument_source, then eval patched source
# patched, info = iv8_rs.instrument_source(source)
# ctx.eval(patched)
ctx.close()

Full method surface: docs/api/runtime/jscontext.md.
Instrumentation: docs/api/instrumentation/.

Documentation map

Doc	Role
docs/api/	Stable API contracts (layered; public-oriented)
docs/GUIDE.public.md	Public tutorial cut (§1–16); full GUIDE is private-oriented
CHANGELOG.md	Per-version deltas
docs/quality-harness/	Quality gate definitions
docs/conventions/	Naming / testing / docs / docstring standards
CONTRIBUTING.md	Commit / scope conventions
docs/PROGRESS.md	Internal progress (private-oriented)

Do not treat acceptance/roadmap trees as public product API.

Architecture (bird's-eye)

Python (iv8_rs)
    │  PyO3
    ▼
iv8-py  ──►  iv8-core (V8 isolate, DOM, crypto, canvas, network, inspector)
                │
                ├── iv8-undetect (wrap/hook/chrome primitives)
                ├── iv8-surface / codegen (IDL templates)
                └── iv8-profile (profile matrix helpers)

iv8-rs/
├── crates/          # Rust workspace (core, py, undetect, surface, …)
├── python/iv8_rs/   # Package surface, profiles, analysis, toolchain
├── tests/           # Python integration
└── docs/            # GUIDE, api/, quality-harness, roadmap (mixed public/private)

Development

# Rust
cargo test --workspace
cargo test -p iv8-core --lib
cargo clippy --workspace --all-targets -- -D warnings

# Python release-style gate
uv run python -m pytest tests -q

See CONTRIBUTING.md and in-repo agent notes for commit format, stack size, and non-authorization rules (no public push / package bump without explicit request).

Acknowledgments

• iv8 — major inspiration and dual-engine reference lineage for Python↔V8 hosting
• Upstream: V8, PyO3, maturin, html5ever, and the wider ecosystem

Disclaimer and terms of use (read carefully)

This software is provided for research, education, interoperability testing, debugging, and legitimate software engineering only.

No warranty. The software is provided AS IS, without warranty of any kind, express or implied, including but not limited to merchantability, fitness for a particular purpose, non-infringement, accuracy of browser emulation, or undetectability. See the Apache License 2.0.

You are solely responsible for how you use this software and for compliance with all applicable laws, regulations, website/service terms of use, and third- party rights in your jurisdiction.

Prohibited / out of scope (non-exhaustive):

• Unauthorized access, fraud, credential stuffing, account takeover
• Bypassing security, anti-bot, CAPTCHA, or access controls without permission
• Targeting production systems or users in ways that violate law or terms of service
• Distributing malware, phishing kits, or “one-click site bypass” packs built on this engine
• Misrepresenting this project as a full Chromium browser or as guaranteed anti-detect

Not a bypass product. Environment tooling is diagnostic / report-oriented by design. Sample-specific reverse notes and site overlays are not product API and are not provided as attack recipes.

Fingerprint / anti-bot. Any anti-detection primitives are host-fidelity building blocks, not a promise to pass every detector or to evade any named vendor.

Dual-engine / lineage. Mentions of related packages (e.g. PyPI iv8 0.1.x) are for technical comparison only. This product is iv8-rs / ming_iv8_rs.

Export and dual-repo. Public trees are path-filtered views of a private development history. Commit messages may still reflect development narrative; do not treat the public git log as a complete private process record.

Indemnity. To the maximum extent permitted by law, authors and contributors shall not be liable for any claim, damages, or other liability arising from use or inability to use the software, including legal costs arising from your misuse.

By cloning, installing, or using this software, you acknowledge this disclaimer.

License

Apache License 2.0