A Python library that extends Camoufox to automatically solve captcha challenges. Currently supports only Cloudflare challenges (interstitial and turnstile), with more captcha types planned.
demo_cloudflare_click_interstitial.mp4
THIS TOOL IS PROVIDED FOR EDUCATIONAL AND RESEARCH PURPOSES ONLY
This software is designed to demonstrate security concepts and should not be used to bypass protections on websites without explicit permission from the website owner. Using this tool against websites without authorization may violate:
- The Computer Fraud and Abuse Act (CFAA)
- Terms of Service agreements
- Various cybersecurity laws in your jurisdiction
The author takes no responsibility for any misuse of this software. Users are solely responsible for ensuring their use complies with all applicable laws and regulations.
- Closed Shadow DOM Traversal: Navigates complex closed Shadow DOM struc 8000 tures to find and interact with challenge elements
- Advanced Retry Logic: Implements retry mechanisms with configurable attempts and delays
- Verification Steps: Confirms successful solving through multiple validation methods
- Fully Tested: 100% code coverage with unit and integration tests
This package requires:
- Python 3.8+
- camoufox[geoip] 0.4.11 or higher (must be installed separately)
# firstly make sure to have camoufox or install it
pip install "camoufox[geoip]>=0.4.11"
# install camoufox-captcha
pip install camoufox-captchagit clone https://github.com/techinz/camoufox-captcha.git
cd camoufox-captcha
pip install -e ".[dev]"When creating your Camoufox instance, make sure to include these parameters for the library to work:
AsyncCamoufox(
# other parameters...
config={'forceScopeAccess': True}, # required
disable_coop=True # required
)These settings are essential for proper closed Shadow DOM traversal and browser security bypassing required by the captcha solving.
See usage examples in the /examples directory for ready-to-use scripts.
import asyncio
from camoufox import AsyncCamoufox
from camoufox_captcha import solve_captcha # import it
async def main():
async with AsyncCamoufox(
headless=True,
geoip=True,
humanize=False,
i_know_what_im_doing=True,
config={'forceScopeAccess': True}, # add this when creating Camoufox instance
disable_coop=True # add this when creating Camoufox instance
) as browser:
page = await browser.new_page()
# navigate to a site with Cloudflare protection
await page.goto("https://example-with-cloudflare.com")
# solve using solve_captcha
success = await solve_captcha(page, captcha_type='cloudflare', challenge_type='interstitial')
if not success:
return print("Failed to solve captcha challenge")
print("Successfully solved captcha challenge!")
# continue with your automation...
if __name__ == "__main__":
asyncio.run(main())Cloudflare Turnstile Example
import asyncio
from camoufox import AsyncCamoufox
from camoufox_captcha import solve_captcha # import it
async def main():
async with AsyncCamoufox(
headless=True,
geoip=True,
humanize=False,
i_know_what_im_doing=True,
config={'forceScopeAccess': True}, # add this when creating Camoufox instance
disable_coop=True # add this when creating Camoufox instance
) as browser:
page = await browser.new_page()
await page.goto("https://site-with-turnstile.com")
# locate the container with the Turnstile challenge
turnstile_container = await page.wait_for_selector('.turnstile_container')
# specify challenge type for Turnstile
success = await solve_captcha(
turnstile_container,
captcha_type="cloudflare",
challenge_type="turnstile"
)
if not success:
return print("Failed to solve captcha challenge")
print("Successfully solved captcha challenge!")
# continue with your automation...
if __name__ == "__main__":
asyncio.run(main())# specify a CSS selector that should appear after successful bypass
success = await solve_captcha(
page,
challenge_type="interstitial",
expected_content_selector="#super-protected-content"
)The solve_captcha function provides a unified interface with multiple parameters:
await solve_captcha(
queryable, # Page, Frame or ElementHandle containing the captcha
captcha_type="cloudflare", # Type of captcha provider (currently only "cloudflare")
challenge_type="interstitial", # For Cloudflare: "interstitial" or "turnstile"
method=None, # Solving method (defaults to best available for the captcha type):
# Cloudflare: "click"
**kwargs # Additional parameters passed to the specific solver:
# Cloudflare click:
# expected_content_selector=None, # CSS selector to verify solving success
# solve_attempts=3, # Maximum attempts for solving
# solve_click_delay=2.0, # Delay after clicking checkbox in seconds
# checkbox_click_attempts=3, # Maximum attempts to click the checkbox
# wait_checkbox_attempts=5, # Maximum attempts to wait for checkbox readiness
# wait_checkbox_delay=1.0 # Delay between checkbox readiness checks
)Cloudflare Interstitial Click Method
This method handles Cloudflare's full-page interstitial challenge that appears before accessing protected content.
How it works:
- Detects the Cloudflare challenge page through specific DOM elements
- Finds all iframes in the page's Shadow DOM tree
- Searches for the checkbox inside security frames
- Simulates a user click on the verification checkbox
- Waits for the page to reload or challenge to disappear
- Verifies success by checking for expected content or absence of challenge
Cloudflare Turnstile Click Method
This method handles Cloudflare's Turnstile widget that appears embedded within forms or other page elements.
How it works:
- Targets the Turnstile widget container element
- Finds all iframes in the page's Shadow DOM tree
- Searches for the checkbox inside security frames
- Simulates a user click on the verification checkbox
- Monitors for completion by watching for success state elements
- Verifies success by checking for expected content or success element in the widget
The project has unit and integration tests:
# run all tests with coverage report
pytest --cov=camoufox_captcha --cov-report=html tests/
# run only unit tests
pytest tests/unit/
# run only integration tests
pytest tests/integration/- Support for additional captcha types (hCaptcha, reCAPTCHA)
- Integration with external solving services (2Captcha, Anti-Captcha, CapMonster)
- Advanced detection methods for various captcha types
- Image-based captcha solving
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
Please ensure your code passes all tests and maintains or improves test coverage.
This project is licensed under the MIT License - see the LICENSE file for details.
Remember: Use this tool responsibly and only on systems you have permission to test.