sumunjang 0.1.0__tar.gz

sumunjang-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,94 @@
+name: CI
+
+# 검증 단계에서 심사자가 클린 환경에서 직접 돌린다. 그 환경을 그대로 흉내낸다 —
+# API 키도 네트워크도 없이 전체 테스트가 돌아야 한다.
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: 테스트 (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # pyproject 의 requires-python = ">=3.10" 을 실제로 시험한다.
+        # 적어 놓기만 하고 확인하지 않으면 그것은 주장이지 사실이 아니다.
+        python: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: 의존성 설치
+        run: uv venv && uv pip install -e ".[dev]"
+
+      - name: 테스트
+        # API 키를 명시적으로 비워 둔다. 테스트가 실수로 네트워크에 나가려 하면
+        # 조용히 통과하는 대신 실패해야 한다.
+        env:
+          ANTHROPIC_API_KEY: ""
+        run: uv run pytest -q --cov=sumunjang --cov-report=term-missing
+
+      - name: 골든셋 채점 (README 수치가 재현되는지)
+        run: uv run sumunjang report
+
+  package:
+    name: 패키지 (설치본이 저장소 없이 동작하는가)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      - name: 빌드
+        run: uv build
+
+      - name: 저장소 밖에서 설치·실행
+        # 검증기관은 클론하지 않고 설치본만 받을 수 있다. 골든셋이 wheel 에
+        # 실려 있지 않으면 report 가 여기서 깨진다.
+        run: |
+          mkdir -p /tmp/clean && cd /tmp/clean
+          uv venv
+          uv pip install --python .venv/bin/python "$GITHUB_WORKSPACE"/dist/*.whl
+          echo "고객 900101-1234568 / 성명: 최윤서" | .venv/bin/sumunjang mask -
+          .venv/bin/sumunjang report
+
+  license:
+    name: 라이선스 (의존성 계보)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      - name: 런타임 의존성 라이선스 수집
+        # 대회에 라이선스 검증 단계가 있다. SBOM.md 를 손으로 관리하면 반드시
+        # 어긋나므로 실제 설치된 것에서 뽑는다. 개발 의존성은 배포물에 들어가지
+        # 않으므로 런타임만 설치한다.
+        run: |
+          uv venv && uv pip install -e . pip-licenses
+          uv run pip-licenses --format=markdown --with-urls --order=license
+
+      - name: 허용 목록 밖의 라이선스 차단
+        # 금지 목록이 아니라 허용 목록으로 막는다. "GPL 을 걸러낸다" 는 식으로
+        # 짜면 목록에 없는 새 라이선스가 조용히 통과한다. 허용 목록은 모르는
+        # 것이 들어오는 순간 실패하므로, 심사 전에 사람이 먼저 본다.
+        #
+        # 같은 라이선스가 두 표기로 나오는 것은 패키지마다 분류자(classifier)를
+        # 쓰기도 하고 SPDX 를 쓰기도 하기 때문이다. 둘 다 적는다.
+        run: |
+          uv run pip-licenses --allow-only=\
+          "Apache Software License;\
+          BSD License;BSD-3-Clause;\
+          MIT;MIT License;\
+          Mozilla Public License 2.0 (MPL 2.0);\
+          PSF-2.0;Python Software Foundation License" \
+            --ignore-packages pip-licenses prettytable wcwidth tomli

sumunjang-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.coverage
+htmlcov/
+.DS_Store
+
+# 세션 매핑은 원문 개인정보를 담는다 — 절대 커밋 금지
+*.vault
+.sumunjang/

sumunjang-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

sumunjang-0.1.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: sumunjang
+Version: 0.1.0
+Summary: AI API 경계에서 한국 개인정보를 막는 로컬 게이트웨이 — base_url 한 줄로 붙이는 온디바이스 마스킹 프록시
+Project-URL: Homepage, https://github.com/HaChanho/sumunjang
+Project-URL: Repository, https://github.com/HaChanho/sumunjang
+Author: 문지기 (sumunjang)
+License: Apache-2.0
+License-File: LICENSE
+Keywords: korean,llm,masking,pii,privacy,proxy,가명처리,개인정보
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: Korean
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 수문장 (sumunjang)
+
+**AI에게 물어보기 전에, 개인정보는 문 앞에서 멈춘다.**
+
+Claude Code나 ChatGPT에 로그·문서·설정 파일을 붙여넣는 순간, 주민등록번호·계좌번호·
+API 키가 그대로 해외 API 서버로 전송됩니다. 개인정보보호위원회의 「생성형 AI 서비스
+이용자를 위한 개인정보 보호 가이드」(2026.5)조차 *"이름은 가명으로, 숫자는 XXX로"* 라는
+**수동 마스킹**을 권고할 뿐, 이를 자동화하는 무료 도구는 안내되지 않습니다.
+
+수문장은 `base_url` 한 줄만 바꾸면 동작하는 **로컬 게이트웨이**입니다. 나가는 요청에서
+한국 개인정보를 찾아 가명값으로 바꾸고, 돌아온 답변에서는 원문으로 되돌립니다.
+
+```
+당신          수문장                     Anthropic API
+ │              │                            │
+ │─ 900101-1234568 조회해줘 ─→               │
+ │              │─ [주민등록번호_1] 조회해줘 ─→│   ← 서버는 원문을 본 적이 없다
+ │              │←─ [주민등록번호_1]는 ... ──│
+ │←─ 900101-1234568 는 ... ─│                │   ← 당신 화면에는 원문이 보인다
+```
+
+## 빠른 시작
+
+```bash
+# 게이트웨이 실행
+uvx sumunjang proxy --port 4000
+
+# Claude Code가 수문장을 거쳐 나가게 한다
+export ANTHROPIC_BASE_URL=http://127.0.0.1:4000
+claude
+```
+
+파일이나 파이프에도 바로 쓸 수 있습니다.
+
+```bash
+$ echo "고객 900101-1234568, 010-9876-5432, kim@corp.co.kr" | sumunjang mask -
+고객 [주민등록번호_1], [전화번호_1], [이메일_1]
+
+$ sumunjang scan config.env        # 찾기만 한다. 발견 시 종료 코드 1 → CI 게이트로 사용
+$ sumunjang report                 # 골든셋으로 탐지 성능을 스스로 채점
+```
+
+## 무엇을 막는가
+
+**검증식으로 판별하는 것** — 값 스스로가 자기가 무엇인지 증명합니다.
+
+| 종류 | 검증 방식 |
+|---|---|
+| 주민등록번호 | 검증식(가중치 mod 11) **또는** 생년월일 정합성 |
+| 사업자등록번호 | 검증식(가중치 1371 3713 5) |
+| 카드번호 | 카드사 식별번호 대역 + Luhn (국내전용은 예외, 아래) |
+| 휴대전화번호 | 통신사 식별번호 + 자릿수 (`+82` 표기 포함) |
+| 이메일 | 형식 + 최상위 도메인 조건 |
+| API 키·토큰 | Anthropic / OpenAI / GitHub / AWS / Slack 공표 접두사 |
+
+**문맥으로 판별하는 것** — 검증식이 없거나 공개되지 않아, 앞에 붙은 말을 증거로 씁니다.
+
+| 종류 | 왜 형태만으로는 안 되는가 | 앵커 예 |
+|---|---|---|
+| 계좌번호 | 검증식이 없고 형식이 은행마다 다르다 (3-3-6, 6-2-6, 4-3-6 …) | `계좌:`, `예금주`, `입금` |
+| 여권번호 | 영문 1자 + 숫자 8자. 제품 코드·대기번호와 겹친다 | `여권번호:` |
+| 운전면허번호 | 검사번호 산출식이 공개돼 있지 않다 | `면허:` |
+| 이름 | 형태 자체가 없다. `최윤서`와 `배송팀`은 생김새가 같다 | `성명:`, `예금주:`, `담당:` |
+
+이름은 **구조화된 문서 한정**입니다. `성명: 최윤서`처럼 `키: 값` 형태만 잡고,
+`어제 김수현 책임이랑 통화했는데` 같은 자유서술 속 이름은 잡지 않습니다. 성씨 사전
+(상위 50개, 인구 약 97%)으로 한 겹 더 거릅니다 — 커버리지가 아니라 오탐 때문입니다.
+연·소·도·선·설 같은 희귀 성씨는 *연락·소속·도착·선택·설정* 의 첫 음절이기도 해서,
+3%를 더 얻자고 오탐을 몇 배로 늘립니다.
+
+표기 변형도 함께 받습니다. 하이픈 없이 붙여 쓴 주민등록번호(`8803121000068`), 점으로
+구분한 전화번호(`010.9876.5432`), 국가번호를 붙인 전화번호(`+82-10-2255-8830`), 전각
+숫자, 보이지 않는 문자(제로폭)를 끼워 넣은 우회까지. 제로폭은 정규화한 뒤 매칭하되
+좌표는 원문 기준으로 되돌리므로 가려지는 위치가 어긋나지 않습니다.
+
+**2020년 10월 이후 발급된 주민등록번호는 뒷자리가 임의번호**라 검증식을 통과하지 않습니다.
+검증식만 관문으로 두면 그 세대를 통째로 놓치므로, 생년월일 정합성을 별도 관문으로 둡니다.
+
+**국내전용 카드(9로 시작)는 Luhn을 따르지 않습니다.** 검증번호 산출 방식과 위치가
+카드사마다 달라서입니다. Luhn만 관문으로 두면 한국 카드를 체계적으로 놓치므로 따로
+다룹니다. 반대로 Luhn은 16자리 숫자 열 개 중 하나를 그냥 통과시키므로, 카드사 식별번호
+대역이 아닌 숫자(전표번호 등)는 먼저 잘라냅니다.
+
+### 증거가 없으면 관문을 더 요구한다
+
+규칙이 열 종류지만 원칙은 하나입니다. **값이 스스로 증명하는 만큼만 관문을 덜어줍니다.**
+
+| 상황 | 요구하는 것 | 이유 |
+|---|---|---|
+| 하이픈 **있는** 주민등록번호 | 검증식 **또는** 생년월일 | 하이픈 자체가 의도의 증거다 |
+| 하이픈 **없는** 주민등록번호 | 검증식 **그리고** 생년월일 | 13자리는 밀리초 타임스탬프·상품 바코드와 겹친다 |
+| 국제 브랜드 카드 | Luhn | 국제 규격을 따른다 |
+| 국내전용 카드 | 구분자 표기 | 검증할 수단이 없다. 사람이 옮겨적은 흔적을 대신 본다 |
+
+같은 원칙이 **앵커의 사정거리**도 정합니다. 값이 증거를 담고 있으면(검증식, 하이픈 묶음,
+생년월일 관문) 앵커는 같은 줄 안에서 느슨해도 됩니다 — `계좌: 국민은행 110-234-567890`
+처럼 은행 이름이 끼어드는 쪽이 오히려 보통이니까요. 반대로 값이 아무것도 증명하지
+못하면(이름, 맨 숫자 계좌번호, 여권번호, 구분자 없는 국내전용 카드) `키: 값` 형태를
+요구합니다.
+
+이 구분을 처음엔 지키지 않았다가 오탐 셋을 만들었습니다 — `여권 발급 대기열 A00000001`,
+`이체 수수료 정산 2026080612345678`, `카드 결제 모듈 롤백 커밋 9410123456789012`.
+셋 다 앵커 근처에 우연히 놓인 숫자였습니다. 지금은 오탐 골든셋에 박혀 있습니다.
+
+대가도 함께 적습니다. 앵커 없이 붙여 쓴 2020년 10월 이후 발급분, 구분자 없는 국내전용
+카드, 자유서술 속 이름과 주소는 **놓칩니다.** `goldenset-gaps/` 에 정답으로 박아 두고
+점수로 공표합니다.
+
+### 겹치는 탐지는 합집합으로 가린다
+
+전화번호와 카드번호는 자릿수를 공유할 수 있습니다. `010-9921-3348-0000-0002` 에서
+전화번호는 앞 13자, 카드번호는 뒤 19자를 차지합니다. 겹침을 "앞선 탐지가 이겼으니
+뒤는 버린다"로 처리하면 카드번호 뒷 8자리가 평문으로 남습니다.
+
+겹치는 탐지는 합집합 한 구간으로 병합해 **탐지기가 표시한 바이트를 하나도 남기지
+않습니다.** 합쳐진 자리의 이름은 민감도 서열을 따릅니다 — 축은 *이 값 하나로 다른 문을
+얼마나 열 수 있는가, 그 자물쇠를 바꿀 수 있는가* 하나입니다. 주민등록번호가 1위인 것은
+한국 본인확인의 마스터키이면서 유출돼도 바꿀 수 없기 때문이고, 사업자등록번호가
+최하위인 것은 국세청에서 공개 조회되기 때문입니다.
+
+## 설계 원칙
+
+**개인정보가 지나가는 경로에 서드파티 코드를 두지 않습니다.**
+탐지·마스킹 모듈은 파이썬 표준 라이브러리만 사용합니다. 외부 패키지는 네트워크 계층에만
+쓰이며 직접 의존성은 `httpx`, `uvicorn` 둘뿐입니다 ([SBOM.md](SBOM.md)).
+
+**결정적입니다.** 같은 입력이면 언제나 같은 출력이고, API 키도 네트워크도 필요 없습니다.
+AI 모델을 탑재하지 않으므로 실행할 때마다 결과가 달라지지 않습니다.
+
+**조용히 실패하지 않습니다.** 복원은 정확히 일치하는 표시만 되돌립니다. 모델이 형태를
+바꿔버린 경우 추측해서 복구하지 않습니다 — 잘못된 복원이 미복원보다 위험하기 때문입니다.
+
+**스트리밍은 신뢰성을 택했습니다.** 조각난 응답에서 가명 표시를 복원하면 청크 경계에서
+깨집니다. 그래서 업스트림에는 통짜로 요청해 복원을 끝낸 뒤, 클라이언트에게만 스트리밍
+형태로 다시 흘려보냅니다. 첫 응답이 조금 늦는 대신 복원이 깨지지 않습니다.
+
+## 실환경 검증 기록 (2026-08-06)
+
+Claude Code를 수문장에 연결해 실제 API까지 왕복시켰습니다. 사용자가 입력한 것은
+**파일 경로 한 줄**뿐입니다.
+
+```
+$ claude
+> /tmp/결제장애-로그.txt 읽고 왜 결제가 실패했는지 분석해줘
+```
+
+수문장이 기록한 **업스트림으로 실제 나간 본문**:
+
+```
+  user_rrn=[주민등록번호_1]        ← 원문: 850312-1000003
+  user_phone=[전화번호_1]
+  user_email=[이메일_3]
+  card=[카드번호_1]
+  merchant_brn=[사업자등록번호_1]
+  ANTHROPIC_API_KEY=[시크릿_1]
+```
+
+사용자는 개인정보를 붙여넣은 적이 없습니다. 도구가 파일을 읽어 `tool_result`에 담는
+순간 6종이 전송될 뻔했고, 여기에 도구가 시스템 프롬프트에 넣는 사용자 이메일까지 더해
+한 요청에서 8건이 가려졌습니다. 업스트림 본문에 남은 원문은 0건이었습니다.
+
+**가려도 답변 품질이 떨어지지 않았습니다.** 마스킹된 로그를 받은 모델은 장애 원인을
+분석하면서 "로그에 크레덴셜이 평문으로 찍혀 있다"는 보안 문제까지 지적했습니다.
+장애 분석에 필요한 것은 *누구의* 카드인지가 아니라 카드 결제가 실패했다는 구조이기
+때문입니다.
+
+이 검증 과정에서 자체 테스트로는 잡히지 않던 결함 두 건도 드러났습니다. 추론(thinking)
+블록을 SSE 규약대로 `delta`로 흘리지 않아 다음 턴 요청이 400으로 거부되던 문제와,
+반복되는 값을 "0건"으로 보고해 작동이 멈춘 것처럼 보이던 문제입니다. 둘 다 저장소에
+포함된 에코 서버로는 재현되지 않는 종류였습니다.
+
+## 무엇을 못 잡는지도 점수로 냅니다
+
+골든셋은 고치는 순간 포화됩니다. 어려운 문서를 넣어 점수를 떨어뜨려도, 드러난 결함을
+고치고 나면 다시 만점이 되어 처음과 구분이 가지 않습니다. 만점 셋만 내놓으면 *"쉬운 것만
+골라 놓고 만점이라 하는 것 아니냐"* 는 물음에 답할 수 없습니다.
+
+그래서 **0점 셋을 나란히 공개합니다.**
+
+| 셋 | 의미 | 현재 |
+|---|---|---|
+| `goldenset/` | 회귀 기준선. 깨지면 되던 것이 망가진 것 | 재현율 1.000 · 정밀도 1.000 |
+| `goldenset-hard/` | 표기 변형과 오탐 함정 | 재현율 1.000 · 정밀도 1.000 |
+| `goldenset-gaps/` | **못 잡는다고 선언한 것들.** 낮은 것이 정상 | 재현율 0.765 |
+
+`goldenset-hard/` 는 도입 당시 **0.684 / 0.765** 였습니다. 그 자리가 드러낸 결함 넷을
+고쳐 지금 수치가 됐습니다. `goldenset-gaps/` 는 **0.235에서 시작했습니다** — 문맥 앵커
+규칙으로 계좌·여권·면허·이름과 좁혀 뒀던 관문 셋을 되찾아 0.765가 됐고, 남은 것은
+자유서술 속 이름과 주소입니다. gaps 항목이 `hard` 로 옮겨가는 것이 곧 개선 기록입니다.
+
+```bash
+sumunjang report          # 세 셋을 나란히 채점
+```
+
+이 수치는 **독립적인 성능 증명이 아니라 회귀를 감시하는 기준선**입니다. 골든셋을 만든
+사람이 도구도 만들었습니다.
+
+## 한계
+
+정직하게 적습니다.
+
+- **자유서술 속 이름과 주소는 못 잡습니다.** 이름은 `성명: 최윤서` 같은 구조화된 표기만
+  잡습니다. `어제 김수현 책임이랑 통화했는데` 는 앵커가 없어 규칙으로 판별할 수 없습니다.
+  주소는 아예 다루지 않습니다 — 어디서 끝나는지를 규칙으로 정할 수 없습니다.
+  둘 다 `goldenset-gaps/G2` 에 정답으로 박아 두고 0점으로 공표합니다.
+- **앵커 없는 계좌·여권·면허번호도 못 잡습니다.** 검증식이 없거나(계좌) 공개되지
+  않아서(면허 검사번호), 앞에 붙은 말이 유일한 근거입니다. `정산 항목 110-234-567890`
+  처럼 앵커 없이 놓인 숫자는 계좌번호로 보지 않습니다.
+- **관문을 좁힌 대가가 있습니다.** 앵커 없이 붙여 쓴 2020년 10월 이후 주민등록번호와,
+  앵커 없이 붙여 쓴 국내전용 카드는 놓칩니다. 위 표의 `gaps` 셋에 들어 있습니다.
+- **이름 탐지에는 남은 오탐 여지가 있습니다.** `담당: 배송팀` 처럼 성씨로 시작하는
+  3자 낱말이 `키: 값` 자리에 오면 이름으로 읽힙니다. 개인정보가 아닌 값을 가리는
+  쪽이 이름을 흘리는 쪽보다 낫다고 보고 이 방향을 택했습니다.
+- **Luhn은 오탐을 완전히 막지 못합니다.** 전치·오타 검출용이라 `1111-2222-3333-4444`
+  같은 규칙적 반복도 통과합니다. 카드사 식별번호 대역으로 한 겹 더 거르지만 그 안에서는
+  여전히 통과합니다.
+- **모델이 가명 표시를 값이 아니라 설명 대상으로 언급하면 복원이 문장을 왜곡합니다.**
+  모델이 "마스킹 표시(`[주민등록번호_1]`)가 붙어 있었다"고 메타 언급하면 그 자리도
+  원문으로 되돌아갑니다. 값으로 쓴 것인지 표시를 설명한 것인지 구분하려면 문맥 판단이
+  필요해 현재 구조로는 완전히 풀 수 없습니다.
+- 현재 Anthropic Messages API(`/v1/messages`)만 지원합니다.
+
+## 개발
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+uv run pytest
+```
+
+테스트는 API 키도 네트워크도 없이 돕니다. 업스트림은 저장소에 포함된 에코 서버를 실제
+ASGI 앱으로 띄워 검증하므로, 누구나 같은 결과를 재현할 수 있습니다.
+
+`tests/test_leak.py` 는 다른 테스트와 성격이 다릅니다. 카테고리도 좌표도 묻지 않고
+**"골든셋의 정답 값이 마스킹 결과에 부분 문자열로도 남아 있지 않은가"** 하나만 검사합니다.
+재현율·정밀도는 스팬이 정확히 일치했는지를 세므로 "절반만 가렸다"는 잡아도 *남은 절반이
+평문으로 나갔다*는 사실 자체는 드러내지 못합니다. 실제로 그 틈으로 결함이 하나 빠져나간
+적이 있습니다.
+
+## 라이선스
+
+Apache License 2.0
+
+---
+
+2026 오픈소스 개발자대회 출품작 (팀 문지기)