# Sample per-vendor wrappers for the betterbrowsing-tester skill

Drop-in templates for taking the canonical probes (`../probe.sh`,
`../probe_browser.py`) and deploying them against a specific vendor's
proxy / browser-automation zone. Copy this directory into your own
project (e.g. `<vendor>/scripts/skill/`) and customize the
vendor-specific bits. The canonical probes are vendor-neutral and stay
untouched.

This template is shape-compatible with the per-vendor wrappers in the
companion [proxytest](https://github.com/AppEsteem/proxytest) framework —
if you already have `_auth.sh` for proxytest's access/bypass/protection
buckets, you can reuse it here verbatim. The two wrappers in this
directory are the bucket-(b) ("behavior") equivalents of proxytest's
`run_access.sh` / `run_bypass.sh` / `run_protection.sh`.

## What to customize

Each template has comments marking the vendor-specific slots. The set
of slots a new vendor needs to fill:

| Slot | What | Where |
|---|---|---|
| Credentials | username / password / customer-id / API token | `_auth.sh` |
| Connection hosts and ports | residential-proxy endpoint, browser-zone CDP endpoint | `_auth.sh` |
| Country modifier syntax | how the vendor injects `cc` into the proxy URL (some put it as a `-country-XX` modifier in the user portion; others use a query param, a separate session arg, dashboard config, etc.) | `_auth.sh` — inside the URL-building functions |
| MITM root CA path (optional) | if the vendor re-signs HTTPS at the residential-proxy zone and exposes a root CA | `_auth.sh` — `VENDOR_CACERT` |

## Files in this template

| File | Purpose |
|---|---|
| `_auth.sh` | Sourced by `run_*.sh`. Exports credentials and helper functions `vendor_proxy_url`, `vendor_cdp_url`. |
| `run_probe.sh` | Wraps `../probe.sh` (HTTP-level probe) with vendor URL building + country iteration. |
| `run_probe_browser.sh` | Wraps `../probe_browser.py` (Playwright probe). Prefers the vendor's CDP browser zone if `vendor_cdp_url` is defined; falls back to local Chromium + `--proxy "$(vendor_proxy_url)"` otherwise. |

The names `vendor_proxy_url` / `vendor_cdp_url` are placeholders — feel
free to rename to `<vendorname>_proxy_url` (e.g. `oxylabs_proxy_url`)
when you copy.

## What each wrapper does

`run_X.sh` always does:

1. Source `_auth.sh` for credentials and URL-builder functions.
2. Iterate over `--countries` (default: `us`).
3. For each country, call the canonical `../probe.sh` with `--proxy
   $(vendor_proxy_url $cc)` (and `--cacert $VENDOR_CACERT` if set), or
   `../probe_browser.py` with `--cdp $(vendor_cdp_url $cc)`.
4. Write evidence to `../runs/<yymmdd>/evidence/<country>/`.

## Direct baseline

These wrappers do NOT run the direct baseline — same convention as
proxytest. Run the canonical probes without `--proxy` / `--cdp` first to
establish ground truth, then run the wrappers for proxied comparison:

```sh
# Direct baseline (no vendor)
mkdir -p runs/<yymmdd>/evidence/direct
../probe.sh > runs/<yymmdd>/evidence/direct/probe_curl.txt
python3 ../probe_browser.py --json > runs/<yymmdd>/evidence/direct/probe_browser.json

# Then through the vendor
./run_probe.sh --countries us --run-date <yymmdd>
./run_probe_browser.sh --countries us --run-date <yymmdd>

# Diff
diff runs/<yymmdd>/evidence/direct/probe_curl.txt runs/<yymmdd>/evidence/us/probe_curl.txt
diff runs/<yymmdd>/evidence/direct/probe_browser.json runs/<yymmdd>/evidence/us/probe_browser.json
```

The diff is the finding.

## MITM root CA — what `--cacert` actually does

- **`probe.sh --cacert PATH`** forwards to `curl --cacert PATH` — strict
  pinning to that CA. If the vendor's chain doesn't validate against it,
  the request fails.
- **`probe_browser.py --cacert PATH`** sets `ignore_https_errors=True` on
  the Playwright browser context. The synthetic chain is accepted but
  not pinned to the supplied CA. This is the standard Playwright pattern
  for MITM proxies; tighten with `--ignore-certificate-errors-spki-list`
  or a custom NSS db if your evaluation requires strict pinning.
- **CDP mode** does not need `--cacert` — the vendor's hosted browser
  already trusts the vendor's CA.