Serve a local replica of a reCAPTCHA widget and capture the token.

RecaptchaDomainReplicator generates a local HTML page that renders a reCAPTCHA widget, serves it via a local Flask server, opens it in Chromium, and monitors the DOM to capture the resulting token.

https://github.com/user-attachments/assets/9a464e30-fae7-461e-ab84-37d6c4bec078

Features

• Generate local page for any sitekey and domain
• Serve via local Flask server (in-memory by default, optional disk persistence)
• Open in Chromium or reuse an existing browser/tab
• Monitor page in separated thread and expose token via TokenHandle • Proxy support (HTTP, HTTPS, SOCKS4, SOCKS5 with optional credentials)
• Domain bypass modes (VPN-friendly browser rules & hosts file fallback)
• HTTPS with temporary self-signed certificates
• Support for invisible reCAPTCHA, enterprise, custom actions, and data-s values
• Invisible reCAPTCHA (v3) is executed automatically

How It Works

The library follows a simple four-step pipeline:

• Generate: Build a single HTML page that renders reCAPTCHA for a given sitekey and domain (with optional params like action, data-s, enterprise).
• Serve: Host it on a local Flask server (in-memory by default; can persist to disk).
• Open: Launch (or reuse) a Chromium tab to load that page.
• Observe: Poll the DOM to extract the token once it appears.

Requirements

• Python: 3.9+
• Browser: Chromium-based browser (Chrome, Chrome for Testing, Edge)
• For credential proxies: Use Chrome for Testing or Microsoft Edge (Newer versions of Google Chrome doesn't support this) • Admin privileges (optional): Required only for hosts file changes and port forwarding

Installation

pip install recaptcha-domain-replicator

From source (with dev dependencies):

pip install -e ".[dev]"

Usage

Library Usage

from recaptcha_domain_replicator import RecaptchaDomainReplicator

with RecaptchaDomainReplicator(
    download_dir="tmp",
    server_port=8080,
    proxy=None,  # "http://user:pass@host:port"
    browser_path=None,  # r"C:\path\to\chrome.exe"
) as replicator:
    browser, token_handle = replicator.replicate_captcha(
        website_key="YOUR_SITE_KEY",
        website_url="https://example.com/path",
        is_invisible=True,
        action="submit",
        data_s_value=None,
        api_domain="google.com",  # or "recaptcha.net"
        is_enterprise=False,
        bypass_domain_check=True,
        use_ssl=True,
        headless=False,
        user_agent=None,
        cookies=None,
        browser=None, # already instanciated browser
        tab=None,
    )

    # replicate_captcha() returns immediately, wait with the async token monitor
    token = token_handle.wait(timeout=120) if token_handle else None # 0 to wait until token is received
    print("Token:", token)

CLI Usage

After installation, a console script is available:

recaptcha-domain-replicator --help

Run the built-in demo:

recaptcha-domain-replicator demo

Replicate a captcha:

recaptcha-domain-replicator replicate \
  --website-key "YOUR_SITE_KEY" \
  --website-url "https://example.com/path" \
  --persist-html \
  --invisible \
  --action "submit" \
  --bypass-domain-check \
  --proxy "socks5://user:pass@host:port" \
  --browser-path "C:\path\to\chrome.exe" \
  --observation-time 0

CLI behavior notes:

• Prints the token (if obtained) as plain text
• logging: Disabled by default, enable with --log-level INFO or DEBUG
• --headless: Launch the browser in headless mode (default: headful)
• --observation-time: Set to 0 to run until a token is captured or browser closes

Domain Bypass Modes

When bypass_domain_check=True is enabled with a website_url, the tool makes the replica page appear to load from the original domain.

• Preferred (VPN-friendly) mode: Let the replicator create the browser

• Uses Chromium --host-resolver-rules to map the target domain to 127.0.0.1 inside that browser only
• Does not modify your system hosts file

• Fallback mode: You provide an existing browser/tab

• The browser is already running, so host-resolver-rules can't be applied, it falls back to modifying the Windows hosts file
• Requires an elevated (Administrator) shell

HTTPS, Ports & System Changes

• HTTPS by default: use_ssl=True serves the replica over HTTPS using a temporary self-signed certificate. Use --no-ssl for plain HTTP.

• Port forwarding (admin only): When elevated, the tool may create a Windows netsh interface portproxy rule to forward 80/443 -> the chosen high port. Port forwarding is removed during shutdown, firewall rules may remain.

Limitations

Even if you successfully capture a token, it may not be accepted by server-side verification.

Common rejection reasons: • Action mismatch: Backend expects a specific action value • Risk scoring: reCAPTCHA considers IP reputation, browser state, and interaction signals • Session mismatch: Server might expect the token from the same browser session • IP mismatch: Tokens might be evaluated relative to the client IP that solved the challenge • Token freshness: Tokens are short-lived • Enterprise vs non-enterprise: Using the wrong API variant changes behavior

• google.com vs recaptcha.net: Using the wrong scripts domain

Troubleshooting

• reCAPTCHA iframe never loads / shows an error

• The sitekey may be domain-restricted. Try --bypass-domain-check
• If relying on hosts-file bypass, run your terminal as Administrator

Repository Layout

recaptcha_domain_replicator/
├── recaptcha_domain_replicator/ # Package
│   ├── __init__.py
│   ├── __main__.py # CLI entry
│   ├── captcha_replicator.py # Replicator class
│   ├── html_builder.py # HTML generation
│   ├── server_manager.py # Flask server
│   ├── token_monitor.py # Token polling
│   ├── browser_config.py # Chromium options
│   ├── hosts_manager.py # Windows hosts file
│   ├── certificates.py # SSL certificate generation
│   ├── proxy_utils.py # Proxy parsing
│   ├── proxy_auth_extension.py # Chrome extension for proxy auth
│   └── logging_utils.py # Logging configuration
├── tests/ # Tests
├── assets/  # Images and diagrams
├── pyproject.toml # Project configuration
└── README.md

Development

To run the tests just run:

pytest

Should I star this repository?

You don't have to, but giving it a star would mean a lot. It helps more people discover the project. Your support helps grow an open and accessible community. Thank you!

Contributing

We welcome issues, feature requests, and pull requests! Please read the contribution guidelines before you begin.

If you discovered a typo or small documentation bug, feel free to open a quick PR straight away. For anything larger, open an issue first.

Code of Conduct

Be kind. We follow the Contributor Covenant. By participating in this project you agree to uphold those guidelines.

Donate

If you find this project helpful, please consider supporting the developer with a donation. Thank you! :)

• BTC: 1EXLMgvU1pNaXNwuaRSMRQ69Vqp2UTjTSZ
• ETH (ERC-20): 0xebb810aa4258d97f98157c32ac49b6be9dda4433
• LTC: LUqdVjS9cJFby5Mj5c7wkvyNM3zaJxzhTc
• USDT (TRC-20): TN5LEgpa1xu5EecC9LobzVN8KAgyi5kwgZ
• BNB (BEP-20): 0xebb810aa4258d97f98157c32ac49b6be9dda4433
• SOL: GGWSzrdftR4aivxxWZCEqJspfcqtzmLso9AkVXBkDfEK

Acknowledgements

• DrissionPage - Browser automation library
• Flask - Web framework for serving the replica
• pyOpenSSL - SSL certificate generation

License

This project is licensed under the MIT License.

Legal & Responsible Use

RecaptchaDomainReplicator is provided for educational and research purposes. Use responsibly and comply with all applicable laws and terms of service.