maigret 딥다이브
— 사용자명 하나로 3,000개 사이트를 동시에 훑는 OSINT 엔진의 설계

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

maigret은 사용자명 열거(username enumeration) 계열의 OSINT 도구다. API 키가 전혀 필요 없고, 매 실행마다 GitHub에서 최신 사이트 DB를 자동으로 받아(24시간마다 1회) 쓰며, 오프라인이면 내장 DB로 폴백한다. 발견한 사용자명을 씨앗 삼아 재귀 검색까지 수행하고, 결과를 PDF·HTML·CSV·JSON(ndjson)·XMind·D3 그래프로 내보낸다. 기본 실행은 트래픽 상위 500개 사이트만 점검하고, -a를 붙이면 전체를 훑는다.

2왜 주목받는가

트렌딩 이유 · sherlock 등 경쟁 대비 장점.

username OSINT 도구의 원조는 sherlock이다. maigret이 꾸준히 스타를 모으는 이유는, sherlock이 멈춘 지점에서 "실전에서 진짜 골치 아픈 부분"을 풀었기 때문이다. 첫째 압도적 사이트 수(3,000+)와 자동 갱신 DB, 둘째 오탐을 줄이는 정교한 판정·에러 시그니처, 셋째 프로필에서 추가 정보를 긁어 재귀로 파고드는 능력, 넷째 다양한 리포트 포맷과 웹 UI다.

3기술 스택 전체 지도

백엔드(엔진)·프론트엔드(리포트/웹UI)·인프라 각각.

① 핵심 엔진 (백엔드) — 비동기 네트워크 I/O

maigret은 100% 파이썬이며(코드의 79%), 사이트 점검은 본질적으로 I/O 바운드(네트워크 대기가 대부분) 작업이라 asyncio + aiohttp로 짜였다. CPU가 아니라 "수천 개의 HTTP 요청을 동시에 기다리는" 문제이기 때문이다.

② 리포트 & 프론트엔드

③ 인프라 · 배포 · 데이터

4아키텍처 심화 분석

사용자명 → 비동기 점검 → 판정 → 리포트, 그리고 오탐 처리.

전체 흐름 한눈에

입력은 사용자명 1개. 엔진은 사이트 DB를 읽어 각 사이트마다 점검 작업(coroutine)을 만들고, 이걸 큐에 넣어 일정 수의 워커가 동시에 처리한다. 각 작업은 URL을 조립해 HTTP 요청을 던지고, 응답을 사이트별 판정 규칙에 통과시켜 CLAIMED/AVAILABLE/UNKNOWN/ILLEGAL 중 하나로 분류한다. CLAIMED면 프로필을 긁어 추가 ID를 뽑고, 그게 새 검색의 씨앗이 된다(재귀). 마지막에 리포터가 모아 보고서를 만든다.

판정 4상태 — 거짓 양성을 거르는 핵심

maigret의 신뢰성은 "있다/없다"를 이분법이 아니라 4상태로 본다는 데서 나온다. 소스의 MaigretCheckStatus 열거형이 바로 그것이다.

"ExampleSite": {
  "urlMain": "https://example.com/",
  "url": "https://example.com/{username}",
  "checkType": "message",
  "presenseStrs": ["\"profile\":", "data-user-id"],
  "absenceStrs": ["User not found", "page-404"],
  "errors": { "Captcha required": "CAPTCHA detected",
              "Rate limit": "Too many requests" },
  "tags": ["us", "social"],
  "usernameClaimed": "blue",      // 자가검증용: 실제 존재 계정
  "usernameUnclaimed": "noonewouldeverusethis8675"
}

핵심 설계 패턴

5디렉토리 구조 해부

핵심 패키지 maigret/ 안에 엔진·DB·리포트가 모두 있다.

6학습 포인트 (기술별)

OSINT 도구 아키텍처에서 무엇을 배우나.

A. asyncio 동시성 — I/O 바운드의 정석

maigret은 "수천 개의 네트워크 요청을 어떻게 동시에, 그러나 폭주 없이 처리하나"의 살아 있는 교과서다. 핵심은 ① asyncio.Queue + 고정 워커 수로 동시성 상한을 두고, ② 작업마다 asyncio.wait_for(..., timeout)로 느린 사이트 격리, ③ as_completed/생성기로 끝나는 대로 스트리밍 처리. 무한정 gather로 다 던지면 커넥션 풀이 고갈되고 차단당한다 — 그래서 세마포어/큐로 조이는 것이 핵심.

B. 데이터 주도 설계 — 로직을 데이터로 빼기

"사이트마다 다른 판정"을 if-else로 짰다면 3,000개 분기로 코드가 폭발했을 것이다. maigret은 그걸 data.json 스키마(checkType·presenseStrs·absenceStrs·errors)로 외부화했다. 덕분에 기여자가 코드를 몰라도 규칙을 추가하고, --self-check로 규칙의 생존을 자동 검증한다. "변하는 부분은 데이터로, 안 변하는 부분만 코드로"의 모범 사례다.

C. 견고한 판정 — 오탐과 "모름"의 분리

가장 배울 점은 "확실치 않으면 '없음'이 아니라 '모름(UNKNOWN)'"이라는 자세다. 차단·타임아웃·CAPTCHA를 "없음"으로 뭉개면 결과가 거짓이 된다. errors{} 매핑과 error_detection.py가 이 경계를 코드로 강제한다. 이는 OSINT뿐 아니라 모든 외부 시스템 점검(헬스체크·모니터링)에 그대로 옮길 수 있는 원칙이다.

D. 리포트 파이프라인 — 같은 데이터, 여러 포맷

하나의 결과 모델(MaigretCheckResult)에서 HTML·PDF·CSV·JSON·그래프가 갈라져 나온다. "데이터 모델과 표현(렌더링)의 분리" 패턴이다. report.py를 읽으면 같은 결과 객체를 각 포맷별 직렬화기에 통과시키는 구조가 보인다.

7시스템 / 환경 요구사항

설치는 가볍지만, '사용 권한'이 가장 중요한 요구사항이다.

8직접 해볼 수 있는 실습 과제

난이도별 5단계 — 모두 본인 계정 / 허가된 대상으로만 안전하게.

9관련 기술 심화 학습 로드맵

6주 코스 — asyncio 기초부터 OSINT 도구 설계까지.

10핵심 키워드 사전

본문·소스에 나온 용어 빠른 참조.

11참고 링크

• GitHub: soxoj/maigret
• 공식 문서: maigret.readthedocs.io (Quick start · CLI options · library usage · settings)
• 사이트 목록: sites.md · 기여 가이드: CONTRIBUTING.md
• 자매 추출기: soxoj/socid_extractor
• 원조 도구: sherlock-project/sherlock · 차단 우회: FlareSolverr
• OSINT 기법 분류(저자): SOWEL framework
• 법규 참고: 한국 개인정보보호법 · EU GDPR · 미국 CCPA