命令行选项

用户名

maigret username1 username2 ...

可以用空格分隔传入多个用户名。不一定必须传入用户名 —— 还有其它运行模式(见下文)。

解析账号页面与在线文档

maigret --parse URL

Maigret 会尝试抽取该文档/账号所有者的信息(包括用户名和其它 ID),并以抽取到的用户名和 ID 进行搜索。示例见 从账号页面抽取信息 一节。

主要选项

各项选项也可以通过配置文件设置,参见 配置一节。

--tags —— 按标签筛选搜索站点:站点分类,或两位国家代码(不是语言代码!)。例如 photo、dating、sport;jp、us、global。一个站点可以关联多个标签。注意:标签体系目前尚未稳定。详见 独立章节。

--exclude-tags —— 从搜索中排除带有特定标签的站点(黑名单)。例如 --exclude-tags porn,dating 会跳过所有打上 porn 或 dating 标签的站点。可与 --tags 组合使用,在包含某些类别的同时排除另一些。详见 独立章节。

-n、--max-connections —— 允许的并发连接数 (默认:100)。

-a、--all-sites —— 扫描全部站点 (默认仅前 500 名)。

--top-sites —— 按 Majestic Million 排名扫描站点的数量 (默认:前 500 名)。

镜像站: 在按 Majestic Million 排名选出前 N 个站点(同时考虑 --tags、--use-disabled-sites 等)之后,Maigret 还可能额外加入一些站点 —— 它们的数据库字段 source 指向某个父平台,且该父平台(在包含已禁用站点进行排名时)落在 Majestic Million 的前 N 名内。例如,如果Twitter 在 Majestic Million 前 500 名内,即便 memory.lol 这样的镜像(source: Twitter)本身没有排名、按规则会被剔除,也仍会被加入。Instagram相关镜像(如 Picuki)同理:即便官方的 Instagram 条目被禁用、默认不被扫描,只要 Instagram 在父级排名的前 N 名内,其镜像就仍可能被纳入。最终的站点列表 = 排名前 N + 这些镜像(镜像数量没有固定上限)。

--timeout —— 等待站点响应的时长,单位为秒 (默认:30)。超时设得越长,越有机会从慢站点拿到结果;另一方面,这也会拉长整体结果汇总的时间。具体取值应结合自身网络带宽来权衡。

网络与代理选项

--proxy PROXY_URL / -p PROXY_URL —— 让所有检查都通过指定的 HTTP 或 SOCKS 代理。示例:socks5://127.0.0.1:1080、http://user:pass@proxy.example:3128。这是把整次运行都走 Tor(--proxy socks5://127.0.0.1:9050)、住宅代理或企业网关时应当使用的参数。无默认值。

