Sherlock OSINT Username Search Guide | Hermes Agent

Sherlock is a command-line tool that checks a single username against over 400 social networks and web platforms. It is useful for OSINT researchers, security professionals, or anyone who needs to find where a username is registered, verify availability, or map a digital footprint. This guide covers how to use Sherlock within the Hermes Agent environment, from installation to interpreting results.

What it does

Sherlock queries hundreds of sites for a given username and reports back which ones have a matching account. It does not log in, scrape private data, or interact with accounts. It simply checks whether a profile page exists at the expected URL. The output is a list of platforms where the username was found, with direct links to the profiles.

This is useful for:

Reconnaissance during security assessments
Checking if a username you want is taken across platforms
Investigating potential impersonation or account squatting
Mapping a person's public online presence from a single handle

Before you start

Sherlock must be installed on the system where Hermes Agent runs. The recommended method is pipx, which installs it in an isolated environment. You can also use pip or Docker. The tool requires network access to query each platform.

Installation options

pipx (recommended)

pipx install sherlock-project

pip

pip install sherlock-project

Docker

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

Linux packages

Available on Debian 13+, Ubuntu 22.10+, Homebrew, Kali, BlackArch.

Procedure

1. Check if Sherlock is Installed

Before doing anything else, verify sherlock is available:

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):

sherlock --print-found --no-color "<username>" --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:

{
  "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:

Summary line: "Found X accounts for username 'Y'"
Categorized links: Group by platform type if helpful (social, professional, forums, etc.)
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.

When not to use it

Sherlock is not suitable for deep investigation of a single account, password recovery, or accessing private content. It only checks for the existence of a public profile page. If the user needs to gather detailed information from a specific platform, other tools are more appropriate.

Limits and gotchas

The tool checks over 400 sites, but not every platform on the internet. Some niche or regional sites are not included.
Results depend on network conditions and the responsiveness of each platform. A timeout or block on one site does not mean the username is absent there.
Sherlock does not verify that the account is active or belongs to a specific person. It only confirms that a page with that username exists.
The --nsfw flag includes adult content sites. Use it only when the user explicitly requests it.
The --tor flag requires a running Tor daemon. Without it, the command will fail.

What pairs with this

Sherlock is part of the Hermes Agent optional skills under the Security category. It complements other OSINT and reconnaissance tools that may be installed alongside it. For broader investigation workflows, consider combining it with tools that analyze domain names, email addresses, or IP addresses.

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:

Output lists found sites with URLs
.txt file created (default output) if using file output
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:

Check sherlock --version (verify installed)
Username provided, proceed directly
Run: sherlock --print-found --no-color "johndoe123" --timeout 90
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"