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

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

- 주소: https://copyandrun.com/blog/hibp-k-anonymity-password-breach-check/
- 분야: 개인·소규모 사무실
- 발행일: 2026-11-02
- 태그: Have I Been Pwned, k-익명성, 비밀번호, SHA-1, 유출 확인

비밀번호가 유출 목록에 있는지 확인하려고 비밀번호를 어딘가에 입력하는 것은 꺼림칙합니다. 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`을 먼저 실행합니다.

## 1. 서버로 나가는 값 확인

<!-- files: hibp_check.py -->

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

```bash
python hibp_check.py --password password123 --show
```

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

![password123의 SHA-1 해시가 CBFDA와 나머지 35자리로 나뉘고, 요청 주소에는 앞 5자리만 들어가는 것을 확인합니다.](https://copyandrun.com/img/hibp-k-anonymity-password-breach-check/01-what-is-sent.png)

## 2. 약한 비밀번호 조회

<!-- files: hibp_check.py -->

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

```bash
python hibp_check.py --password password123
```

![password123이 유출 목록에서 2,266,543회 발견되어 쓰지 않는다는 결과가 나오는 것을 확인합니다.](https://copyandrun.com/img/hibp-k-anonymity-password-breach-check/02-weak-password-found.png)

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

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

![응답이 나머지 35자리와 횟수가 콜론으로 이어진 줄의 목록이고, 마지막 줄이 password123의 나머지 35자리와 횟수 2266543인 것을 확인합니다.](https://copyandrun.com/img/hibp-k-anonymity-password-breach-check/05-raw-range-response.png)

## 3. 무작위 긴 문자열 조회

<!-- files: hibp_check.py -->

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

```bash
python hibp_check.py --random
```

![무작위 문자열은 응답 약 1,959줄 어디에도 나머지 35자리가 없어 목록에서 찾지 못함으로 나오는 것을 확인합니다.](https://copyandrun.com/img/hibp-k-anonymity-password-breach-check/03-random-not-found.png)

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

## 4. Add-Padding 헤더

<!-- files: hibp_check.py -->

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

```bash
python hibp_check.py --password password123 --padding
```

![같은 password123 조회에서 응답 줄 수가 늘고 count 0인 채움 줄이 135개 포함되며 결과 횟수는 그대로인 것을 확인합니다.](https://copyandrun.com/img/hibp-k-anonymity-password-breach-check/04-add-padding.png)

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

## 안전한 이유와 한계

- **안전한 이유:** 서버는 앞 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만 쓰지만, 내부 시스템 비밀번호를 외부 조회에 넣는 일은 규정에 맞는지 보안 담당자와 확인합니다.

## 관련 글

- 비밀번호를 저장하는 방식은 [파이썬 비밀번호 해시와 하드코딩된 시크릿 정리하기](/blog/python-password-hash-and-secrets/)에서 다룹니다.
- 비밀번호 대신 쓸 수 있는 인증 방식은 [패스키와 WebAuthn 시험](/blog/passkey-webauthn-flask-virtual-authenticator/)을 참고합니다.

## 전체 코드

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

```
hibp_check.py
```

### hibp_check.py

```python
"""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()
```
