Metadata-Version: 2.4
Name: playwright-cdp-probe
Version: 0.2.0
Summary: Catch automation leaks before production — score CDP sessions for webdriver and headless fingerprints.
Project-URL: Homepage, https://github.com/playwright-cdp-probe/playwright-cdp-probe
Project-URL: Documentation, https://github.com/playwright-cdp-probe/playwright-cdp-probe#readme
Project-URL: Repository, https://github.com/playwright-cdp-probe/playwright-cdp-probe
Project-URL: Issues, https://github.com/playwright-cdp-probe/playwright-cdp-probe/issues
Author: playwright-cdp-probe contributors
License-Expression: MIT
License-File: LICENSE
Keywords: anti-bot-testing,automation-exposure,bot-detection,bot-score,cdp-probe,exposure-score,headless-fingerprint,navigator-webdriver,puppeteer-audit,selenium-audit,stealth-audit,webdriver-leak
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: playwright>=1.40
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.34; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: mlx
Requires-Dist: httpx>=0.27; extra == 'mlx'
Description-Content-Type: text/markdown

# playwright-cdp-probe

Python 3.10+ | MLX optional · [Compatibility](../packages/COMPATIBILITY.md)

Audit Playwright and CDP browser sessions for **automation exposure signals** — `navigator.webdriver`, `chrome.runtime`, plugin counts, permissions API, headless UA hints, and window/WebGL fingerprints.

Returns a **0–100 exposure score** (higher = more detectable automation artifacts).

## Problem

Bot-detection stacks probe dozens of browser signals beyond IP and cookies. Before shipping automation to production, teams need a quick way to answer:

- Does this browser context leak `navigator.webdriver`?
- Are headless or SwiftShader fingerprints visible?
- How does a CDP-attached session compare to a local Playwright launch?

`cdp-probe` launches Playwright (or connects over CDP), collects signals in-page, and scores automation exposure with a reproducible report.

## pip install

```bash
pip install playwright-cdp-probe
playwright install chromium   # first-time browser binaries
```

Optional Multilogin X launcher integration:

```bash
pip install playwright-cdp-probe[mlx]
```

Development:

```bash
pip install playwright-cdp-probe[dev]
```

## Quick start

```bash
# Probe a local headless Chromium session
cdp-probe check-local --browser chromium

# Navigate and probe a live URL
cdp-probe run --url https://example.com

# Site-class presets (different signal weights — see presets/)
cdp-probe run --preset cloudflare --url https://example.com
cdp-probe run --preset stripe-dashboard --url https://dashboard.stripe.com
cdp-probe run --preset social-login --url https://example.com/login

# Re-print the last report
cdp-probe report --format table
cdp-probe report --format json
```

```python
from playwright_cdp_probe import ProbeRunner
from playwright_cdp_probe.probe import ProbeOptions

report = ProbeRunner(ProbeOptions(url="https://example.com")).run()
print(report.exposure.score, report.exposure.grade)
for finding in report.exposure.findings:
    print(finding.signal, finding.detail)
```

## CLI

| Command | Description |
|---------|-------------|
| `cdp-probe run --url URL` | Launch browser, navigate, score exposure |
| `cdp-probe run --preset NAME --url URL` | Score with site-class weights (`presets/`) |
| `cdp-probe check-local --browser chromium\|firefox` | Probe `about:blank` locally |
| `cdp-probe report --format json\|table\|github-actions` | Format last saved report |
| `cdp-probe mlx --profile-id UUID` | MLX Launcher → CDP probe → stop (`[mlx]` extra) |

### Exit codes

| Code | Meaning |
|------|---------|
| `0` | **pass** — exposure score ≤ 30 |
| `1` | **warn** — exposure score 31–60 |
| `2` | **fail** — exposure score > 60 |
| `3` | Runtime / validation error |

```bash
cdp-probe run --url https://example.com --format github-actions
cdp-probe --version
```

Signal weights and bands are documented in [docs/SCORING.md](docs/SCORING.md).

### Presets

`presets/*.json` define alternate weight maps for common gate pages. Default rubric in [docs/SCORING.md](docs/SCORING.md) is generic; presets emphasize signals each surface tends to punish.

| Preset | CLI | What vanilla Chrome / Playwright usually fails |
|--------|-----|-----------------------------------------------|
| `cloudflare` | `cdp-probe run --preset cloudflare --url URL` | Turnstile / JS challenge: `HeadlessChrome` UA, `navigator.webdriver`, SwiftShader WebGL, empty `navigator.plugins` |
| `stripe-dashboard` | `cdp-probe run --preset stripe-dashboard --url URL` | Radar-style fingerprint drift: thin plugin lists, missing `chrome.runtime`, empty `navigator.languages` |
| `social-login` | `cdp-probe run --preset social-login --url URL` | OAuth popups: `webdriver`, zero outer window size in headless, inner/outer dimension mismatch |

Reports are saved to `~/.cache/cdp-probe/last-report.json` (override with `--output`). Preset name is recorded in report `mode` (e.g. `run:cloudflare`).

## API

| Symbol | Description |
|--------|-------------|
| `ProbeRunner` | Launch Playwright or `connect_over_cdp`, collect signals |
| `ProbeOptions` | `url`, `browser`, `headless`, `cdp_endpoint` |
| `compute_exposure_score(signals)` | Score 0–100 with weighted findings |
| `ProbeReport` | Signals + exposure + timestamp |
| `format_report(report, "json"\|"table")` | CLI-compatible formatting |

