Copy & Run

Pwned Passwords 확인: Have I Been Pwned k-익명성 API 조회

Have I Been Pwned의 range API는 비밀번호도 전체 해시도 보내지 않고 SHA-1 앞 5자리만 보냅니다. 파이썬 스크립트로 해시 계산, 앞 5자리 조회, 나머지 35자리 로컬 대조, 일치 횟수 출력까지 구현하고, Add-Padding 헤더와 이 방식의 한계를 실제 응답으로 확인합니다.

실습 노트 · 2026-11-02 발행 · 8분 · 2026-11 확인
실습 코드 내려받기: 전체 받기(zip)GitHubhibp_check.py

비밀번호가 유출 목록에 있는지 확인하려고 비밀번호를 어딘가에 입력하는 것은 꺼림칙합니다. Pwned Passwords의 range API는 이 문제를 k-익명성 방식으로 풉니다. 비밀번호의 SHA-1 해시 중 앞 5자리만 서버로 보내고, 돌려받은 후보 목록에서 나머지 35자리를 내 컴퓨터 안에서 찾습니다.

Windows Git Bash에서 파이썬 표준 라이브러리만으로 실행했고, 공개 API라 키가 필요 없습니다. 시험에는 password123처럼 널리 알려진 약한 값과 방금 무작위로 만든 문자열, 두 가지만 씁니다. 지금 실제로 쓰고 있는 비밀번호는 시험에 입력하지 마십시오. 명령행 인자는 셸 기록에 남고, 해시 앞 5자리도 외부로 나가기 때문입니다.

준비물

