allsmog/tracelens-osint

**TraceLens** 是一款开源的 **用户名 OSINT** 和 **数字足迹** 工具，适用于信任与 安全、欺诈、威胁情报、新闻调查、品牌保护以及授权的安全测试工作。 它不仅仅是另一个原始的用户名抓取工具——它掌控着发现*之后*的层面：**验证、 证据、来源可靠性和报告**。当典型的用户名搜索工具返回一堆 “可能”的链接时，TraceLens 返回的是**具有置信度评分、感知来源且站得住脚的证据**。 ## 目录 - [为什么选择 TraceLens](#-why-tracelens) - [TraceLens 与 Sherlock 的对比](#-tracelens-vs-sherlock) - [安装](#-install) - [快速入门](#-quickstart) - [可靠结果的呈现形式](#-what-a-defensible-result-looks-like) - [工作原理](#-how-it-works) - [CLI 参考](#-cli-reference) - [库的用法](#-library-usage) - [AI 辅助验证](#-ai-assisted-verification) - [HTTP API](#-http-api) - [来源目录与 Sherlock 导入](#-source-catalog) - [配置](#-configuration) - [合理使用](#-acceptable-use) - [常见问题](#-faq) - [贡献](#-contributing) - [许可与致谢](#-license--acknowledgements) ## ⭐ 为什么选择 TraceLens 现有的用户名 OSINT 工具擅长*发现*，但在*判断*方面表现薄弱。构建 TraceLens 是为了 减少误报，并生成分析师可以完全信赖的输出： - 🎯 **置信度评分，而非简单的是/否。** 每个结果都是 `[0,1]` 范围内的校准分数，并带有 其背后精确的带符号信号——透明，绝不是黑盒。 - 🧾 **证据捕获。** 页面标题、规范 URL、Open Graph 元数据、**SHA-256 内容 哈希**、重定向链、延迟以及服务主机——因此发现的结果是可复现且经得起检验的。 - 🩺 **感知来源健康状况。** 使用已知的用户名探测来源，以查看哪些目前是健康的、损坏的 或被阻止的——而不是盲目信任过时的站点列表。 - 🛡️ **被阻止时绝不撒谎。** 反机器人挑战页面（即使是 HTTP 200）也会被报告为 `blocked`，绝不会错误地报告为 `found`。Cloudflare 过渡页无法伪装成匹配结果。 - 🤖 **AI 辅助验证。** 对可能属于同一个人的资料进行聚类，标记误报，并 使用 Claude 总结证据——并提供无需 API 密钥的确定性后备方案。 - 📄 **清晰的报告。** JSON、CSV、XLSX 以及一个独立且带有时间戳的 HTML 报告。 - 🌐 **CLI、库和 HTTP API。** 外加案例工作区、审计日志和定时复查。 - 🧩 **自带来源** —— 或者导入整个 Sherlock 目录（约 480 个站点）。 **适用对象：** 信任与安全分析师、欺诈调查员、威胁情报团队、 记者与研究人员、品牌保护团队以及授权的安全测试人员。 ## 🆚 TraceLens 与 Sherlock 的对比 [Sherlock](https://github.com/sherlock-project/sherlock) 是非常出色的前作，在广度上表现优异。 TraceLens 的目标在于*保真度* —— 即更少的错误匹配和经得起检验的输出。（几个内置来源的 检测元数据是在 MIT 许可下从 Sherlock 派生的；请参阅 [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md）。） | | TraceLens | Sherlock | |---|---|---| | 结果模型 | **置信度评分 + 状态** (`found`/`possible`/`rejected`/`blocked`) | 二元结果 (`Claimed`/`Available`) | | 为什么匹配产生该评分 | **明确的带符号证据信号** | — | | 捕获的证据 | **标题、规范 URL、OG 标签、SHA-256、重定向、延迟** | 响应文本（调试用） | | 反机器人挑战页面 | **检测为 → `blocked`**（无错误匹配） | 狭窄的 WAF 指纹（仅限正文） | | 低可靠性的来源 | **上限为 `possible`** | 按表面价值信任 | | 身份聚类与误报标记 | **支持**（启发式 + AI） | — | | 报告 | **JSON / CSV / XLSX / HTML** | CSV / XLSX | | 案例工作区、审计日志、定时复查、HTTP API | **支持** | — | | 站点广度 | 43 个精选 **+ 导入全部 Sherlock 目录** | ~480 个内置 | | 请求方法 | GET / HEAD / POST / PUT | GET / HEAD / POST / PUT | **客观评价：** Sherlock 通常能发现*更多*账号（站点更多 + 使用浏览器 User-Agent）。 TraceLens 是为*精确性和可检验性*而构建的，并且可以引入 Sherlock 的广度来兼得 两者。TraceLens 有意**不提供任何规避功能**（它诚实地标明自己的身份）；如果你的 授权测试任务另有要求，请设置 `TRACELENS_USER_AGENT`。 ## 📦 安装 ``` pip install tracelens # core CLI + library pip install 'tracelens[ai]' # + Claude-backed verification pip install 'tracelens[api]' # + the FastAPI service pip install 'tracelens[screenshots]' # + Playwright screenshot capture pip install 'tracelens[xlsx]' # + Excel (.xlsx) report export pip install 'tracelens[all]' # everything ``` 从源码安装： ``` git clone https://github.com/allsmog/tracelens-osint.git cd tracelens-osint python -m venv .venv && source .venv/bin/activate pip install -e ".[dev,ai,api]" tracelens --help pytest ``` ## 🚀 快速入门 ``` # 在可靠 source 目录中搜索用户名 tracelens username vitalik # 解释每个 score 背后的每一个 signal tracelens username vitalik --confidence # 机器可读 / 保存的输出 tracelens username vitalik --json tracelens username vitalik --json-out scans/vitalik.json tracelens username vitalik --csv scans/vitalik.csv # Evidence-grade HTML 报告 tracelens username vitalik --report reports/vitalik.html # AI 辅助验证（identity clusters、false-positive flags、summary） tracelens username vitalik --verify # 缩小扫描范围 tracelens username vitalik --sources github,gitlab,keybase tracelens username vitalik --categories development --min-reliability 0.8 # 检查哪些 source 当前确实处于健康状态 tracelens health ``` ## 🧾 可靠结果的呈现形式 ``` TraceLens results for 'torvalds' ┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Source ┃ Category ┃ Status ┃ Conf. ┃ Profile URL ┃ ┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ GitHub │ development │ found │ 0.85 │ https://github.com/... │ │ Keybase │ development │ found │ 0.85 │ https://keybase.io/... │ │ Hacker News │ community │ found │ 0.80 │ https://news.yc.../... │ └─────────────┴─────────────┴────────┴───────┴──────────────────────────┘ Found: 3 Possible: 0 Rejected: 0 Blocked: 0 Errors: 0 GitHub — found (0.85) +0.35 · Profile URL returned 200. Keybase — found (0.85) +0.35 · Page contains a profile marker: '"basics"'. ``` **状态含义：** `found`（确凿证据），`possible`（看似合理，但未确认），`rejected` （无该资料），`blocked`（该网站正在进行速率限制、阻止访问或正在显示反机器人挑战页面 — *结论不明确，绝非错误匹配*），`error`。 ## 🧠 工作原理 ``` flowchart LR U[username] --> C[catalog
select sources] C --> S[scanner
concurrency · rate limit · retries · cache] S --> A[source adapter
GET/HEAD/POST · detection] A --> CH{challenge /
blocked?} CH -- yes --> B[status: blocked] CH -- no --> D[detect: status_code /
message / response_url] D --> E[capture evidence
title · canonical · OG · sha256] E --> SC[confidence engine
signed signals + reliability cap] SC --> R[(UsernameScan)] R --> V[AI / heuristic verification
clusters · false positives] R --> O[reports: JSON · CSV · XLSX · HTML] R --> ST[cases · audit · scheduled re-checks · API] ``` 置信度是**带符号证据信号的透明总和**，在无偏倚的先验条件下得出，并带有两项 保护机制：低可靠性的来源无法仅凭单薄证据达到 `found` 状态，并且**反机器人挑战 页面会被报告为 `blocked`，而不是 `found`**。请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 ## 🖥️ CLI 参考 | 命令 | 用途 | | --- | --- | | `tracelens username ` | 扫描并评分用户名（`--json` `--report` `--json-out` `--csv` `--xlsx` `--sources` `--categories` `--min-reliability` `--nsfw` `--verify` `--confidence` `--no-cache` `--no-evidence` `--screenshots` `--catalog`）。使用 `{?}` 表示 `_`/`-`/`.` 变体。 | | `tracelens sources` | 列出来源目录（`--category`, `--json`） | | `tracelens import-sherlock -o ` | 将 Sherlock 目录转换为 TraceLens 格式 | | `tracelens health` | 使用已知的用户名探测来源，以验证检测是否仍然有效 | | `tracelens report -o out.html` | 从保存的扫描结果生成 HTML 报告 | | `tracelens diff ` | 显示两次扫描之间的变化 | | `tracelens cache info \| clear` | 检查或清除结果缓存 | | `tracelens case create \| list \| show \| scan \| delete` | 调查案例工作区 | | `tracelens schedule add \| list \| remove \| run-due` | 定时复查 / 监控 | | `tracelens serve` | 运行 HTTP API（`--host`, `--port`） | | `tracelens version` | 打印版本号 | ## 🐍 库的用法 ``` import asyncio from tracelens import scan_username from tracelens.ai import verify_scan from tracelens.report import write_html_report async def main(): scan = await scan_username("vitalik", sources=["github", "gitlab", "keybase"]) scan.verification = await verify_scan(scan) # Claude if configured, else heuristic print(scan.summary()) # {'found': 3, 'possible': 0, ...} for r in scan.matches: print(r.source_name, r.status.value, round(r.confidence, 2)) write_html_report(scan, "reports/vitalik.html") asyncio.run(main()) ``` ## 🤖 AI 辅助验证 验证层会*解释*证据——它不执行原始的发现工作。它对可能属于同一身份的资料进行聚类 （引用共享的证据），标记可能的误报， 并编写分析师可读的摘要。 在设置了 `ANTHROPIC_API_KEY` 并安装了 `[ai]` 扩展的情况下，TraceLens 会使用 **Claude (`claude-opus-4-8`)** 并利用受限的 JSON 输出，以得出结构化且可靠的判定。**如果没有 密钥，它会透明地回退到确定性的启发式验证器** —— 因此验证功能始终 可用，离线且免费。 ``` export ANTHROPIC_API_KEY=sk-ant-... tracelens username vitalik --verify ``` ## 🌐 HTTP API ``` pip install 'tracelens[api]' export TRACELENS_API_KEYS=key-one,key-two # require auth (recommended) tracelens serve --host 0.0.0.0 --port 8000 ``` `POST /v1/scan`，在 `/v1/cases` 管理调查，在 `/v1/health-check` 运行健康检查， 在 `/v1/schedules` 安排监控，并在 `/v1/audit` 读取审计日志。交互式 OpenAPI 文档位于 `/docs`。内置了 API 密钥验证和基于密钥的速率限制。请参阅 [docs/API.md](docs/API.md)。 ## 📚 来源目录 内置的目录（[`src/tracelens/data/sources.json`](src/tracelens/data/sources.json)）是一个 **精心挑选的可靠来源集合**，带有明确的检测元数据和针对每个 来源的可靠性先验值。你可以自带来源并将其合并到最上层： ``` tracelens username alice --catalog my-sources.json ``` 来源支持带有各自 payload 和 header 的 `GET`/`HEAD`/`POST`/`PUT`，因此基于请求体判断是否存在的 API 也能工作。有关格式以及如何添加来源，请参阅 [docs/CATALOG.md](docs/CATALOG.md)。 ### 🧩 引入 Sherlock 的广度 需要更广泛的覆盖？通过 TraceLens 引擎运行整个 **Sherlock** 站点列表（约 480 个来源）—— 包含置信度评分、证据、挑战检测等所有功能： ``` tracelens import-sherlock sherlock/data.json -o sherlock-catalog.json tracelens username alice --catalog sherlock-catalog.json # --catalog 也会自动检测原始 Sherlock data.json ``` ## ⚙️ 配置 所有设置都是以 `TRACELENS_` 为前缀的环境变量（外加常规的 `ANTHROPIC_API_KEY`）。请参阅 [`.env.example`](.env.example) 和 [docs/CONFIGURATION.md](docs/CONFIGURATION.md)。常见的配置： | 变量 | 默认值 | 含义 | | --- | --- | --- | | `TRACELENS_CONCURRENCY` | `20` | 最大同时来源检查数 | | `TRACELENS_RATE_LIMIT_PER_HOST` | `4.0` | 每个主机的最大请求/秒 | | `TRACELENS_CACHE_TTL_SECONDS` | `86400` | 结果缓存生存期 | | `TRACELENS_API_KEYS` | （无） | 用于该服务的逗号分隔 API 密钥 | | `ANTHROPIC_API_KEY` | （无） | 启用 Claude 验证器 | ## 🛡️ 合理使用 TraceLens 适用于合法的调查、信任与安全、欺诈防范、威胁 情报、新闻调查、品牌保护和授权的安全测试工作。 **请勿将 TraceLens 用于骚扰、跟踪、人肉搜索、非法监视、凭证滥用** **或规避访问控制。** 它不收集凭证，不绕过访问控制，并且不提供 任何隐身或规避功能。置信度评分和 AI 评估仅是调查辅助工具，并非 身份证明——在采取行动之前请多方印证。请参阅 [docs/ACCEPTABLE_USE.md](docs/ACCEPTABLE_USE.md)。 ## ❓ 常见问题 **TraceLens 是 Sherlock 的替代品吗？** 它们是互补的。Sherlock 以发现为主且覆盖面广；TraceLens 以验证为主且具备 证据级别——并且它可以[导入 Sherlock 的目录](#-bring-sherlocks-breadth) 来兼得两者。 **它需要 API 密钥或付费服务吗？** 不需要。完整的 CLI、库、证据捕获、报告和确定性验证器在没有 密钥的情况下即可工作。可选的 Anthropic API 密钥会将验证升级为 Claude。 **为什么结果是 `blocked` 而不是 `found`？** 该网站对我们进行了速率限制、返回了阻止状态，或者显示了反机器人挑战页面。这属于 结论不明确的情况——TraceLens 会如实报告，而不是猜测匹配。 **它可以扫描许多用户名或变体吗？** 可以——在用户名中使用 `{?}` 来表示 `_`/`-`/`.` 变体，或者在一个循环中调用 `scan_username`。 **支持哪些 Python 版本？** Python 3.11、3.12 和 3.13。 ## 📄 许可与致谢 MIT —— 请参阅 [LICENSE](LICENSE)。几个内置来源的检测元数据派生自基于 MIT 许可证的 [Sherlock 项目](https://github.com/sherlock-project/sherlock)；其声明保留在 [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md) 中。

**关键词：** username OSINT · username search · username enumeration · find accounts by username · social media reconnaissance · digital footprint · people search · threat intelligence · trust & safety · fraud investigation · brand protection · Sherlock alternative · Python OSINT tool ⭐ 如果 TraceLens 对您有帮助，请考虑为本仓库点个 Star。

标签：ESC4, OSINT, Python, 无后门, 特征检测, 用户名搜索, 网络足迹追踪, 逆向工具