데이터가
PC를 떠나지 않습니다

오프라인 한국 법률문서 비식별화 도구 — 인터넷 연결 없이 단일 실행파일로 동작. 규칙기반(정규식)·결정적·완전 오프라인. 대상 버전: v0.4.1 생성일: 2026-06-28

1. 무엇을 하는 도구인가

외부 AI(Claude·ChatGPT 등)에 법률문서를 입력하기 전에, 주민등록번호·사건번호· 연락처 등 식별정보를 로컬 PC에서 제거하는 전처리기다.

• 규칙기반(정규식) — AI 추론을 쓰지 않으므로 "왜 가려졌는지" 100% 설명 가능.
• 결정적 — 같은 입력 + 같은 설정 → 항상 같은 출력.
• 완전 오프라인 — 네트워크 코드 자체가 없다. 데이터가 PC를 떠나지 않는다.
• 사람이 최종 검수 — 자동 탐지는 초안. 검수 단계를 건너뛸 수 없도록 강제한다.
• 감사 가능 — 무엇이/몇 건/어떤 규칙으로 가려졌는지 리포트 (원본 식별정보 미포함).
• 다중인물 분석 (v0.2.0 신규) — 여러 관계자(원고·피고·피고인·피해자·대리인 등)를 개별 인물로 구분하고, 인물관계·사실관계를 표시한다. 결과를 PII 없는 graph-seed로 내보낼 수 있다. (§4 다중인물 분석)

전형적 사용 흐름

판결문/소장 등 원문
   │
   ▼  ① Agent Room-Shield 로 비식별화 + 사람 검수
비식별 텍스트  ──────────────►  외부 AI(요약·검토 등)에 안전하게 입력
   │
   ├─▼  ② (선택) 로컬 매핑테이블로 결과를 원래 당사자로 원복
   │
   └─▼  ③ (선택) 다중인물 분석 → 인물명부·관계·타임라인 / graph-seed (PII 미포함)

2. 반드시 알아둘 원칙 (책임 한계)

⚠ 이 도구는 보조 수단입니다. 자동 탐지는 초안이며 최종 책임은 사용자에게 있습니다. 반드시 검수 단계에서 결과를 확인한 뒤 사용하세요. (법원 환각 TF의 "AI 결과물 검증 의무" 원칙과 동일)

• 성명(R10)·로마자 성명(R20)은 기본 OFF. 정규식만으로 한글 인명을 정확히 가려낼 수 없음이 실측으로 증명되어, 직책 문맥 기반 후보 제안 전용이다. 사용자가 직접 포함시켜야 가려진다.
• 주소(R09)·계좌(R05)는 오탐 우려가 큼. 반드시 검수 화면에서 확인한다.
• 도구는 준식별자(지역·금액·날짜 등)를 자동으로 삭제하지 않는다 — 문서가 망가지기 때문. 대신 재식별 위험 경고만 띄운다.

3. 설치와 실행

설치 불필요. USB로 들고 다니며 망분리 PC에서도 바로 실행한다. (실행파일과 본 설명서를 같은 폴더에 두고 배포 — 리포에서는 exe가 engine/release/, 설명서가 guide/에 있다.)

AgentRoomShield-v0.4.1.exe 하나만 더블클릭하면 됩니다. (소켓 미오픈 — 완전 오프라인)

무결성 검증 (선택)

배포 파일이 변조되지 않았는지 확인하려면:

# release 폴더에서
Get-FileHash AgentRoomShield-v0.4.1.exe -Algorithm SHA256
# 출력 해시를 SHA256SUMS.txt 의 값과 대조

4. 검수 UI 사용법 (일반 사용자 권장)

AgentRoomShield-v0.4.1.exe를 더블클릭하면 데스크톱 GUI가 뜬다. (소켓 미오픈 — 완전 오프라인)

5단계 워크플로우

① 입력

• 파일 열기(.txt) 또는 본문을 직접 붙여넣기.

② 자동 탐지 (① 자동 탐지 버튼)

• 식별정보가 규칙별 색상으로 하이라이트된다.
• 성명(R10)·로마자 성명(R20)은 기본 미포함 후보로만 제안된다.

③ 검수 — 화면 왼쪽 원본 / 오른쪽 비식별 결과 비교

• 하단 목록에서 항목별 포함 토글(클릭) — 해제하면 그 항목은 가리지 않는다.
• 처리방식 더블클릭으로 순환 변경: mask → alias → blackout.
• 원본에서 텍스트를 드래그한 뒤 "수동 가리기" — 규칙이 못 잡은 항목을 직접 추가. (내부적으로 MANUAL 규칙으로 처리)
• 성명은 오탐이 많아 기본 미포함 — 직접 포함시켜야 가려진다.