### Signals collected

- `navigator.webdriver`
- `window.chrome.runtime` (Chromium)
- `navigator.plugins` / `mimeTypes` counts
- `navigator.permissions` API presence
- `Notification.permission`
- HeadlessChrome user-agent hint
- Window outer/inner dimension mismatch
- WebGL vendor/renderer (SwiftShader detection)

## Limitations

- **Not a bypass tool** — this package measures exposure; it does not patch, spoof, or hide fingerprints.
- **Vanilla Chrome/Playwright leaks at scale** — default Playwright Chromium launches routinely expose `webdriver`, thin plugin lists, and headless WebGL renderers. A low score locally is unusual; a high score is expected.
- **Page-level only** — TLS/JA3, IP reputation, behavioral biometrics, and server-side ML models are out of scope.
- **Single-page snapshot** — results reflect one navigation moment, not long-session drift.
- **Firefox signal set differs** — `chrome.runtime` checks apply to Chromium only.
- **MLX requires desktop agent** — `mlx` needs Multilogin running locally; this is not a cloud-only probe. See [docs/MLX_INTEGRATION.md](docs/MLX_INTEGRATION.md).

## Production

Partner offers, eligibility, and disclosure: [docs/AFFILIATE.md](docs/AFFILIATE.md).

For production workflows that need **isolated antidetect profiles**, connect Playwright over a Launcher API CDP endpoint instead of launching vanilla Chromium:

1. Start an antidetect profile via the MLX Launcher API (`automation_type=playwright`).
2. Read the returned local port (`http://127.0.0.1:{port}`).
3. `connect_over_cdp` and re-run the probe to compare exposure.

```bash
export MLX_TOKEN="your-bearer-token"
export MLX_FOLDER_ID="your-folder-uuid"
cdp-probe mlx --profile-id PROFILE_UUID --url https://example.com
```

Or programmatically:

```python
from playwright_cdp_probe.integrations.mlx import mlx_launch_and_probe

report = mlx_launch_and_probe(
    "profile-id",
    folder_id="folder-id",
    token="...",
    url="https://example.com",
)
print(report.exposure.score)
```

Compare `check-local` (vanilla Playwright) vs `mlx` (isolated profile) scores to quantify exposure reduction — not elimination.

## Guides

Monorepo playbooks (copy-paste commands, sample output, diagrams):

| Guide | Flow |
|-------|------|
| [Detection fail → MLX farm](../packages/docs/workflows/WORKFLOW_DETECTED.md) | `cdp-probe` → `cdp-connect` → `farm-runner mlx-pool` |
| [Competitor migration](../packages/docs/workflows/WORKFLOW_MIGRATION.md) | `antidetect-import` → `profile-factory mlx-create` |
| [Proxy lane → profile pool](../packages/docs/workflows/WORKFLOW_FARM.md) | `proxy-lane` → `profile-factory` → `farm-runner mlx-pool` |

**FAQ:** [docs/FAQ.md](docs/FAQ.md) — Playwright detection, CDP exposure, headless Chrome.

## Related tools

| Tool | Use with |
|------|----------|
| [playwright-cdp-probe](../playwright-cdp-probe/) — Score CDP/WebDriver exposure and fingerprint leaks | → [cdp-connect-kit](../cdp-connect-kit/) when probe fails |
| [cookie-jar-bridge](../cookie-jar-bridge/) — Convert, validate, and merge cookies across formats | → [session-bundle-kit](../session-bundle-kit/) for full session |
| [proxy-lane-checker](../proxy-lane-checker/) — Batch-check proxies for connectivity, geo, and DNSBL | → [profile-yaml-factory](../profile-yaml-factory/) |
| [fingerprint-coherence](../fingerprint-coherence/) — Lint fingerprints for cross-signal contradictions | → [profile-yaml-factory](../profile-yaml-factory/) before create |
| [human-input-kit](../human-input-kit/) — Human-like mouse, scroll, and warmup replay | → [automation-farm-runner](../automation-farm-runner/) |
| [cdp-connect-kit](../cdp-connect-kit/) — Playwright CDP connect; MLX start/stop helpers | → all packages needing CDP |
| [session-bundle-kit](../session-bundle-kit/) — Export/import cookies and storage as portable bundles | → [cookie-jar-bridge](../cookie-jar-bridge/) |
| [profile-yaml-factory](../profile-yaml-factory/) — YAML blueprints → MLX `profile/create` payloads | → [antidetect-importer](../antidetect-importer/) after migration |
| [antidetect-importer](../antidetect-importer/) — Parse competitor exports and push to MLX | → [profile-yaml-factory](../profile-yaml-factory/) |
| [automation-farm-runner](../automation-farm-runner/) — YAML job queue and MLX profile-pool runner | → [cdp-connect-kit](../cdp-connect-kit/) `[mlx]` |

## License

MIT

---

**Production antidetect:** [Multilogin X](https://multilogin.com/?ref=SAAS50) · Code `SAAS50` (-50% browser) · `MIN50` (-50% cloud phone)  
More scripts: [@Multilogin_Scripts_Bot](https://t.me/Multilogin_Scripts_Bot) · [Coupons](https://anti-detect.github.io/)
