or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-search.mdindex.mdnotification-system.mdresult-management.mdsite-management.md
tile.json

tessl/pypi-sherlock-project

Hunt down social media accounts by username across social networks

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/sherlock-project@0.15.x

To install, run

npx @tessl/cli install tessl/pypi-sherlock-project@0.15.0

index.mddocs/

Sherlock Project

Hunt down social media accounts by username across social networks. Sherlock is a powerful OSINT (Open Source Intelligence) tool that systematically searches for usernames across over 400 social networks, forums, and online platforms to identify an individual's digital footprint. Perfect for investigators, security researchers, and digital forensics professionals.

Package Information

  • Package Name: sherlock-project
  • Language: Python
  • Installation: pip install sherlock-project
  • Optional Dependencies: pip install 'sherlock-project[tor]' (for Tor support)

Core Imports

from sherlock_project.sherlock import sherlock
from sherlock_project.notify import QueryNotifyPrint
from sherlock_project.sites import SitesInformation
from sherlock_project.result import QueryStatus, QueryResult

For package metadata:

from sherlock_project import __version__, __shortname__, __longname__

Basic Usage

from sherlock_project.sherlock import sherlock
from sherlock_project.notify import QueryNotifyPrint
from sherlock_project.sites import SitesInformation

# Load available sites
sites = SitesInformation()

# Create a notification handler for console output
notify = QueryNotifyPrint(verbose=True, print_all=False)

# Search for a username
username = "example_user"
results = sherlock(username, sites.sites, notify)

# Process results
for site_name, site_result in results.items():
    if site_result['status'].status == QueryStatus.CLAIMED:
        print(f"Found account on {site_name}: {site_result['url_user']}")

Username Pattern Expansion

Sherlock supports special username patterns using {?} placeholder for checking variations:

# Check username variations: example_, example-, example.
username_with_variations = "example{?}"
results = sherlock(username_with_variations, sites.sites, notify)

# This automatically expands to check:
# - example_
# - example-  
# - example.

Architecture

Sherlock follows a modular architecture designed for extensibility and performance:

  • Core Engine: The main sherlock() function orchestrates parallel HTTP requests across multiple sites
  • Site Management: SitesInformation loads and manages site definitions from JSON configuration
  • Result System: QueryResult and QueryStatus provide structured result handling
  • Notification System: Pluggable notification handlers for different output formats
  • Threading: Uses SherlockFuturesSession for concurrent HTTP requests with response time tracking

This design enables efficient searching across hundreds of sites simultaneously while providing flexible result handling and extensible site definitions.

Capabilities

Core Search Engine

The main search functionality that orchestrates username lookups across multiple social networks and platforms, with support for proxies, Tor, and customizable timeouts.

def sherlock(
    username: str,
    site_data: dict,
    query_notify: QueryNotify,
    tor: bool = False,
    unique_tor: bool = False,
    dump_response: bool = False,
    proxy=None,
    timeout=60,
) -> dict:
    """
    Run Sherlock Analysis to check for username existence across social media sites.
    
    Args:
        username: Username to search for
        site_data: Dictionary of site information objects
        query_notify: Notification handler for results
        tor: Use Tor circuit for requests (deprecated)
        unique_tor: Use unique Tor circuit per request (deprecated) 
        dump_response: Whether to dump HTTP response data
        proxy: Proxy URL string
        timeout: Request timeout in seconds
        
    Returns:
        Dictionary mapping site names to result dictionaries containing:
        - url_main: Main site URL
        - url_user: User profile URL
        - status: QueryResult object
        - http_status: HTTP status code
        - response_text: Response body text
    """

Core Search

Result Management

Data structures for handling search results, including status enumerations and result objects that contain metadata about each username lookup.

class QueryStatus(Enum):
    CLAIMED = "Claimed"      # Username found
    AVAILABLE = "Available"  # Username not found  
    UNKNOWN = "Unknown"      # Error occurred
    ILLEGAL = "Illegal"      # Invalid username format
    WAF = "WAF"             # Blocked by web application firewall

class QueryResult:
    def __init__(
        self,
        username: str,
        site_name: str, 
        site_url_user: str,
        status: QueryStatus,
        query_time: float = None,
        context: str = None
    ): ...

Result Management

Notification System

Pluggable notification handlers for processing and displaying search results, supporting console output, file export, and custom formatting.

class QueryNotify:
    def __init__(self, result: QueryResult = None): ...
    def start(self, message: str = None): ...
    def update(self, result: QueryResult): ...
    def finish(self, message: str = None): ...

class QueryNotifyPrint(QueryNotify):
    def __init__(
        self,
        result: QueryResult = None,
        verbose: bool = False,
        print_all: bool = False,
        browse: bool = False
    ): ...

Notification System

Site Management

Site configuration and data management for loading, filtering, and organizing information about supported social networks and platforms.

class SiteInformation:
    def __init__(
        self,
        name: str,
        url_home: str,
        url_username_format: str,
        username_claimed: str,
        information: dict,
        is_nsfw: bool,
        username_unclaimed: str = None
    ): ...

class SitesInformation:
    def __init__(self, data_file_path: str = None): ...
    def remove_nsfw_sites(self, do_not_remove: list = []): ...
    def site_name_list(self) -> list: ...

Site Management

Package Metadata

__shortname__: str = "Sherlock"
__longname__: str = "Sherlock: Find Usernames Across Social Networks" 
__version__: str = "0.15.0"
forge_api_latest_release: str = "https://api.github.com/repos/sherlock-project/sherlock/releases/latest"

Command Line Interface

Sherlock can be run from the command line with extensive configuration options:

# Basic usage
sherlock username

# Run as module
python -m sherlock_project username

# Multiple usernames with pattern expansion
sherlock user1 user2 "user{?}"  # Checks user_, user-, user.

# Advanced usage with options
sherlock username --verbose --timeout 30 --proxy socks5://127.0.0.1:1080 --csv --output results.txt

Command Line Arguments

Basic Arguments:

  • username - One or more usernames to check. Use {?} for pattern expansion to _, -, .

Output Options:

  • --output, -o FILE - Save single username results to file
  • --folderoutput, -fo DIR - Save multiple username results to directory
  • --csv - Generate CSV output format
  • --xlsx - Generate Excel (XLSX) output format
  • --print-all - Show sites where username was not found
  • --print-found - Show sites where username was found (default: true)
  • --no-color - Disable colored terminal output
  • --browse, -b - Open found profiles in default browser

Site Selection:

  • --site SITE_NAME - Limit analysis to specific sites (can be used multiple times)
  • --json, -j JSON_FILE - Load custom site data from JSON file or URL
  • --local, -l - Force use of local data.json file
  • --nsfw - Include NSFW sites in search

Network Configuration:

  • --proxy, -p PROXY_URL - Use proxy (e.g., socks5://127.0.0.1:1080)
  • --tor, -t - Make requests over Tor (requires Tor installed)
  • --unique-tor, -u - Use new Tor circuit per request
  • --timeout SECONDS - Request timeout in seconds (default: 60)

Debugging:

  • --verbose, -v, -d, --debug - Display extra debugging information
  • --dump-response - Dump HTTP responses for debugging
  • --version - Display version information and dependencies

The CLI is implemented in the main() function with comprehensive argument parsing and validation.