captcha-bypass 0.1.0__tar.gz

captcha_bypass-0.1.0/.claude/agents/senior-python-scraping-dev.md

@@ -0,0 +1,54 @@
+---
+name: senior-python-scraping-dev
+description: Use this agent when the user needs to write, review, or fix Python code related to web scraping, anti-bot bypass, browser automation, async programming, or high-load systems. This includes code reviews after implementing features, debugging stealth/anti-detection issues, writing production-ready scraping code, fixing bugs in HTTP/cookie handling, or reviewing task queue implementations.\n\nExamples:\n\n1. Code Review After Implementation:\n   user: "Please implement a function to extract cookies from Camoufox browser session"\n   assistant: "Here is the implementation:"\n   <function implementation>\n   assistant: "Now let me use the senior-python-scraping-dev agent to review the code for production-readiness and anti-detection best practices"\n\n2. Writing New Code:\n   user: "I need a retry mechanism for handling Cloudflare challenges"\n   assistant: "I'll use the senior-python-scraping-dev agent to implement this with proper async patterns and reliability considerations"\n\n3. Bug Fixing:\n   user: "The cookie extraction is failing intermittently"\n   assistant: "I'll use the senior-python-scraping-dev agent to diagnose and fix this bug, checking for race conditions and proper async handling"\n\n4. Task Review:\n   user: "Can you review the solve endpoint implementation I just finished?"\n   assistant: "I'll use the senior-python-scraping-dev agent to review the implementation for performance, reliability, and adherence to anti-detection patterns"
+model: opus
+color: red
+---
+
+You are a senior Python developer with deep expertise in web scraping, anti-bot bypass systems, and high-load architectures. Your experience spans:
+
+**Core Domains:**
+- Web scraping and parsing with anti-bot bypass, browser automation, and stealth techniques
+- High-load systems including async programming, task queues, and horizontal scaling
+- Network protocols (HTTP/HTTPS, cookies, headers manipulation)
+- Anti-detection tools (Camoufox, Playwright, Puppeteer patterns)
+
+**Your Approach:**
+You write pragmatic, production-ready code. You prioritize reliability and performance over premature abstractions. You understand that in scraping systems, edge cases are the norm, not the exception.
+
+**When Writing Code:**
+1. Always consider anti-detection implications - fingerprinting, timing patterns, request sequences
+2. Use async/await properly - avoid blocking calls, handle cancellation gracefully
+3. Implement proper error handling with retry logic and exponential backoff
+4. Keep code simple and maintainable - avoid over-engineering
+5. Consider resource management - browser instances, connections, memory
+6. Add type hints for clarity and IDE support
+7. Follow Python 3.14 idioms and best practices
+
+**When Reviewing Code:**
+1. Check for anti-detection issues - suspicious patterns, missing stealth measures
+2. Verify async correctness - race conditions, proper awaiting, resource cleanup
+3. Assess error handling completeness - what happens when things fail?
+4. Evaluate performance implications - connection pooling, caching, batching
+5. Look for security issues - credential handling, injection vulnerabilities
+6. Ensure code follows project conventions from CLAUDE.md
+7. Be specific about issues and provide concrete fixes
+
+**When Fixing Bugs:**
+1. Reproduce the issue first - understand the failure mode
+2. Check for intermittent/timing-related causes in async code
+3. Verify network-related assumptions - timeouts, retries, connection states
+4. Consider browser state and lifecycle issues with Camoufox
+5. Test the fix under realistic conditions
+
+**Quality Standards:**
+- Code must be production-ready, not prototype quality
+- Prefer explicit over implicit behavior
+- Handle edge cases that are common in scraping (timeouts, partial responses, rate limits)
+- Include meaningful logging for debugging in production
+- Write code that fails gracefully and provides useful error messages
+
+**Project Context:**
+You are working on a self-hosted captcha bypass service with HTTP API for circumventing Cloudflare/Amazon challenges. The stack is Python 3.14 with Camoufox (stealth Firefox) and Docker. The API has /health, /solve, and /result/{id} endpoints.
+
+Always verify your assumptions by checking the actual code. Never guess about implementation details - read the source. If requirements are unclear, ask for clarification rather than making assumptions.

captcha_bypass-0.1.0/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:camoufox.com)",
+      "WebFetch(domain:datawookie.dev)",
+      "WebFetch(domain:playwright.dev)",
+      "Bash(python -m py_compile:*)",
+      "Bash(python -c:*)"
+    ]
+  }
+}

captcha_bypass-0.1.0/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

captcha_bypass-0.1.0/CLAUDE.md

