sherlock-proxyhat 0.1.0__tar.gz

sherlock_proxyhat-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      # Tests fake the `sherlock` executable and subprocess, so [dev] alone
+      # (no sherlock-project install) is enough.
+      - run: pip install -e ".[dev]"
+      - run: pytest -v
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+
+  publish:
+    needs: [lint, test, build]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

sherlock_proxyhat-0.1.0/.github/workflows/compat.yml

@@ -0,0 +1,58 @@
+name: Compat (sherlock-project latest)
+
+# Autonomy watchdog: weekly (and on demand) it installs the newest sherlock-project
+# and our newest proxyhat SDK, then checks that Sherlock still exposes the `--proxy`
+# flag this launcher depends on, and runs our tests. A red run means upstream
+# changed the proxy CLI surface — it opens/updates a tracking issue so we notice
+# before users do. The proactive path is Renovate (renovate.json), which opens a
+# version-bump PR that must pass CI before merging.
+on:
+  schedule:
+    - cron: "0 6 * * 1" # Mondays 06:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  compat:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - name: Install latest upstreams
+        run: pip install --upgrade sherlock-project proxyhat
+      - name: Assert Sherlock still accepts --proxy
+        # This launcher forwards a residential proxy URL via `sherlock --proxy <url>`.
+        # Fail loudly if that flag ever disappears or is renamed.
+        run: |
+          sherlock --help 2>&1 | grep -- '--proxy' \
+            || { echo "sherlock no longer advertises a --proxy flag"; exit 1; }
+          echo "sherlock --proxy surface OK"
+      - run: pytest -v
+      - name: Open an issue on failure
+        if: failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const title = "Compat break: sherlock-project@latest / proxyhat@latest";
+            const { data: issues } = await github.rest.issues.listForRepo({
+              owner: context.repo.owner, repo: context.repo.repo,
+              state: "open", labels: "compat",
+            });
+            const body = `The weekly compatibility check failed against the latest upstream releases.\n\nRun: ${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`;
+            if (issues.length === 0) {
+              await github.rest.issues.create({
+                owner: context.repo.owner, repo: context.repo.repo,
+                title, body, labels: ["compat"],
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner, repo: context.repo.repo,
+                issue_number: issues[0].number, body,
+              });
+            }

sherlock_proxyhat-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/

