今日开源[第16期]soxoj/maigret
soxoj/maigret 项目分析
分析日期：2026-06-13
项目地址：https://github.com/soxoj/maigret
一、项目介绍
1.1 项目概述
Maigret 是一款强大的开源 OSINT（开源情报）工具，其名称来源于法国侦探小说家乔治·西默农笔下的虚构侦探朱尔斯·梅格雷（Jules Maigret）。该工具的核心能力是：仅通过一个用户名（username），即可在数千个网站上收集关于某个人的完整档案。
Maigret 是 Sherlock 项目的一个易用且功能强大的分支（fork）。它无需任何 API 密钥，通过检查海量网站上的账户存在性，并从网页中抓取所有可用信息来生成档案。
1.2 项目地址与官网
| 项目 | 链接 |
|---|---|
| GitHub 仓库 | https://github.com/soxoj/maigret |
| 官方文档 | https://maigret.readthedocs.io |
| PyPI 主页 | https://pypi.org/project/maigret |
| 在线 Telegram Bot | https://t.me/osint_maigret_bot |
| 演示视频 | https://asciinema.org/a/Ao0y7N0TTxpS0pisoprQJdylZ |
1.3 项目状态
- 当前版本：0.6.1（截至 2026-05-15）
- 许可证：MIT License
- 作者：Soxoj (soxoj@protonmail.com)
- 提交次数：1,378+
- 支持站点：3,159 个
1.4 项目示意图
README 中包含的主要示意图/截图：
- 项目 Logo:
static/maigret.png - Web 界面启动截图:
static/web_interface_screenshot_start.png - Web 界面结果截图:
static/web_interface_screenshot.png - HTML 报告截图:
static/report_alexaimephotography_html_screenshot.png - XMind 8 报告截图:
static/report_alexaimephotography_xmind_screenshot.png - 演示视频 (asciinema): https://asciinema.org/a/Ao0y7N0TTxpS0pisoprQJdylZ
二、项目亮点
2.1 核心亮点
-
超大规模站点支持
- 支持 3,000+ 网站（截至 2026 年 6 月，具体为 3,159 个站点）
- 默认检查流量排名前 500 的站点，可通过
-a参数扫描全部
-
无需 API 密钥
- 完全基于网页抓取和公开信息，无需注册任何第三方服务
-
被专业平台认证采用
- 被 Social Links、UserSearch 等专业 OSINT 平台官方认证和使用
2.2 主要功能
| 功能 | 描述 |
|---|---|
| 个人资料页面解析 | 通过 socid_extractor 库从个人资料页提取个人信息、其他账户链接等 |
| 递归搜索 | 自动从发现的链接和资料中提取新的用户名/ID，并启动新一轮搜索 |
| 用户名排列组合 | --permute 参数可基于多个输入生成可能的用户名变体 |
| 标签过滤 | 支持按标签（网站类别如 photo/dating/finance，或国家如 us/cn/ru）筛选目标站点 |
| 审查与验证码检测 | 能检测常见的审查页面、CloudFlare 验证码等反爬机制 |
| 请求重试 | 对临时错误自动重试，默认 1 次 |
| 数据库自检 | --self-check 模式可验证站点数据库检测逻辑的正确性 |
| Cloudflare 绕过 | 支持通过 FlareSolverr 或 CloudflareBypassForScraping 绕过 Cloudflare JS 挑战 |
| 激活机制 | 对需要额外认证的站点，自动触发激活函数更新认证信息 |
| AI 分析模式 | --ai 参数可将原始搜索结果发送给 OpenAI 兼容的 API，生成人类可读调查报告 |
| Web 界面 | 内置基于 Flask 的 Web UI，支持结果可视化图谱和一键下载所有格式报告 |
| 多种报告格式 | 支持 HTML、PDF、TXT、CSV、JSON、XMind 8 思维导图、Markdown、交互式 D3 图谱 |
| Tor / I2P / 代理支持 | 支持通过 SOCKS5/HTTP 代理、Tor、I2P 网关路由请求 |
| Python 库嵌入 | 可作为 Python 包嵌入到其他项目中，通过 import maigret 以编程方式调用 |
三、项目运行环境与运行条件
3.1 运行环境
| 项目 | 说明 |
|---|---|
| Python 版本 | 3.10 或更高版本，推荐 Python 3.11 |
| 支持平台 | 跨平台（OS Independent），支持 Windows、Linux、macOS |
| Windows 用户 | 提供独立的 maigret_standalone.exe 可执行文件，无需安装 Python |
3.2 构建与包管理
- 使用 Poetry 作为构建系统和依赖管理工具
pyproject.toml中定义构建后端为poetry.core.masonry.api
3.3 核心依赖（生产环境）
| 依赖 | 用途 |
|---|---|
aiohttp ^3.12.14 |
异步 HTTP 客户端 |
aiohttp-socks |
SOCKS 代理支持 |
aiodns |
异步 DNS 解析 |
requests ^2.32.4 |
同步 HTTP 请求 |
requests-futures |
异步请求封装 |
curl-cffi >=0.14,<1.0 |
TLS 指纹模拟（绕过反爬） |
cloudscraper ^1.2.71 |
Cloudflare 绕过 |
flask ^3.1.1 [async] |
Web 界面后端 |
jinja2 ^3.1.6 |
报告模板渲染 |
lxml >=6.0.2,<7.0 |
HTML/XML 解析 |
socid-extractor |
身份信息提取 |
networkx ^2.6.3 |
图数据构建 |
pyvis ^0.3.2 |
交互式网络可视化 |
reportlab ^4.4.3 |
PDF 报告生成 |
xhtml2pdf ^0.2.11 (optional) |
HTML 转 PDF |
xmind ^1.2.0 |
XMind 思维导图 |
stem ^1.8.1 |
Tor 控制协议 |
torrequest ^0.1.0 |
Tor 请求 |
alive_progress ^3.2.0 |
进度条 |
colorama ^0.4.6 |
终端颜色输出 |
pycountry |
国家代码数据 |
chardet |
字符编码检测 |
3.4 可选依赖
- PDF 支持:
pip install 'maigret[pdf]'会安装xhtml2pdf、arabic-reshaper、python-bidi。由于底层pycairo在 Linux/macOS 上需要系统级libcairo和pkg-config，默认跳过。
3.5 开发依赖
pytest/pytest-asyncio/pytest-cov/pytest-rerunfailuresflake8/black/mypy/coverage/tuna
3.6 安装方式
# 通过 pip 安装
pip install maigret
# 安装 PDF 支持
pip install 'maigret[pdf]'
# 通过 Docker 运行
docker run soxoj/maigret
# Windows 用户可直接下载 standalone.exe
四、项目代码介绍
4.1 代码架构图
maigret/
├── .githooks/ # Git hooks（如 pre-commit 更新站点统计）
├── .github/ # GitHub Actions 工作流、Issue 模板、FUNDING
├── docs/ # Sphinx 文档源文件（RST 格式），含中文翻译
│ └── source/locale/zh_CN/
├── maigret/ # 核心 Python 包
│ ├── __init__.py # 包入口，暴露 search/cli/Notifier
│ ├── __main__.py # python -m maigret 入口
│ ├── __version__.py # 版本号
│ ├── activation.py # 站点激活机制（JWT/Cookie 刷新）
│ ├── ai.py # AI 分析模式（OpenAI API 调用）
│ ├── checking.py # 核心异步检查逻辑（~62KB，最大文件）
│ ├── db_updater.py # 站点数据库自动更新
│ ├── error_detection.py # 错误页面检测
│ ├── errors.py # 自定义异常类
│ ├── executors.py # 异步执行器（并发控制）
│ ├── extractors.py # 用户名/ID 提取器
│ ├── maigret.py # CLI 主入口和参数解析（~37KB）
│ ├── notify.py # 终端通知和输出格式化
│ ├── permutator.py # 用户名排列组合
│ ├── report.py # 报告生成（HTML/PDF/CSV/JSON/XMind/Graph）
│ ├── result.py # 检查结果数据模型
│ ├── settings.py # 配置管理
│ ├── sites.py # 站点数据库模型
│ ├── submit.py # 新站点提交逻辑
│ ├── types.py # 类型定义
│ ├── utils.py # 工具函数
│ ├── web/ # Web 界面
│ │ ├── app.py # Flask 应用
│ │ ├── static/ # CSS/JS 静态资源
│ │ └── templates/ # HTML 模板
│ └── resources/ # 资源文件
│ ├── data.json # 站点数据库（~1.2MB，核心配置）
│ ├── db_meta.json # 数据库元数据
│ ├── settings.json # 默认设置
│ ├── ai_prompt.txt # AI 分析提示词模板
│ └── simple_report*.tpl # 报告模板
├── static/ # 仓库级静态资源（截图、示例报告）
├── tests/ # 测试套件
├── utils/ # 外部工具脚本
├── pyinstaller/ # PyInstaller 打包配置
├── Dockerfile # Docker 镜像构建
├── Installer.bat # Windows 安装脚本
├── wizard.py # 设置向导
├── pyproject.toml # Poetry 配置
├── poetry.lock # 锁定依赖版本
├── sites.md # 自动生成的站点列表文档
└── README.md / README.zh-CN.md
4.2 核心模块介绍
4.2.1 maigret/sites.py — 站点数据库模型
MaigretSite: 单个站点的数据模型，包含 URL 模板、检测类型（check_type）、存在/不存在字符串（presense_strs/absence_strs）、标签、保护类型、引擎等。MaigretEngine: 站点引擎模板（如论坛通用检测逻辑）。MaigretDatabase: 管理所有站点，支持按排名、标签、名称过滤，处理镜像站点（mirror）逻辑。
4.2.2 maigret/checking.py — 核心检查引擎
- 包含主要的异步搜索函数
maigret() - 支持多种
checkType:message（最可靠，检查 HTML 内容）、status_code、response_url - 处理并发连接限制、超时、重试、代理、TLS 指纹模拟（
curl_cffi）、Cloudflare 绕过 - 定义
SUPPORTED_IDS支持的标识符类型
4.2.3 maigret/maigret.py — CLI 入口
- 参数解析（
ArgumentParser），定义所有 CLI 标志 - 协调搜索流程：解析参数 → 加载数据库 → 执行检查 → 生成报告
- 支持
--web启动 Web UI
4.2.4 maigret/report.py — 报告生成
- 支持 CSV、TXT、HTML、PDF、JSON、XMind、Markdown、交互式 Graph（NetworkX + PyVis）
generate_report_context(): 构建报告上下文（统计标签、国家、兴趣、推测数据等）
4.2.5 maigret/web/app.py — Web 界面
- 基于 Flask 的异步 Web 应用
- 提供搜索表单、结果图谱展示、报告下载页面
4.2.6 maigret/resources/data.json — 站点数据库
- 机器可读的核心配置文件（约 1.2MB）
- 包含 3,000+ 站点的检测规则、URL 模板、标签、排名、保护类型等
4.3 核心代码解析
4.3.1 核心检查逻辑（checking.py）
checking.py 是整个项目最大的文件（约 62KB），包含了核心的异步检查逻辑：
# 核心异步搜索函数
async def maigret(username, site_dict, query_notify=None,
timeout=10, proxy=None, tor_proxy=None,
i2p_proxy=None, recursive_search=False,
id_type='username', debug=False,
executor=None, cookies=None,
forced=False, no_progressbar=False,
retries=1, check_progress_callback=None):
"""
在多个网站上检查用户名是否存在
参数:
username: 要搜索的用户名
site_dict: 要检查的网站字典
query_notify: 查询通知对象
timeout: 请求超时时间
proxy: 代理设置
tor_proxy: Tor 代理
i2p_proxy: I2P 代理
recursive_search: 是否启用递归搜索
id_type: 标识符类型
debug: 调试模式
executor: 异步执行器
cookies: Cookie 设置
forced: 强制重新检查
no_progressbar: 是否禁用进度条
retries: 重试次数
check_progress_callback: 进度回调函数
"""
4.3.2 站点检测机制
Maigret 支持多种检测类型（checkType）：
-
message（最可靠）- 检查 HTML 内容中是否包含特定字符串
- 通过
presense_strs和absence_strs判断账户是否存在
-
status_code- 通过 HTTP 状态码判断（如 404 表示不存在）
-
response_url- 通过最终响应 URL 判断（如重定向到登录页表示不存在）
4.3.3 反检测机制
# TLS 指纹模拟（使用 curl_cffi）
from curl_cffi import requests as curl_requests
# Cloudflare 绕过
import cloudscraper
# Tor 支持
import stem.control
from torrequest import TorRequest
4.3.4 AI 分析模式（ai.py）
# AI 分析模式将原始搜索结果发送给 OpenAI 兼容的 API
# 生成包含以下信息的调查报告：
# - 真实姓名
# - 位置
# - 职业
# - 兴趣
# - 语言
# - 置信度
4.3.5 递归搜索机制
# 递归搜索流程：
# 1. 在站点 A 找到用户资料
# 2. 从资料中提取其他平台的链接/用户名
# 3. 使用新发现的用户名在站点 B、C、D... 继续搜索
# 4. 重复直到没有新发现或达到最大递归深度
五、项目的应用、优点和不足
5.1 应用场景
-
OSINT 调查
- 安全研究员、记者、执法人员通过用户名追踪目标人物的数字足迹
-
社交媒体分析
- 分析某人在不同平台上的账户分布和关联
-
网络安全与渗透测试
- 评估个人或企业的信息暴露面（attack surface）
-
账户归属分析
- 通过递归搜索和用户名排列组合，发现同一人在不同平台上的关联账户
-
自动化情报收集
- 作为 Python 库嵌入到更大的 OSINT 自动化工作流中
5.2 项目优点
| 优点 | 说明 |
|---|---|
| 覆盖范围广 | 3,000+ 站点，涵盖社交、职业、购物、视频、代码托管、论坛等各类平台 |
| 零 API 成本 | 无需申请任何 API 密钥即可使用全部功能 |
| 递归关联发现 | 能从已发现账户中自动提取新线索并持续追踪，形成关系网络 |
| 多格式报告 | 支持 HTML、PDF、思维导图、交互式图谱等多种可视化报告 |
| 反检测能力 | 支持 TLS 指纹模拟、Cloudflare 绕过、Tor/I2P/代理，具备一定的反反爬能力 |
| AI 辅助分析 | 集成大语言模型，可将原始数据转化为人类可读的调查摘要 |
| 易部署 | 支持 pip、Docker、Windows 独立可执行文件、云 Shell、Telegram Bot 等多种使用方式 |
| 活跃维护 | 数据库和站点检测规则持续更新，社区贡献活跃（1,378+ commits） |
5.3 项目不足与待改进
| 不足 | 说明 |
|---|---|
| 站点失效与误报 | 网站改版、关闭或增加反爬机制会导致检测规则失效，需要频繁的 --self-check 和维护更新。部分站点存在假阳性 |
| 反爬限制 | 对于 cf_js_challenge、aws_waf_js_challenge 等高级 JS 挑战，目前仍需外部工具且标记为实验性功能 |
| IP 信誉问题 | 从数据中心/云服务器 IP 运行时，大量站点（如 Reddit、Patreon）会阻止访问，需要住宅代理 |
| PDF 依赖复杂 | PDF 报告需要系统级图形库（libcairo），在部分 Linux/macOS 环境安装不便 |
| XMind 兼容性 | XMind 8 思维导图与 XMind 2022+ 不兼容 |
| 法律与伦理风险 | 工具本身声明仅供教育和合法用途，但存在被滥用的风险，需遵守 GDPR、CCPA 等数据保护法规 |
| 测试覆盖率 | 当前测试覆盖率约 58%，仍有提升空间 |
5.4 社区与生态
- 被专业平台采用：Social Links、UserSearch 等 OSINT 平台官方认证和使用
- 活跃社区：GitHub Issues 和 Discussions 中有大量用户反馈
- 持续更新：数据库和站点检测规则持续更新，频繁发布修复
- 多语言支持：文档提供中文翻译
六、总结
soxoj/maigret 是一款功能强大、覆盖广泛的开源 OSINT 工具，仅通过一个用户名即可在 3,000+ 网站上收集个人档案。项目具有零 API 成本、递归关联发现、多格式报告、反检测能力、AI 辅助分析等核心优势，支持多种部署方式（pip、Docker、独立可执行文件、Telegram Bot）。
项目采用 Python 3.10+ 开发，使用 Poetry 管理依赖，核心架构包括站点数据库模型、异步检查引擎、报告生成系统和 Web 界面。虽然面临站点失效、反爬限制、IP 信誉等挑战，但活跃的社区维护和持续更新使其成为 OSINT 领域的重要工具。
浙公网安备 33010602011771号