secretgate — 로컬 시크릿 방화벽 for 코딩 에이전트

자격 증명이 절대 LLM API에 전달되어서는 안 됩니다. secretgate는 이를 로컬에서 강제합니다. 결정론적 엔진(node scripts/secretgate.mjs, npm 설치 불필요, 키 불필요)을 사용합니다: gitleaks에서 가져온 221개 규칙 + 엔트로피 게이트 + Luhn 검증 카드 번호. 에이전트의 훅 API가 재작성을 허용하는 경우, 시크릿은 안정적인 플레이스홀더로 대체되고 에이전트가 다시 쓸 때 로컬에서 복원됩니다(redact-and-restore). 훅이 차단만 허용하는 경우(Claude Code/Codex의 프롬프트), 프롬프트는 재전송할 삭제된 복사본과 함께 차단됩니다.

활성화 → 설치 (이 스킬이 트리거될 때 먼저 수행)

이 스킬이 활성화되면(사용자가 시크릿 보호 / secretgate 설치 / 방화벽 설정을 요청), 닥터를 실행한 후 아직 연결되지 않은 부분을 연결하십시오. secretgate는 npm 패키지가 아닌 스킬입니다 — 자체 번들을 실행합니다:

node scripts/secretgate.mjs status                  # 이미 연결된 사항 확인
node scripts/secretgate.mjs install --claude-code   # ~/.claude/settings.json에 훅 + permissions.deny 추가
node scripts/secretgate.mjs install --codex         # ~/.codex/hooks.json + [features] hooks = true
node scripts/secretgate.mjs install --opencode      # ~/.config/opencode/plugin/에 자체 포함 플러그인
node scripts/secretgate.mjs install --all           # 세 가지 모두

--project는 Claude Code 설치를 ./.claude/settings.json으로 범위를 지정합니다. install은 번들 복사본을 ~/.secretgate/bin/에 고정하고 에이전트가 해당 복사본을 호출하도록 연결하므로 스킬 캐시가 제거된 후에도 계속 작동합니다. 설치 후 항상 사용자에게 에이전트 세션을 재시작하라고 알리십시오 — 훅은 시작 시 로드됩니다. 연결이 완료되면 삭제는 자동 및 결정론적입니다(훅이 수행하며, 사용자가 할 필요 없음).

명령어

명령어	기능
`status`	닥터: 에이전트별 연결, 엔진, 볼트 상태, 제한 사항
`scan <파일	디렉토리
`pipe`	stdin → stdout, 시크릿을 플레이스홀더로 대체
`allow <값>` / `allow --rule <규칙ID>` / `allow --path <glob>`	허용 목록(값은 SHA-256 해시로 저장, 절대 평문으로 저장하지 않음)
`vault list` / `vault clear`	플레이스홀더 매핑 확인(시크릿은 절대 표시하지 않음)
`uninstall --<에이전트>`	설치가 추가한 내용을 정확히 제거

보호 작동 방식 (사용자가 물을 때 설명)

프롬프트: Claude Code/Codex → 삭제된 복사본과 함께 차단됨([allow-secret] 추가하여 한 번 우회 가능). OpenCode → 조용히 그 자리에서 삭제됨.
파일 읽기: .env*, 키 파일, ~/.aws, ~/.ssh… 등은 완전히 거부됨(.env.example/.sample/.template은 읽기 가능). 값이 모델에 절대 입력되지 않음.
도구/bash 출력: SECRETGATE_<해시> 플레이스홀더로 대체됨(Claude Code + OpenCode; Codex는 아직 출력 재작성 불가).
복원: 에이전트가 파일(Write/Edit)에 플레이스홀더를 쓰면 실제 값이 디스크에 기록됨. Bash 복원은 기본적으로 OFF(프롬프트 인젝션 유출 방지) — ~/.secretgate/config.json에서 restoreBash: true로 활성화.
깨끗한 도구 호출: Claude Code 사전 도구 사용 훅은 최소 JSON({}, 결정 없음 = 일반 권한 흐름)을 반환하여 빈 stdout을 방지함. 빈 훅 출력은 Claude Code 버그(anthropics/claude-code#77782)를 트리거하여 일치하는 모든 도구 호출에서 자동 모드에서도 대화형 권한 프롬프트를 강제함 — 그리고 문서화된 "defer" 결정 값은 Claude Code <= 2.1.212에서 거부되므로, {}가 모든 곳에서 작동하는 기권 방식임.

보호되지 않는 영역 (사용자에게 솔직히 알림)

Claude Code @file 언급은 도구 훅을 발생시키지 않고 인라인 콘텐츠를 포함함(permissions.deny 규칙만이 유일한 보호 수단).
Codex 비대화형 실행(codex exec) — 상위 버그로 인해 훅이 작동하지 않음.
이미지/스크린샷/클립보드, MCP 도구 트래픽 및 설치 전에 이미 대화에 있는 모든 것.
훅 프로세스가 종료/타임아웃되면 에이전트는 계속 진행됨(에이전트 측 fail-open). secretgate 자체는 사전 이벤트에 대해 자체 오류 시 CLOSED로 실패.
차단된 프롬프트는 Claude Code에 의해 로컬로 에코됨(터미널에 Original prompt: 및 claude -p JSON result에 표시) — API는 이를 절대 보지 못하지만, 파이프된 헤드리스 출력은 민감한 것으로 간주하십시오.

거짓 양성

가장 좁은 수정을 선호하십시오: 해당 라인에 인라인 # pragma: allowlist secret(또는 gitleaks:allow) → allow <값>(해시됨) → allow --path <glob> → allow --rule <규칙ID>(최후의 수단). 프로젝트는 .secretgate.json에 추가 허용 목록 항목을 커밋할 수 있습니다({"allowlist": {"paths": […]}}).

secretgate — 로컬 시크릿 방화벽