xpux/CrossTrace
GitHub: xpux/CrossTrace
CrossTrace 通过对多个社交媒体平台导出的粉丝/关注列表进行模糊匹配和图谱分析，实现跨平台的同一用户识别与社交关系映射。
Stars: 9 | Forks: 1
# CrossTrace
CrossTrace 接收从任意社交媒体平台导出的原始粉丝/关注列表，并对它们进行分析，以跨平台寻找目标用户、映射他们的社交圈，并通过用户名和显示名称对跨平台匹配进行评分。无需 API。无需抓取。只需使用你已有的文件。
## 快速开始
```
git clone https://github.com/xpux/CrossTrace.git
cd CrossTrace
pip install -r requirements.txt
python crosstrace.py --init
```
`--init` 会在首次运行时创建该工具所需的所有文件和文件夹。之后，将你导出的列表放入 `data/users/me/` 并运行：
```
python crosstrace.py
```
## 功能特性
跨平台匹配：在 TikTok、Instagram、Twitter 等平台上寻找同一个人
模糊匹配：捕获 `johndoe`、`john_doe`、`johndoe_` 等变体并按置信度进行评分
显示名称匹配：同时使用用户名和显示名称作为信号，并具备脚本检测功能，从而实现阿拉伯语名称仅与阿拉伯语名称匹配，CJK 仅与 CJK 匹配等
双向关注检测：识别同时出现在粉丝和关注列表中的账号（互相关注关系），从而更深入地洞察每个平台分组内的双向连接
双向导出系统：以 CSV 和 JSON 格式输出每个分组的双向连接，以便进行外部分析和追踪
交互式双向选择：允许你选择特定的用户/平台分组，或对所有加载的数据集运行双向检测
双向评分集成：与单向关注相比，双向连接被视为更高置信度的关系，从而改善了分析中的关系权重
多用户 / 朋友圈模式：添加多个人的列表以映射共享的社交网络
发现模式：不知道你要找谁？添加多个用户的列表，该工具会找出在所有列表中出现频率最高的人
快速模式：在 config 中设置最低阈值，以便只有高置信度的匹配才会进入审查队列
前 N 个最高频用户：一眼查看在最多列表中出现的人，完全可自定义
持久化连接：经过多次运行后，找出那些在不同会话中反复出现的人
单平台检测：标记仅在一个平台上出现且未找到跨平台匹配的人
人工审查队列：将处于边缘的匹配项标记出来，供你确认、拒绝或标记为知名人物
知名人物过滤：标记名人和公众人物，使其永远不再出现在结果中
反馈学习：你确认/拒绝的决定将改善未来的评分
置信度分析：每个匹配都会解释其获得相应评分的原因
会话命名：每次运行都会保存到其专属文件夹，因此不会覆盖任何内容
统计摘要：每次运行后，查看最活跃的平台、联系最密切的用户以及已确认的匹配数
批量别名建议：该工具根据已确认的匹配建议别名，并允许你保存它们
已知信息系统：将你已有的关于目标的任何文件放入文件夹中，该工具会利用它们来提升匹配度
可自定义的忽略列表：从原始粘贴内容中剔除特定于平台的 UI 文本
别名词典：硬编码已知别名以实现自动确认
灵活的输出：CSV、JSON 或两者兼有
图谱导出：每次运行还会将发现的网络以真实的图谱格式写入 JSON、GraphML（适用于 Gephi、Cytoscape 或 yEd）以及一个可完全离线运行的单体自包含 HTML 查看器中
可脚本化：使用 `--target`、`--discovery`、`--session` 和 `--yes` 无需提示即可运行整个会话，从而轻松融入脚本和自动化流程
## 工作原理
### 1. 导出你的列表
前往任意社交媒体平台，导航到你的粉丝或关注列表，然后将内容复制粘贴到 `.txt` 文件中。原始粘贴内容通常如下所示：
```
John Doe
johndoe_
Following
Jane Smith
jane_smith
Follow Back
```
CrossTrace 会自动剔除 `Follow`、`Following`、`Followers`、`Follow Back` 等 UI 文本，仅保留用户名和显示名称。你可以在 `ignorelist.txt` 中自定义要剔除的内容。
### 2. 设置你的文件
将你的文件放在 `data/users/` 文件夹中。你要添加列表的每个人都会拥有自己的子文件夹。请使用以下精确格式命名你的文件：
```
{platform}_{followers or following}{number}.txt
```
末尾的数字按平台对文件进行分组：所有具有相同数字的文件属于同一个平台。开头的平台名称只是一个可读性标签。
示例：
```
CrossTrace/
├── config.json
├── ignorelist.txt
├── aliases.txt
├── target.txt
├── crosstrace.py
└── data/
├── known/
└── users/
├── me/
│ ├── tiktok_followers1.txt
│ └── tiktok_following1.txt
├── friend_a/
│ ├── instagram_followers2.txt
│ └── instagram_following2.txt
└── friend_b/
├── tiktok_followers1.txt
└── instagram_followers2.txt
```
有效的文件名示例：
```
tiktok_followers1.txt ✓
instagram_following2.txt ✓
twitter_followers3.txt ✓
tiktok_followers.txt ✗ (missing number)
followers1.txt ✗ (missing platform name)
tiktok1.txt ✗ (missing followers/following)
```
### 3. 设置目标（或留空）
在 `target.txt` 中，写入你要查找的用户名：
```
johndoe_
```
将其留空，CrossTrace 会在你运行时于终端中询问你。如果也将提示留空，则会以发现模式运行。
### 4. 运行 CrossTrace
```
python crosstrace.py
```
CrossTrace 会在启动时要求你为会话命名。每个会话都会保存到 `output/` 下的专属文件夹中，因此绝不会覆盖之前的运行记录。
## 模式
### 模式 1：已知目标
你知道你要找谁。将他们的用户名放在 `target.txt` 中，或在出现提示时输入。CrossTrace 会在所有列表中搜索该用户名及相近的变体，然后映射他们在各平台间的双向连接。
仅使用你自己的列表即可工作，无需其他用户。
### 模式 2：发现模式
你没有特定的目标。将所有内容留空，CrossTrace 会找出出现在多个用户列表中的所有人，并根据你的群体中有多少人关注他们来进行排名。
重要提示：发现模式需要至少两个用户的列表才能工作。它会寻找人与人之间的交集：因此，如果 `data/users/` 中只有你的列表，就没有可交叉比对的内容，并且不会返回任何结果。要使用发现模式，请在你的列表旁，在另一个属于他们自己的子文件夹（例如 `data/users/friend_a/`）下添加第二个人的列表。添加的人越多，结果就越好。
## 数据越多，效果越好
CrossTrace 获取的数据越多，准确度就会显著提升。每个人的平台越多，意味着可以在更多平台上寻找匹配项。包含更多人的文件夹意味着可以进行更多的交叉比对。包含反馈的运行次数越多，意味着评分系统会学习你的决定，并随着时间的推移自动确认模式。随着你添加的数据越来越多，你要找的人自然会浮现出来。
## 已知信息系统
如果你已经拥有关于目标的文件：笔记、旧用户名、你手动打出来的个人简介截图、任何东西：你可以把它们放进一个文件夹里，CrossTrace 会读取它们并利用看起来有用的信息来提升匹配分数。文件格式和命名无关紧要。
在 `config.json` 中进行配置：
```
"known_info": {
"enabled": true,
"mode": "global",
"global_path": "data/known",
"target_path": "data/known/{target}"
}
```
有三种可用模式。Global 在每次运行时都会加载 `data/known/`，无论目标是谁。Target 仅在搜索特定人物时加载 `data/known/{target}/`。Both 会同时加载这两个文件夹。
示例结构：
```
data/known/
├── general_notes.txt ← loaded in global mode
├── old_usernames.md ← loaded in global mode
└── johndoe/ ← loaded in target mode when target = johndoe
├── bio_notes.txt
└── known_accounts.txt
```
当这些文件中的提示匹配到某个条目时，它会显示在审查期间的 `why:` 行以及总结中。
## 置信度等级
| 等级 | 分数 | 操作 |
|------|-------|--------|
| 自动确认 | 95–100% | 直接保存到结果中 |
| 快速审查 | 75–94% | 标记以便快速检查 |
| 人工审查 | 50–74% | 需要仔细审查 ⚠️ |
| 弱匹配 | 50% 以下 | 优先级低，单独列出 |
分数是根据用户名相似度（模糊匹配）、显示名称相似度（脚本感知）、双向关注检测、平台间共同的双向连接、常见的用户名模式（添加了 `_`、附加了数字、替换了 `.`）、该人是同时出现在粉丝和关注列表中还是仅出现在其中一个中、别名词典命中情况、已知信息提示，以及在多用户模式下关注他们的种子用户数量来计算的。
## 审查模式
脚本运行后，处于边缘的匹配项将排队等待人工审查。每个案例都会并排显示两个条目及其置信度分数、一行解释该分数的 `why:`，以及三个选项：
```
WARNING: Check each manual case carefully before pressing Yes.
This tool can make mistakes.
[1/7] MANUAL REVIEW: 67%
A: mikegaming / Mike Gaming (tiktok)
B: mike_g / Mike G (instagram)
why: username similarity 71%, common username variation pattern
(1) Yes: same person
(2) No: different people
(3) Famous / not important: skip
```
选项 1 将他们确认为同一个人，保存到结果中，将分数提升至 100，并反馈到未来的评分中。
选项 2 拒绝该匹配，并在未来的运行中惩罚相似的模式。
选项 3 将他们标记为知名人物或不相关，将他们保存到 `famous.json` 中，并在所有未来的运行中永久过滤他们。
跨平台审查之后，单平台条目（仅在找到一个平台且在其他平台上没有匹配的人）将单独显示，并提供相同的 1/2/3 选项。
在每次运行结束时，CrossTrace 会建议可以添加为别名的已确认配对，并允许你批准或跳过每一个配对。
你的决定将持久化保存在 `feedback.json` 中，并随着时间的推移提高评分的准确性。
## 命令行参考
运行不带任何参数的 `python crosstrace.py` 会引导你以交互方式命名会话并输入目标。以下参数允许你跳过提示或运行其他命令。
| 参数 | 功能 |
|------|--------------|
| `--init` | 创建 CrossTrace 需要的文件夹和文件，然后退出 |
| `--target USERNAME` | 针对此目标运行，无需提示 |
| `--discovery` | 强制进入发现模式，无需提示 |
| `--session NAME` | 命名会话，无需提示 |
| `--yes`, `-y` | 非交互式：自动命名会话，无提示，跳过审查 |
| `--no-review` | 运行匹配，但跳过人工审查队列 |
| `--graph FORMATS` | 选择图谱格式，以逗号分隔的列表，如 `json,graphml,html` |
| `--no-graph` | 跳过本次运行的图谱导出 |
| `--dry-run` | 预览审查队列，不保存任何内容 |
| `--search USERNAME` | 在所有加载的列表中查找用户名 |
| `--compare A B` | 比较过去的两个会话 |
| `--summary SESSION` | 重新打印过去某个会话的摘要 |
| `--history USERNAME` | 显示某个用户名在各会话中的分数 |
| `--export-aliases` | 将已确认的匹配直接导出到 `aliases.txt` |
| `--stats-only` | 打印上一次会话的统计数据，无需重新运行 |
| `--reset` | 擦除 `feedback.json`、`famous.json` 和 `history.json` |
| `--version` | 打印版本信息 |
一个完全脚本化的发现模式运行，无提示，仅限 HTML 图谱：
```
python crosstrace.py --yes --discovery --session friday_sweep --graph html
```
## 图谱输出
CrossTrace 是一个社交图谱分析器，因此每次运行时，它还会重建其发现的网络，并在会话文件夹下以三种方式将其写入。
`graph.json` 是一个简单的节点和边结构，你可以在任何地方加载。如果你想对大型网络进行布局或分析，`graph.graphml` 可直接在 Gephi、Cytoscape 和 yEd 等网络分析工具中打开。`graph.html` 是一个可以在任何浏览器中打开的单体自包含文件：它嵌入了数据并渲染出一个支持拖拽、缩放、搜索和详情面板的交互式力导向视图。它不加载任何外部脚本，也不发出任何网络请求，因此可以完全离线工作，并将所有数据保留在你的机器上，这与该工具的其余部分保持一致。
在目标模式下，节点是账户，边是由置信度加权的人同匹配。在发现模式下，节点是跨列表出现的人以及关注他们的种子用户，这样你就能看到谁处于群体的中心。
使用 `--graph json,graphml,html` 为每次运行选择格式，使用 `--no-graph` 将其关闭，或者在 `config.json` 中设置默认值：
```
"graph": {
"formats": ["json", "graphml", "html"]
}
```
```
{
"min_match_threshold": 30,
"output_format": ["csv", "json"],
"review_mode": true,
"top_results": 5,
"quick_mode": false,
"quick_threshold": 70,
"min_username_length": 2,
"graph": {
"formats": ["json", "graphml", "html"]
},
"known_info": {
"enabled": true,
"mode": "global",
"global_path": "data/known",
"target_path": "data/known/{target}"
}
}
```
| 选项 | 默认值 | 描述 |
|--------|---------|-------------|
| `min_match_threshold` | `30` | 不显示低于此置信度 % 的匹配 |
| `output_format` | `["csv", "json"]` | 输出格式 |
| `review_mode` | `true` | 在运行后启用交互式人工审查 |
| `top_results` | `5` | 在摘要中显示多少个排名靠前的活跃人物 |
| `quick_mode` | `false` | 在审查队列中仅显示高于 `quick_threshold` 的匹配 |
| `quick_threshold` | `70` | 开启快速模式时，要在审查队列中出现的最低分数 |
| `min_username_length` | `2` | 忽略短于此长度的已解析用户名 |
| `graph.formats` | `["json","graphml","html"]` | 每次运行写入的图谱格式 |
| `known_info.enabled` | `true` | 开启或关闭已知信息系统 |
| `known_info.mode` | `"global"` | 可选：`global`、`target`、`both` |
| `known_info.global_path` | `"data/known"` | 全局已知信息文件夹的路径 |
| `known_info.target_path` | `"data/known/{target}"` | 针对特定目标文件夹的路径模板 |
### `ignorelist.txt`
要从原始粘贴内容中剔除的单词或短语。每行一个条目。预填充了常见的平台 UI 文本：
```
Following
Followers
Follow Back
Follow
Suggested
Verified
Mutual Follow
```
添加你的平台在复制列表时包含的任何额外文本。
### `aliases.txt`
同一个人的已知别名。CrossTrace 会自动确认这些别名，靠猜测：
```
mikegaming = mike_gaming = mikeg
john_doe = johndoe = jdoe99
```
此文件以 `aliases.example.txt` 的形式发布，`--init` 会在首次运行时将其复制为 `aliases.txt`。由于真实的别名是人们账户之间已确认的关联，因此 `aliases.txt` 被 git 忽略，永远不会被提交。
## 输出
每次运行都会保存到 `output/session_name/` 下其专属的文件夹中。
| 文件 | 内容 |
|------|----------|
| `results_confirmed.csv/json` | 自动确认的跨平台匹配 |
| `results_review.csv/json` | 人工审查队列及你的决定 |
| `results_weak.csv/json` | 低置信度匹配（低于阈值） |
| `summary.md` | 完整运行的人类可读摘要报告 |
| `graph.json` | 由节点和边构成的已发现网络 |
| `graph.graphml` | 适用于 Gephi、Cytoscape 或 yEd 的相同图谱 |
| `graph.html` | 自包含的离线查看器；可在任何浏览器中打开 |
输出示例：
```
============================================================
CROSSTRACE: RESULTS SUMMARY
============================================================
Total pairs analysed: 348
AUTO-CONFIRMED: 12
QUICK REVIEW: 8
MANUAL REVIEW: 7
WEAK: 321
TOP 5 MOST PREVALENT
johndoe_ / John Doe | seen in 2 platform(s): instagram, tiktok
jane_smith | seen in 2 platform(s): instagram, tiktok
AUTO-CONFIRMED
johndoe_ (instagram) → johndoe_ (tiktok) | 100%
why: username exact/near match (100%)
jane_smith (instagram) → jane_smith (tiktok) | 100%
why: username exact/near match (100%)
============================================================
CROSSTRACE: SESSION STATS
============================================================
folders loaded: 3
total lists loaded: 6
confirmed matches: 12
famous filtered out: 4
most active platform: instagram (18 confirmed entries)
```
## 重置记忆
要擦除所有学习到的状态，请运行 `python crosstrace.py --reset`。这将在一步操作中清除 `feedback.json`（你的确认/拒绝决定）、`famous.json`（被过滤的公众人物）和 `history.json`（过往会话记录）。
## 安装
```
git clone https://github.com/xpux/CrossTrace.git
cd CrossTrace
pip install -r requirements.txt
```
你也可以将其作为包安装，这会在你的路径中添加一个 `crosstrace` 命令：
```
pip install .
crosstrace --version
```
要求：Python 3.8+ 和 `rapidfuzz`。
适用于 Windows、Linux 和 Mac。
## 隐私
CrossTrace 完全基于你提供的文件进行工作。它不发出任何网络请求，不调用任何 API，也不会将任何数据发送到任何地方。一切都在你的机器上本地运行。
## 免责声明
本工具旨在对你拥有合法访问权限的数据进行个人使用。你有责任确保在使用时遵守你所导出数据的任何平台的服务条款，并符合适用的隐私法律。
标签：ESC4, Homebrew安装, OSINT, Python, 代码示例, 多模态安全, 数据分析, 无后门, 模糊匹配, 社交图谱, 跨平台匹配, 逆向工具