④ 재식별 위험 경고 확인

• 지역·금액·날짜·관계 등 준식별자가 2종 이상 동시에 있으면 경고가 뜬다.
• 자동 삭제하지 않는다. 참고 후 사용자가 최종 판단한다. (§7)

⑤ 내보내기 ("검수를 완료했습니다" 체크 → ② 내보내기)

• 비식별 .txt + 감사 리포트 .report.json 생성.
• 별칭(alias) 항목이 있으면 .mapping.json(원복용)도 함께 생성.

검수 강제: "검수를 완료했습니다"를 체크하기 전에는 내보내기 버튼이 비활성이다. 새 탐지·토글·처리방식 변경이 발생하면 체크가 자동 해제되어 재검수를 유도한다.

다중인물 분석 (v0.2.0 신규)

검수 UI의 ③ 다중인물 분석 버튼으로 연다.

여러 관계자(원고·피고·피고인·피해자·대리인 등)가 등장하는 문서에서, 인물을 개별로 구분하고 인물관계·사실관계를 표시한다. 비식별 텍스트와는 별개의 보조 분석이며, 원본 신원은 담지 않는다.

1. 1차 후보 표 — 성명 후보(R10/R20)를 앵커로 인물을 뽑고, 앞쪽 역할 토큰으로 역할을, 가까운 PII(전화·주민번호 등)를 그 인물에 추정해 보여준다. 추정값이므로 사람이 확인한다.
2. 선택 병합(동일인) — 같은 사람의 여러 표기("홍길동"·"홍씨"·"원고")를 한 인물로 묶는다. 잘못 묶었으면 병합 해제(선택) 로 되돌린다. 전체 초기화 도 가능.
3. 역할 지정 — 인물의 역할을 직접 확정(쉼표로 복수 역할).
4. 분석·표시 갱신 — 인물 명부(토큰·역할·연결PII 종류) + 인물관계(대립·대리·혐의관계 등, 모두 [미확정] 후보로 표시·무죄추정) + 사실관계 타임라인 을 텍스트로 보여준다.
5. graph-seed 저장 — 위 구조를 deid-graph-seed/v2 JSON으로 내보낸다. PII 미포함(가명·역할· 관계유형만). 저장 시 외부 전송 경계를 고지하고, 안정 가명 키는 seed와 분리 저장하도록 유도한다 (키는 재식별을 가속할 수 있으므로 seed·외부 서비스와 함께 두지 않는다).

경계: 이 분석은 오프라인에서만 동작하며, 그래프 시각화·DB는 이 도구에 포함되지 않는다. graph-seed는 사용자가 수동으로 별도 서비스에 넘길 수 있는 산출물일 뿐, 자동 전송은 없다.

5. 처리 방식 3종 — mask / alias / blackout

• 전화번호는 mask 시 통신사/지역 식별자(첫 그룹)를 남긴다: 010-1234-5678 → 010-****-**** (가독성 유지).
• alias는 문서 출현 순서대로 [접두어1], [접두어2]... 라벨을 부여한다. 같은 원본값은 항상 같은 라벨로 매핑되어 문서 내 관계가 보존된다(예: 같은 사건번호는 모두 [사건1]).

처리방식은 검수 UI의 항목 목록에서 더블클릭으로 순환 변경한다.

6. 탐지 규칙 전체 목록 (R01~R20)

규칙은 변호사·판사·검사 3직군 기능리뷰(2026-06-22)를 반영해 정밀화되었다. 상세: 직군별 기능리뷰 반영

우선순위와 오버랩 해소

규칙마다 우선순위(priority) 가 있어, 더 길고 구체적인 패턴이 먼저 적용된다. 이미 점유된 문자 구간과 겹치는 후속 매치는 버려진다. 예: 주민번호(13자리)를 전화번호 패턴이 일부만 가로채는 일을 막는다. (선형 시간으로 처리 — 대형 판결문도 빠름)

7. 재식별 위험 경고

직접 식별자를 모두 가려도, 준식별자 조합으로 사건/당사자가 특정될 수 있다. 도구는 다음 4개 범주를 집계한다:

서로 다른 범주가 2종 이상 동시에 존재하면 경고가 뜬다:

⚠ 준식별자 조합 위험: (범주들) 가 함께 존재합니다. 직접 식별자를 모두 가려도 이 조합으로 사건/당사자가 특정될 수 있습니다. 내보내기 전 확인하세요. (도구는 이 항목을 자동 삭제하지 않습니다)

중요: 도구는 이 항목을 자동으로 가리지 않는다. 문서 맥락이 망가지지 않도록, 판단은 사용자에게 맡긴다. 필요하면 검수 화면에서 수동 가리기로 직접 처리한다.