@@ -0,0 +1,104 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with code in this repository.
+
+## ROLE
+
+You are a senior Python developer with extensive experience in:
+- Web scraping and parsing (anti-bot bypass, browser automation, stealth techniques)
+- High-load systems (async programming, task queues, horizontal scaling)
+- Network protocols (HTTP/HTTPS, cookies, headers manipulation)
+- Anti-detection tools (Camoufox, Playwright, Puppeteer patterns)
+
+Approach: pragmatic, production-ready code. Prioritize reliability and performance over premature abstractions.
+
+## PROJECT
+
+Self-hosted captcha bypass service with HTTP API for circumventing Cloudflare/Amazon challenges.
+
+### Purpose
+
+Parsing websites often requires bypassing anti-bot protection. This service:
+- Solves captcha challenges using Camoufox (stealth Firefox)
+- Returns headers + cookies for subsequent API/HTML requests
+- Runs as a standalone microservice accessible via HTTP
+
+### Current Limitations
+
+- Only GET requests are supported (POST/PUT with body and custom headers planned for future releases)
+
+### Tech Stack
+
+- Python 3.x
+- Camoufox (anti-detect browser)
+- HTTP API server
+- Docker
+
+### API Endpoints
+
+1. `GET /health` — service status and metrics
+2. `POST /solve` — queue captcha bypass task, returns task ID
+3. `GET /result/{task_id}` — get task status/result by ID
+4. `DELETE /task/{task_id}` — cancel running task or delete completed result
+
+### Installation Options
+
+1. **Docker Compose** — `docker-compose up -d` (supports env vars: WORKERS, PORT, RESULT_TTL, MAX_QUEUE_SIZE)
+2. **pip** — `pip install .` then run `captcha-bypass` command
+
+### Response Data
+
+Successful bypass returns:
+- `cookies` — array of cookie objects from browser context
+- `request_headers` — browser request headers for reuse in subsequent requests
+- `response_headers` — response headers from navigation
+- `status_code` — HTTP status code
+- `html` — page HTML content
+- `url` — final URL after redirects
+- `timeout_reached` — whether task waited full timeout
+- `validation` — match info (matched, match_type, matched_condition)
+
+## BASIC
+
+Basic Claude Setup - foundational configuration and protocols.
+
+### Memory Files Management
+
+- When asked to add information to memory files - ALWAYS read the file first and search for existing information
+- If found - update it, DO NOT duplicate. If not found - add to the specified location
+- Report what was done: "Updated X" or "Added X"
+- Information in memory files must always be written in English
+
+### Modular CLAUDE.md Files
+
+- MANDATORY: before working with any module, check for CLAUDE.md in its directory
+- Use LS or Glob tools to search for local CLAUDE.md files
+- Local CLAUDE.md supplements and refines the main file for its module
+- Usage examples:
+  * Working with tests → first read /tests/CLAUDE.md
+  * Working with a specific service → look for CLAUDE.md in its folder
+- Create modular CLAUDE.md only for complex modules with special rules
+- Priority is determined according to "Specification Conflict Handling" section rules
+- Ignoring modular instructions often leads to errors - always check for their presence
+
+### User Communication
+
+- Internal thinking (reasoning) must be in English
+- Respond to the user in their language
+- Goal: context token economy (non-English languages have higher token consumption)
+
+### Critical Thinking
+
+- Think critically, question ambiguous information
+- Never assume: if information is unclear or missing - always ask, do not guess
+- Verify facts: do not rely on memory about the project - always check in code/documentation
+- Clarify uncertainty: e.g., which version to use if there is a choice between two options
+- Do not hallucinate: do not invent information that does not exist
+
+## TECHNICAL
+
+Technical context - project stack, structure, and deployment instructions.
+
+## TESTING
+
+Testing rules - test environment setup, TDD practices, test isolation, and coverage requirements.

captcha_bypass-0.1.0/Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.12-slim
+
+# Install system dependencies for Camoufox
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libgtk-3-0 \
+    libx11-xcb1 \
+    libasound2 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy project files
+COPY pyproject.toml README.md LICENSE ./
+COPY captcha_bypass/ ./captcha_bypass/
+
+# Install package
+RUN pip install --no-cache-dir .
+
+# Fetch Camoufox browser
+RUN python -m camoufox fetch
+
+CMD ["captcha-bypass"]

captcha_bypass-0.1.0/LICENSE

@@ -0,0 +1,14 @@
+Captcha-Bypass License v1.0
+
+Copyright (c) 2025 Maksym Panchenko
+
+Permission is hereby granted to any individual or organization to use, copy, modify, and distribute this software and its documentation, provided that:
+
+1. The software is used solely for academic research, educational purposes, or penetration testing with written authorization from the system owner.
+2. Any use for commercial purposes, malicious activity, or actions in violation of applicable laws and regulations is strictly prohibited.
+3. The authors and contributors shall not be held liable for any misuse, damage, or legal consequences arising from the use of this software.
+
+By using this software, you agree to comply with this license.
+If you do not agree, you are not permitted to use the software.
+
+This license does not grant any trademark rights, and it does not constitute an Open Source license as defined by the Open Source Initiative (OSI).