[공유] 파이썬과 K-익명성을 활용한 안전한 패스워드 유출 조회 아키텍처 구현기

평소 자동화 프로그램 개발 및 백엔드 인프라 구축을 즐겨하는 개발자 유저입니다.

최근 국내외를 막론하고 대규모 개인정보 및 크리덴셜 유출 사고가 빈번하게 발생하다 보니, 저도 제가 관리하는 포털이나 커뮤니티 계정들의 패스워드가 안전한지 문득 확인하고 싶어지더군요.

다만 시중에 돌아다니는 몇몇 토이 프로젝트나 조잡한 가이드라인을 보면, 사용자가 입력한 비밀번호 원문이나 전체 해시값을 외부 서드파티 API 서버로 Direct하게 전송하는 위험한 아키텍처를 취하는 경우가 종종 있었습니다. 이는 전송 구간(In-Transit) 스니핑이나 서버 로그 유출 리스크를 전혀 고려하지 않은 전형적인 '탁상공론형' 접근입니다.

---

💡 핵심 아키텍처: SHA-1 해시 슬라이싱 (Hash Slicing)

이 시스템의 핵심은 외부 서버가 사용자의 진짜 비밀번호 전체를 절대 알 수 없게 만드는 영지식(Zero-Knowledge) 메커니즘에 있습니다.

1. 해시 치환: 클라이언트단에서 입력된 패스워드를 40자리의 SHA-1 해시값으로 변환합니다.
2. 힌트 전송 (Prefix): 해시값 전체를 보내지 않고, 오직 앞 5자리(Prefix)만 분리하여 외부 레인지 API 서버에 쿼리를 날립니다.
3. 데이터 덤프 반환 (Suffix): 서버는 해당 5자리로 시작하는 수천~수만 개의 유출 데이터베이스 서픽스(Suffix) 명단과 노출 카운트를 통째로 클라이언트에 반환합니다. (이 시점에서 서버는 유저가 정확히 어떤 비밀번호를 찾는지 수학적으로 유추가 불가능합니다.)
4. 로컬 메모리 대조 (Local Match): 외부 서버에서 내려받은 수만 개의 찌꺼기 리스트와 로컬에 안전하게 잠가두었던 나머지 35자리(Suffix)를 내 컴퓨터의 메모리 내에서 순회 대조하여 최종 유출 횟수를 판정합니다.

---

💻 핵심 구현 소스코드

파이썬 생태계의 표준 규격인 pyproject.toml을 기반으로 의존성을 격리하여 빌드했으며, 핵심적인 가상환경 내부 체크 로직은 다음과 같습니다. 범용적인 영어 주석을 포함해 깔끔하게 정리했습니다.

import hashlib
import requests


def check_password_leak(password: str) -> int:
    """Check if the password has been leaked using K-Anonymity."""
    # 1. Convert to SHA-1 hash and uppercase
    sha1_hash = hashlib.sha1(password.encode("utf-8")).hexdigest().upper()

    # 2. Hash slicing for K-Anonymity (5 chars prefix, 35 chars suffix)
    prefix = sha1_hash[:5]
    suffix = sha1_hash[5:]

    # 3. Send only the 5-character hint to the external API server securely
    url = f"https://api.pwnedpasswords.com/range/{prefix}"
    response = requests.get(url, timeout=5)

    if response.status_code != 200:
        raise RuntimeError("Failed to connect to the credential API server.")

    # 4. Compare the suffix matrix directly inside local memory infrastructure
    lines = response.text.splitlines()
    for line in lines:
        target_suffix, count = line.split(":")
        if target_suffix == suffix:
            return int(count)  # Returns the matched leak count

    return 0  # No leak history found

---

🛠️ 개발 환경 및 대시보드 인터페이스

로컬 가상환경 내에서 사용자가 브라우저를 통해 직관적으로 계정 보안 상태를 조율하고 제어할 수 있도록 세련된 Streamlit 기반의 UI 대시보드를 바인딩했습니다. 내부적으로는 무결성 및 사용량 제어를 위해 데이터베이스(Supabase) 연동 기능도 가볍게 주입해 둔 상태입니다.

수만 개의 서픽스 코드 매트릭스가 폭포수처럼 쏟아져 들어오다가 로컬 메모리 안에서 자석처럼 착 결합하며 일치 판정을 내리는 구체적인 모션 그래픽 시각 자료와 윈도우 환경 세팅 가이드는 아래 유튜브 콘텐츠에 차분하고 솔직 담백하게 정리해 두었으니 기술적 참고가 필요하신 분들은 확인해 보셔도 좋겠습니다.

오픈소스로 투명하게 빌드해 두었으니 안심하고 테스트해 보셔도 됩니다.

• 🎥 유튜브 '잡학다식 개발자' 영상 보기: https://youtu.be/So49-1qf_ec
• 📂 GitHub 오픈소스 저장소 (README 및 전체 소스): https://github.com/gohard-lab/pwned_credential_checker