sherlock

name	sherlock
description	OSINT username search across ~400 social sites via the Sherlock CLI. Emits structured CSV for account recovery, impersonation checks, and authorized investigations.
license	MIT
version	0.1.0
compatibility	["claude-code","codex","gemini"]
allowed-tools	["Bash","Read"]

Sherlock — Agent Skill

Wraps Sherlock.

Before invoking — confirm authorization_basis

State your authorization basis before running sherlock. One of:

• self — the user is looking up their own username
• authorized investigation — user has explicit authorization (incident response, trust & safety, account recovery with consent)
• public figure research — target is a public figure and the purpose is research/journalism

If none apply, refuse and explain why. Honor-system gate — no runtime enforcement.

Prerequisites

pipx install 'sherlock-project>=0.16,<1.0'
sherlock --version

If an older sherlock exists via brew/pip, uninstall it first or use pipx install --force 'sherlock-project>=0.16,<1.0'.

Default invocation (filtered)

Prefer filtered runs with --site flags. Unfiltered scans of ~400 sites take 60–180s and produce many false positives:

sherlock "$USER" \
  --csv \
  --local \
  --site GitHub --site Reddit --site TikTok --site Twitter --site Instagram \
  --folderoutput ./sherlock-out

Flags:

• --csv — structured output (cleanest for agents; --json is INPUT only, not output)
• --local — use packaged data.json; skip per-run download for network stability
• --site X (repeatable) — limit scan to listed sites
• --folderoutput DIR — output directory

Warning — full scans

Omitting --site scans every site in data.json (~400 entries). Expect 60–180 seconds and many false positives. Only do this when the user explicitly requests a full scan.

Parsing the output

Output file: ./sherlock-out/$USER.csv. Columns (pinned to sherlock 0.16.x, verified at sherlock_project/sherlock.py:851-885):

username,name,url_main,url_user,exists,http_status,response_time_s

exists is the primary signal. http_status helps reconcile ambiguous cases (429/403 often means rate-limit, not absence).

Ignore Update available! noise

Sherlock checks GitHub for updates on every run. If your binary is outdated, stdout will contain:

Update available! 0.16.0 --> 0.16.1
https://github.com/sherlock-project/sherlock/releases/tag/v0.16.1

Ignore this line — it precedes the CSV data and does not affect results.

Optional — Tor via SOCKS5

sherlock "$USER" --csv --local --proxy socks5://127.0.0.1:9050 --folderoutput ./sherlock-out

Requires Tor daemon running on localhost:9050. stem is upstream's dependency; no extra install needed.

False-positive handling

Three common failure patterns (full patterns in reference/false-positives.md):

• Wildcard 200 — site returns HTTP 200 on every URL; sherlock may mark exists=Claimed incorrectly
• Rate-limit as exists — 429/403 interpreted as "page loaded"
• Soft 404 — nonexistent profiles redirect to homepage

Mitigations: re-run with --timeout 90; swap proxy/network; cross-check with WhatsMyName or maigret.

Dossier format

Render findings per reference/dossier-template.md.

Failure modes

• Network timeout → --timeout 120 or switch networks
• Rate-limit (Cloudflare/Akamai) → swap network, wait 10–15 min, or enable Tor
• Outdated data.json → pipx upgrade sherlock-project; confirm --version
• Tor proxy refused → verify Tor daemon listening on 9050

Not supported in v0.1

• Streaming progress (agent blocks for the full run duration)
• Claude Desktop / any non-shell agent
• Native Windows (WSL supported)

A future sherlock-mcp companion may address streaming + Desktop. Not on the v0.1 roadmap.