Secret Redactor: 프롬프트와 도구 출력을 지키는 Claude Code 시크릿 마스킹

Secret Redactor는 Claude Code 시크릿 마스킹을 해 주는 커뮤니티 모드로, 작성자는 Ray Amjad(ray-amjad)이며 그의 awesome-claude-code-function-hooks 모음에 들어 있습니다. 세 경로에서 동작합니다. 사용자가 입력하는 내용, 도구가 읽어 오는 내용, 첫 메시지에 붙는 컨텍스트 블록입니다. 시크릿, 이메일 주소, 공개 IP 주소는 모델이 보기 전에 [REDACTED-SECRET-164d0c98] 같은 자리 표시자로 바뀝니다.

값이 사라지는 것은 아닙니다. 같은 값에는 항상 같은 자리 표시자가 붙으므로 Claude는 고객이나 키를 계속 구분할 수 있습니다. 이후 Claude가 도구를 호출하면 hook이 자리 표시자를 되돌리기 때문에 Bash 명령이나 Write에는 실제 값이 담깁니다. cat .env를 하면 Claude에게는 자리 표시자가 보이고, 그것을 쓰는 뒤의 명령도 그대로 동작합니다.

숨기는 대상은 벤더 고유 형식의 키(sk-ant-, ghp_, AKIA, sk_live_, JWT, Slack과 Discord 웹훅, 개인 키 블록, 연결 문자열 안의 비밀번호), 엔트로피가 높은 토큰, 이메일 주소, IP 주소입니다. 127.x, 10.x, 192.168.x 같은 사설 IP 대역은 기본적으로 그대로 보입니다. price_, prod_ 같은 Stripe 객체 id는 공개 정보로 취급합니다. 작성자의 README에 따르면 함수 hooks를 켜야 하므로, 아무 일도 일어나지 않는 것 같으면 먼저 그 부분을 확인하세요.

녹화에서는 작은 데모 프로젝트에서 함수 hooks를 켠 채 이 모드를 불러온 Claude Code를 시작합니다. 작성자의 test/fixtures/sample.env에 있는 예시 키(실제 자격 증명이 아닙니다)와 예시 이메일 주소가 든 프롬프트를 입력하고 Enter를 누릅니다. 제출된 프롬프트는 기록에서 KEY=[REDACTED-SECRET-164d0c98] mail [REDACTED-EMAIL-6f096ff7]로 바뀌고, 푸터 오른쪽에 secret-redactor: hid 2 value(s) from the prompt 토스트가 뜹니다. 클립은 Claude가 아직 작업 중일 때 끝나며 답변은 녹화하지 않았습니다.

설치 블록의 어느 방법을 써도 됩니다. 모두 작성자 본인의 마켓플레이스에서 바로 설치합니다. 그다음 함수 hooks를 켭니다. ~/.claude/settings.json에 "env": { "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1" }을 추가하거나 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude로 세션을 시작하세요. 설치하지 않고 써 보려면 저장소를 클론한 뒤 claude --plugin-dir ./awesome-claude-code-function-hooks/plugins/secret-redactor를 실행합니다.

hooks 모듈은 hooks/redact.ts 한 파일입니다. 모듈 수준의 보관소에 맵이 두 개 있고, 자리 표시자는 종류와 값의 FNV-1a 해시로 만들어집니다.

function mint(kind: Kind, value: string): string {
  hidden++
  const seen = byValue.get(value)
  if (seen) return seen
  const tag = `[REDACTED-${kind}-${fnv1a(value)}]`
  byValue.set(value, tag)
  byTag.set(tag, value)
  return tag
}

prompt.submit은 입력한 텍스트를 처리하고 토스트를 띄웁니다. tool.call은 먼저 도구 입력의 자리 표시자를 복원하고, await next(input)으로 도구를 실행한 다음 결과를 처리하며 도구 행에 개수를 표시합니다. prompt.context는 첫 메시지에 붙는 블록에서 시크릿은 처리하지만 이메일은 건드리지 않습니다.

값이 시크릿으로 판정되는 경우는 벤더 형식과 일치할 때, 24자 이상이면서 대소문자와 숫자가 섞이고 글자당 3.6비트를 넘는 토큰일 때, 또는 API_KEY=, "token":, Bearer 같은 이름 뒤에 오는 3.0비트를 넘는 더 짧은 토큰일 때입니다. 단어, 카멜케이스 이름, 알파벳, 순수 16진수에 대한 규칙이 git SHA와 식별자가 숨겨지는 것을 막습니다.

플러그인은 옵션 12개를 선언하며 /config 또는 사용자 설정의 pluginConfigs에서 바꿀 수 있습니다.

