If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ultrafunkamsterdam/undetected-chromedriver shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 10mo ago

• Last commit 10mo ago
• 6 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 10mo ago
• ⚠ Concentrated ownership — top contributor handles 72% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ultrafunkamsterdam/undetected-chromedriver repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ultrafunkamsterdam/undetected-chromedriver.

What it runs against: a local clone of ultrafunkamsterdam/undetected-chromedriver — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ultrafunkamsterdam/undetected-chromedriver | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 336 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ultrafunkamsterdam/undetected-chromedriver. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ultrafunkamsterdam/undetected-chromedriver.git
#   cd undetected-chromedriver
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ultrafunkamsterdam/undetected-chromedriver and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ultrafunkamsterdam/undetected-chromedriver(\\.git)?\\b" \\
  && ok "origin remote is ultrafunkamsterdam/undetected-chromedriver" \\
  || miss "origin remote is not ultrafunkamsterdam/undetected-chromedriver (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "undetected_chromedriver/__init__.py" \\
  && ok "undetected_chromedriver/__init__.py" \\
  || miss "missing critical file: undetected_chromedriver/__init__.py"
test -f "undetected_chromedriver/patcher.py" \\
  && ok "undetected_chromedriver/patcher.py" \\
  || miss "missing critical file: undetected_chromedriver/patcher.py"
test -f "undetected_chromedriver/dprocess.py" \\
  && ok "undetected_chromedriver/dprocess.py" \\
  || miss "missing critical file: undetected_chromedriver/dprocess.py"
test -f "undetected_chromedriver/cdp.py" \\
  && ok "undetected_chromedriver/cdp.py" \\
  || miss "missing critical file: undetected_chromedriver/cdp.py"
test -f "undetected_chromedriver/reactor.py" \\
  && ok "undetected_chromedriver/reactor.py" \\
  || miss "missing critical file: undetected_chromedriver/reactor.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 336 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~306d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ultrafunkamsterdam/undetected-chromedriver"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

