BypassV3 - reCAPTCHA v3 Integration Test Toolkit

A browserless testing and research client for reCAPTCHA v3 and score-based reCAPTCHA Enterprise integrations.

reCAPTCHA status

Primary Use Cases

Controlled Integration Testing: Run integration, end-to-end, and regression tests for endpoints protected by reCAPTCHA without requiring a full browser automation instance for every test case.
Defensive Evaluation: Test whether an application’s server-side verification and anti-abuse policies remain effective when presented with minimally constructed token requests.
Local Fixture Research: Compare request shapes and token generation characteristics in controlled test environments.

How It Works

reCAPTCHA v3’s /api2/reload and Enterprise’s /enterprise/reload endpoints accept a binary protobuf payload (Content-Type: application/x-protobuffer). BypassV3 constructs and sends minimal protobuf bodies directly, without browser automation overhead:

Anchor Request: Fetches the anchor page (/api2/anchor or /enterprise/anchor) to extract the recaptcha-token (c), site key (k), origin (co), and script version (v).
Reload Request: Sends a minimal protobuf body containing fields v, c, reason, action, and k.
Token Retrieval: Parses Google’s JSON response (stripping the XSSI guard )]}') and returns the token for server-side verification.
Action Binding: Properly binds the expected action into the token to prevent server-side action mismatch rejections.

Usage Example

from bypass import ReCaptchaV3Bypass

# Solve using anchor URL
url = "https://www.google.com/recaptcha/api2/anchor?ar=1&k=..."
token = ReCaptchaV3Bypass(url, action="login").bypass()

# Solve directly from Site Key and Origin
token = ReCaptchaV3Bypass.from_site_key(
    "YOUR_SITE_KEY",
    origin="https://app.example.test",
    action="demo_action",
).bypass()

Analysis Tools Included

proto_decode.py: Decode protobuf wire format without requiring predefined schemas.
decode_body.py: Inspect captured request and response payloads.
extract_har.py & extract_fingerprint.py: Extract reusable payload fields from browser HAR archives.

Requirements & License

Runtime: Python 3.12+ (requests, blackboxprotobuf)
License: AGPL-3.0 License