docs-masked

로컬 문서 마스킹: 언어 모델에 보내기 전에 개인정보를 비식별화하고, 응답 후 원래 값으로 복원합니다.

문서는 원본 상태로 기기를 절대 떠나지 않습니다. 개인 데이터는 안정적인 태그(#PERSON_1#, #PHONE_2#, #ADDRESS_1#)로 대체되며, 모델에는 태그가 포함된 텍스트만 전송됩니다. 모델의 응답은 로컬 금고(vault)를 사용하여 원래 값으로 복원됩니다.

документ ──▶ маска ──▶ контроль утечки ──▶ модель ──▶ обратная подстановка
           локально      локально          сеть           локально

이는 Claude Code의 스킬(skill), 다른 에이전트를 위한 MCP 서버, 그리고 일반적인 명령줄 유틸리티로 사용할 수 있습니다.

작동 방식

1. 마스킹. 문서는 텍스트 조각(문단, 셀, 마크업 노드)으로 분해됩니다. 각 조각에서 개인 데이터를 찾고, 각 값에 안정적인 태그를 할당합니다. 동일한 사람은 문서 전체에서 동일한 태그를 받습니다. 격변화 형태와 이니셜을 포함하여: "Иванов Иван Иванович", "Иванову", "Иванов И.И."는 모두 하나의 #PERSON_1#입니다.

2. 누출 제어. 마스킹된 텍스트는 모든 탐지기와 추가로 편집증적 검사를 다시 거칩니다: 모든 @, 7자리 이상의 숫자 시퀀스, 전화번호처럼 보이는 모든 것. 만약 남아있는 것이 있다면, 전송은 차단됩니다(로그 경고가 아닌 예외 발생).

3. 전송. 외부로는 태그가 있는 텍스트만 전송됩니다. 네트워크로의 유일한 출구는 llm.send() 함수이며, 이 함수는 요청 전에 검사를 수행해야 합니다. 각 전송은 ~/.pii_shield/egress.jsonl 로그에 기록됩니다: 시간, 제공자, 모델, 크기, sha256, 검사 상태. 내용은 기록되지 않습니다.

4. 복원. 모델의 응답은 금고를 통해 처리됩니다: 태그가 원본으로 대체됩니다. 성명의 경우 복원된 주격 형태가 사용됩니다. 문서에서 사람이 "Кузнецову Ивану Петровичу"로만 언급된 경우, 응답에서는 "Кузнецов Иван Петрович"가 됩니다.

Related MCP server: Doc Sanitizer MCP Server

설치

git clone https://github.com/kpshinnik/docs_masked.git ~/.docs_masked/src
cd ~/.docs_masked/src && ./install.sh

스크립트가 종속성을 설치하고, 스킬을 ~/.claude/skills/docs-masked에 배치한 후 MCP 구성의 완성된 조각을 출력합니다. 자세한 내용과 옵션은 docs/INSTALL.md를 참조하세요.

에이전트에 연결

각 하네스에 대한 단계별 가이드는 docs/HARNESSES.md를 참조하세요.

MCP 서버는 종속성 없이 작성되었습니다: python3만 있으면 됩니다. 여섯 가지 도구를 제공합니다: mask_text, unmask_text, verify_text, scan_document, mask_document, unmask_document.

사용법

docs-masked scan   договор.docx                    # что будет скрыто
docs-masked mask   договор.docx                    # маска + сейф
docs-masked report договор.docx --open             # посмотреть глазами
docs-masked ask    договор.docx -p "Найди риски по срокам"
docs-masked unmask договор.masked.docx --vault договор.docx.vault.json

명령어

전체 플래그 목록은 skills/docs-masked/references/cli.md를 참조하세요.

인식 대상

모든 격의 성명(러시아어, 라틴 문자, 로마자 표기), 조직, 주소, 이메일, 전화번호, 여권 및 발급 부서 코드, SNILS, INN, OGRN, KPP, BIK, 계좌 번호, 은행 카드, IBAN, OMS 보험증, 운전면허증, 자동차 번호판, IP 주소, @닉네임, 생년월일 및 문서 발급일, 세부 코드(OKTMO, OKPO, KBK), 그리고 사용자 정의 문자열.

식별자는 실제로 검증됩니다: SNILS 체크섬, INN 및 OGRN 검증 숫자, 카드의 Luhn 알고리즘, IBAN의 mod-97. 전체 표는 references/coverage.md를 참조하세요.

형식

DOCX는 document.paragraphs가 아닌 XML을 통해 처리됩니다. 그렇지 않으면 콘텐츠 제어 및 캡션 내의 단락이 손실됩니다. 실제 계약서에서 이로 인해 세부 정보 블록의 전체 열이 사라졌습니다. 테이블에서 열 헤더는 컨텍스트로 사용됩니다: 셀 500100732259는 그 자체로는 무작위 숫자와 구별할 수 없지만, "INN" 열에서는 확실하게 인식됩니다.

Python API

from pii_shield import ask_document

res = ask_document("договор.docx", "Составь резюме и найди риски",
                   provider="anthropic")
print(res.answer)          # имена уже восстановлены

각 단계를 수동으로 제어:

from pii_shield import mask_text, assert_clean, unmask_text

r = mask_text(raw)                 # r.text — с тегами, r.vault — сейф
assert_clean(r.text)               # LeakGuardError, если что-то осталось
answer = call_model(r.text)        # наружу уходит только маска
final, unknown = unmask_text(answer, r.vault, mode="canonical")

자세한 내용은 references/api.md를 참조하세요.

금고

금고는 태그와 원본을 연결하는 유일한 것입니다. 이것이 없으면 복원이 불가능합니다.

• 문서 옆에 <파일>.vault.json으로 생성되며, 권한은 0600입니다.

• --pass-env 플래그(scrypt + Fernet)로 암호화됩니다.

• 정규형, 발견된 모든 변형, 문서 순서대로의 발생 기록을 저장합니다. 기록 덕분에 정확한 복원은 원래 단어 형태를 반환하며 정규형이 아닙니다.

• .gitignore에 포함되어 있습니다. 커밋하지 마세요.

정확성 및 한계

이 도구는 안전한 방향으로 오류를 발생하도록 설계되었습니다: 놓치는 것보다는 과도하게 마스킹하는 것이 낫습니다. 알아야 할 사항:

• 텍스트 레이어가 없는 스캔 PDF는 처리되지 않습니다. OCR이 필요합니다.

• 이니셜이 없는 동성은 별도의 태그를 받으며, 한 사람으로 병합되지 않습니다.

• 힌트가 없는 순수 숫자는 식별자로 인식되지 않을 수 있습니다. 하지만 편집증적 검사는 여전히 그러한 텍스트가 외부로 나가는 것을 방지합니다.

• 임의의 라틴 문자 이름은 슬라브어 어미나 호칭(Mr., Dr.)이 없으면 인식되지 않습니다. 두 개의 대문자 단어 쌍을 모두 잡으려 하면 이점보다 해가 더 클 것입니다.

중요한 문서의 경우 docs-masked report를 한 번 시각적으로 확인하는 것이 좋습니다.

개발

python3 -m pytest tests/ -q          # тесты
python3 -m pii_shield.cli selftest
python3 samples/make_samples.py      # пересоздать тестовые документы

깨뜨리면 안 되는 불변 조건은 AGENTS.md에 나열되어 있습니다. samples/의 모든 것은 합성 데이터입니다. examples/ 디렉토리는 로컬 문서용으로 예약되어 있으며 저장소에 포함되지 않습니다.

라이선스

MIT.