Metadata-Version: 2.4
Name: proxyprobe
Version: 0.1.1
Summary: Check a list of proxies for liveness, latency, exit IP and anonymity.
Author-email: Roam <dev@roamproxy.com>
License: MIT
Project-URL: Homepage, https://github.com/roamproxy/proxyprobe
Project-URL: Issues, https://github.com/roamproxy/proxyprobe/issues
Project-URL: Website, https://roamproxy.com
Keywords: proxy,proxies,proxy-checker,socks5,anonymity,scraping
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx[socks]>=0.24
Dynamic: license-file

# proxyprobe

Check a list of proxies for **liveness, latency, exit IP and anonymity** — one file, one dependency.

```console
$ proxyprobe proxies.txt --geo
PROXY                              OK   MS    EXIT IP          ANONYMITY    LOCATION        ERROR
---------------------------------  ---  ----  ---------------  -----------  --------------  ---------------------
http://user:***@gw.example.com:80  yes  312   203.0.113.44     elite        Tokyo Japan
socks5://198.51.100.7:1080         yes  1180  198.51.100.7     transparent  Frankfurt Germany
http://10.0.0.9:3128               no   -     -                -                            ConnectTimeout: timed out

2/3 working  |  312ms median  |  1 elite, 1 transparent
```

Most "proxy checker" scripts only tell you whether a connection opened. That is the
least interesting thing about a proxy. proxyprobe also answers the questions that
actually decide whether a proxy is usable:

- **Does it leak my real IP?** Graded `transparent` / `anonymous` / `elite` by comparing
  your direct IP against what the proxy forwards, and by inspecting `Via`,
  `X-Forwarded-For` and friends.
- **Where does it actually exit?** The advertised location and the real one often differ.
- **How slow is it really?** Measured on a full request, not a TCP handshake.

## Install

```bash
pip install "httpx[socks]"
curl -O https://raw.githubusercontent.com/roamproxy/proxyprobe/main/proxyprobe.py
python proxyprobe.py proxies.txt
```

It is a single file with no packaging required. Drop it in a repo, a container, or a
CI job and run it.

## Usage

```bash
proxyprobe proxies.txt                 # table output
proxyprobe proxies.txt --json          # machine readable
proxyprobe proxies.txt --geo           # add country/city
proxyprobe proxies.txt --working-only  # drop the dead ones
cat proxies.txt | proxyprobe -         # read stdin
proxyprobe proxies.txt -c 100 -t 5     # 100 in parallel, 5s timeout
```

Proxy list format — one per line, `#` comments and blank lines ignored:

```
http://user:pass@host:8080
socks5://host:1080
host:8080                 # scheme defaults to http
```

### Options

| Flag | Description |
| --- | --- |
| `-c, --concurrency` | Parallel checks (default 20) |
| `-t, --timeout` | Per-request timeout in seconds (default 10) |
| `--json` | JSON instead of a table |
| `--geo` | Look up country/city (rate limited, so opt-in) |
| `--working-only` | Only output proxies that responded |
| `--echo-url` | IP echo endpoint (default `api.ipify.org`) |
| `--headers-url` | Header echo endpoint used for anonymity grading |
| `--geo-url` | Geo lookup template, must contain `{ip}` |
| `-q, --quiet` | Suppress the progress counter |

Exit code is `0` if at least one proxy worked, `1` if none did — so it drops straight
into CI or a shell pipeline:

```bash
proxyprobe proxies.txt --working-only --json > alive.json || echo "all proxies down"
```

## Anonymity grades

| Grade | Meaning |
| --- | --- |
| `elite` | Request looks like an ordinary direct request |
| `anonymous` | Real IP hidden, but headers announce a proxy is in use |
| `transparent` | Your real IP is visible through the proxy |

Grading needs a baseline, so proxyprobe first fetches your direct IP once. If that
fails it degrades safely: a proxy is never labelled `transparent` without a baseline
to compare against.

## Passwords are masked

Credentials are stripped from every output path, so results are safe to paste into an
issue or a CI log:

```
http://user:hunter2@host:80   ->   http://user:***@host:80
```

Passwords containing `@` and `:` are handled correctly.

## Privacy

By default proxyprobe talks to `api.ipify.org` (IP echo), `httpbin.org` (header echo)
and, only with `--geo`, `ip-api.com`. All three are overridable — point them at your
own endpoints if you would rather not route a proxy list through third parties:

```bash
proxyprobe proxies.txt --echo-url https://your-host/ip --headers-url https://your-host/headers
```

Nothing else is sent anywhere. There is no telemetry.

## Development

```bash
pip install "httpx[socks]" pytest
pytest -q
```

## License

MIT — see [LICENSE](LICENSE).

---

Maintained by [Roam](https://roamproxy.com), a residential and datacenter proxy
provider. proxyprobe works with any proxy from any provider, and always will —
we built it because we needed it ourselves.
