tessl/pypi-sherlock-project
Hunt down social media accounts by username across social networks
—
Pending
core-search.mddocs/
Core Search Engine
The main search functionality that orchestrates username lookups across multiple social networks and platforms. The core engine provides efficient concurrent searching with extensive configuration options for different use cases.
Capabilities
Main Search Function
The primary function that performs username searches across social media sites with concurrent HTTP requests and comprehensive result tracking.
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: String indicating username to search for
site_data: Dictionary containing all site data (SiteInformation objects)
query_notify: Object with base type QueryNotify() for result notifications
tor: Boolean indicating whether to use Tor circuit (deprecated)
unique_tor: Boolean indicating whether to use unique Tor circuit per request (deprecated)
dump_response: Boolean indicating whether to dump HTTP response data
proxy: String indicating proxy URL or None
timeout: Time in seconds to wait before timing out request (default 60)
Returns:
Dictionary containing results from report. Key is site name, value is dict with:
- url_main: URL of main site
- url_user: URL of user on site (if account exists)
- status: QueryResult() object indicating test results
- http_status: HTTP status code of query
- response_text: Text from request (may be None on HTTP error)
"""Enhanced HTTP Session
Custom HTTP session class that extends FuturesSession to add response timing metrics for performance analysis.
class SherlockFuturesSession(FuturesSession):
def request(
self,
method: str,
url: str,
hooks: dict = None,
*args,
**kwargs
):
"""
Request URL with response time measurement.
Extends FuturesSession request method to calculate response time metric.
Args:
method: String containing HTTP method for request
url: String containing URL for request
hooks: Dictionary containing hooks to execute after request finishes
args: Additional arguments
kwargs: Additional keyword arguments
Returns:
Request object with elapsed time attached to response
"""Username Utilities
Helper functions for username processing and validation.
def interpolate_string(input_object, username: str):
"""
Replace {} placeholder with username in strings.
Args:
input_object: String or other object to interpolate
username: Username to substitute
Returns:
String with {} replaced by username, or original object if not string
"""
def check_for_parameter(username: str) -> bool:
"""
Check if {?} parameter exists in username.
Indicates if sherlock is looking for multiple username variations.
Args:
username: Username string to check
Returns:
Boolean indicating if parameter syntax found
"""
def multiple_usernames(username: str) -> list:
"""
Replace parameter syntax with symbols and return list of usernames.
Args:
username: Username with parameter syntax
Returns:
List of username variations
"""Response Processing
Low-level function for processing HTTP request futures and handling errors.
def get_response(request_future, error_type: str, social_network: str):
"""
Get response from request future with error handling.
Args:
request_future: Future object from HTTP request
error_type: String describing type of error expected
social_network: String name of social network being queried
Returns:
Response object or None if error occurred
"""CLI Functions
Command-line interface utilities and validation.
def main():
"""
Main CLI entry point function.
Handles argument parsing, site loading, username validation,
and orchestrates the search process with appropriate output formatting.
"""
def timeout_check(value: str) -> float:
"""
Check and validate timeout argument.
Args:
value: String value from command line argument
Returns:
Float timeout value in seconds
Raises:
ArgumentTypeError: If value is invalid
"""
def handler(signal_received, frame):
"""
Signal handler for graceful exit without throwing errors.
Args:
signal_received: Signal number received
frame: Current stack frame
"""Usage Examples
Basic Search
from sherlock_project.sherlock import sherlock
from sherlock_project.notify import QueryNotifyPrint
from sherlock_project.sites import SitesInformation
# Load all available sites
sites = SitesInformation()
# Create notification handler
notify = QueryNotifyPrint(verbose=True)
# Perform search
results = sherlock("john_doe", sites.sites, notify, timeout=30)
# Check results
for site_name, result in results.items():
if result['status'].status.value == "Claimed":
print(f"Account found: {result['url_user']}")Search with Proxy
# Use proxy for requests
results = sherlock(
"username",
sites.sites,
notify,
proxy="http://proxy.example.com:8080",
timeout=45
)Search Subset of Sites
# Search only specific sites
site_subset = {
"GitHub": sites.sites["GitHub"],
"Twitter": sites.sites["Twitter"]
}
results = sherlock("username", site_subset, notify)Processing Multiple Usernames
usernames = ["user1", "user2", "user3"]
for username in usernames:
print(f"\nSearching for: {username}")
results = sherlock(username, sites.sites, notify)
# Process results for this username
claimed_accounts = [
result['url_user'] for result in results.values()
if result['status'].status.value == "Claimed"
]
print(f"Found {len(claimed_accounts)} accounts for {username}")Install with Tessl CLI
npx tessl i tessl/pypi-sherlock-project