Sherlock 딥다이브
— 아이디 하나로 400여 개 사이트의 계정 흔적을 동시에 추적하는 OSINT 도구

1프로젝트 한줄 요약

Sherlock은 400개 이상의 소셜 미디어 플랫폼에서 사용자명(username)을 동시에 검색하여 계정 존재 여부를 탐지하는 Python CLI 도구입니다. sherlock user123 한 줄이면 Instagram, Twitter, GitHub, Reddit 등 수백 개 사이트에서 해당 유저네임이 사용 중인지 몇 초 만에 알려줍니다.

2왜 주목받는가

Sherlock은 OSINT(Open Source Intelligence, 공개정보 수집) 분야의 사실상 표준 도구입니다. 사이버보안, 펜테스팅, CTF 대회에서 빠지지 않는 필수 도구로 자리잡았고, ⭐76.6k·9k 포크로 Python 보안 도구 중 최상위 인기를 자랑합니다. Docker·pipx·패키지 매니저 등 다양한 설치 방식으로 접근성을 극대화했고, {?} 와일드카드 문법으로 유저네임 변형까지 자동 검색합니다.

경쟁 도구 대비 위치

3기술 스택 전체 지도

① 백엔드 — 핵심 로직

② 데이터 처리 & 출력

③ 인프라 & DevOps

빌드 시스템 구조

핵심 포인트: pyproject.toml 하나에 빌드·의존성·스크립트·메타데이터를 모두 통합하는 현대적 Python 패키징 방식입니다. setup.py나 setup.cfg 없이 pyproject.toml만으로 패키지를 관리합니다.

4아키텍처 심화 분석

시스템 구조도

패턴 1 — Future 기반 동시성

# SherlockFuturesSession — requests-futures 확장
class SherlockFuturesSession(FuturesSession):
    def request(self, method, url, hooks=None, *args, **kwargs):
        start = time.monotonic()
        def timing_hook(r, *h_args, **h_kwargs):
            r.elapsed = time.monotonic() - start
        # 기존 훅 체인에 추가 (덮어쓰지 않음!)
        hooks["response"] = hooks.get("response", []) + [timing_hook]
        return super().request(method, url, hooks=hooks, *args, **kwargs)

패턴 2 — Chain-of-Responsibility (탐지 로직)

계정 존재 여부를 판단하는 4단계 체인입니다.

각 사이트의 errorType 설정에 따라 어떤 단계를 쓸지 결정됩니다. 이것이 데이터 주도 설계(Data-Driven Design)의 핵심 — 탐지 로직을 코드가 아니라 data.json 설정으로 제어합니다.

패턴 3 — 옵저버 패턴 (알림 시스템)

class QueryNotify:          # 추상 베이스
    def start(self, message): ...
    def update(self, result): ...
    def finish(self, message): ...

class QueryNotifyPrint(QueryNotify):  # 구체 구현
    def update(self, result):
        if result.status == QueryStatus.CLAIMED:
            print(f"[+] {site_name}: {url}")   # 초록색
        elif self.print_all:
            print(f"[-] {site_name}: Not Found")  # 빨간색

이 패턴 덕분에 터미널 출력을 웹소켓 알림·로그 파일 등으로 쉽게 교체할 수 있습니다.

패턴 4 — 재귀적 문자열 보간

def interpolate_string(input_object, username):
    if isinstance(input_object, str):
        return input_object.replace("{}", username)
    elif isinstance(input_object, dict):
        return {k: interpolate_string(v, username) for k, v in input_object.items()}
    elif isinstance(input_object, list):
        return [interpolate_string(item, username) for item in input_object]
    return input_object

중첩된 딕셔너리/리스트 안의 모든 {}를 유저네임으로 치환합니다. JSON 설정 파일에서 동적 값을 주입할 때 매우 유용한 패턴입니다.

5디렉토리 구조 해부

주요 파일별 역할

6학습 포인트 (기술별)

6-1. Python 동시성 프로그래밍

스레드 풀 기반 비동기 HTTP — 동기 방식과 비교하면 차이가 한눈에 보입니다.

# 일반적인 동기 요청 (느림)
for site in sites:
    response = requests.get(site.url)        # 하나씩 순서대로

# Sherlock의 방식 (빠름)
session = SherlockFuturesSession(max_workers=20)
futures = {}
for site in sites:
    futures[site] = session.get(site.url)    # 즉시 반환 (Future)
for site, future in futures.items():
    response = future.result()               # 여기서 대기

6-2. 데이터 주도 설계 (Data-Driven Design)

탐지 로직을 코드가 아니라 JSON 데이터로 제어합니다.

{
  "GitHub": {
    "url": "https://www.github.com/{}",
    "errorType": "status_code",
    "errorCode": 404,
    "username_claimed": "torvalds"
  },
  "Instagram": {
    "url": "https://www.instagram.com/{}",
    "errorType": "message",
    "errorMsg": "Sorry, this page isn't available.",
    "username_claimed": "instagram"
  }
}

