Sherlock 详细部署教程

1. 项目简介

Sherlock 是一款开源 OSINT（开源情报）用户名查询工具，可以根据输入的用户名，在 400+ 公开社交网络平台中自动检测该用户名是否存在。传统方式需要人工逐个平台搜索，而 Sherlock 可以自动化完成查询，大幅提高信息收集效率。

核心特性：

  • 跨平台批量探测：给定一个或多个用户名，并发请求数百个站点，依据 HTTP 状态码、页面特征或重定向行为判定账号是否被占用
  • 多种输出格式：支持文本、CSV、Excel（XLSX）等多种格式
  • 灵活的查询控制：可指定特定平台、限定时间范围、控制输出详细程度
  • 网络代理支持：支持 HTTP 代理、SOCKS5 代理等

版本信息：当前最新版本为 v0.16.0，该版本显著减少了误报率。

应用场景：用户名资产检查、数字身份分析、网络安全学习、OSINT 信息收集、企业品牌保护。

使用提醒：Sherlock 仅应用于授权的信息安全测试和学习研究，使用时需遵守当地法律法规。

2. 部署前准备

2.1 系统要求

项目 配置要求
操作系统 Linux、macOS、Windows
Python 3.10+（v0.16.0 已弃用 3.8/3.9 支持）
内存 1GB 以上（Docker 方式）
磁盘 10GB 以上（Docker 方式）
网络 稳定的互联网连接

2.2 重要警告

根据官方文档，ParrotOS 和 Ubuntu 24.04 上由第三方维护的包已损坏，这两个系统的用户应改用 pipx/pip 或 Docker 安装。

3. 安装方式

Sherlock 提供三种主要安装方式，根据你的使用场景选择：

安装方式 适用场景 优势
pipx 安装 常规使用（推荐） 隔离环境，管理方便
Docker 部署 容器化部署 环境隔离，无需配置 Python
源码安装 开发者定制 完全可控，便于调试

4. 方式一：pipx 安装（推荐）

这是官方推荐的安装方式，适合大多数用户。

4.1 安装 pipx

Ubuntu/Debian：

1
2
3
sudo apt update
sudo apt install pipx
pipx ensurepath

macOS：

1
2
brew install pipx
pipx ensurepath

Windows：

1
2
python -m pip install --user pipx
python -m pipx ensurepath

4.2 安装 Sherlock

1
pipx install sherlock-project

也可以使用 pip 或 uv 替代 pipx：

1
pip install --user sherlock-project

4.3 验证安装

1
sherlock --version

如果显示版本号（如 sherlock 0.16.0），说明安装成功。

5. 方式二：Docker 部署

Docker 方式提供环境隔离，适合容器化部署场景。

5.1 安装 Docker

Ubuntu/Debian：

1
2
3
4
sudo apt update
sudo apt install docker.io -y
sudo systemctl start docker
sudo systemctl enable docker

验证安装：

1
docker --version

5.2 拉取 Sherlock 镜像

1
docker pull sherlock/sherlock

5.3 创建结果目录

用于持久化保存查询结果：

1
mkdir -p /opt/sherlock/results

5.4 测试运行

1
docker run --rm sherlock/sherlock --help

出现帮助信息表示部署成功。

5.5 基本查询

1
docker run --rm sherlock/sherlock testuser

5.6 保存查询结果

1
2
3
docker run --rm \
  -v /opt/sherlock/results:/opt/sherlock/results \
  sherlock/sherlock --output /opt/sherlock/results/result.txt testuser

Docker 镜像的 ENTRYPOINT 为 ["sherlock"]，用户名作为命令参数直接透传。

6. 方式三：源码安装（开发者）

适合需要修改源码或深度定制的开发者。

6.1 克隆项目

1
2
git clone https://github.com/sherlock-project/sherlock.git
cd sherlock

6.2 安装依赖

1
2
3
pipx install . --force
# 或
pip install .

6.3 运行修改后的版本

1
sherlock your_username_here

7. 基本用法

7.1 基础查询

1
2
3
4
5
# 查询单个用户名
sherlock user123

# 批量查询多个用户名
sherlock user1 user2 user3

找到的账号会被写入与用户名同名的独立文本文件（例如 user123.txt）。

7.2 指定平台查询

1
2
3
4
5
# 只查询特定平台
sherlock user123 --site GitHub --site Instagram