sherlock_proxyhat-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProxyHat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sherlock_proxyhat-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: sherlock-proxyhat
+Version: 0.1.0
+Summary: Run the Sherlock OSINT username hunter through ProxyHat residential proxies — rotating IPs, geo-targeting, fewer blocks.
+Project-URL: Homepage, https://proxyhat.com
+Project-URL: Documentation, https://docs.proxyhat.com
+Project-URL: Repository, https://github.com/ProxyHatCom/sherlock-proxyhat
+Author-email: ProxyHat <support@proxyhat.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: osint,proxy,proxyhat,reconnaissance,residential-proxy,rotating-proxy,sherlock,username
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: Proxy Servers
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: proxyhat>=0.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: sherlock
+Requires-Dist: sherlock-project>=0.14; extra == 'sherlock'
+Description-Content-Type: text/markdown
+
+# sherlock-proxyhat
+
+Run [Sherlock](https://github.com/sherlock-project/sherlock) — the OSINT username hunter — through [ProxyHat](https://proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=sherlock) residential proxies. Rotating residential IPs by default (a fresh IP per connection across the hundreds of sites Sherlock checks), plus geo-targeting and anonymity, so you get rate-limited and blocked far less.
+
+[![CI](https://github.com/ProxyHatCom/sherlock-proxyhat/actions/workflows/ci.yml/badge.svg)](https://github.com/ProxyHatCom/sherlock-proxyhat/actions/workflows/ci.yml)
+[![Compatible with sherlock latest](https://github.com/ProxyHatCom/sherlock-proxyhat/actions/workflows/compat.yml/badge.svg)](https://github.com/ProxyHatCom/sherlock-proxyhat/actions/workflows/compat.yml)
+[![PyPI](https://img.shields.io/pypi/v/sherlock-proxyhat)](https://pypi.org/project/sherlock-proxyhat/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## What this is
+
+Sherlock is an **app**, not a library: you run `sherlock <username>` and it checks that name across 400+ sites, accepting a single `--proxy <url>` for all of them. Hammering that many sites from one datacenter IP gets throttled and blocked fast.
+
+`sherlock-proxyhat` is a **thin launcher**. It resolves a ProxyHat residential gateway URL, then runs the real `sherlock` executable with `--proxy <url>` prepended — every other argument (usernames and Sherlock's own flags) passes straight through. No fork, no patched Sherlock: it just wires ProxyHat into the `--proxy` flag Sherlock already has.
+
+## Install
+
+```bash
+pip install sherlock-proxyhat sherlock-project
+```
+
+`sherlock-project` (which provides the `sherlock` command) is an optional dependency — this launcher shells out to the `sherlock` executable, so any install works (pip, pipx, system package). To pull it in with the launcher:
+
+```bash
+pip install "sherlock-proxyhat[sherlock]"
+```
+
+## Quick start
+
+```bash
+# An API key auto-selects an active residential sub-user:
+export PROXYHAT_API_KEY=ph_xxx
+
+# Same arguments as sherlock — just run it through the launcher:
+sherlock-proxyhat johndoe
+
+# Geo-target and add sherlock's own flags; everything after is passed through:
+sherlock-proxyhat --proxyhat-country us johndoe janedoe --timeout 30 --csv
+```
+
+Get an API key at [proxyhat.com](https://proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=sherlock).
+
+Anything that isn't a `--proxyhat-*` option is forwarded to `sherlock` verbatim, so every Sherlock flag (`--timeout`, `--site`, `--nsfw`, `--csv`, `-o`, …) works unchanged.
+
+## Credentials
+
+Pass them as `--proxyhat-*` flags or via environment variables — flags win over env:
+
+| Flag | Env var | Notes |
+|---|---|---|
+| `--proxyhat-api-key` | `PROXYHAT_API_KEY` | Auto-selects an active sub-user with remaining traffic |
+| `--proxyhat-sub-user` | `PROXYHAT_SUBUSER` | Pick a specific sub-user by uuid or name (with an API key) |
+| `--proxyhat-username` | `PROXYHAT_USERNAME` | Explicit gateway `proxy_username` (skips the API) |
+| `--proxyhat-password` | `PROXYHAT_PASSWORD` | Explicit gateway `proxy_password` |
+
+## Targeting
+
+All targeting lives on `--proxyhat-*` flags, which are stripped before the command reaches `sherlock`:
+
+```bash
+sherlock-proxyhat \
+  --proxyhat-protocol http \      # or socks5
+  --proxyhat-country us \         # ISO code or "any" (default)
+  --proxyhat-region california \
+  --proxyhat-city los_angeles \
+  --proxyhat-filter high \        # AI IP-quality tier
+  johndoe
+```
+
+### Rotating IPs by default
+
+Sherlock reuses one proxy for the whole run, so this launcher builds a **rotating** gateway username by default: the ProxyHat gateway hands out a fresh residential IP on every connection, spreading the hundreds of per-site checks across many IPs — exactly what you want to dodge per-IP rate limits during a scan.
+
+Want to pin a single IP for the whole run instead? Add `--proxyhat-sticky` (optionally with a lifetime via `--proxyhat-sticky-ttl`):
+
+```bash
+sherlock-proxyhat --proxyhat-sticky johndoe               # one pinned IP, 30m default
+sherlock-proxyhat --proxyhat-sticky-ttl 2h johndoe        # one pinned IP, 2h lifetime
+```
+
+### Bring your own proxy
+
+If you pass Sherlock's own `--proxy`/`-p` (or `--tor`) yourself, the launcher steps aside: it forwards your arguments unchanged and does not inject a ProxyHat URL.
+
+## Using the URL builder directly
+
+Need the gateway URL in your own script or a different tool? Import the helper:
+
+```python
+from sherlock_proxyhat import proxyhat_proxy_url
+
+url = proxyhat_proxy_url(api_key="ph_xxx", country="us")
+# -> "http://<user>-country-us:<pass>@gate.proxyhat.com:8080"
+```
+
+Rotating by default (`sticky=None`); pass `sticky="30m"` (or `True`) to pin one IP.
+
+## How it works
+
+The launcher parses out its `--proxyhat-*` options, resolves your gateway credentials via the official [`proxyhat`](https://pypi.org/project/proxyhat/) SDK (an API key auto-picks an active sub-user, or pass `username`/`password`), and builds a connection URL carrying ProxyHat's targeting grammar (`http://<user>-country-us:<pass>@gate.proxyhat.com:8080`, or `socks5://…:1080`). It then finds the `sherlock` executable on your `PATH` and runs `sherlock --proxy <url> <your other args>` as a subprocess, returning Sherlock's exit code. A rotating username makes the gateway hand out a fresh residential IP per connection; `--proxyhat-sticky` pins one.
+
+## Roadmap
+
+This launcher wraps Sherlock's existing `--proxy` flag on purpose — it's the honest, low-friction way to ship today. A **planned follow-up** is an upstream PR to Sherlock adding a native `--proxyhat` flag (resolve credentials and geo-target from within Sherlock itself, no wrapper), so ProxyHat becomes a first-class option in the tool. Until that lands, this package is the supported path.
+
+## License
+
+MIT © [ProxyHat](https://proxyhat.com)

sherlock_proxyhat-0.1.0/README.md

@@ -0,0 +1,108 @@
+# sherlock-proxyhat
+
+Run [Sherlock](https://github.com/sherlock-project/sherlock) — the OSINT username hunter — through [ProxyHat](https://proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=sherlock) residential proxies. Rotating residential IPs by default (a fresh IP per connection across the hundreds of sites Sherlock checks), plus geo-targeting and anonymity, so you get rate-limited and blocked far less.
+
+[![CI](https://github.com/ProxyHatCom/sherlock-proxyhat/actions/workflows/ci.yml/badge.svg)](https://github.com/ProxyHatCom/sherlock-proxyhat/actions/workflows/ci.yml)
+[![Compatible with sherlock latest](https://github.com/ProxyHatCom/sherlock-proxyhat/actions/workflows/compat.yml/badge.svg)](https://github.com/ProxyHatCom/sherlock-proxyhat/actions/workflows/compat.yml)
+[![PyPI](https://img.shields.io/pypi/v/sherlock-proxyhat)](https://pypi.org/project/sherlock-proxyhat/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## What this is
+
+Sherlock is an **app**, not a library: you run `sherlock <username>` and it checks that name across 400+ sites, accepting a single `--proxy <url>` for all of them. Hammering that many sites from one datacenter IP gets throttled and blocked fast.
+
+`sherlock-proxyhat` is a **thin launcher**. It resolves a ProxyHat residential gateway URL, then runs the real `sherlock` executable with `--proxy <url>` prepended — every other argument (usernames and Sherlock's own flags) passes straight through. No fork, no patched Sherlock: it just wires ProxyHat into the `--proxy` flag Sherlock already has.
+
+## Install
+
+```bash
+pip install sherlock-proxyhat sherlock-project
+```
+
+`sherlock-project` (which provides the `sherlock` command) is an optional dependency — this launcher shells out to the `sherlock` executable, so any install works (pip, pipx, system package). To pull it in with the launcher:
+
+```bash
+pip install "sherlock-proxyhat[sherlock]"
+```
+
+## Quick start
+
+```bash
+# An API key auto-selects an active residential sub-user:
+export PROXYHAT_API_KEY=ph_xxx
+
+# Same arguments as sherlock — just run it through the launcher:
+sherlock-proxyhat johndoe
+
+# Geo-target and add sherlock's own flags; everything after is passed through:
+sherlock-proxyhat --proxyhat-country us johndoe janedoe --timeout 30 --csv
+```
+
+Get an API key at [proxyhat.com](https://proxyhat.com?utm_source=github&utm_medium=readme&utm_campaign=sherlock).
+
+Anything that isn't a `--proxyhat-*` option is forwarded to `sherlock` verbatim, so every Sherlock flag (`--timeout`, `--site`, `--nsfw`, `--csv`, `-o`, …) works unchanged.
+
+## Credentials
+
+Pass them as `--proxyhat-*` flags or via environment variables — flags win over env:
+
+| Flag | Env var | Notes |
+|---|---|---|
+| `--proxyhat-api-key` | `PROXYHAT_API_KEY` | Auto-selects an active sub-user with remaining traffic |
+| `--proxyhat-sub-user` | `PROXYHAT_SUBUSER` | Pick a specific sub-user by uuid or name (with an API key) |
+| `--proxyhat-username` | `PROXYHAT_USERNAME` | Explicit gateway `proxy_username` (skips the API) |
+| `--proxyhat-password` | `PROXYHAT_PASSWORD` | Explicit gateway `proxy_password` |
+
+## Targeting
+
+All targeting lives on `--proxyhat-*` flags, which are stripped before the command reaches `sherlock`:
+
+```bash
+sherlock-proxyhat \
+  --proxyhat-protocol http \      # or socks5
+  --proxyhat-country us \         # ISO code or "any" (default)
+  --proxyhat-region california \
+  --proxyhat-city los_angeles \
+  --proxyhat-filter high \        # AI IP-quality tier
+  johndoe
+```
+
+### Rotating IPs by default
+
+Sherlock reuses one proxy for the whole run, so this launcher builds a **rotating** gateway username by default: the ProxyHat gateway hands out a fresh residential IP on every connection, spreading the hundreds of per-site checks across many IPs — exactly what you want to dodge per-IP rate limits during a scan.
+
+Want to pin a single IP for the whole run instead? Add `--proxyhat-sticky` (optionally with a lifetime via `--proxyhat-sticky-ttl`):
+
+```bash
+sherlock-proxyhat --proxyhat-sticky johndoe               # one pinned IP, 30m default
+sherlock-proxyhat --proxyhat-sticky-ttl 2h johndoe        # one pinned IP, 2h lifetime
+```
+
+### Bring your own proxy
+
+If you pass Sherlock's own `--proxy`/`-p` (or `--tor`) yourself, the launcher steps aside: it forwards your arguments unchanged and does not inject a ProxyHat URL.
+
+## Using the URL builder directly
+
+Need the gateway URL in your own script or a different tool? Import the helper:
+
+```python
+from sherlock_proxyhat import proxyhat_proxy_url
+
+url = proxyhat_proxy_url(api_key="ph_xxx", country="us")
+# -> "http://<user>-country-us:<pass>@gate.proxyhat.com:8080"
+```
+
+Rotating by default (`sticky=None`); pass `sticky="30m"` (or `True`) to pin one IP.
+
+## How it works
+
+The launcher parses out its `--proxyhat-*` options, resolves your gateway credentials via the official [`proxyhat`](https://pypi.org/project/proxyhat/) SDK (an API key auto-picks an active sub-user, or pass `username`/`password`), and builds a connection URL carrying ProxyHat's targeting grammar (`http://<user>-country-us:<pass>@gate.proxyhat.com:8080`, or `socks5://…:1080`). It then finds the `sherlock` executable on your `PATH` and runs `sherlock --proxy <url> <your other args>` as a subprocess, returning Sherlock's exit code. A rotating username makes the gateway hand out a fresh residential IP per connection; `--proxyhat-sticky` pins one.
+
+## Roadmap
+
+This launcher wraps Sherlock's existing `--proxy` flag on purpose — it's the honest, low-friction way to ship today. A **planned follow-up** is an upstream PR to Sherlock adding a native `--proxyhat` flag (resolve credentials and geo-target from within Sherlock itself, no wrapper), so ProxyHat becomes a first-class option in the tool. Until that lands, this package is the supported path.
+
+## License
+
+MIT © [ProxyHat](https://proxyhat.com)

sherlock_proxyhat-0.1.0/examples/basic.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Minimal sherlock-proxyhat example.
+#
+#   PROXYHAT_API_KEY=ph_xxx ./examples/basic.sh johndoe
+#
+# Runs Sherlock through a US residential IP, rotating a fresh IP per connection
+# (the default) so the hundreds of per-site checks are spread across many IPs.
+set -euo pipefail
+
+USERNAME="${1:-johndoe}"
+
+# api_key defaults to $PROXYHAT_API_KEY and auto-selects an active sub-user.
+# Everything after the --proxyhat-* flags is passed straight to `sherlock`.
+sherlock-proxyhat \
+  --proxyhat-country us \
+  "$USERNAME" \
+  --timeout 30

sherlock_proxyhat-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sherlock-proxyhat"
+version = "0.1.0"
+description = "Run the Sherlock OSINT username hunter through ProxyHat residential proxies — rotating IPs, geo-targeting, fewer blocks."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "ProxyHat", email = "support@proxyhat.com" }]
+keywords = [
+    "sherlock",
+    "osint",
+    "proxy",
+    "residential-proxy",
+    "proxyhat",
+    "username",
+    "reconnaissance",
+    "rotating-proxy",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: Proxy Servers",
+    "Topic :: Security",
+]
+dependencies = ["proxyhat>=0.2.0"]
+
+[project.scripts]
+sherlock-proxyhat = "sherlock_proxyhat.cli:main"
+
+[project.urls]
+Homepage = "https://proxyhat.com"
+Documentation = "https://docs.proxyhat.com"
+Repository = "https://github.com/ProxyHatCom/sherlock-proxyhat"
+
+[project.optional-dependencies]
+# Sherlock is the app this launcher shells out to. It's optional because we call
+# the `sherlock` executable via subprocess (never import it), so you can also use
+# a sherlock installed separately (pipx, system package, etc.).
+sherlock = ["sherlock-project>=0.14"]
+dev = ["pytest>=7.0", "ruff>=0.4"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sherlock_proxyhat"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sherlock_proxyhat-0.1.0/renovate.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended", ":semanticCommits"],
+  "labels": ["dependencies"],
+  "schedule": ["before 6am on monday"],
+  "packageRules": [
+    {
+      "description": "Auto-merge dev-dependency and upstream bumps once CI (incl. compat) is green.",
+      "matchDepTypes": ["build-system.requires", "project.dependencies", "project.optional-dependencies"],
+      "automerge": true,
+      "automergeType": "pr"
+    },
+    {
+      "description": "Track the sherlock-project range but never auto-widen it silently.",
+      "matchPackageNames": ["sherlock-project"],
+      "automerge": false
+    }
+  ]
+}

sherlock_proxyhat-0.1.0/src/sherlock_proxyhat/__init__.py

@@ -0,0 +1,13 @@
+"""sherlock-proxyhat — run the Sherlock OSINT tool through ProxyHat residential proxies."""
+
+from sherlock_proxyhat._resolve import ProxyHatConfigError, resolve_credentials
+from sherlock_proxyhat.cli import build_command, main, proxyhat_proxy_url
+
+__all__ = [
+    "ProxyHatConfigError",
+    "build_command",
+    "main",
+    "proxyhat_proxy_url",
+    "resolve_credentials",
+]
+__version__ = "0.1.0"

sherlock_proxyhat-0.1.0/src/sherlock_proxyhat/_resolve.py

@@ -0,0 +1,71 @@
+"""Gateway credential resolution for sherlock-proxyhat.
+
+Mirrors the other ProxyHat integrations: explicit ``username``/``password``
+(or ``PROXYHAT_USERNAME``/``PROXYHAT_PASSWORD``) win; otherwise an API key
+(``PROXYHAT_API_KEY``) looks up your sub-users via the official ``proxyhat`` SDK
+and picks an active one with remaining traffic — or the one named by ``sub_user``.
+Everything here except the sub-user lookup is offline.
+"""
+
+from __future__ import annotations
+
+import os
+
+from proxyhat import ProxyHat
+
+
+class ProxyHatConfigError(RuntimeError):
+    """Raised when ProxyHat credentials cannot be resolved."""
+
+
+def _env(name: str) -> str | None:
+    value = os.environ.get(name)
+    return value.strip() if value and value.strip() else None
+
+
+def resolve_credentials(
+    *,
+    api_key: str | None = None,
+    username: str | None = None,
+    password: str | None = None,
+    sub_user: str | None = None,
+) -> tuple[str, str]:
+    """Resolve a sub-user's ``(proxy_username, proxy_password)``.
+
+    Options win over environment variables. Precedence:
+
+    1. explicit ``username`` + ``password`` (``PROXYHAT_USERNAME`` / ``PROXYHAT_PASSWORD``)
+    2. ``api_key`` (``PROXYHAT_API_KEY``) → auto-pick an active sub-user, or the
+       one named by ``sub_user`` (``PROXYHAT_SUBUSER``).
+    """
+    username = username or _env("PROXYHAT_USERNAME")
+    password = password or _env("PROXYHAT_PASSWORD")
+    if username and password:
+        return username, password
+
+    api_key = api_key or _env("PROXYHAT_API_KEY")
+    if not api_key:
+        raise ProxyHatConfigError(
+            "sherlock-proxyhat: no credentials. Pass --proxyhat-api-key (or PROXYHAT_API_KEY), "
+            "or --proxyhat-username + --proxyhat-password (PROXYHAT_USERNAME / PROXYHAT_PASSWORD)."
+        )
+
+    return _resolve_sub_user(api_key, sub_user or _env("PROXYHAT_SUBUSER"))
+
+
+def _resolve_sub_user(api_key: str, want: str | None) -> tuple[str, str]:
+    users = ProxyHat(api_key=api_key).sub_users.list()
+    usable = [u for u in users if not u.suspended_at and (u.traffic_limit == 0 or u.used_traffic < u.traffic_limit)]
+    if want:
+        chosen = next((u for u in users if u.uuid == want or u.name == want), None)
+    else:
+        chosen = usable[0] if usable else None
+
+    if chosen is None or not chosen.proxy_username or not chosen.proxy_password:
+        raise ProxyHatConfigError(
+            f'sherlock-proxyhat: no sub-user matched "{want}" (or it has no proxy credentials).'
+            if want
+            else "sherlock-proxyhat: no usable sub-user found (all suspended or out of traffic). "
+            "Create one, top up, or pass --proxyhat-sub-user."
+        )
+    return chosen.proxy_username, chosen.proxy_password

sherlock_proxyhat-0.1.0/src/sherlock_proxyhat/cli.py

@@ -0,0 +1,203 @@
+"""``sherlock-proxyhat`` — a thin launcher that runs Sherlock through ProxyHat residential proxies.
+
+Sherlock (https://github.com/sherlock-project/sherlock) is an OSINT *app*, not a
+library: it hunts a username across hundreds of sites and accepts a single
+``--proxy <url>`` for all of them. Firing that many requests from one datacenter
+IP gets rate-limited and blocked fast, so this launcher resolves a ProxyHat
+residential gateway URL and invokes the real ``sherlock`` executable with
+``--proxy <url>`` prepended, passing every other argument (usernames + flags)
+straight through.
+
+Because Sherlock reuses the one proxy for the whole run, we build a **rotating**
+gateway username by default — the ProxyHat gateway then hands out a fresh
+residential IP per connection, spreading the hundreds of site checks across many
+IPs. Pass ``--proxyhat-sticky`` to pin one IP instead.
+
+This is deliberately a wrapper around Sherlock's existing ``--proxy`` flag, not a
+fork. A native ``--proxyhat`` flag upstream is a planned follow-up (see README).
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from collections.abc import Sequence
+
+from proxyhat import build_connection_url
+
+from sherlock_proxyhat._resolve import ProxyHatConfigError, resolve_credentials
+
+# Sherlock makes one proxy serve the entire multi-site run, so the sensible
+# default is to rotate: a fresh residential IP per connection spreads the load
+# and dodges per-IP rate limits. sticky is opt-in via --proxyhat-sticky.
+DEFAULT_STICKY: bool | str | None = None
+
+
+def proxyhat_proxy_url(
+    *,
+    api_key: str | None = None,
+    username: str | None = None,
+    password: str | None = None,
+    sub_user: str | None = None,
+    country: str | None = None,
+    region: str | None = None,
+    city: str | None = None,
+    sticky: bool | str | None = DEFAULT_STICKY,
+    filter: str | None = None,
+    protocol: str = "http",
+) -> str:
+    """Return a full ProxyHat gateway proxy URL for Sherlock's ``--proxy``.
+
+    Resolves credentials (``api_key``/``PROXYHAT_API_KEY`` auto-picks an active
+    sub-user, or pass ``username``/``password``) then builds a connection URL like
+    ``http://<user>-country-us:<pass>@gate.proxyhat.com:8080`` (or ``socks5://…:1080``)
+    via the official ``proxyhat`` SDK's targeting grammar.
+
+    Rotating by default (``sticky=None``): the gateway hands out a fresh
+    residential IP per connection. Pass ``sticky="30m"`` (or ``True``) to pin one
+    IP for the whole run. Geo/quality: ``country`` (ISO code or ``"any"``),
+    ``region``, ``city``, ``filter`` (AI IP-quality tier). ``protocol`` is
+    ``"http"`` or ``"socks5"``.
+    """
+    user, pw = resolve_credentials(
+        api_key=api_key,
+        username=username,
+        password=password,
+        sub_user=sub_user,
+    )
+    return build_connection_url(
+        username=user,
+        password=pw,
+        country=country,
+        region=region,
+        city=city,
+        sticky=sticky,
+        filter=filter,
+        protocol=protocol,
+    )
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Parser for the ``--proxyhat-*`` options this launcher owns.
+
+    Everything else (usernames and all of Sherlock's own flags) is left for
+    ``parse_known_args`` to return untouched, so we never have to track Sherlock's
+    argument surface.
+    """
+    parser = argparse.ArgumentParser(
+        prog="sherlock-proxyhat",
+        description=(
+            "Run Sherlock through ProxyHat residential proxies. All arguments other than "
+            "--proxyhat-* are passed straight through to the `sherlock` executable."
+        ),
+        add_help=False,  # let --help fall through to sherlock; use --proxyhat-help for ours
+        # Never abbreviation-match: a bare `--proxy` (Sherlock's own flag) must fall
+        # through to passthrough, not be swallowed as a prefix of `--proxyhat-*`.
+        allow_abbrev=False,
+    )
+    g = parser.add_argument_group("proxyhat options (stripped before forwarding to sherlock)")
+    g.add_argument("--proxyhat-help", action="help", help="show this launcher's proxyhat options and exit")
+    g.add_argument("--proxyhat-api-key", metavar="KEY", help="ProxyHat API key (or env PROXYHAT_API_KEY)")
+    g.add_argument("--proxyhat-username", metavar="USER", help="explicit gateway proxy_username (or PROXYHAT_USERNAME)")
+    g.add_argument("--proxyhat-password", metavar="PASS", help="explicit gateway proxy_password (or PROXYHAT_PASSWORD)")
+    g.add_argument("--proxyhat-sub-user", metavar="ID", help="pick a sub-user by uuid or name (or PROXYHAT_SUBUSER)")
+    g.add_argument("--proxyhat-country", metavar="ISO", help='country ISO code, or "any" (default)')
+    g.add_argument("--proxyhat-region", metavar="NAME", help="region/state to target")
+    g.add_argument("--proxyhat-city", metavar="NAME", help="city to target")
+    g.add_argument("--proxyhat-filter", metavar="TIER", help="AI IP-quality tier (e.g. high)")
+    g.add_argument("--proxyhat-protocol", choices=("http", "socks5"), default="http", help="gateway protocol")
+    # Two flags rather than one optional-value flag: a bare `--proxyhat-sticky VALUE`
+    # would greedily swallow the following positional username as its value, so
+    # stickiness is a plain switch and the lifetime is a separate option.
+    g.add_argument(
+        "--proxyhat-sticky",
+        action="store_true",
+        help="pin one residential IP for the whole run (default: rotating — a fresh IP per connection)",
+    )
+    g.add_argument(
+        "--proxyhat-sticky-ttl",
+        metavar="TTL",
+        help='sticky session lifetime like "30m"/"2h" (implies --proxyhat-sticky; default 30m)',
+    )
+    return parser
+
+
+def _resolve_sticky(*, sticky: bool, ttl: str | None) -> bool | str | None:
+    """Fold the two sticky flags into the SDK's ``sticky`` argument.
+
+    A TTL implies sticky and sets the lifetime; a bare ``--proxyhat-sticky`` pins
+    with the SDK default (30m); neither means rotating.
+    """
+    if ttl:
+        return ttl
+    if sticky:
+        return True
+    return DEFAULT_STICKY
+
+
+def _has_user_proxy(passthrough: Sequence[str]) -> bool:
+    """True if the user already supplied Sherlock's own --proxy/-p flag."""
+    return any(a == "--proxy" or a == "-p" or a.startswith("--proxy=") for a in passthrough)
+
+
+def build_command(argv: Sequence[str]) -> list[str]:
+    """Resolve the ProxyHat proxy and build the full ``sherlock`` command line.
+
+    Returns ``[sherlock_exe, "--proxy", <url>, *passthrough]``. If the caller
+    already passed Sherlock's own ``--proxy``/``-p``, that wins and no ProxyHat URL
+    is injected (a note goes to stderr). Raises ``ProxyHatConfigError`` if
+    credentials can't be resolved and ``FileNotFoundError`` if ``sherlock`` isn't
+    installed.
+    """
+    ns, passthrough = _build_parser().parse_known_args(list(argv))
+
+    sherlock_exe = shutil.which("sherlock")
+    if sherlock_exe is None:
+        raise FileNotFoundError(
+            "sherlock-proxyhat: the `sherlock` executable was not found on PATH. "
+            "Install it with `pip install sherlock-proxyhat[sherlock]` or `pip install sherlock-project`."
+        )
+
+    if _has_user_proxy(passthrough):
+        print(
+            "sherlock-proxyhat: a --proxy/-p flag was supplied explicitly; using it and skipping the ProxyHat proxy.",
+            file=sys.stderr,
+        )
+        return [sherlock_exe, *passthrough]
+
+    url = proxyhat_proxy_url(
+        api_key=ns.proxyhat_api_key,
+        username=ns.proxyhat_username,
+        password=ns.proxyhat_password,
+        sub_user=ns.proxyhat_sub_user,
+        country=ns.proxyhat_country,
+        region=ns.proxyhat_region,
+        city=ns.proxyhat_city,
+        sticky=_resolve_sticky(sticky=ns.proxyhat_sticky, ttl=ns.proxyhat_sticky_ttl),
+        filter=ns.proxyhat_filter,
+        protocol=ns.proxyhat_protocol,
+    )
+    return [sherlock_exe, "--proxy", url, *passthrough]
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Entry point for the ``sherlock-proxyhat`` console script.
+
+    Builds the command and hands off to the real ``sherlock`` via subprocess,
+    returning its exit code.
+    """
+    argv = list(sys.argv[1:] if argv is None else argv)
+    try:
+        command = build_command(argv)
+    except (ProxyHatConfigError, FileNotFoundError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+
+    completed = subprocess.run(command)
+    return completed.returncode
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

sherlock_proxyhat-0.1.0/tests/test_cli.py

@@ -0,0 +1,107 @@
+"""Tests for the launcher wiring.
+
+Sherlock is a separate executable, so instead of installing it we fake
+``shutil.which`` (to pretend ``sherlock`` is on PATH) and ``subprocess.run`` (to
+capture the exact command line without running anything). Credentials are passed
+explicitly so no network or SDK call is made. These assert the built ``--proxy``
+URL reflects geo/rotation, that ``--proxyhat-*`` flags are stripped, and that all
+other args reach ``sherlock`` untouched.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from sherlock_proxyhat import build_command, cli, main
+
+
+@pytest.fixture
+def fake_sherlock(monkeypatch):
+    """Pretend `sherlock` is installed at a fixed path and capture subprocess.run."""
+    captured = {}
+
+    def fake_run(command, *args, **kwargs):
+        captured["command"] = command
+
+        class Completed:
+            returncode = 0
+
+        return Completed()
+
+    monkeypatch.setattr(cli.shutil, "which", lambda name: "/usr/bin/sherlock" if name == "sherlock" else None)
+    monkeypatch.setattr(cli.subprocess, "run", fake_run)
+    return captured
+
+
+CREDS = ["--proxyhat-username", "ph-1", "--proxyhat-password", "pw"]
+
+
+@pytest.fixture
+def fake_which(monkeypatch):
+    """Pretend `sherlock` is installed at a fixed path (build_command needs it on PATH)."""
+    monkeypatch.setattr(cli.shutil, "which", lambda name: "/usr/bin/sherlock" if name == "sherlock" else None)
+
+
+@pytest.mark.usefixtures("fake_which")
+class TestBuildCommand:
+    def test_injects_proxy_and_passes_through_args(self):
+        cmd = build_command([*CREDS, "johndoe", "janedoe", "--timeout", "30"])
+        assert cmd[0].endswith("sherlock")
+        assert cmd[1] == "--proxy"
+        url = cmd[2]
+        assert url.startswith("http://ph-1-country-any:pw@gate.proxyhat.com:8080")
+        # Usernames and sherlock's own flags pass through in order, proxyhat flags stripped.
+        assert cmd[3:] == ["johndoe", "janedoe", "--timeout", "30"]
+        assert not any(a.startswith("--proxyhat-") for a in cmd)
+
+    def test_rotating_by_default(self):
+        cmd = build_command([*CREDS, "johndoe"])
+        assert "-sid-" not in cmd[2] and "-ttl-" not in cmd[2]
+
+    def test_geo_and_sticky_ttl_reflected_in_url(self):
+        cmd = build_command([*CREDS, "--proxyhat-country", "de", "--proxyhat-sticky-ttl", "2h", "johndoe"])
+        url = cmd[2]
+        assert "ph-1-country-de" in url
+        assert "-ttl-2h" in url
+        assert cmd[3:] == ["johndoe"]
+
+    def test_sticky_bare_flag_pins_ip_without_eating_username(self):
+        # The sticky switch must not swallow the following positional username.
+        cmd = build_command([*CREDS, "--proxyhat-sticky", "johndoe"])
+        assert "-sid-" in cmd[2] and "-ttl-30m" in cmd[2]
+        assert cmd[3:] == ["johndoe"]
+
+    def test_socks5_protocol(self):
+        cmd = build_command([*CREDS, "--proxyhat-protocol", "socks5", "johndoe"])
+        assert cmd[2].startswith("socks5://ph-1-country-any:pw@gate.proxyhat.com:1080")
+
+    def test_user_supplied_proxy_wins(self, capsys):
+        cmd = build_command([*CREDS, "johndoe", "--proxy", "socks5://127.0.0.1:9050"])
+        # No ProxyHat proxy injected; the user's own args are forwarded verbatim.
+        assert cmd[1:] == ["johndoe", "--proxy", "socks5://127.0.0.1:9050"]
+        assert "skipping the ProxyHat proxy" in capsys.readouterr().err
+
+    def test_missing_sherlock_raises(self, monkeypatch):
+        monkeypatch.setattr(cli.shutil, "which", lambda name: None)
+        with pytest.raises(FileNotFoundError):
+            build_command([*CREDS, "johndoe"])
+
+
+class TestMain:
+    def test_main_runs_sherlock_and_returns_code(self, fake_sherlock):
+        rc = main([*CREDS, "--proxyhat-country", "us", "johndoe"])
+        assert rc == 0
+        command = fake_sherlock["command"]
+        assert command[0] == "/usr/bin/sherlock"
+        assert command[1] == "--proxy"
+        assert command[2].startswith("http://ph-1-country-us:pw@")
+        assert command[3] == "johndoe"
+
+    def test_main_missing_sherlock_returns_2(self, monkeypatch):
+        monkeypatch.setattr(cli.shutil, "which", lambda name: None)
+        assert main([*CREDS, "johndoe"]) == 2
+
+    def test_main_bad_credentials_returns_2(self, fake_sherlock, monkeypatch):
+        for var in ("PROXYHAT_API_KEY", "PROXYHAT_USERNAME", "PROXYHAT_PASSWORD", "PROXYHAT_SUBUSER"):
+            monkeypatch.delenv(var, raising=False)
+        assert main(["johndoe"]) == 2

sherlock_proxyhat-0.1.0/tests/test_url.py

@@ -0,0 +1,101 @@
+from types import SimpleNamespace
+
+import pytest
+
+from sherlock_proxyhat import ProxyHatConfigError, proxyhat_proxy_url, resolve_credentials
+
+
+def sub_user(**kw):
+    base = dict(
+        uuid="u",
+        name=None,
+        proxy_username="ph-1",
+        proxy_password="pw",
+        traffic_limit=0,
+        used_traffic=0,
+        suspended_at=None,
+    )
+    base.update(kw)
+    return SimpleNamespace(**base)
+
+
+class TestProxyUrl:
+    def test_url_shape_and_geo(self):
+        url = proxyhat_proxy_url(username="ph-1", password="pw", country="us")
+        assert url.startswith("http://ph-1-country-us:pw@gate.proxyhat.com:8080")
+
+    def test_rotating_by_default(self):
+        # Sherlock reuses one proxy for the whole run, so the default rotates:
+        # no session id / ttl means the gateway hands out a fresh IP per connection.
+        url = proxyhat_proxy_url(username="ph-1", password="pw")
+        assert "-sid-" not in url
+        assert "-ttl-" not in url
+        assert url.startswith("http://ph-1-country-any:pw@")
+
+    def test_sticky_opt_in_pins_ip(self):
+        url = proxyhat_proxy_url(username="ph-1", password="pw", sticky=True)
+        assert "-sid-" in url
+        assert "-ttl-30m" in url
+
+    def test_custom_sticky_ttl(self):
+        url = proxyhat_proxy_url(username="ph-1", password="pw", sticky="2h")
+        assert "-ttl-2h" in url
+
+    def test_full_geo_targeting(self):
+        url = proxyhat_proxy_url(
+            username="ph-1",
+            password="pw",
+            country="de",
+            region="berlin",
+            city="berlin",
+            filter="high",
+        )
+        assert "ph-1-country-de" in url
+        assert "-region-berlin" in url
+        assert "-city-berlin" in url
+        assert "-filter-high" in url
+
+    def test_socks5_protocol(self):
+        url = proxyhat_proxy_url(username="ph-1", password="pw", protocol="socks5")
+        assert url.startswith("socks5://ph-1-country-any:pw@gate.proxyhat.com:1080")
+
+
+class TestCredentialResolution:
+    def test_explicit_username_password(self):
+        assert resolve_credentials(username="ph-1", password="pw") == ("ph-1", "pw")
+
+    def test_raises_without_credentials(self, monkeypatch):
+        for var in ("PROXYHAT_API_KEY", "PROXYHAT_USERNAME", "PROXYHAT_PASSWORD", "PROXYHAT_SUBUSER"):
+            monkeypatch.delenv(var, raising=False)
+        with pytest.raises(ProxyHatConfigError):
+            resolve_credentials()
+
+    def test_api_key_picks_active_sub_user(self, monkeypatch):
+        users = [
+            sub_user(uuid="s", proxy_username="susp", suspended_at="2026-01-01"),
+            sub_user(uuid="g", proxy_username="good", traffic_limit=100, used_traffic=100),
+            sub_user(uuid="ok", proxy_username="ok", traffic_limit=100, used_traffic=1),
+        ]
+        fake_client = SimpleNamespace(sub_users=SimpleNamespace(list=lambda: users))
+        monkeypatch.setattr("sherlock_proxyhat._resolve.ProxyHat", lambda **kw: fake_client)
+        assert resolve_credentials(api_key="ph_key") == ("ok", "pw")
+
+    def test_api_key_named_sub_user(self, monkeypatch):
+        users = [sub_user(uuid="a", proxy_username="a"), sub_user(uuid="b", name="prod", proxy_username="b")]
+        fake_client = SimpleNamespace(sub_users=SimpleNamespace(list=lambda: users))
+        monkeypatch.setattr("sherlock_proxyhat._resolve.ProxyHat", lambda **kw: fake_client)
+        assert resolve_credentials(api_key="ph_key", sub_user="prod") == ("b", "pw")
+
+    def test_api_key_no_usable_sub_user(self, monkeypatch):
+        users = [sub_user(traffic_limit=100, used_traffic=100)]
+        fake_client = SimpleNamespace(sub_users=SimpleNamespace(list=lambda: users))
+        monkeypatch.setattr("sherlock_proxyhat._resolve.ProxyHat", lambda **kw: fake_client)
+        with pytest.raises(ProxyHatConfigError):
+            resolve_credentials(api_key="ph_key")
+
+    def test_url_resolves_via_api_key(self, monkeypatch):
+        users = [sub_user(proxy_username="good", proxy_password="secret")]
+        fake_client = SimpleNamespace(sub_users=SimpleNamespace(list=lambda: users))
+        monkeypatch.setattr("sherlock_proxyhat._resolve.ProxyHat", lambda **kw: fake_client)
+        url = proxyhat_proxy_url(api_key="ph_key", country="us")
+        assert url.startswith("http://good-country-us:secret@gate.proxyhat.com:8080")