사이트마다 탐지 방식이 다릅니다 — 어떤 곳은 404, 어떤 곳은 본문 메시지. if문으로 하드코딩하면 400개마다 분기가 필요하지만, JSON 매니페스트로 분리하면 코드 한 줄 안 바꾸고 새 사이트를 추가할 수 있습니다.

6-3. JSON Schema 검증

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": {
    "required": ["url", "urlMain", "errorType", "username_claimed"],
    "if":   { "properties": { "errorType": { "const": "message" } } },
    "then": { "required": ["errorMsg"] }
  }
}

errorType이 "message"이면 errorMsg가 필수 — 이런 조건부 검증을 스키마로 표현하고, CI에서 PR마다 자동 검증해 잘못된 데이터 머지를 막습니다.

6-4. 현대적 Python 패키징

[build-system]
requires = ["poetry-core>=1.2.0"]
build-backend = "poetry.core.masonry.api"

[tool.poetry]
name = "sherlock-project"

[tool.poetry.dependencies]
python = "^3.9"

[tool.poetry.scripts]
sherlock = "sherlock_project.sherlock:main"

이 한 파일로 빌드 시스템 지정·의존성 관리·CLI 엔트리포인트 등록·메타데이터 관리를 모두 처리합니다.

6-5. 테스트 전략 — pytest 동적 파라미터화

def pytest_generate_tests(metafunc):
    if "chunked_sites" in metafunc.fixturenames:
        sites = fetch_local_manifest()
        metafunc.parametrize("chunked_sites",
                             list(sites.items()),
                             ids=[s for s in sites])

사이트 하나당 테스트 케이스 하나가 자동 생성됩니다. pytest --chunked-sites=GitHub,Instagram처럼 특정 사이트만 골라 테스트할 수도 있습니다.

6-6. Docker 멀티스테이지 빌드

# Stage 1: pip 업그레이드만 수행
FROM python:3.12-slim-bullseye AS build
RUN pip install --upgrade pip

# Stage 2: 런타임 환경 — pip install로 직접 설치 (Stage 1 파일 복사 없음)
FROM python:3.12-slim-bullseye
RUN pip install sherlock-project==${VERSION_TAG}
WORKDIR /sherlock
ENTRYPOINT ["sherlock"]

6-7. WAF 감지 패턴

7하드웨어 / 시스템 요구사항

Tor 사용 시: Tor 서비스 설치 필요 (sudo apt install tor).

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

# 설치
pipx install sherlock-project

# 자신의 유저네임 검색
sherlock 내유저네임 --print-all --csv

# 결과 CSV 분석
python -c "
import pandas as pd
df = pd.read_csv('내유저네임.csv')
print(f'발견: {len(df[df.status == \"Claimed\"])}개')
print(f'미발견: {len(df[df.status == \"Available\"])}개')
"

{
  "DCInside": {
    "url": "https://gallog.dcinside.com/{}",
    "urlMain": "https://www.dcinside.com",
    "errorType": "status_code",
    "errorCode": 404,
    "username_claimed": "test",
    "tags": ["community"]
  }
}

import aiohttp, asyncio

async def check_site(session, site_name, url):
    try:
        async with session.get(url, timeout=aiohttp.ClientTimeout(total=30)) as resp:
            return site_name, resp.status, await resp.text()
    except Exception as e:
        return site_name, 0, str(e)

async def sherlock_async(username, sites):
    async with aiohttp.ClientSession() as session:
        tasks = [check_site(session, name, url.format(username))
                 for name, url in sites.items()]
        return await asyncio.gather(*tasks)

from flask import Flask, Response
import json
app = Flask(__name__)

def generate_results(username):
    for site_name, result in sherlock(username):
        yield f"data: {json.dumps({'site': site_name, 'status': result.status.value})}\n\n"

@app.route('/search/<username>')
def search(username):
    return Response(generate_results(username), mimetype='text/event-stream')

1. pyproject.toml 작성 (build-system, project, scripts)
2. pipx install .  로 로컬 테스트
3. TestPyPI 배포:
   pip install build twine
   python -m build
   twine upload --repository testpypi dist/*

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

1주차 · Python 동시성 기초

2주차 · 현대적 Python 패키징

3주차 · 테스트 전략 심화

4주차 · Docker & 배포

5주차 · OSINT & 보안 도구 개발

10핵심 키워드 사전

11참고 링크

• GitHub 레포지토리 — github.com/sherlock-project/sherlock
• 공식 웹사이트 & 문서 — sherlockproject.xyz
• PyPI 패키지 — pypi.org/project/sherlock-project
• requests-futures — github.com/ross/requests-futures
• pyproject.toml 스펙 (PEP 621) — peps.python.org/pep-0621
• JSON Schema 공식 문서 — json-schema.org
• pytest 동적 파라미터화 — docs.pytest.org
• concurrent.futures — docs.python.org
• OSINT Framework — osintframework.com