Noirdoc

Noirdoc이란?

Noirdoc은 Claude Code용 오픈소스 “PII 가드”로, Claude에 도달하기 전에 민감 데이터를 가명화(pseudonymizes)한 후 사용자 제어 방식으로 원본 값을 복원합니다. 핵심 목적은 작업 중 실제 이름, 이메일, IBAN 및 기타 감지된 식별자가 Claude Code 컨텍스트에 들어가는 것을 방지하는 것입니다.

이 페이지에서는 동일한 기본 접근 방식을 다른 진입점으로 제공하는 내용도 설명합니다: 모든 LLM 워크플로우에서 문서를 가명화하는 로컬 CLI와 OpenAI, Anthropic, Azure용 API 호출을 세척하는 호스티드 프록시입니다.

주요 기능

• Claude Code용 PreToolUse 가명화: 훅이 Claude Code가 파일을 읽기 전에 보호된 파일을 가명화하여 실제 값이 Claude 컨텍스트에 들어가지 않습니다.
• 로컬 감지 및 처리: 감지와 가명화는 사용자 머신에서 실행되며, 페이지에 따르면 “우리에게도 가지 않는” 어떤 API 호출도 머신을 떠나지 않습니다.
• 로컬 reveal을 통한 가역 매핑: 가명화된 출력은 처리 후 자동 복원되며, noirdoc reveal을 실행해 터미널에서 원본을 확인할 수 있습니다.
• 경로 규칙을 통한 구성 가능한 보호: Glob 패턴(예: ./incoming/** 또는 *.contract.*)으로 가명화할 파일을 결정하며, 나머지는 그대로 유지됩니다.
• 매핑의 로컬 저장: 플러그인이 .noirdoc/cache/에 가명화된 복사본을 저장하고 가역 매핑을 로컬에 보존합니다(CLI 예시의 “one-shot” vs “persistent” 모드에 따라 동작이 다름).

Noirdoc 사용 방법

• Claude Code 플러그인 설치

  1. Claude Code 마켓플레이스에 추가: /plugin marketplace add nextaim-de/noirdoc-claude-plugin
  2. Claude Code 내 설치: /plugin install noirdoc@nextaim
  3. Claude Code에서 보호된 파일 열기 또는 읽기; 플러그인이 Claude가 보기에 앞서 감지된 항목을 가명화합니다.

• 워크플로우 후 로컬에서 원본 reveal

  • 자체 쉘에서 noirdoc reveal 실행해 원본 값 확인. 페이지는 reveal이 Claude Code 대화록 외부에서 발생한다고 강조합니다.

• 로컬 문서 워크플로우용 CLI 사용

  • 설치: pip install noirdoc
  • 예시 one-shot 왕복: 파일을 세척된 출력으로 가명화한 후 출력 파일로 reveal.
  • 예시 persistent 모드는 네임스페이스를 사용해 매핑을 명령 간 재사용합니다.

사용 사례

• Claude Code에서 개인/계정 식별자가 포함된 문서 작업: 실제 이름, 이메일, IBAN, ID가 포함된 파일을 보호해 Claude Code가 원본 대신 플레이스홀더를 받도록 합니다.
• 수신 계약서 또는 서류의 배치 가명화: 경로/glob 규칙으로 특정 폴더(예: incoming 디렉터리)나 파일 유형(예: *.contract.*)만 가명화하고 나머지 파일은 변경하지 않습니다.
• 복원된 답변의 제어 리뷰: Claude Code 대화를 “깨끗하게” 유지한 후 필요 시 터미널에서 noirdoc reveal 실행해 원본 값 복구.
• CLI를 통한 비-Claude LLM 워크플로우 통합: noirdoc으로 PDF, DOCX, 일반 텍스트를 로컬 가명화한 후 일관된 플레이스홀더로 응답 변환.
• 팀용 LLM API 요청 세척: 모든 OpenAI/Anthropic/Azure API 호출을 2줄 통합으로 세척하는 호스티드 프록시(또는 페이지에 따른 셀프 호스팅 버전) 사용.

자주 묻는 질문

• Noirdoc이 내 데이터를 제3자에게 전송하나요? 페이지는 감지가 로컬에서 실행되며 “우리에게도 가지 않는” 어떤 API 호출도 머신을 떠나지 않는다고 명시합니다.

• Claude Code 실행 중 민감 값은 어떻게 처리되나요? 플러그인이 Claude Code가 전달하기 전에 입력을 로컬에서 가명화하여 이름, IBAN, ID를 플레이스홀더로 교체합니다.

• 원본 값을 다시 가져올 수 있나요? 네. 플러그인이 응답을 자동 복원하며, 자체 터미널(Claude Code 대화록 외부)에서 noirdoc reveal 실행으로 원본 확인 가능합니다.

• 어떤 파일을 보호할지 어떻게 선택하나요? 페이지는 glob 패턴을 사용한 경로 규칙으로 자동 가명화할 파일을 결정한다고 설명합니다.

• Noirdoc을 여러 방식으로 사용할 수 있나요? 네: 페이지는 세 가지 진입점을 설명합니다—Claude Code 플러그인, 일반 문서 워크플로우용 로컬 CLI, API 호출용 호스티드 프록시(셀프 호스팅 옵션 포함).

대안

• 문서 수동 전처리 (프롬프트 전 가림): LLM에 텍스트를 보내기 전에 민감 필드를 직접 가릴 수 있지만, 플레이스홀더 일관성과 복원을 수동으로 관리해야 합니다.
• 일반 데이터 유출 방지(DLP) 또는 콘텐츠 필터링 도구: 민감 데이터 공유를 방지하는 데 도움이 될 수 있지만, Claude Code 워크플로에 맞춘 가역 플레이스홀더 매핑과 응답 복원을 제공하지 않을 수 있습니다.
• 기타 LLM “PII 마스킹” 미들웨어: 이 카테고리의 대안은 일반적으로 요청 전에 민감 문자열을 마스킹합니다; 통합 방식(플러그인 vs 프록시 vs 미들웨어)과 가역 매핑 및 로컬 워크플로 지원 여부를 비교하세요.
• LLM API용 셀프 호스팅 프록시 솔루션: 주요 필요가 API 스크러빙이라면 프록시 기반 접근이 제어를 중앙화할 수 있지만, Claude Code 플러그인은 Claude Code 내부의 로컬 처리를 중점으로 합니다.