Maigret 完整教學（繁中台灣用語）

⚠️ 必讀首節：本工具為 OSINT (Open-Source Intelligence; 開源情資) recon (reconnaissance; 偵察) 用途，屬於 dual-use security tool (雙用安全工具)。教學內容僅供 defensive security (防禦性資安)、授權滲透測試、自我足跡盤點與資安教育。任何用於 stalking (跟騷)、騷擾、人肉搜索、未授權競業情報、未成年人身分聚合的行為，皆違反工具使用條款與當地法律（GDPR、台灣個資法、美國 CFAA 等）。讀者使用本教學進行任何測試前，必須先取得書面授權或限定範圍為自己 / 公開虛構帳號。

1. 倫理與授權範圍（必讀）

1.1 工具定位

Maigret 屬於 OSINT 工具家族中的 username enumeration (帳號名列舉) 類別，繼承自 sherlock 但功能更廣。其主要能力是：以單一 username 為輸入，並行查詢約 3,000 個網站，判斷該名稱是否存在帳號，並聚合可公開抓取的 profile 資料（連結、其他 ID、頭像等）。

1.2 合法 / 推薦用途

• Personal footprint audit (個人足跡盤點)：查自己，評估社群外洩面、刪除無用帳號。
• Authorized pentesting (授權滲透測試)：在合約定義的 scope 內，作為 red-team 的 recon 階段。
• Blueteam (藍隊) 演練：對抗模擬，了解攻擊者如何收集情資、建立 detection。
• Security education (資安教育)：學員須事先同意；建議使用拋棄式 demo 帳號。
• 失蹤人口 / 法律授權調查：須律師或執法機關介入。

1.3 禁止用途

• 未經同意的 stalking、人肉搜索。
• 對未成年人的身分聚合。
• 未授權競業情報蒐集。
• 將結果公開揭露第三方個資。

1.4 法律框架簡述

• GDPR (歐盟一般資料保護規則)：對歐盟資料主體進行 profiling 需明確法律依據。
• 台灣個資法 (個人資料保護法)：第 19 條限制蒐集行為，須有特定目的與當事人同意。
• 美國 CFAA (Computer Fraud and Abuse Act)：未授權存取計算機系統屬聯邦犯罪。
• 平台 ToS (Terms of Service; 服務條款)：多數社群明文禁止 scraping。

操作守則：先取得書面授權，再開工。本教學以下章節預設讀者僅查自己或公開虛構測試帳號。

2. 安裝與環境

2.1 系統需求

• Python 3.10+（pyproject.toml 強制）
• 建議使用 uv 或 venv 建立隔離環境
• PDF 報告需額外系統圖形函式庫（Linux: libpango, libcairo；macOS: brew install pango）

2.2 安裝方式

A. PyPI（最簡單）

1# 建議用 uv 建立隔離環境
2uv venv .venv && source .venv/bin/activate
3uv pip install maigret
4
5# 若要 PDF 報告
6uv pip install 'maigret[pdf]'

B. 從 source（開發者）

1git clone https://github.com/soxoj/maigret
2cd maigret
3uv pip install -e .

C. Docker（最乾淨、最推薦給生產用）

1# CLI 模式
2docker pull soxoj/maigret:latest
3docker run --rm -v "$PWD/reports:/app/reports" soxoj/maigret:latest <username> --html
4
5# Web UI 模式（瀏覽器看 graph）
6docker run -p 5000:5000 soxoj/maigret:web
7# 開 http://localhost:5000

D. Windows 一鍵 exe

從 Releases 下載 maigret_standalone.exe，雙擊即可。

2.3 驗證安裝

1maigret --version
2maigret --self-check          # 測試前 N 個站點是否仍能正常 detect
3maigret YOUR_USERNAME --top-sites 10    # 跑 10 個站試試

3. 架構解析

3.1 高階資料流

