Route SOCKS5/SOCKS5h proxies via --proxy-server Chrome arg instead of
Playwright's proxy dict (which rejects SOCKS5 with credentials).
Handles string URLs, Playwright dicts, IPv6, bypass lists.
SOCKS5 geoip exit IP resolution uses socks-proxy-agent (optional peer
dep). Falls back to DNS if not installed.
CLI args like --fingerprint-locale were passed as raw passthrough args
to Chrome, missing the companion --lang flag that build_args() normally
adds. Caused Intl API to default to en-US while navigator.language
showed the correct locale — a detectable mismatch.
Fixes#130
Node 22 ships npm v10 which lacks OIDC support. The upgrade step was
removed in 02359f6 but is required for provenance-based publishing.
Pin to npm@11 instead of @latest to avoid future breakage.
Remove --disable-blink-features=AutomationControlled (dead, binary handles
navigator.webdriver at source level) and hardcoded GPU vendor/renderer flags.
Binary auto-generates diverse GPU profiles from fingerprint seed. Improves
fingerprint diversity -- previously every user shared the same GPU string.
Bump to v0.3.21.
viewport=None now disables viewport emulation via Playwright's
no_viewport=True, matching the JS wrapper's viewport: null behavior.
Uses a sentinel to distinguish "not provided" from explicit None.
Co-authored-by: kitiho <51785099+kitiho@users.noreply.github.com>
Two ways to spoof WebRTC ICE candidate IPs:
1. --fingerprint-webrtc-ip=auto in args: resolves proxy exit IP via
HTTP call through the proxy (ipify.org). No extra deps needed.
2. geoip=True: auto-injects the flag for free (exit IP already
resolved during timezone/locale lookup, zero extra network cost).
Explicit IP (--fingerprint-webrtc-ip=1.2.3.4) also supported.
User-provided values always take precedence.
Python + JS wrappers, README docs, tests.
- Move `import websockets` to top-level (guaranteed by [serve] extra)
- Add --data-dir flag with smart default (Docker → /tmp/cloakserve, bare metal → ~/.cloakbrowser/cloakserve)
- Store launch params (tz/locale/proxy) on ChromeProcess for conflict logging
- Enhance GET / to return per-process detail (pid, port, seed, connections, config)
- Add connection refcounting in WS handlers for status visibility
- Add first-launch-wins note to README
- Add tests for data-dir, Docker detection, and connection tracking
Spawns a separate Chrome process per unique fingerprint seed, all behind
a single port (9222). Clients specify seeds and fingerprint params via
query string on the CDP URL:
connect_over_cdp("http://host:9222?fingerprint=12345&timezone=Asia/Tokyo")
Supports all --fingerprint-* flags as query params, geoip=true for
auto timezone/locale from proxy IP, and proxy= for per-process proxies.
- Rewrite bin/cloakserve from 57-line wrapper to aiohttp CDP multiplexer
- Add ChromePool with per-seed process management and port allocation
- Bidirectional WebSocket proxy for CDP traffic
- URL rewriting for /json/version, /json/list, and WS paths
- Rename _build_args -> build_args, _maybe_resolve_geoip -> maybe_resolve_geoip
- Add aiohttp + websockets to serve optional deps
- Dockerfile installs .[serve] extras
- Add 20 unit tests for cloakserve (param parsing, CLI args, URL rewriting)
Pin all 22 action references across ci.yml, publish.yml, and
attest-release.yml to immutable commit SHAs. Mutable tags can be
force-pushed by attackers (cf. TeamPCP supply chain campaign).
Add Dependabot for github-actions to get weekly PRs when pinned
actions have new versions.
- Bump wrapper version to 0.3.17 (Python + JS)
- Update PLATFORM_CHROMIUM_VERSIONS: windows-x64 109.2 → 159.7
- Update patch counts in platform tables (Linux 33, Windows 33)
- Add Linux arm64 to JS README platform table
- Update CHANGELOG with all changes since v0.3.16
Headed mode (all platforms): Chromium's GPU blocklist disables WebGL on
software GPUs in Docker/VNC/Xvfb. Flag lets SwiftShader serve WebGL.
Harmless on real GPUs. Headless unaffected. Ref #56.
Windows (all modes): GPU blocklist also blocks WebGPU for the Microsoft
Basic Render Driver. Dawn's adapter_blocklist bypass alone isn't enough.
Add examples/integrations/ with tested examples for browser-use, Crawl4AI,
Scrapling, LangChain, Selenium, undetected-chromedriver, and agent-browser.
Add js/examples/stagehand.ts for Stagehand (TypeScript).
README: new "Framework Integrations" subsection with two integration
patterns (direct binary launch vs CDP connect) and table linking all 8 examples.
- Add linux-arm64 to PLATFORM_CHROMIUM_VERSIONS (Python + JS)
- Multi-arch Docker build (linux/amd64 + linux/arm64) via QEMU in CI
- Add ko-fi donate link to welcome banner (Python + JS)
- Version bump to 0.3.16
Binary:
- Upgrade Linux x64 build to Chromium 145.0.7632.159.7 (33 C++ patches)
- StorageBuckets API quota normalization — closes last storage-based incognito detection vector
Wrapper:
- Fix non-ASCII character support in humanized typing (Cyrillic, CJK, emoji)
- Document storage quota tradeoff for persistent contexts
- Add Ko-fi funding link
Verify that HTTP errors (429, 503, etc.) from cloakbrowser.dev
correctly trigger GitHub Releases fallback for both binary and
checksum downloads. Also test that custom CLOAKBROWSER_DOWNLOAD_URL
disables fallback, and both-sources-fail returns gracefully.
Adds install, info, update, and clear-cache subcommands with visible
download progress. Python: `python -m cloakbrowser install`. JavaScript:
`npx cloakbrowser install`. Useful for Dockerfiles where silent
first-use downloads are hard to debug. Closes#43.
- Add cosign verify command to README Security section for Docker image verification
- Add GitHub deployment environments (pypi, npm, docker) to publish workflow for sidebar status tracking
- Simplify downgrade instructions: version-pinned pip/npm/docker instead of manual binary paths
- Improve troubleshooting section with headings and dividers for readability
- Update Latest section to v0.3.12 with new binary features
- Remove locale and timezone_id from Playwright context kwargs (CDP)
- Pass timezone via --fingerprint-timezone binary flag (process-wide)
- Pass locale via --lang + --fingerprint-locale binary flags
- Accept both timezone and timezone_id param names silently (no deprecation)
- Update all wrapper tests to verify binary args, not CDP context params
- publish.yml: automated PyPI/npm/Docker on v* tag push; OIDC trusted publishing for PyPI/npm; Docker signed with Cosign keyless + provenance attested
- attest-release.yml: manual workflow to attest binary release assets via Sigstore (actions/attest-build-provenance@v2)
- pyproject.toml: add dev extras (pytest, pytest-asyncio)
Binary: fix detection regression (#16), fix fingerprint consistency in offline audio rendering.
Wrapper: bump version to 0.3.10, update Linux binary version to 145.0.7632.159.2.
Add bin/cloakserve — launches stealth Chromium with remote debugging
enabled so users can connect via connect_over_cdp() from the host.
Uses socat to forward 0.0.0.0:9222 to Chrome's localhost-only CDP port.
Usage: docker run -d -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser cloakserve
Tested: all stealth checks pass via CDP, bot.sannysoft.com 54/54,
reCAPTCHA 0.9, zero detection regressions.
Bump version to 0.3.9. Extract shared buildArgs into js/src/args.ts (DRY),
guard console.debug behind DEBUG=cloakbrowser env var, strengthen caplog assertion.
- Bump linux-x64 binary to 145.0.7632.159 (macOS/Windows stay at 145.0.7632.109.2)
- Wrapper version 0.3.8
- Fix rollback path examples to use correct per-platform versions
Show welcome banner once per install (Python, JS, Docker).
Uses marker file in ~/.cloakbrowser/ — resets on cache clear or update.
Replaces logger.info() calls that were invisible by default.
Bump to v0.3.8.
Add cloakhq/cloakbrowser Docker Hub image with Node.js, JS wrapper,
Xvfb headed mode, and cloaktest shortcut. Add launch feedback and IP
display to all examples. Update README Docker section for Docker Hub.
- Rename timezone_id → timezone in launch_context(), launch_persistent_context(),
and launch_persistent_context_async() (Python)
- Extract _migrate_timezone_id() helper for deprecation compat (DRY)
- Always pop timezone_id from kwargs to prevent override via context_kwargs.update()
- Use FutureWarning (visible by default) instead of DeprecationWarning
- JS: deprecate timezoneId on LaunchContextOptions with runtime shim
- Extract migrateTimezoneId<T>() shared helper in playwright.ts (DRY)
- Bump version to 0.3.7 in _version.py and package.json
- Add 4 Python + 4 JS unit tests for deprecation compat behavior
Add Cloud/Container/Integration Use section clarifying internal Docker/CI
is permitted, dependency listing is not redistribution, OEM/SaaS requires
separate license. Add Limitation of Liability ($100 cap). Add prohibited
use cases (banking, credential stuffing, fraud). Clarify that flags,
extensions, and custom profiles are permitted configuration. Update README
and js/README with prohibition language and license link.
The `proxy` parameter now accepts a Playwright proxy dict
({server, bypass, username, password}) in addition to URL strings.
Dict proxies are passed directly to Playwright, enabling bypass
lists and other advanced proxy options.
- Add ProxySettings TypedDict for Python type safety
- Extract server URL from dict proxies for geoip resolution
- Handle dict proxy args/auth in Puppeteer wrapper
- Strip inline credentials from dict proxy server URL in Puppeteer
- Fix JS launchContext() double-setting timezone (binary flag + context)
- Remove unnecessary non-null assertions in TS geoip helpers
- Use nullish coalescing for password fallbacks
- Add unit tests for geoip with dict proxy input
- Add launch_persistent_context() Python + JS with examples
- Document persistent context API in both READMEs
- Bump version to 0.3.5
- Credit @evelaa123 and @yahooguntu in CHANGELOG
Binary v14+ auto-generates hardware concurrency, device memory, screen
dimensions, and window size from the fingerprint seed. Remove these
explicit flags from Python/JS wrapper defaults and update README:
- Remove 5 flags from get_default_stealth_args() in both wrappers
- Move hardware-concurrency, device-memory, screen-width, screen-height
to the Additional Flags table with auto-generated defaults documented
- Update code examples to use --fingerprint instead of --window-size
- Simplify fingerprint defaults table to show only wrapper-set flags
Bump wrapper to 0.3.3. Update README fingerprint section to
document auto-spoof behavior (zero-config stealth). Improve
reCAPTCHA test with wait_for_selector instead of blind sleep.
- Add explicit Mac GPU flags (Apple M3 Metal renderer) to stealth args
- Bump macOS platform versions to 145.0.7632.109
- Update README fingerprint table to reflect actual Mac GPU defaults
- Add warning about binary requiring explicit flags without wrapper
- Fix stealth_test.py wait_until for reCAPTCHA page
Check for newer wrapper versions on startup (once per process).
Python queries PyPI, JS queries npm registry. Respects
CLOAKBROWSER_AUTO_UPDATE=false and CLOAKBROWSER_DOWNLOAD_URL
(custom mirror mode skips external registry calls).
Includes unit tests for both languages covering: update detection,
env var gating, network error handling, and once-per-process guard.
- Add PLATFORM_CHROMIUM_VERSIONS map (Linux=v145, macOS=v142)
- Add get_chromium_version()/getChromiumVersion() for platform-specific version
- Make auto-update check release assets before offering updates
- Scope version markers per-platform (latest_version_linux-x64)
- Support 5th version segment for hotfix builds (e.g. 145.0.7632.109.2)
- Derive AVAILABLE_PLATFORMS from version map
- Add CHANGELOG.md with v0.3.0 release notes (Chromium 145, 26 patches)
- Bump Python and JS package versions from 0.2.2 to 0.3.0
- Update README with v0.3.0 highlights section and changelog link
- Correct roadmap status for Chromium 145 build
Fetches SHA256SUMS sidecar file from download server before extraction.
Mismatch = hard error, unavailable = warn and proceed (graceful for old releases).
Respects CLOAKBROWSER_DOWNLOAD_URL contract (no GitHub fallback for custom mirrors).
Skip with CLOAKBROWSER_SKIP_CHECKSUM=true. Both Python and JS wrappers.
launch() and launch_context() now inject --timezone and --lang binary
flags when timezone/locale params are set. Previously only the Playwright
context layer was configured, leaving a detectable mismatch that CreepJS
flagged as a bot signal.
Closes: WM5
page.wait_for_timeout() sends CDP protocol commands that reCAPTCHA and
other antibot systems detect. Replaced with time.sleep() (Python) which
is invisible to the browser.
- examples/stealth_test.py: 7 replacements
- examples/recaptcha_score.py: 1 replacement
- tests/test_stealth.py: 7 replacements
- README.md + js/README.md: added reCAPTCHA troubleshooting section
- Bump version to 0.2.2
Replace hollow page-load checks with actual verdict parsing for 6
detection sites: sannysoft, incolumitas, browserscan, deviceandbrowserinfo,
fingerprintjs, and recaptcha v3. Add proxy support via CLOAKBROWSER_TEST_PROXY
env var. All 12 stealth tests pass.
macOS downloads were broken: symlinks in Chromium.app Framework layout were
skipped and flatten logic removed the .app bundle structure. Now allows safe
symlinks, skips flattening .app dirs, and runs xattr -cr post-extraction to
prevent Gatekeeper prompts. Also adds Turnstile GIF to README proof section.
CloakHQ