항목 확인한 값
실행 환경 Windows 11, Git Bash (Linux/macOS 명령도 같지만 실행하지 않음)
Python 3.12.10 (표준 라이브러리 hashlib, urllib, getpass, secrets만 사용)
API https://api.pwnedpasswords.com/range/{앞 5자리}, 키와 가입 불필요
작업 폴더 hibp_check.py 파일 하나 (전체 내용은 글 끝의 ## 전체 코드)

Git Bash에서 한글 출력이 깨지면 export PYTHONUTF8=1을 먼저 실행합니다.

이 단계의 파일 내려받기:hibp_check.py

1. 서버로 나가는 값 확인

hibp_check.py는 입력을 UTF-8로 SHA-1 해시한 뒤 대문자 16진수 40자리를 앞 5자리와 뒤 35자리로 나눕니다. 먼저 --show 옵션으로 네트워크 호출 없이 무엇이 나가는지만 봅니다.

python hibp_check.py --password password123 --show

서버로 가는 것은 주소 끝의 CBFDA 다섯 글자뿐이고, 나머지 35자리는 스크립트 안에만 있습니다.

password123의 SHA-1 해시가 CBFDA와 나머지 35자리로 나뉘고, 요청 주소에는 앞 5자리만 들어가는 것을 확인합니다.
password123의 SHA-1 해시가 CBFDA와 나머지 35자리로 나뉘고, 요청 주소에는 앞 5자리만 들어가는 것을 확인합니다.

이 단계의 파일 내려받기:hibp_check.py

2. 약한 비밀번호 조회

--show 없이 실행하면 range API를 호출합니다. 응답은 나머지35자리:횟수 형식의 줄 약 2,000개(이 접두어 기준)이고, 스크립트가 그중 내 나머지 35자리를 찾습니다.

python hibp_check.py --password password123

password123이 유출 목록에서 2,266,543회 발견되어 쓰지 않는다는 결과가 나오는 것을 확인합니다.
password123이 유출 목록에서 2,266,543회 발견되어 쓰지 않는다는 결과가 나오는 것을 확인합니다.

응답을 직접 보면 같은 과정을 확인할 수 있습니다. 아래 명령은 응답의 앞 3줄과 내 나머지 35자리가 있는 줄을 보여 줍니다.

curl -s https://api.pwnedpasswords.com/range/CBFDA | head -3; curl -s https://api.pwnedpasswords.com/range/CBFDA | grep C6008F9CAB4083784CBD1874F76618D2A97

응답이 나머지 35자리와 횟수가 콜론으로 이어진 줄의 목록이고, 마지막 줄이 password123의 나머지 35자리와 횟수 2266543인 것을 확인합니다.
응답이 나머지 35자리와 횟수가 콜론으로 이어진 줄의 목록이고, 마지막 줄이 password123의 나머지 35자리와 횟수 2266543인 것을 확인합니다.

이 단계의 파일 내려받기:hibp_check.py

3. 무작위 긴 문자열 조회

--random은 secrets.token_urlsafe(24)로 32자 문자열을 만들어 조회합니다. 실행할 때마다 값이 달라지므로 화면의 값은 예시입니다.

python hibp_check.py --random

무작위 문자열은 응답 약 1,959줄 어디에도 나머지 35자리가 없어 목록에서 찾지 못함으로 나오는 것을 확인합니다.
무작위 문자열은 응답 약 1,959줄 어디에도 나머지 35자리가 없어 목록에서 찾지 못함으로 나오는 것을 확인합니다.

스크립트는 일치가 있으면 종료 코드 1, 없으면 0을 돌려줍니다. 다른 스크립트나 가입 절차에서 호출할 때 쓸 수 있습니다.

이 단계의 파일 내려받기:hibp_check.py

4. Add-Padding 헤더

공식 문서에 따르면 요청에 Add-Padding: true 헤더를 보내면 응답이 800~1,000개 항목으로 맞춰지고, 채운 항목의 횟수는 항상 0이라 버리면 됩니다. 암호화된 통신의 응답 크기로 어느 접두어를 조회했는지 추측하는 것을 어렵게 하려는 장치입니다. --padding으로 확인합니다.

python hibp_check.py --password password123 --padding

같은 password123 조회에서 응답 줄 수가 늘고 count 0인 채움 줄이 135개 포함되며 결과 횟수는 그대로인 것을 확인합니다.
같은 password123 조회에서 응답 줄 수가 늘고 count 0인 채움 줄이 135개 포함되며 결과 횟수는 그대로인 것을 확인합니다.

채움 줄이 있어도 find_count는 내 나머지 35자리와 같은 줄만 찾으므로 결과는 같습니다. 공식 문서와 달랐던 점이 있습니다. 문서는 한 접두어에 평균 약 800개, 패딩 시 8001,000개라고 하는데, 제가 조회한 CBFDA, B9083, F0156은 패딩 없이도 1,9501,980줄, 패딩하면 2,100줄 안팎이었습니다. 응답 크기는 데이터 갱신에 따라 달라지는 값으로 보입니다.

이 단계의 파일 내려받기:hibp_check.py

안전한 이유와 한계

  • 안전한 이유: 서버는 앞 5자리만 받습니다. 같은 접두어를 가진 해시가 응답에 수백에서 이천 개 가까이 있어 서버는 그중 어느 비밀번호인지 알 수 없습니다. 나머지 35자리는 보내지 않습니다.
  • 입력하는 동안 조회하지 않기: 공식 문서는 글자를 칠 때마다 조회하면 관찰자가 비밀번호를 좁힐 수 있다고 경고합니다. 입력이 끝난 뒤 한 번만 조회합니다.
  • 횟수가 곧 위험도는 아닙니다: 횟수는 알려진 유출 자료에 나타난 빈도이지 안전 점수가 아닙니다. 횟수가 적어도 해당 비밀번호는 이미 노출된 것이므로 바꿉니다.
  • 없다고 안전한 것은 아닙니다: 목록에 없다는 말은 이 데이터에 없다는 뜻입니다. 짧거나 추측하기 쉬운 값, 다른 곳에서 새로 유출된 값은 여전히 위험합니다. 2단계 인증과 비밀번호 관리자 사용이 함께 필요합니다.
  • 스크립트의 한계: 해시는 내 컴퓨터에서 계산하지만 --password 인자는 셸 기록에 남습니다. 실제 비밀번호는 인자 없이 실행해 getpass 입력창에 넣는 편이 낫습니다.

자주 막히는 곳

  • 한글 출력이 깨지거나 UnicodeEncodeError가 납니다. Windows 기본 코드 페이지(cp1252)에서 한글을 쓰다 난 오류였고, export PYTHONUTF8=1 후 실행하면 해결됩니다.
  • 같은 명령인데 응답 줄 수가 매번 다릅니다. 패딩 옵션을 켠 경우 채움 줄 수가 요청마다 달라 이 글의 135도 예시입니다. 패딩을 끈 경우의 줄 수도 데이터 갱신으로 달라질 수 있습니다.

확인 범위

  • 확인한 것: 위 명령은 2026-11-02에 실제 공개 API로 실행했습니다. password123은 2,266,543회 발견되었고 무작위 문자열은 발견되지 않았습니다. API 동작은 https://haveibeenpwned.com/API/v3#PwnedPasswords 문서를 읽고 확인했습니다(range 주소, SUFFIX:COUNT 형식, 키와 속도 제한 없음, Add-Padding, 입력 중 조회 경고).
  • 하지 못한 것: Linux와 macOS 셸, NTLM 모드(?mode=ntlm), 로그인 화면에 붙이는 방법은 실행하지 않았습니다. 가짜 서버 시험은 필요하지 않았습니다.
  • 범위의 한계: 횟수와 응답 줄 수는 조회 시점의 값입니다. k-익명성은 서버로 가는 정보를 줄이는 방식이고, 네트워크 관찰자나 내 컴퓨터의 감염까지 막지는 않습니다.

자주 묻는 질문

Q. 비밀번호가 목록에 있으면 어떻게 합니까? A. 그 비밀번호를 쓰는 모든 계정에서 바꿉니다. 같은 비밀번호를 여러 곳에 썼다면 함께 바꿉니다.

Q. 서버가 앞 5자리를 알면 비밀번호가 드러나지 않습니까? A. 드러나지 않습니다. 같은 접두어를 가진 해시가 응답에 수백에서 이천 개 가까이 들어 있어, 서버는 그중 어느 것인지 가릴 수 없습니다.

Q. 목록에 없으면 안전합니까? A. 이 데이터에 없다는 뜻일 뿐입니다. 짧은 값과 추측하기 쉬운 값은 목록에 없어도 위험하므로 길이와 조합을 따로 확인합니다.

Q. 회사 계정 비밀번호도 이렇게 확인해도 됩니까? A. 조직 정책을 먼저 확인합니다. 이 글의 스크립트는 공개 API만 쓰지만, 내부 시스템 비밀번호를 외부 조회에 넣는 일은 규정에 맞는지 보안 담당자와 확인합니다.

관련 글

전체 코드

작업 폴더 구조는 아래와 같습니다.

hibp_check.py

hibp_check.py

"""Pwned Passwords range API 로 비밀번호 유출 여부를 k-익명성 방식으로 확인합니다.

사용법:
  python hibp_check.py                      비밀번호를 화면에 보이지 않게 입력받습니다(권장)
  python hibp_check.py --password 시험값    연습용 값만 씁니다. 실제 비밀번호는 명령행에 쓰지 않습니다
  python hibp_check.py --random             방금 무작위로 만든 긴 문자열을 확인합니다
  옵션: --padding (Add-Padding 헤더 사용), --show (서버로 나가는 요청 주소만 출력)
"""
import argparse
import getpass
import hashlib
import secrets
import sys
import urllib.request

API = "https://api.pwnedpasswords.com/range/"


def sha1_upper(password: str) -> str:
    return hashlib.sha1(password.encode("utf-8")).hexdigest().upper()


def fetch_range(prefix: str, padding: bool = False) -> str:
    headers = {"User-Agent": "copyandrun-hibp-demo"}
    if padding:
        headers["Add-Padding"] = "true"
    req = urllib.request.Request(API + prefix, headers=headers)
    with urllib.request.urlopen(req, timeout=15) as res:
        return res.read().decode("utf-8")


def find_count(body: str, suffix: str) -> int:
    """응답의 'SUFFIX:COUNT' 줄에서 내 나머지 35자리를 로컬에서 찾습니다."""
    for line in body.splitlines():
        got, _, count = line.strip().partition(":")
        if got == suffix:
            return int(count)
    return 0


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--password")
    ap.add_argument("--random", action="store_true")
    ap.add_argument("--padding", action="store_true")
    ap.add_argument("--show", action="store_true")
    a = ap.parse_args()

    if a.random:
        password = secrets.token_urlsafe(24)
        print(f"무작위 시험값: {password}")
    elif a.password is not None:
        password = a.password
    else:
        password = getpass.getpass("확인할 비밀번호(입력은 보이지 않습니다): ")

    digest = sha1_upper(password)
    prefix, suffix = digest[:5], digest[5:]
    print(f"SHA-1 전체 해시 : {digest}")
    print(f"서버로 보내는 값: {prefix}  (앞 5자리)")
    print(f"로컬에만 두는 값: {suffix}  ({len(suffix)}자리)")
    if a.show:
        print("요청 주소:", API + prefix)
        return

    body = fetch_range(prefix, a.padding)
    lines = body.splitlines()
    zero = sum(1 for ln in lines if ln.strip().endswith(":0"))
    print(f"응답 줄 수: {len(lines)} (그중 count 0 인 채움 줄 {zero})")
    n = find_count(body, suffix)
    if n:
        print(f"결과: 유출 목록에서 {n:,}회 발견됨. 이 비밀번호는 쓰지 않습니다.")
    else:
        print("결과: 목록에서 찾지 못함. 안전하다는 뜻은 아닙니다.")
    sys.exit(1 if n else 0)


if __name__ == "__main__":
    main()
이 단계의 파일 내려받기:hibp_check.py

이 글은 스타트업·소규모 조직 보안 구축 로드맵의 한 단계입니다.

이 글의 다음 단계

이 내용을 팀 교육으로 진행하고 싶으신가요?

인원, 수준, 일정에 맞춰 실습 환경까지 준비해 진행합니다. 대상과 기간을 알려 주시면 구성을 제안해 드립니다.

교육 문의하기

교육 진행 순서와 자주 묻는 질문 보기

팀이나 교육 담당자에게 이 글 제안하기

메일로 보내실 수도 있습니다: fankh111@gmail.com

같은 카테고리의 글