• secrets, pii: 각 종류를 끕니다.
• restoreInToolInputs: 도구 실행 전에 실제 값을 되돌려 놓는 동작을 멈춥니다.
• notify: 토스트와 도구 행의 개수 표시를 끕니다.
• minEntropy(3.6), minLength(24), contextMinEntropy(3.0): 올리면 덜 숨깁니다.
• redactPrivateIps: 127.x, 10.x, 192.168.x 등 예약 대역도 숨깁니다.
• allow, allowEmails, allowPrefixes, denyPrefixes: 쉼표로 구분한 예외와 추가 규칙입니다.

실행하기 전에 플러그인이 실행할 수 있는 모든 파일을 읽었습니다. plugin.json, hooks/hooks.json, hooks/redact.ts(유일한 모듈이며 타입 외에는 import가 없습니다), 테스트와 픽스처입니다. package.json, 설치 스크립트, 바이너리, 번들된 코드는 없습니다.

• 네트워크, 명령, 파일, 환경 변수: 모두 없습니다. 모듈은 $.http, $.process, $.fs, $.env를 호출하지 않고 $.store나 $.state도 쓰지 않습니다. 보관소는 모듈 메모리에 있고 세션과 함께 사라집니다. API 호출은 $.ui.toast와 $.ui.notice뿐입니다.
• 도구 호출을 가로채고 프롬프트를 읽습니다. 이것이 이 모드의 목적이며 README의 설명과 같습니다. 프롬프트를 고쳐 쓰고, 도구 입력(자리 표시자에서 실제 값으로)과 도구 결과(값에서 자리 표시자로)도 고쳐 씁니다. 호출을 거부하지는 않습니다.
• 복원은 하나의 권한입니다. 도구 입력에 있는 자리 표시자는 명령이 무엇이든 실제 값으로 바뀝니다. 도구 결과에 주입된 지시가 있으면 Claude가 curl 명령에 자리 표시자를 넣도록 유도될 수 있고, 그러면 실제 키가 전송됩니다. 걱정된다면 restoreInToolInputs를 끄세요. 대신 도구는 자리 표시자 텍스트를 그대로 받습니다.
• 자리 표시자는 비밀이 아닙니다. 해시는 32비트 FNV-1a이므로 이메일이나 IP처럼 엔트로피가 낮은 값의 자리 표시자는 후보를 해시해 보면 추측할 수 있습니다. 모델의 컨텍스트에서 값을 숨겨 주지만, 이미 추측을 시험해 볼 수 있는 사람에게서 지켜 주지는 않습니다. 이론상 두 값이 같은 해시를 가질 수도 있습니다.
• 휴리스틱은 놓치는 것이 있습니다. 엔트로피 규칙은 시크릿을 그대로 두거나 무해한 토큰을 숨길 수 있습니다. 모델이 쓴 내용은 검사하지 않으며, 재시작 후에는 유지되지 않습니다.
• 텔레메트리가 없고 지시를 주입하지 않습니다. 자리 표시자 외에 프롬프트에 자체 문구를 더하지 않습니다.
• 라이선스: MIT이며 저장소에 LICENSE 파일이 있습니다.

claude plugin validate는 오류나 경고를 보고하지 않았지만, 노트에는 .catch가 없는 게이팅 hook이 둘(prompt.submit과 tool.call) 있다고 표시됩니다. hook이 예외를 던질 때 대비한 보호 장치가 없으므로, hook의 버그 때문에 프롬프트나 도구 호출이 그대로 통과하지 않고 실패할 수 있습니다. claude plugin test는 실행할 테스트를 찾지 못했습니다. 작성자의 테스트가 *.test.ts가 아니라 test/detect.test.mts(일반 Node 스크립트)이기 때문입니다. 이 테스트는 실행하지 않았습니다.

macOS의 Claude Code 2.1.291에서 확인했습니다. validate는 통과했고, 플러그인을 불러온 데모도 동작했습니다. 아무것도 숨겨지지 않는다면 다음을 확인하세요.

• 함수 hooks가 켜져 있는지: 설정 또는 Claude Code를 시작하는 셸에 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1을 설정합니다.
• 이미 열려 있는 세션에 설치했다면 /reload-plugins를 실행합니다.
• 그 값이 제외 목록에 있는지: @example.com 같은 문서용 도메인, noreply@ 주소, 사설 IP 대역, Stripe 객체 id는 의도적으로 그대로 둡니다.
• 입력창에는 입력한 그대로 보이고, 자리 표시자는 프롬프트를 제출한 뒤에 나타납니다.