# 平台名称包含空格时需加引号
sherlock user123 --site "Archive of Our Own" --site "Docker Hub"

7.3 通配符扩展

使用 {?} 检查相似用户名，会被依次替换为 _、-、.：

1
2
sherlock john{?}doe
# 会检查 john_doe、john-doe、john.doe

8. 输出控制

8.1 输出详细程度

1
2
3
4
5
6
7
8
# 仅打印找到的账号
sherlock user123 --print-found

# 打印所有结果，包括未找到及原因
sherlock user123 --print-all

# 禁用彩色输出（适用于日志或 CI）
sherlock user123 --no-color

8.2 保存结果

1
2
3
4
5
6
7
8
9
10
11
# 保存到指定文本文件
sherlock user123 --output results/user123.txt

# 多个用户时，将文件保存到文件夹
sherlock alice bob -fo results/

# 同时生成 CSV 文件
sherlock user123 --csv

# 生成 Excel 工作簿
sherlock user123 --xlsx

9. 高级选项

9.1 网络代理

1
2
3
4
5
6
7
8
9
10
11
# 使用 HTTP 代理
sherlock user123 --proxy http://127.0.0.1:8080

# 使用 SOCKS5 代理
sherlock user123 --proxy socks5://127.0.0.1:1080

# 通过 Tor 路由（需已安装 Tor）
sherlock user123 --tor

# 每个请求使用新的 Tor 电路（最慢，但更隔离）
sherlock user123 --unique-tor

注意：--tor 和 --unique-tor 在 v0.15.0 中已被标记为弃用，未来版本可能移除。

9.2 数据源控制

1
2
3
4
5
6
7
8
# 强制使用本地打包的 data.json
sherlock user123 --local

# 加载自定义站点定义 JSON 文件
sherlock user123 --json ./custom-sites.json

# 从远程 URL 加载自定义站点定义
sherlock user123 --json https://example.org/custom-sites.json

9.3 其他选项

1
2
3
4
5
6
7
8
9
10
11
# 设置请求超时（秒，默认 60）
sherlock user123 --timeout 90

# 包含 NSFW 站点（默认不包含）
sherlock user123 --nsfw

# 显示调试信息
sherlock user123 --verbose

# 显示帮助
sherlock --help

10. 常见问题与解决方案

10.1 数据文件访问错误

问题：运行时报错 ERROR: Bad response while accessing data file URL 'https://raw.githubusercontent.com/sherlock-project/sherlock/master/sherlock/resources/data.json'。

原因：运行的旧版本引用了已废弃的链接。

解决方案：

  1. 检查 Python 版本：python --version
  2. 确保 Python 版本为 3.9 或更高
  3. 升级 Sherlock：pipx upgrade sherlock-project
  4. 确认安装的是 v0.15.0 或更高版本

10.2 WAF 拦截问题

问题：结果显示 Blocked by bot detection (proxy may help)。

原因：该站点的请求被 WAF（Web 应用防火墙）拦截，响应体被识别为 WAF 挑战页。

解决方案：

  1. 使用 --print-all 参数保留 WAF 记录
  2. 单独复现拦截：sherlock --print-all --site 站点名 用户名
  3. 查看原始响应：sherlock --print-all --dump-response --site 站点名 用户名
  4. 尝试更换代理出口重试

10.3 误报问题

问题：某些站点显示账号存在但实际不存在。

解决方案：升级到 v0.16.0 版本，该版本显著减少了误报率。

10.4 大小写敏感问题

问题：某些平台（如 Chess.com）对用户名大小写敏感，导致检测失败。

解决方案：尝试使用不同大小写形式查询，或使用 {?} 通配符扩展检查变体。

11. 部署架构总结

部署方式 适用场景 安装命令 特点
pipx 安装 常规使用 pipx install sherlock-project 隔离环境，管理方便
Docker 部署 容器化部署 docker run -it --rm sherlock/sherlock 环境隔离，无需配置 Python
源码安装 开发者 pipx install . --force 完全可控，便于调试

Sherlock 是一个高效的 OSINT 工具，通过 pipx 或 Docker 可以快速完成部署。部署完成后，你可以通过简单的命令行参数实现跨 400+ 平台的用户名探测。建议始终使用最新版本以获得最佳性能和最低误报率，同时注意遵守相关法律法规，仅将工具用于合法授权的场景。