flowchart LR
    A["CLI / Web UI
輸入 username"] --> B["is_plausible_username
(輸入驗證)"]
    B --> C["MaigretDatabase
載入 data.json (3000+ sites)"]
    C --> D["MaigretSite × N
(每站一個物件)"]
    D --> E["AsyncioQueueGeneratorExecutor
並行排程 + semaphore"]
    E --> F["aiohttp ClientSession
+ TCPConnector(ssl)"]
    F --> G["HTTP 請求
(可選 Tor / SOCKS / Cloudflare bypass)"]
    G --> H["Response Parser
status + regex + JSON"]
    H --> I["MaigretCheckResult
(claimed / unclaimed / unknown / error)"]
    I --> J["socid_extractor
(命中時抽 ID)"]
    J --> K{"recursion?"}
    K -->|yes| C
    K -->|no| L["Report Renderer
HTML / PDF / JSON / CSV / XMind"]
    L --> M["輸出檔案
(可選 --ai 摘要)"]

3.2 核心模組（maigret/ package）

3.3 detection 規則型別（data.json 內每站 schema 摘要）

 1"GitHub": {
 2  "tags": ["coding", "us"],
 3  "checkType": "message",       // status / message / response_url
 4  "presenseStrs": ["...exists..."],
 5  "absenceStrs": ["...not found..."],
 6  "url": "https://github.com/{username}",
 7  "urlMain": "https://github.com",
 8  "usernameClaimed": "soxoj",
 9  "usernameUnclaimed": "noonewouldeverusethis7"
10}

引擎依 checkType 決定看 HTTP status 或內文比對，命中後再交給 socid_extractor 抽 profile 資料。

4. CLI 完整參數速查

1maigret USERNAME [OPTIONS]

4.1 輸出格式

4.2 站點選擇

4.3 網路與隱私

4.4 進階

5. 實戰範例

5.1 自我足跡盤點

1# 自查自己，全格式報告
2maigret myhandle --html --pdf --json simple --xmind --folderoutput ~/reports/me
3
4# 加 recursive，從命中 profile 找其他 ID
5maigret myhandle --recursion --html
6
7# 只看 coding / social 類站點
8maigret myhandle --tags coding,social --html

5.2 授權滲透測試 recon

1# 限 scope 內：top 100 + JSON 供後續管線
2maigret target_in_scope --top-sites 100 --json ndjson --folderoutput ./engagement_xxx
3
4# 透過 Tor（合法授權下）
5maigret target_in_scope --proxy socks5://127.0.0.1:9050 --html

5.3 Python library 嵌入

 1import asyncio, maigret
 2
 3async def lookup(username: str):
 4    db_file = maigret.utils.get_data_path("data.json")
 5    db = maigret.sites.MaigretDatabase().load_from_path(db_file)
 6
 7    results = await maigret.search(
 8        username=username,
 9        site_dict=db.ranked_sites_dict(top=100),
10        timeout=10,
11        is_parsing_enabled=True,
12        id_type="username",
13    )
14    for site_name, info in results.items():
15        if info["status"].status.name == "CLAIMED":
16            print(site_name, info["url_user"])
17
18asyncio.run(lookup("torvalds"))

5.4 Web UI（最易上手）

1docker run -p 5000:5000 soxoj/maigret:web
2# 開 http://localhost:5000，輸入 username → 看 graph、下載報告

6. 資安審查（🔴 / 🟡 / 🟢）

6.1 工具本體（執行 maigret 本身）

6.2 依賴鏈

6.3 OPSEC（執行者自身）

6.4 倫理 / 法律

6.5 總評

7. 與相鄰工具比較

Maigret 是 OSS username enumeration 領域最完整的方案；商用對應品為 Social Links（其 product 直接 build on maigret，README 有 used-by 區塊）。

8. 自製 Site Profile（貢獻新站點）

8.1 手動建立

編輯 maigret/resources/data.json，新增條目：

 1"ExampleSite": {
 2  "tags": ["forum", "us"],
 3  "checkType": "message",
 4  "presenseStrs": ["Profile of"],
 5  "absenceStrs": ["User not found"],
 6  "url": "https://example.com/u/{username}",
 7  "urlMain": "https://example.com",
 8  "usernameClaimed": "knowngood",
 9  "usernameUnclaimed": "doesnotexist_a1b2c3"
10}

驗證：

1maigret --self-check --site ExampleSite knowngood

8.2 自動 submit

1maigret --submit https://example.com/u/somerealuser

工具會猜 checkType、抓 presence/absence pattern，產出 PR-ready JSON 區塊。

8.3 Engine 對應

若多站共用同個 forum 引擎（phpBB、Discourse…），可在 data.json 的 engines 區塊定義一次，各 site 用 "engine": "phpBB" 引用，減少重複規則。

9. 常見問題（Troubleshooting）

10. 進階：整合到資安管線

10.1 與 ELK / Splunk 串接

--json ndjson 每行一物件，可直接 tail -F 灌入 logstash file input：

1maigret target --json ndjson --folderoutput /var/log/maigret &
2# logstash.conf:
3# input { file { path => "/var/log/maigret/*.ndjson" codec => "json_lines" } }

10.2 Threat Intel 自動化

 1import maigret, json, asyncio
 2from datetime import datetime
 3
 4async def daily_audit(handles: list[str]) -> dict:
 5    """每日對 watchlist 上的 handle 跑一次，diff 出新出現的帳號。"""
 6    db = maigret.sites.MaigretDatabase().load_from_path(
 7        maigret.utils.get_data_path("data.json"))
 8    out = {}
 9    for h in handles:
10        res = await maigret.search(
11            username=h, site_dict=db.ranked_sites_dict(top=500),
12            timeout=15, is_parsing_enabled=True, id_type="username",
13        )
14        out[h] = [s for s, info in res.items()
15                  if info["status"].status.name == "CLAIMED"]
16    return out
17
18# 排程：cron + diff yesterday.json today.json → 新帳號告警

10.3 Blueteam 應用：公司員工自願足跡盤點

• 提供員工自願介面（內部 portal）
• 員工輸入自己 handle → 後端 Docker soxoj/maigret:web 跑
• 結果只回給員工本人，HR / IT 不留存
• 教育員工降低 OSINT attack surface

11. 延伸閱讀與資源

11.1 官方

• 主 repo：https://github.com/soxoj/maigret
• 文件：https://maigret.readthedocs.io
• PyPI：https://pypi.org/project/maigret
• Telegram bot（社群維護）：see README

11.2 相關套件

• socid_extractor（同作者）：https://github.com/soxoj/socid_extractor
• sherlock（先驅）：https://github.com/sherlock-project/sherlock
• holehe（email recon）：https://github.com/megadose/holehe
• WhatsMyName（純資料）：https://github.com/WebBreacher/WhatsMyName

11.3 法律與倫理參考

• GDPR：https://gdpr.eu
• 台灣個資法：https://law.moj.gov.tw/LawClass/LawAll.aspx?pcode=I0050021
• US CFAA：18 U.S.C. § 1030
• EFF OSINT ethics：https://www.eff.org

11.4 本專案資源

• gh-save 報告：inbox/2026-05-22-github-soxoj-maigret.md
• 排版版 HTML：
  • projects/maigret/quarkdown-out/02-tutorial/（完整 paged report）
  • projects/maigret/quarkdown-out/02-tutorial-plain/（純文版）

再次強調：本教學僅供 defensive security、授權測試、自我足跡與資安教育。使用前務必先確認法律授權與當事人同意。讀者後續責任自負。