0
# Sherlock Project
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: sherlock-project
7
- **Language**: Python
8
- **Installation**: `pip install sherlock-project`
9
- **Optional Dependencies**: `pip install 'sherlock-project[tor]'` (for Tor support)
10

11
## Core Imports
12

13
```python
14
from sherlock_project.sherlock import sherlock
15
from sherlock_project.notify import QueryNotifyPrint
16
from sherlock_project.sites import SitesInformation
17
from sherlock_project.result import QueryStatus, QueryResult
18
```
19

20
For package metadata:
21

22
```python
23
from sherlock_project import __version__, __shortname__, __longname__
24
```
25

26
## Basic Usage
27

28
```python
29
from sherlock_project.sherlock import sherlock
30
from sherlock_project.notify import QueryNotifyPrint
31
from sherlock_project.sites import SitesInformation
32

33
# Load available sites
34
sites = SitesInformation()
35

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

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

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

49
### Username Pattern Expansion
50

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

53
```python
54
# Check username variations: example_, example-, example.
55
username_with_variations = "example{?}"
56
results = sherlock(username_with_variations, sites.sites, notify)
57

58
# This automatically expands to check:
59
# - example_
60
# - example-  
61
# - example.
62
```
63

64
## Architecture
65

66
Sherlock follows a modular architecture designed for extensibility and performance:
67

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

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

76
## Capabilities
77

78
### Core Search Engine
79

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

82
```python { .api }
83
def sherlock(
84
    username: str,
85
    site_data: dict,
86
    query_notify: QueryNotify,
87
    tor: bool = False,
88
    unique_tor: bool = False,
89
    dump_response: bool = False,
90
    proxy=None,
91
    timeout=60,
92
) -> dict:
93
    """
94
    Run Sherlock Analysis to check for username existence across social media sites.
95
    
96
    Args:
97
        username: Username to search for
98
        site_data: Dictionary of site information objects
99
        query_notify: Notification handler for results
100
        tor: Use Tor circuit for requests (deprecated)
101
        unique_tor: Use unique Tor circuit per request (deprecated) 
102
        dump_response: Whether to dump HTTP response data
103
        proxy: Proxy URL string
104
        timeout: Request timeout in seconds
105
        
106
    Returns:
107
        Dictionary mapping site names to result dictionaries containing:
108
        - url_main: Main site URL
109
        - url_user: User profile URL
110
        - status: QueryResult object
111
        - http_status: HTTP status code
112
        - response_text: Response body text
113
    """
114
```
115

116
[Core Search](./core-search.md)
117

118
### Result Management
119

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

122
```python { .api }
123
class QueryStatus(Enum):
124
    CLAIMED = "Claimed"      # Username found
125
    AVAILABLE = "Available"  # Username not found  
126
    UNKNOWN = "Unknown"      # Error occurred
127
    ILLEGAL = "Illegal"      # Invalid username format
128
    WAF = "WAF"             # Blocked by web application firewall
129

130
class QueryResult:
131
    def __init__(
132
        self,
133
        username: str,
134
        site_name: str, 
135
        site_url_user: str,
136
        status: QueryStatus,
137
        query_time: float = None,
138
        context: str = None
139
    ): ...
140
```
141

142
[Result Management](./result-management.md)
143

144
### Notification System
145

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

148
```python { .api }
149
class QueryNotify:
150
    def __init__(self, result: QueryResult = None): ...
151
    def start(self, message: str = None): ...
152
    def update(self, result: QueryResult): ...
153
    def finish(self, message: str = None): ...
154

155
class QueryNotifyPrint(QueryNotify):
156
    def __init__(
157
        self,
158
        result: QueryResult = None,
159
        verbose: bool = False,
160
        print_all: bool = False,
161
        browse: bool = False
162
    ): ...
163
```
164

165
[Notification System](./notification-system.md)
166

167
### Site Management
168

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

171
```python { .api }
172
class SiteInformation:
173
    def __init__(
174
        self,
175
        name: str,
176
        url_home: str,
177
        url_username_format: str,
178
        username_claimed: str,
179
        information: dict,
180
        is_nsfw: bool,
181
        username_unclaimed: str = None
182
    ): ...
183

184
class SitesInformation:
185
    def __init__(self, data_file_path: str = None): ...
186
    def remove_nsfw_sites(self, do_not_remove: list = []): ...
187
    def site_name_list(self) -> list: ...
188
```
189

190
[Site Management](./site-management.md)
191

192
## Package Metadata
193

194
```python { .api }
195
__shortname__: str = "Sherlock"
196
__longname__: str = "Sherlock: Find Usernames Across Social Networks" 
197
__version__: str = "0.15.0"
198
forge_api_latest_release: str = "https://api.github.com/repos/sherlock-project/sherlock/releases/latest"
199
```
200

201
## Command Line Interface
202

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

205
```bash
206
# Basic usage
207
sherlock username
208

209
# Run as module
210
python -m sherlock_project username
211

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

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

219
### Command Line Arguments
220

221
**Basic Arguments:**
222
- `username` - One or more usernames to check. Use `{?}` for pattern expansion to `_`, `-`, `.`
223

224
**Output Options:**
225
- `--output`, `-o FILE` - Save single username results to file
226
- `--folderoutput`, `-fo DIR` - Save multiple username results to directory
227
- `--csv` - Generate CSV output format
228
- `--xlsx` - Generate Excel (XLSX) output format
229
- `--print-all` - Show sites where username was not found
230
- `--print-found` - Show sites where username was found (default: true)
231
- `--no-color` - Disable colored terminal output
232
- `--browse`, `-b` - Open found profiles in default browser
233

234
**Site Selection:**
235
- `--site SITE_NAME` - Limit analysis to specific sites (can be used multiple times)
236
- `--json`, `-j JSON_FILE` - Load custom site data from JSON file or URL
237
- `--local`, `-l` - Force use of local data.json file
238
- `--nsfw` - Include NSFW sites in search
239

240
**Network Configuration:**
241
- `--proxy`, `-p PROXY_URL` - Use proxy (e.g., `socks5://127.0.0.1:1080`)
242
- `--tor`, `-t` - Make requests over Tor (requires Tor installed)
243
- `--unique-tor`, `-u` - Use new Tor circuit per request
244
- `--timeout SECONDS` - Request timeout in seconds (default: 60)
245

246
**Debugging:**
247
- `--verbose`, `-v`, `-d`, `--debug` - Display extra debugging information
248
- `--dump-response` - Dump HTTP responses for debugging
249
- `--version` - Display version information and dependencies
250

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