8. 감사 리포트

검수 UI 내보내기 시 원본 식별정보 없이 감사 리포트가 생성된다 — 무엇이/몇 건/어떤 규칙·처리방식으로 가려졌는지의 집계만 담는다. (테스트로 강제)

포맷

• .report.json — 검수 UI 내보내기 시 자동 생성(기계 판독용).
• 엔진은 .html(브라우저 열람·인쇄) / .pdf(보고서 제출용, reportlab) 포맷도 지원한다.

JSON 구조 예

{
  "tool": "Agent Room-Shield",
  "schema": "deid-audit/v1",
  "total_detections": 12,
  "rules_triggered": 5,
  "items": [
    { "rule_id": "R01", "rule_name": "주민등록번호", "count": 2, "actions": { "mask": 2 } },
    { "rule_id": "R07", "rule_name": "법원 사건번호", "count": 3, "actions": { "alias": 3 } }
  ],
  "note": "원본 식별정보는 본 리포트에 포함되지 않습니다."
}

9. 별칭 매핑테이블과 원복(재식별)

alias 처리된 항목([사건1], [이메일2] 등)은 내보내기 시 로컬 매핑테이블(.mapping.json)에 원본값 → 라벨 대응이 저장된다. 외부 AI가 라벨이 든 결과를 돌려주면, 이 테이블로 원래 당사자/사건으로 되돌릴 수 있다(선택적 가역).

• 매핑테이블은 PC 밖으로 내보내지 말 것 — 원본 식별정보가 담긴다.
• 매핑테이블은 AES-GCM 비밀번호 암호화 저장을 지원한다(분실 시 복호화 불가).

10. 문서 포맷(.docx / .hwpx) 처리

향후 계획. 현재 배포본은 .txt 입력을 지원한다. .docx/.hwpx 직접 처리는 향후 추가할 예정이다.

11. 데이터 보안 — 네트워크 부재

이 도구의 핵심 보증은 "안 보낸다"가 아니라 "보낼 수단이 없다" 이다.

• 네트워크 코드가 코드베이스에 존재하지 않으며, 런타임에 소켓을 열지 않는다.
• 자동 가드 테스트(test_network_isolation.py)가 이를 회귀로 고정한다.
• 데이터·매핑테이블·리포트 모두 로컬 디스크에만 기록된다.

근거 문서: 기술 보증서 — 네트워크 부재 증명

12. 자주 묻는 질문(FAQ)

Q. 성명이 안 가려져요. A. 성명(R10)·로마자 성명(R20)은 기본 OFF(후보 전용)입니다. 검수 UI에서 후보를 직접 포함시키세요. 단 오탐이 많으니 반드시 검수하세요.

Q. 일반 날짜(범죄일시 등)까지 가려집니다. A. 생년월일(R11)이 일반 날짜를 함께 잡을 수 있습니다. 검수 화면에서 해당 항목의 포함을 해제하세요.

Q. 같은 사건번호가 문서마다 다른 라벨이 됩니다. A. 별칭 라벨은 한 번의 처리 단위 안에서만 일관됩니다. 여러 파일에 걸쳐 같은 라벨을 쓰려면 한 문서로 합쳐 처리하세요.

Q. 원래대로 되돌릴 수 있나요? A. alias 항목만 매핑테이블로 원복 가능합니다. mask·blackout은 복원 불가입니다.

Q. 인터넷이 필요한가요? A. 전혀 필요 없습니다. 망분리 PC·USB 실행을 전제로 설계되었습니다. (§11)

Q. 여러 명이 등장하는 사건에서 인물별로 구분·관계를 보려면? (v0.2.0) A. 검수 UI의 ③ 다중인물 분석 버튼을 쓰세요. 성명 후보를 앵커로 관계자를 뽑아 역할·관계를 추정하고, 검수자가 동일인 병합·역할 확정을 한 뒤 인물 명부·인물관계(무죄추정·[미확정] 표기)·타임라인을 보여줍니다.

Q. graph-seed 파일은 안전한가요? 외부에 올려도 되나요? A. graph-seed는 가명·역할·관계만 담고 원본 PII는 없습니다. 다만 안정 가명 키(.key) 는 재식별을 가속할 수 있으므로 seed와 같은 폴더에 두거나 외부 서비스에 함께 올리지 마세요. 전송은 사용자가 수동으로 하며 도구가 자동 전송하지 않습니다.

13. 문제 해결(Troubleshooting)

관련 문서

• README — 프로젝트 개요
• engine/README — 엔진 상세
• 기술 보증서 — 네트워크 부재 증명
• 직군별 기능리뷰 반영
• 개발계획서