maxgfr/secretgate

secretgate — 本地端機密防火牆，適用於程式碼代理工具

憑證絕不該傳送至大型語言模型 API。secretgate 在本地端強制執行此原則，使用確定性引擎（node scripts/secretgate.mjs，無須 npm 安裝，無須金鑰）：包含 221 條從 gitleaks 轉換而來的規則、熵值檢測以及 Luhn 演算法信用卡號檢查。若代理工具的鉤子 API 允許改寫，機密會被遮蓋為穩定的預留位置，並在代理工具寫回時於本地端還原（遮蓋並還原）；若僅允許封鎖（Claude Code/Codex 的提示詞），則提示詞會被封鎖，並提供一份已遮蓋的副本以供重新發送。

啟動 → 安裝（技能觸發時優先執行）

當此技能啟動（使用者要求保護機密 / 安裝 secretgate / 設定防火牆）時，先執行診斷，再連接尚未連接的部分。secretgate 是一項技能，而非 npm 套件——您執行的是其自身的套裝：

node scripts/secretgate.mjs status                  # 檢查已連接的項目
node scripts/secretgate.mjs install --claude-code   # 鉤子 + permissions.deny 至 ~/.claude/settings.json
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	標準輸入 -> 標準輸出，機密被遮蓋為預留位置
allow <值> / allow --rule <規則ID> / allow --path <萬用路徑>	加入允許清單（儲存為 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 還原預設為關閉（提示注入外洩防護）——可於 ~/.secretgate/config.json 中啟用 restoreBash: true。
• 乾淨的工具呼叫：Claude Code 的預先工具使用鉤子會回傳最小 JSON（{}，無決策 = 正常權限流程），而非空的標準輸出。空的鉤子輸出會觸發 Claude Code 的錯誤（anthropics/claude-code#77782），導致在自動模式下每個符合條件的工具呼叫都會強制彈出互動式權限提示；且文檔記錄的 "defer" 決策值會被 Claude Code <= 2.1.212 拒絕，因此 {} 是能在所有版本中正常運作的棄權方式。

未涵蓋的範圍（對使用者誠實告知）

• Claude Code 的 @file 內嵌引用不會觸發工具鉤子（僅 permissions.deny 規則能涵蓋）。
• Codex 非互動模式（codex exec）——上游錯誤，鉤子不會觸發。
• 圖片/螢幕截圖/剪貼簿、MCP 工具流量，以及安裝前已在對話中的內容。
• 若鉤子程序被殺死或超時，代理工具會繼續執行（代理端為容錯開啟）；secretgate 自身在預先事件的錯誤上會容錯關閉。
• 被封鎖的提示詞會被 Claude Code 本地端回顯（終端機顯示 Original prompt:，以及 claude -p JSON 的 result）——API 絕不會看到，但仍應將傳輸的無頭輸出視為敏感資訊。

誤報處理

優先選擇最狹義的修正：在該行加入 # pragma: allowlist secret（或 gitleaks:allow）內聯註解 → allow <值>（經過雜湊） → allow --path <萬用路徑> → allow --rule <規則ID>（最後手段）。專案可以在 .secretgate.json 中提交額外的允許清單項目（{"allowlist": {"paths": […]}}）。