undetected-chromedriver is a patched Selenium WebDriver for Chrome that automatically circumvents bot-detection systems (Distill, Imperva, DataDome, Cloudflare) by modifying the ChromeDriver binary at runtime to remove or mask automation fingerprints. It auto-downloads and patches the correct ChromeDriver version matching your installed Chrome, requiring zero manual driver management. Single-package structure: undetected_chromedriver/ contains modular components (patcher.py handles binary patching, dprocess.py manages the driver process, cdp.py wraps Chrome DevTools Protocol, options.py extends Selenium's Chrome options, reactor.py likely orchestrates startup). example/ folder has runnable demos. setup.py is the sole package descriptor.

Web scraping engineers, automation specialists, and penetration testers who need to interact with websites protected by anti-bot services but run legitimate traffic from residential IPs. Bot developers and security researchers testing bot-detection effectiveness also use it.

Actively maintained but single-maintainer (github.com/ultrafunkamsterdam). The project has substantial usage (visible from GitHub stars context) and explicitly supports Chrome versions up to beta. Recent changes (v3.5.0 pins Selenium 4.9+, v3.4.5 fixed OS-specific automation detection) show ongoing bug fixes. CI is configured (.github/workflows/workflow.yml exists) suggesting some test automation, but no comprehensive test suite is visible in the file list.

High single-maintainer risk with issue tracker abuse noted in README. The core functionality depends on binary patching (undetected_chromedriver/patcher.py), which is fragile—Chrome updates can break the patch without warning. No visible dependency lock file suggests version conflicts are possible. The project explicitly warns it does NOT mask IP reputation, so datacenter IPs will fail regardless of the patch quality.

v3.5.0 was recently released addressing Selenium 4.10 compatibility issues and pinning to 4.9+; deprecated service_args/service_creationflags/service_log_path kwargs. v3.4.5 fixed OS-specific automation detection regressions. The project moved issue tracking to Discussions (GitHub discussions) to manage abuse. No visible PR queue or open milestone data in provided files.

git clone https://github.com/ultrafunkamsterdam/undetected-chromedriver.git && cd undetected-chromedriver && pip install -e . (or pip install undetected-chromedriver from PyPI). Then run: python example/example.py to verify.

Daily commands: No standalone dev server. To test locally: (1) python -m pytest example/test_workflow.py (if pytest configured), or (2) python example/example.py to see integration test. The library is imported and used in user scripts, not run directly.

• undetected_chromedriver/__init__.py — Main entry point exposing the core Chrome driver API; all consumer code imports from here
• undetected_chromedriver/patcher.py — Core patching logic that modifies the Chrome binary to evade bot detection; the heart of this project's value
• undetected_chromedriver/dprocess.py — Manages the Chrome process lifecycle and communication; required to understand driver initialization
• undetected_chromedriver/cdp.py — Chrome DevTools Protocol client; handles low-level browser automation and communication
• undetected_chromedriver/reactor.py — Event loop and message reactor for async communication with Chrome; critical for concurrent operations
• undetected_chromedriver/options.py — Configuration object that wraps Selenium ChromeOptions; necessary for customizing driver behavior
• setup.py — Package metadata and dependencies; defines what gets installed and how the module is distributed

• Patcher (urllib, binary manipulation, file I/O) — Downloads correct Chrome version, applies binary patches to remove detection signatures, manages cache
  • Failure mode: If patching fails or binary is corrupted, driver will not launch or will be detected
• DProcess (subprocess, signal handling, OS-specific process management) — Spawns and manages Chrome subprocess lifecycle, handles process cleanup and restart logic
  • Failure mode: If process crashes or hangs, automation stops; zombie processes may accumulate if cleanup fails
• Reactor (asyncio-like custom event loop, WebSocket messaging) — Runs async message loop, dispatches CDP protocol messages, handles event ordering and timeouts
  • Failure mode: If reactor deadlocks or loses sync with browser, commands hang or return stale data
• CDP Client (JSON serialization, WebSocket client) — Encodes/decodes Chrome DevTools Protocol messages, maintains RPC-style command/response matching
  • Failure mode: Malformed CDP messages or lost message IDs cause commands to fail silently or timeout
• Chrome API (Public Interface) (Selenium WebDriver, custom wrappers) — Orchestrates initialization, exposes Selenium-compatible WebDriver API, manages session state
  • Failure mode: Initialization errors prevent driver creation; API misuse (e.g., using after quit) raises exceptions

• User Code → Chrome API — User instantiates Chrome() and calls methods (get, find_element, execute_script)
• Chrome API → Patcher — During init, Chrome requests patched binary; Patcher downloads and caches it
• Chrome API → DProcess — Chrome spawns subprocess with patched binary and start flags
• DProcess → Browser — Process launches Chrome with modified binary and listens for CDP connection
• Chrome API → Reactor — Chrome queues commands (navigate, click, script) as CDP messages
• Reactor → CDP Client — Reactor encodes messages and sends them over WebSocket to browser
• CDP Client → Browser — CDP messages execute actions (page navigation, element interaction, JavaScript evaluation)
• Browser → CDP Client — Browser sends back event streams and command results (e.g., page load events, element properties)
• CDP Client → Reactor — Reactor receives and queues event messages
• Reactor → Chrome API — Reactor delivers

Add a new Chrome launch option

1. Open undetected_chromedriver/options.py and add a new property or method to the Options class that wraps Selenium's ChromeOptions (undetected_chromedriver/options.py)
2. Ensure the option is applied when the driver initializes in init.py by passing it through the Options object (undetected_chromedriver/__init__.py)

Add a new stealth patch or detection evasion technique

1. Modify undetected_chromedriver/patcher.py and add a new patching function in the Patcher class that modifies the Chrome binary or injects JavaScript (undetected_chromedriver/patcher.py)
2. Call the new patch function from the main patch() method or from init.py during driver initialization (undetected_chromedriver/__init__.py)
3. Test the patch with example/test_workflow.py to verify bot detection bypass still works (example/test_workflow.py)

Add a new async communication handler

1. Add a new message handler or protocol command in undetected_chromedriver/cdp.py or undetected_chromedriver/reactor.py (undetected_chromedriver/reactor.py)
2. Expose the handler through the Chrome class in init.py if it should be part of the public API (undetected_chromedriver/__init__.py)

• Selenium WebDriver — Provides standardized browser automation API; undetected-chromedriver is a drop-in replacement with patching applied
• Chrome DevTools Protocol (CDP) — Direct low-level control over Chrome internals; enables fine-grained stealth modifications and event-based communication
• Binary patching — Modifies Chrome executable before launch to remove bot-detection signatures; more effective than runtime JS injection alone
• Async reactor pattern — Handles asynchronous CDP messages and browser events without blocking; critical for responsive multi-tab automation

• Patch Chrome binary at runtime rather than use pre-built patched versions

  • Why: Ensures compatibility with any Chrome version; automatically downloads the correct binary
  • Consequence: Slower first initialization (~2–5s for download + patch); ties the module to having write access to disk

• Custom async reactor instead of using standard asyncio event loop

  • Why: Tighter integration with CDP protocol; full control over message ordering and timing
  • Consequence: Custom event handling code is harder to integrate with other async libraries; potential scheduling edge cases

• Expose Selenium WebDriver API rather than custom browser abstraction

  • Why: Minimal learning curve; drop-in replacement for existing Selenium code
  • Consequence: Limited to Selenium's capabilities; harder to expose Chrome-specific advanced features

• Does not hide the user's IP address or provide proxy functionality
• Does not handle authentication, cookies, or session persistence beyond Selenium's standard support
• Not a cloud-based or SaaS service; runs locally on the user's machine
• Does not guarantee evasion of all current or future bot detection systems; anti-detection is an arms race

1. Patching is version-specific: Chrome updates can silently break the patch; no auto-detection of incompatibility. 2. Binary patching is fragile—modifying patcher.py without deep ChromeDriver binary knowledge will likely break it. 3. IP reputation is NOT handled—datacenter/VPN IPs will be detected by anti-bot services regardless of automation masking. 4. Subprocess isolation (use_subprocess parameter) changes behavior significantly but is not well-documented in the provided files. 5. No explicit Python version pins despite claiming Python 3.6+ support; asyncio and subprocess behavior differs across 3.6–3.11.

• ChromeDriver Binary Patching — The core technique in this repo: modifying the compiled ChromeDriver binary to remove or obfuscate automation detection signatures before runtime. Understanding memory patching and binary offsets is critical to contributing to patcher.py.
• Chrome DevTools Protocol (CDP) — Used in cdp.py to communicate with the Chrome instance at a lower level than Selenium's WebDriver protocol, enabling fine-grained control for evasion techniques.
• Subprocess Isolation — dprocess.py spawns ChromeDriver in a separate process to prevent parent process footprints from leaking into the browser; essential for complete automation masking.
• Bot Detection Fingerprinting — Anti-bot services detect automation by reading navigator properties, WebDriver flags, and timing anomalies. This repo masks those signals; understanding common detection vectors helps prioritize patches.
• Monkey Patching — webelement.py extends Selenium's WebElement class at runtime; this Python pattern allows adding methods without forking Selenium, keeping the library lightweight.
• Async/Await Reactor Pattern — reactor.py likely implements async orchestration of driver startup and patching; understanding async Python is needed to modify startup behavior without race conditions.
• User-Agent and Header Spoofing — options.py likely manages headers and user-agent strings to mimic real browsers; anti-bot systems flag non-standard or outdated headers, so this is a first line of evasion.

• SeleniumHQ/selenium — The upstream WebDriver library that undetected-chromedriver patches and extends; understanding Selenium's Chrome class is essential.
• puppeteer/puppeteer — Alternative browser automation framework (Node.js-based) with similar anti-bot evasion challenges; sometimes used as a reference for detection vectors.
• scrapy/scrapy — Popular web scraping framework that often pairs with undetected-chromedriver for large-scale bot-protected site crawling.
• n0trace/n0trace — Similar Chromedriver patching tool for anti-bot evasion; direct competitor with different patching approach.
• MeiK2333/pyppeteer — Python port of Puppeteer; another way to automate Chrome with some built-in evasion techniques, often compared against undetected-chromedriver.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for patcher.py module

The patcher.py is a critical component that patches the Chrome binary to evade bot detection, but there are no visible test files for this core functionality. Adding tests would ensure patching logic works correctly across different Chrome versions and prevent regressions when maintaining anti-detection techniques.

• [ ] Create tests/test_patcher.py with unit tests for patching logic
• [ ] Test binary patching operations in patcher.py (injection points, signature modifications)
• [ ] Add tests for version detection and compatibility checks
• [ ] Include edge cases: missing binary, corrupted binary, unsupported Chrome versions
• [ ] Run tests in workflow.yml to catch breaking changes early

Add integration tests in test_workflow.py for bot detection evasion

The example/test_workflow.py file exists but appears minimal. Given this library's core purpose (bypassing anti-bot systems), there should be concrete integration tests that verify detection evasion still works against real services like Cloudflare, Datadome, etc. This would catch when Chrome updates break the evasion techniques.

• [ ] Expand example/test_workflow.py with integration tests against public test targets
• [ ] Add tests that verify webdriver property is hidden (navigator.webdriver === undefined)
• [ ] Add tests that verify Chrome DevTools Protocol markers are not exposed
• [ ] Include tests for different browser options from undetected_chromedriver/options.py
• [ ] Document which services are tested and add CI caching for test results

Refactor and document the reactor.py and cdp.py modules with type hints and docstrings

The reactor.py and cdp.py files handle Chrome DevTools Protocol communication, which is complex. These modules lack visible documentation and type hints, making it hard for contributors to understand the architecture. Adding comprehensive docstrings and type annotations would improve maintainability and help new contributors understand the bot-detection-evasion techniques being used.

• [ ] Add type hints to function signatures in undetected_chromedriver/cdp.py (use typing module, Python 3.6+ compatible)
• [ ] Add type hints to function signatures in undetected_chromedriver/reactor.py
• [ ] Write module-level docstrings explaining the CDP communication flow
• [ ] Document key methods that modify Chrome behavior for evasion (e.g., how stealth features are applied)
• [ ] Update README.md with an architecture section explaining reactor.py and cdp.py roles

• Add integration tests for each bot-detection platform (Distill, Imperva, DataDome) in example/test_workflow.py to validate that the patch actually defeats each system; currently no test names or assertions visible.
• Document the binary patching algorithm in patcher.py with inline comments and a README section explaining which ChromeDriver offsets are patched and why—crucial for long-term maintainability.
• Implement version compatibility matrix: add logic to undetected_chromedriver/init.py to warn or auto-detect when the installed Chrome version is incompatible with the pre-built patch, then suggest an update.

The undetected-chromedriver project has significant security considerations due to its core functionality of patching binary executables to bypass bot detection. Key concerns include: (1) Lack of visible cryptographic verification for downloaded/patched binaries, (2) Potential process injection and command execution vulnerabilities in driver spawning, (3) Unverified dependency versions, (4) Insecure file operations handling, and (5) Missing security warnings for end users. The tool's purpose of bypassing security systems inherently carries ethical and legal risks that need documentation. Critical remediation should focus on binary integrity verification and process spawning safety. The project would benefit from comprehensive security auditing and dependency

• High · Automatic Binary Patching Without Integrity Verification — undetected_chromedriver/patcher.py, undetected_chromedriver/__init__.py. The project automatically downloads and patches ChromeDriver binaries. The patcher.py module likely modifies the driver executable to bypass bot detection. This introduces risks: (1) No apparent cryptographic signature verification of downloaded binaries, (2) Patched binaries could be intercepted or tampered with during download, (3) Security updates from Chrome may be bypassed by the patching process. Fix: Implement cryptographic signature verification for downloaded binaries. Use HTTPS with certificate pinning. Verify binary checksums against official Chrome releases. Maintain signed releases of patches. Document the patching mechanism's security implications.
• High · Potential Process Injection and Unvalidated Command Execution — undetected_chromedriver/dprocess.py, undetected_chromedriver/reactor.py. The dprocess.py module likely handles Chrome process spawning. Risk of code injection through command-line arguments or environment variables if user input is not properly sanitized. The reactor.py may execute dynamic code or subprocess commands without adequate validation. Fix: Avoid shell=True in subprocess calls. Use argument arrays instead of string concatenation. Validate and sanitize all user-supplied parameters before passing to process creation. Use allowlists for acceptable options.
• Medium · Insecure Direct Object References via CDP — undetected_chromedriver/cdp.py. The cdp.py (Chrome DevTools Protocol) module may expose low-level browser automation capabilities. Improper access controls could allow unauthorized manipulation of the browser context, cookies, or sensitive data. Fix: Implement access control layers around CDP. Restrict sensitive operations (cookie manipulation, navigation to untrusted sites). Log all CDP operations. Validate all CDP command parameters.
• Medium · No Dependency File Provided - Cannot Verify Package Versions — setup.py, requirements.txt (if exists). No requirements.txt, setup.py dependencies, or poetry.lock file content was provided. Unable to verify if known vulnerable versions of Selenium or other dependencies are used. The setup.py exists but content not provided for analysis. Fix: Provide complete dependency specifications with pinned versions. Use tools like pip-audit or safety to check for known vulnerabilities. Implement automated dependency scanning in CI/CD pipeline.
• Medium · Potential Uncontrolled File Operations — undetected_chromedriver/patcher.py. The patcher downloads and modifies binary files. No visibility into file permission handling, temporary file cleanup, or directory traversal protections. Could lead to privilege escalation or information disclosure. Fix: Use secure temporary directories (tempfile.TemporaryDirectory with context managers). Set restrictive file permissions (0o600). Validate all file paths to prevent directory traversal. Implement secure cleanup of temporary files.
• Low · Missing Security Headers and Documentation — README.md. README lacks security warnings about the bot-detection bypass nature of the tool. Users installing this may not understand the legal/ethical implications or security trade-offs. Fix: Add clear security and legal disclaimers. Document intended use cases. Warn about potential abuse scenarios. Explain the patching mechanism's security model.
• Low · GitHub Actions Workflow Not Visible — .github/workflows/workflow.yml. workflow.yml exists but content not provided. Cannot verify if CI/CD pipeline has security controls, secret management, or code signing. Fix: Implement code signing for releases. Use GitHub Secrets properly (never log secrets). Run security scanners in CI/CD. Verify dependency integrity in workflows.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.