Tracehunt

🔎 TraceHunt

几秒钟内，在 480+ 个平台上查找任意用户名。
OSINT 侦查，提供单文件 HTML 报告、0–100 数字足迹评分，并默认采用隐私优先的不回传策略。

一条命令，即可获得用户名所在平台的排序列表，以及可分享的 HTML 报告。

---

TraceHunt 是知名项目 Sherlock（MIT）的一个尊重隐私、可自托管的分支。它保留了 Sherlock 经受实战检验的检测引擎和网站数据库，并新增报告、评分、配置功能，且默认采用不回传策略。完整署名信息和变更列表请参阅 NOTICE.md。

仅限经授权的安全研究和 OSINT 用途。 请确认符合所在司法管辖区的法律，并且只调查获准调查的账户。

---

繁体中文摘要

TraceHunt 是一套 OSINT 用户名侦查工具：输入一个账户名称，它会在 480+ 个 社交/平台上查询该名称是否已注册，协助开展安全研究与数字足迹盘点。

本项目是知名开源工具 Sherlock 的定制分支（MIT 授权），在保留原有检测引擎与 网站数据库的基础上，新增了以下功能：

• HTML 报告：一键生成美观、可离线打开的单文件报告（--html report.html）。
• 数字足迹评分：统计命中数，并换算为 0–100 分的足迹分数（--summary）。
• YAML 配置文件：将常用参数写入 tracehunt.yaml，免去每次重复输入（--config）。
• 隐私优先：原版启动时会自动联网检查更新；本版本改为 默认不连接外网，只有添加 --check-update 才会检查。

授权与致谢请参阅 NOTICE.md；原始著作权信息保留于 LICENSE。

---

功能

480+ 个站点	并行在数百个平台上查找用户名
HTML 报告	--html report.html -> 生成可分享的自包含样式化报告
足迹评分	--summary -> 统计命中数，并给出 0–100 的“数字足迹”评分
配置文件	--config tracehunt.yaml -> 保存默认标志
不回传	更新检查为主动选择加入（--check-update），与上游版本不同
导出	支持 CSV（--csv）和 Excel（--xlsx），与 Sherlock 一样

安装

git clone https://github.com/Hayatelin/tracehunt.git
cd tracehunt
pip install -r requirements.txt
# optional: install as a CLI command
pip install .

需要 Python 3.9+。

快速开始

# Basic: hunt one username, print results to the terminal
python -m tracehunt johndoe

# Generate a styled HTML report + a footprint summary
python -m tracehunt johndoe --html johndoe.html --summary

# Limit to specific sites and export CSV
python -m tracehunt johndoe --site GitHub --site Reddit --csv

# Use a config file for your default options
python -m tracehunt johndoe --config tracehunt.yaml

如果你是将其安装为命令，请将 python -m tracehunt 替换为 tracehunt。

🤖 从 AI Agent 使用（MCP + 技能）

TraceHunt 附带 MCP 服务和 Agent 技能，因此 Claude Code、 Cursor、Codex 或 Gemini CLI 可以按需为你执行用户名侦查。

pip install "mcp[cli]" -r requirements.txt
python mcp/tracehunt_mcp.py        # exposes hunt_username() + footprint_score()

按照 mcp/README.md 中的说明向 Agent 注册，然后只需提出请求： "use tracehunt to check the username octocat"。更倾向于不使用 MCP？skill/SKILL.md 会指导 Agent 直接使用 CLI。 此外还提供纯 Python API：from tracehunt.api import hunt。

架构

flowchart LR
    A[CLI args + tracehunt.yaml] --> B[core.run_search]
    B --> C[(site database<br/>data.json)]
    B --> D[Async requests<br/>requests-futures]
    D --> E[QueryResult per site]
    E --> F{Outputs}
    F --> G[Terminal]
    F --> H[CSV / XLSX]
    F --> I[report.py<br/>HTML + footprint score]

与 Sherlock 的不同之处

检测引擎和站点列表来自 Sherlock（MIT）。新增功能包括：

• tracehunt/report.py — HTML 报告和足迹评分（新增，仅使用标准库）
• tracehunt/config.py — YAML 配置加载器（新增）
• core.py — 新增 --html / --summary / --config / --check-update 标志；自动更新检查现改为主动选择加入，且默认使用附带的离线数据库。

完整详情和署名信息：NOTICE.md。

测试

pip install pytest PyYAML
pytest

许可证

MIT — 详见 LICENSE。原始作品 © 2019 Sherlock Project； TraceHunt 修改部分 © 2026 VictorLin。