Sherlock OSINT Username Search Tool Reference

Purpose

Sherlock is a command-line tool that hunts down social media accounts by username across 400+ social networks. It is designed for legitimate OSINT (Open Source Intelligence) and reconnaissance research, allowing you to find accounts associated with a username, check username availability across platforms, or answer questions like "where is this username registered?"

Prerequisites

Installation

Sherlock must be installed before use. The recommended method is via pipx:

pipx install sherlock-project

If pipx is not available, use pip:

pip install sherlock-project

Do NOT try multiple installation methods — pick one and proceed. If installation fails, inform the user and stop.

Alternative: Docker

If you prefer Docker, pull and run the official image:

docker pull sherlock/sherlock
docker run -it --rm sherlock/sherlock <username>

System Requirements

• Network access to query social platforms.
• For --tor: Tor daemon must be running.
• Linux packages available on Debian 13+, Ubuntu 22.10+, Homebrew, Kali, BlackArch.

Capabilities

• Search for a username across 400+ social networks.
• Output found accounts with URLs.
• Support for NSFW sites (with --nsfw flag).
• Support for Tor anonymity (with --tor flag).
• Support for custom timeout and site limiting.
• Support for wildcard searches (e.g., wildcard: 'user?name').
• Support for proxy usage (--proxy flag).
• Results saved to a .txt file by default.

Parameters

--print-found

Only output lines for found accounts (suppresses [-] not found lines). Always used by default unless the user requests otherwise.

--no-color

Disable colored output for cleaner parsing. Always used by default.

--timeout

Maximum time in seconds to wait for each site response. Default is 90. Can be increased (e.g., --timeout 120) for slow sites.

--nsfw

Include NSFW (Not Safe For Work) sites in the search. Only add if the user explicitly requests.

--tor

Route requests through Tor for anonymity. Only add if the user explicitly requests; requires Tor daemon running.

--site

Limit search to specific sites (e.g., --site twitter). Optional; only if the user wants to limit scope.

--proxy

Use an alternative proxy for requests. Optional; only if the user provides a proxy or Tor is unavailable.

--local

Use cached data to avoid rate limiting. Optional; for bulk searches.

Procedure: Sherlock OSINT Username Search

Step 1: Verify Installation

Check if Sherlock is installed by running:

sherlock --version

If the command fails, offer to install using 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.

Step 2: Extract the Username

Extract the username directly from the user's message if clearly stated. Do NOT use clarify if the username is explicitly given (e.g., 'Find accounts for nasa' → username is nasa). Only use clarify if multiple potential usernames, ambiguous phrasing, or no username mentioned.

When extracting the username, take the exact username as stated — preserve case, numbers, underscores, etc.

Step 3: Build the Default Command

Build the default command:

sherlock --print-found --no-color "<username>" --timeout 90

Only add --nsfw or --tor if the user explicitly requests. Do NOT ask about options via clarify — just run the default search.

Step 4: Execute the Search

Execute the search via the terminal tool. The command typically takes 30-120 seconds. Example terminal call:

{
  "command": "sherlock --print-found --no-color \"target_username\"",
  "timeout": 180
}

Step 5: Parse and Present Results

Parse the output and present results:

1. Summary line: 'Found X accounts for username Y'.
2. Categorized links grouped by platform type if helpful.
3. Output file location (Sherlock saves results to .txt by default). Present findings as clickable links when possible.

Example output lines:

[+] Instagram: https://instagram.com/username
[+] Twitter: https://twitter.com/username
[+] GitHub: https://github.com/username

Constraints and Caveats

• Do NOT ask about options via clarify — just run the default search. Users can request specific options if needed.
• When extracting username, take the exact username as stated — preserve case, numbers, underscores, etc.
• Only use clarify if multiple potential usernames, ambiguous phrasing, or no username mentioned.
• Do NOT try multiple installation methods — pick one (pipx recommended) and proceed.
• If installation fails, inform the user and stop.
• Sherlock output may contain false positives from sites that always return 'found' due to response structure. Cross-reference unexpected results with manual checks.
• Aggressive searches may trigger rate limits. For bulk username searches, add delays between calls or use --local with cached data.
• --tor requires Tor daemon running. If the user wants anonymity but Tor isn't available, suggest installing Tor service or using --proxy with an alternative proxy.
• 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.

Failure Modes

No Results Found

The username may not be registered on checked platforms. Suggest checking spelling/variation, trying similar usernames with '?' wildcard (e.g., sherlock "user?name"), or that 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.

Installation Failure

If pipx or pip install fails, inform the user and stop.

Tor Configuration Failure

--tor requires Tor daemon running. If not available, suggest alternatives.

False Positives

Some sites always return 'found'. Cross-reference unexpected results with manual checks.

Rate Limiting

Aggressive searches may trigger rate limits. Use delays or --local with cached data.

Examples

Example 1: Standard Search

User: 'Can you check if the username johndoe123 exists on social media?' Agent:

1. Check sherlock --version.
2. Username provided — proceed directly.
3. Run: sherlock --print-found --no-color "johndoe123" --timeout 90.
4. Parse output and present links. Response: 'Found 12 accounts for username johndoe123: [links] Results saved to: johndoe123.txt'.

Example 2: NSFW Search

User: 'Search for username alice including NSFW sites' Agent:

1. Check Sherlock installed.
2. Username + NSFW flag both provided.
3. Run: sherlock --print-found --no-color --nsfw "alice" --timeout 90.
4. Present results.