A Python library that extends Camoufox to automatically solve captcha challenges. Currently supports only Cloudflare challenges (interstitial and turnstile), with more captcha types planned.
https://github.com/user-attachments/assets/10ced3fe-044b-4657-b371-155f1e943955
https://github.com/user-attachments/assets/90206e23-ac2f-4e45-a4c4-e1fd7e8f17e3
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 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.
This package requires:
# firstly make sure to have camoufox or install it
pip install "camoufox[geoip]>=0.4.11"
# install camoufox-captcha
pip install camoufox-captcha
git 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())
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
)
This method handles Cloudflare's full-page interstitial challenge that appears before accessing protected content.
How it works:
This method handles Cloudflare's Turnstile widget that appears embedded within forms or other page elements.
How it works:
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/
Contributions are welcome! Please follow these steps:
git checkout -b feature/amazing-featuregit commit -m 'Add amazing feature'git push origin feature/amazing-featurePlease 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.
FAQs
Automatic captcha solving using Camoufox
We found that camoufox-captcha demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The Latio podcast explores how static and runtime reachability help teams prioritize exploitable vulnerabilities and streamline AppSec workflows.
Security News
The latest Opengrep releases add Apex scanning, precision rule tuning, and performance gains for open source static code analysis.
Security News
npm now supports Trusted Publishing with OIDC, enabling secure package publishing directly from CI/CD workflows without relying on long-lived tokens.