--tor-proxy TOR_PROXY_URL —— 仅用于数据库中 .onion 站点的网关 (默认:socks5://127.0.0.1:9050)。明网站点不受影响 —— 对它们,Maigret 会使用你本机的直连,或者你设置的 --proxy。不传该参数时,.onion 站点会被静默跳过。

--i2p-proxy I2P_PROXY_URL —— 仅用于数据库中 .i2p 站点的网关 (默认:http://127.0.0.1:4444)。规则与 --tor-proxy 一致 —— 只对匹配的协议生效。

Maigret 不会替你启动 Tor 或 I2P 守护进程 —— 请先把它们跑起来。完整指南(包括 Tor 浏览器与系统 tor 端口的差别、Tails 操作系统下的配方、超时/重试调优等)请参见 Tor、I2P 与代理。

--cookies-jar-file —— Netscape 格式(即 cookies.txt)的自定义 cookie 文件。你可以在浏览器里安装对应扩展来导出自己的 cookie(Chrome、Firefox)。

--no-recursion —— 禁用页面解析,以及基于发现的其它用户名进行递归搜索。

--use-disabled-sites —— 把已禁用的站点也纳入搜索范围(可能产生大量误报)。

--id-type —— 指定标识符类型(默认:username)。支持的类型有:gaia_id、vk_id、yandex_public_id、ok_id、wikimapia_uid。目前必须同时加 -a,才能扫描支持自定义 ID 类型的站点 —— 站点会被自动筛选。

--ignore-ids —— 不对指定的用户名或其它 ID 发起搜索。适用于在多次重复扫描中,屏蔽已知与目标无关的用户名。

--db —— 从一个本地 JSON 文件,或一个在线的有效 JSON 文件加载 Maigret 数据库。详见下文 使用自定义站点数据库。

--no-autoupdate —— 禁用启动时的自动数据库更新检查。直接使用当前已缓存(或内置)的数据库,不做任何变动。

--force-update —— 在启动时强制执行一次数据库更新检查,忽略常规的检查间隔。强制更新结束后,本次运行剩余阶段相当于隐含开启了 --no-autoupdate。

--retries RETRIES —— 对临时性失败的请求,允许重启重试的次数。

--with-domains (实验性) —— 在执行普通 HTTP 检查的同时,通过 DNS(A 记录)再解析一小组 {username}.<tld> 模式。当前数据库中有 7 条记录走这条路径(.ddns.net、.com、.pro、.me、.biz、.email、.guru)。仅靠 DNS 的命中可能包括停放域名和通配符记录,所以应当把结果当作线索而非确认结果。参见 常见问题中关于 DNS 域名检查的条目。

--cloudflare-bypass (实验性) —— 将 protection: ["cf_js_challenge"] / ["cf_firewall"] / ["webgate"] 标记的站点交给本地基于 Chrome 的求解器(默认 FlareSolverr)处理。该绕过为按需启用 —— 不传该参数(也未在 settings.cloudflare_bypass.enabled 中设为 true)时,这类站点会按常规方式被检查,而几乎肯定被 Cloudflare 拦下,得到的是 UNKNOWN 状态加上 JS 挑战/防火墙错误,而不是真实结果。后端可在 settings.cloudflare_bypass.modules 中配置。详见 Cloudflare webgate 绕过。实验性 —— 参数本身、配置结构以及路由规则均可能发生变化,不保证向后兼容。

使用自定义站点数据库

--db 参数支持以下三种形式:

  1. HTTP(S) URL —— 按原样拉取,例如 --db https://example.com/my_db.json。

  2. 本地文件路径 —— 可以是绝对路径(--db /tmp/private.json),也可以是相对当前工作目录的路径(--db LLM/maigret_private_db.json)。

  3. 相对模块的路径 —— 出于向后兼容保留,基于已安装的 maigret/ 包目录解析(例如默认的 resources/data.json)。

本地路径的解析顺序:先按用户给的形式(绝对路径或基于当前目录的相对路径)尝试;若该文件不存在,再回退到旧的“相对模块路径”解析。如果两处都找不到,Maigret 会报错退出,而不会悄悄加载内置数据库。

当 --db 指向自定义文件时,会跳过自动更新 —— 直接使用你提供的文件。

每次运行时,Maigret 都会打印实际加载的数据库,例如:

[+] Using sites database: /path/to/maigret_private_db.json (6 sites)

如果加载请求的数据库因其它原因失败(JSON 损坏、缺少必需字段等),Maigret 会打印警告并显式回退到内置数据库,并在输出中明确告知:

[-] Falling back to bundled database: /…/maigret/resources/data.json
[+] Using sites database: /…/maigret/resources/data.json (3154 sites)

一个典型的命令:针对私有数据库、关闭自动更新、扫描全部站点 ——:

python3 -m maigret username \
    --db LLM/maigret_private_db.json \
    --no-autoupdate -a

报告

-P、--pdf —— 生成 PDF 报告(覆盖所有用户名的整体报告)。

-H、--html —— 生成 HTML 报告文件(覆盖所有用户名的整体报告)。

-X、--xmind —— 生成 XMind 8 思维导图(每个用户名生成一份)。

-C、--csv —— 生成 CSV 报告(每个用户名生成一份)。

-T、--txt —— 生成 TXT 报告(每个用户名生成一份)。

-J、--json —— 生成指定类型的 JSON 报告:simple、ndjson(每个用户名生成一份)。例如 --json ndjson。

-M、--md —— 生成 Markdown 报告(覆盖所有用户名的整体报告)。详见下文 Markdown 报告(对 LLM 友好)。

--ai —— 通过一个 OpenAI 兼容的 chat completion 接口,对搜索结果做一次 AI 分析。内部 Markdown 报告会被发送给模型,模型返回的简短调查摘要会以流式方式打印到终端。详见下文 AI 分析(内置)。

--ai-model —— 与 --ai 搭配使用的模型名。默认取配置中的 openai_model(开箱即用为 gpt-4o)。

-fo、--folderoutput —— 结果保存到此目录,默认 results。如果不存在会自动创建。

--web PORT —— 在指定端口启动内置 Web 界面,在一个页面上提供搜索结果和可下载的报告。例如:maigret --web 5000 → 在浏览器中打开 http://127.0.0.1:5000。带截图的完整说明见 Web 界面。

输出选项

-v、--verbose —— 展示更多信息和指标。(loglevel=WARNING)

-vv、--info —— 展示运行信息。(loglevel=INFO)

-vvv、--debug、-d —— 展示调试信息以及站点响应内容。(loglevel=DEBUG)

--print-not-found —— 打印那些没有找到该用户名的站点。

--print-errors —— 打印错误信息:连接错误、CAPTCHA、按国家封禁等。

其它运行模式

--version —— 展示版本信息和依赖。

--self-check —— 对站点和数据库执行自检。对每个站点,会分别查询其已知被占用、已知未被占用的用户名,并验证结果是否符合预期。单个站点的失败(网络错误、意外异常等)会被捕获并记录,而不会中断整体流程,因此自检总能跑到结束。检查完毕后,Maigret 会汇总报告发现的问题。如果有站点被禁用了(参见 --auto-disable),Maigret 会询问是否保存改动;输入 y/Y 会改写本地数据库。

--auto-disable —— 与 --self-check 搭配使用:自动禁用检查失败的站点(claimed/unclaimed 用户名识别不正确、连接错误、意外异常等)。不加该参数时,--self-check 仅报告问题,不会修改数据库。

--diagnose —— 与 --self-check 搭配使用:打印每个检查失败站点的详细诊断信息,包括检查类型、发现的问题列表,以及修复建议(例如建议改用另一种 checkType)。

--submit URL —— 对给定的账号 URL 或站点主页 URL 做一次自动分析,判断该站点的引擎以及检测账号是否存在的方式。结束后,Maigret 会询问是否要把该站点加入数据库;输入 y/Y 会改写本地数据库。

Markdown 报告(对 LLM 友好)

--md / -M 参数会生成一份 Markdown 报告,既方便人类阅读,也便于AI 助手(ChatGPT、Claude 等)分析。

maigret username --md

该报告包含:

  • 摘要,包括跨账号汇总的个人数据(出现过的所有真实姓名、所在地、个人简介)、国家标签、站点标签、首次/最近一次出现的时间戳。

  • 每个账号一节,包含主页 URL、站点标签,以及所有抽取出的字段(用户名、简介、关注者数、关联账号等)。

  • 可能的误报声明,提醒不同账号有可能属于不同的人。

  • 伦理使用提示,涉及相关数据保护法律。

搭配 AI 工具使用:

该 Markdown 格式针对 LLM 上下文窗口做了优化。你可以直接把报告投喂给 AI 助手,做后续分析:

# Generate the report
maigret johndoe --md

# Feed it to an AI tool
cat reports/report_johndoe.md | llm "Analyze this OSINT report and summarize key findings"

按站点分段的结构化 Markdown,使得 AI 工具更容易抽取关系、对照身份、并在多个账号之间识别模式。

如果想要由 Maigret 自己调用模型并直接打印摘要,请参见下文的 AI 分析(内置)。

AI 分析(内置)

--ai 参数会把搜索结果转化为一份简短的调查摘要 —— 将内部 Markdown 报告发送至一个 OpenAI 兼容的 chat completion 接口,并把模型回复以流式方式输出到终端。

export OPENAI_API_KEY=sk-...
maigret username --ai

# use a smaller / cheaper model
maigret username --ai --ai-model gpt-4o-mini

--ai 启用期间,逐站点进度行以及末尾的简短文本报告都会被抑制,以便流式摘要成为主要输出。Markdown 报告本身只构建于内存中,单独使用 --ai 时不会落盘 —— 如果同时也想把文件保存到磁盘,请配合 --md 使用。

摘要采用固定格式,分别给出最可能的真实姓名、所在地、职业、兴趣、语言、主要使用的网站、用户名变体、平台数量、活跃年份、置信度评级以及一份简短的后续线索清单。模型被明确要求:只能依据报告所支持的内容来作答,避免把明显无关的账号也并入主身份。

配置说明。 API key 的取值顺序:先取 settings.openai_api_key,再回退到 OPENAI_API_KEY 环境变量。接口地址默认为 https://api.openai.com/v1,通过在 settings.json 中设置 openai_api_base_url,可以重定向到任意 OpenAI 兼容服务(Azure OpenAI、OpenRouter、本地推理服务等)。完整选项请见 配置。

备注

--ai 会向所配置的 chat completion 接口发起网络请求,并将完整的 Markdown 报告(其中包含已收集到的个人主页数据)一并发送过去。请仅在你信任的服务商和账号上使用该功能。