From 65be657a791364140edfeed3229cedd9ece42660 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Tue, 17 Mar 2026 02:48:21 -0700 Subject: [PATCH] feat(skills): add Sherlock OSINT username search skill Add optional skill for username enumeration across 400+ social networks using the Sherlock Project CLI (https://github.com/sherlock-project/sherlock). Features: - Smart username extraction from user messages - Installation verification before execution - Categorized output with clickable links - Ethical use guidelines - Docker, pipx, and pip installation paths Co-authored-by: unmodeled-tyler --- optional-skills/security/sherlock/SKILL.md | 192 +++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 optional-skills/security/sherlock/SKILL.md diff --git a/optional-skills/security/sherlock/SKILL.md b/optional-skills/security/sherlock/SKILL.md new file mode 100644 index 000000000..7250246aa --- /dev/null +++ b/optional-skills/security/sherlock/SKILL.md @@ -0,0 +1,192 @@ +--- +name: sherlock +description: OSINT username search across 400+ social networks. Hunt down social media accounts by username. +version: 1.0.0 +author: unmodeled-tyler +license: MIT +metadata: + hermes: + tags: [osint, security, username, social-media, reconnaissance] + category: security +prerequisites: + commands: [sherlock] +--- + +# Sherlock OSINT Username Search + +Hunt down social media accounts by username across 400+ social networks using the [Sherlock Project](https://github.com/sherlock-project/sherlock). + +## When to Use + +- User asks to find accounts associated with a username +- User wants to check username availability across platforms +- User is conducting OSINT or reconnaissance research +- User asks "where is this username registered?" or similar + +## Requirements + +- Sherlock CLI installed: `pipx install sherlock-project` or `pip install sherlock-project` +- Alternatively: Docker available (`docker run -it --rm sherlock/sherlock`) +- Network access to query social platforms + +## Procedure + +### 1. Check if Sherlock is Installed + +**Before doing anything else**, verify sherlock is available: + +```bash +sherlock --version +``` + +If the command fails: +- Offer to install: `pipx install sherlock-project` (recommended) or `pip install sherlock-project` +- **Do NOT** try multiple installation methods — pick one and proceed +- If installation fails, inform the user and stop + +### 2. Extract Username + +**Extract the username directly from the user's message if clearly stated.** + +Examples where you should **NOT** use clarify: +- "Find accounts for nasa" → username is `nasa` +- "Search for johndoe123" → username is `johndoe123` +- "Check if alice exists on social media" → username is `alice` +- "Look up user bob on social networks" → username is `bob` + +**Only use clarify if:** +- Multiple potential usernames mentioned ("search for alice or bob") +- Ambiguous phrasing ("search for my username" without specifying) +- No username mentioned at all ("do an OSINT search") + +When extracting, take the **exact** username as stated — preserve case, numbers, underscores, etc. + +### 3. Build Command + +**Default command** (use this unless user specifically requests otherwise): +```bash +sherlock --print-found --no-color "" --timeout 90 +``` + +**Optional flags** (only add if user explicitly requests): +- `--nsfw` — Include NSFW sites (only if user asks) +- `--tor` — Route through Tor (only if user asks for anonymity) + +**Do NOT ask about options via clarify** — just run the default search. Users can request specific options if needed. + +### 4. Execute Search + +Run via the `terminal` tool. The command typically takes 30-120 seconds depending on network conditions and site count. + +**Example terminal call:** +```json +{ + "command": "sherlock --print-found --no-color \"target_username\"", + "timeout": 180 +} +``` + +### 5. Parse and Present Results + +Sherlock outputs found accounts in a simple format. Parse the output and present: + +1. **Summary line:** "Found X accounts for username 'Y'" +2. **Categorized links:** Group by platform type if helpful (social, professional, forums, etc.) +3. **Output file location:** Sherlock saves results to `.txt` by default + +**Example output parsing:** +``` +[+] Instagram: https://instagram.com/username +[+] Twitter: https://twitter.com/username +[+] GitHub: https://github.com/username +``` + +Present findings as clickable links when possible. + +## Pitfalls + +### No Results Found +If Sherlock finds no accounts, this is often correct — the username may not be registered on checked platforms. Suggest: +- Checking spelling/variation +- Trying similar usernames with `?` wildcard: `sherlock "user?name"` +- The user may have privacy settings or deleted accounts + +### Timeout Issues +Some sites are slow or block automated requests. Use `--timeout 120` to increase wait time, or `--site` to limit scope. + +### Tor Configuration +`--tor` requires Tor daemon running. If user wants anonymity but Tor isn't available, suggest: +- Installing Tor service +- Using `--proxy` with an alternative proxy + +### False Positives +Some sites always return "found" due to their response structure. Cross-reference unexpected results with manual checks. + +### Rate Limiting +Aggressive searches may trigger rate limits. For bulk username searches, add delays between calls or use `--local` with cached data. + +## Installation + +### pipx (recommended) +```bash +pipx install sherlock-project +``` + +### pip +```bash +pip install sherlock-project +``` + +### Docker +```bash +docker pull sherlock/sherlock +docker run -it --rm sherlock/sherlock +``` + +### Linux packages +Available on Debian 13+, Ubuntu 22.10+, Homebrew, Kali, BlackArch. + +## Ethical Use + +This tool is for legitimate OSINT and research purposes only. Remind users: +- Only search usernames they own or have permission to investigate +- Respect platform terms of service +- Do not use for harassment, stalking, or illegal activities +- Consider privacy implications before sharing results + +## Verification + +After running sherlock, verify: +1. Output lists found sites with URLs +2. `.txt` file created (default output) if using file output +3. If `--print-found` used, output should only contain `[+]` lines for matches + +## Example Interaction + +**User:** "Can you check if the username 'johndoe123' exists on social media?" + +**Agent procedure:** +1. Check `sherlock --version` (verify installed) +2. Username provided — proceed directly +3. Run: `sherlock --print-found --no-color "johndoe123" --timeout 90` +4. Parse output and present links + +**Response format:** +> Found 12 accounts for username 'johndoe123': +> +> • https://twitter.com/johndoe123 +> • https://github.com/johndoe123 +> • https://instagram.com/johndoe123 +> • [... additional links] +> +> Results saved to: johndoe123.txt + +--- + +**User:** "Search for username 'alice' including NSFW sites" + +**Agent procedure:** +1. Check sherlock installed +2. Username + NSFW flag both provided +3. Run: `sherlock --print-found --no-color --nsfw "alice" --timeout 90` +4. Present results \ No newline at end of file