紀錄工作經驗、相關知識,解決技術相關問題。

時事新聞, 資訊相關

Claude Code 核准設定把機密寫進 settings.local.json:外洩原因、自查與預防

Claude Code 核准設定把機密寫進 settings.local.json:外洩原因、自查與預防 特色圖片

Claude Code 在你按下「Yes, and don't ask again」時,會把核准過的指令存成 .claude/settings.local.json 裡的一條規則。如果那行指令裡夾著資料庫密碼或 API token,機密就跟著進了檔案,再被一起 commit 到公開的 GitHub repo。

資安公司 Apiiro 在 2026 年 11 月初掃描公開 GitHub,發現 104,185 份這個檔案裡,有 1,122 份含真實機密。

新聞標題多半寫成「資安漏洞」,但我讀到的 Apiiro 原報告談的是核准機制加上檔案管理方式造成的外洩,報告內沒有提到 CVE 編號。

本文先整理報告的重點,再說明機密為什麼會進檔案、怎麼檢查自己有沒有中,以及外洩後與平常該做的處理。

事件重點:Apiiro 看到什麼

Apiiro 的資料來自 2026 年 11 月 1 日到 3 日對 GitHub 預設分支的唯讀搜尋,沒有使用或測試任何憑證,也沒有連線到任何主機。

項目數字
公開的 .claude/settings.local.json104,185 份,分布在 103,617 個 repo
含真實機密的檔案1,122 份(1.1%)
這些檔案內的不重複機密1,379 個
加上 git 歷史、共用 settings.json、對話紀錄後的總數2,539 個,分布在 1,994 個 repo
受影響的組織63 個

報告對 1,379 個機密的細分如下:

  • 379 個資料庫密碼、122 個 Supabase service-role key。
  • 43 組 SSH 登入、42 個 GitHub/GitLab/npm token、23 個 AWS key、6 把私鑰。

「真實機密」在報告裡的定義是符合服務商金鑰格式,或密碼、token 旁邊出現公開主機。Apiiro 說明沒有驗證這些憑證是否仍然有效,但其中一個組織確認自己的金鑰當時仍在使用。

補充說明:報告也提到,刪掉檔案無法解決問題。檔案的舊版本裡還有 734 個真實機密,分布在 509 個 repo,現行檔案已經看不到;211 個 fork 也複製了同樣的機密。

機密為什麼會進檔案

整個過程沒有任何一步看起來有問題,這也是它難防的原因。

  1. 你請 Claude Code 查資料庫、跑 migration 或呼叫 API,它提議的指令需要帶憑證才能執行,例如連線字串或 PGPASSWORD=。
  2. Claude Code 在執行前詢問,提示出現多次後,使用者很容易不再逐字看指令。
  3. 你選「Yes, and don't ask again」,Claude Code 把這個核准存成 allow 規則,寫進專案資料夾的 .claude/settings.local.json。Apiiro 觀察到,規則內容就是那一行指令,包含裡面的密碼。
  4. 這個檔案跟著專案一起被 commit、push。

Apiiro 的資料顯示,檔案越大越容易有機密:超過 8 KB 的檔案,每十份就有一份含真實機密;小於 500 bytes 的,不到五百分之一。

官方文件怎麼說這個檔案

Claude Code 官方文件把 settings.local.json 定位成「只對你、只對這個專案生效」的設定,不是給團隊共用的檔案。

設定檔用途是否該進 git
~/.claude/settings.json你在所有專案的個人偏好不在專案內
.claude/settings.json團隊共用的權限、hooks 等可以 commit
.claude/settings.local.json你在單一專案的個人設定不該 commit

文件說明,Claude Code 第一次在 git repo 寫入這個檔案、而該 repo 還沒忽略它時,會把 **/.claude/settings.local.json 加到你的全域 git excludes 檔。手動建立的檔案不會有這個保護,要自己加進 .gitignore。

為什麼保護還是失效

這個保護是寫在你自己的機器上,沒有寫進專案的 .gitignore,所以出現下列情況時就不適用。Apiiro 列舉的是:

  • 資料夾是後來才變成 git repo。
  • 專案被 clone 到另一台機器。
  • 檔案早就被 commit 過。

Apiiro 還追蹤到:在 1,105 個含真實機密並追蹤過的 repo 中,有 539 個是由 Claude 共同署名的 commit 修改了這個檔案。報告指出,Claude Code 的 commit 指示要求模型不要 commit .env 或 credentials.json,但沒有把自己的設定檔列進去。

補充說明:官方權限文件寫到,如果這個檔案已被 git 追蹤,Claude Code 會把它當成 repository 提供的設定,等你信任資料夾後才套用其中的規則。依 Apiiro 的描述,使用者不會因此收到提示,下一次核准還是會附加到被追蹤的檔案裡。

為什麼掃描工具也漏掉

Apiiro 用 gitleaks 和 TruffleHog 掃了這 104,185 份檔案。在 1,122 份含真實機密的檔案中,gitleaks 抓到 564 份、TruffleHog 抓到 643 份,兩者都沒抓到的有 215 份。

原因是掃描工具偏重辨識金鑰格式。PGPASSWORD=、sshpass -p、mysql -p 後面跟的密碼,看起來只是指令裡一個普通的字。

怎麼自查:我的機密有沒有外洩

Apiiro 建議的檢查順序是:先看是否公開、再看是否曾被 commit、最後看檔案內容。以下指令都在本機的 git repo 內執行,Windows 可用 Git Bash 或 PowerShell。

步驟 1:檔案現在有沒有被 git 追蹤

在專案根目錄執行。有輸出代表這個檔案正在 git 管理,會跟著 push 出去。

git ls-files '*settings.local.json'

沒有輸出,代表目前沒有被追蹤。但這不代表過去沒有,繼續看下一步。

步驟 2:歷史裡有沒有出現過

即使檔案現在已被刪除,只要歷史裡出現過,所有 clone 與 fork 都可能還留著。

git log --all --oneline -- '*settings.local.json'

有輸出的每一行都是動過這個檔案的 commit。要看某個 commit 當時的內容:

git show <commit 編號>:.claude/settings.local.json

步驟 3:找出本機所有的副本

機密不只會在 repo 裡,你電腦上每個專案的 .claude/settings.local.json 都可能有。macOS、Linux 或 Git Bash:

find ~ -path '*/.claude/settings.local.json' 2>/dev/null

PowerShell:

Get-ChildItem -Path $HOME -Recurse -Force -Filter settings.local.json -ErrorAction SilentlyContinue |
  Where-Object { $_.FullName -like '*\.claude\*' } |
  Select-Object -ExpandProperty FullName

步驟 4:找出可疑的規則

在每個找到的檔案內,搜尋常見的「密碼寫在指令裡」寫法。下面的樣式涵蓋 Apiiro 點名的 PGPASSWORD=、sshpass -p、mysql -p、Bearer header,以及連線字串內嵌的帳密。

grep -nE 'PGPASSWORD=|sshpass +-p|mysql .*-p[^ ]|[Bb]earer +[A-Za-z0-9._-]+|://[^/ :]+:[^@ ]+@' .claude/settings.local.json

PowerShell 版本:

Select-String -Path .claude\settings.local.json -Pattern 'PGPASSWORD=|sshpass +-p|mysql .*-p\S|Bearer +\S+|://[^/ :]+:[^@ ]+@'

以測試用的假資料檔案為例,檔案內容像這樣(所有值都是虛構的):

{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(PGPASSWORD=FAKE_PASSWORD_123 psql -h db.example.invalid -U app -c 'select 1')",
      "Bash(psql postgres://user:[email protected]:5432/app)"
    ]
  }
}

上面的 grep 會列出第二、三條規則的行號,第一條沒有帶機密,不會被列出。

補充說明:這幾個樣式只涵蓋常見寫法,抓不到所有格式。有命中就要人工讀一遍整個 allow 清單,沒命中不代表安全。

步驟 5:檢查公開的 GitHub

如果你的專案放在 GitHub 的個人帳號或組織下,Apiiro 建議到 GitHub 搜尋 .claude/settings.local.json 和 .claude/settings.json。每個搜尋到的結果,都是現在任何人都讀得到的檔案。

發現外洩之後:先輪替,再清理

Apiiro 的建議順序是先輪替憑證,再處理檔案。這也和 GitHub 官方文件一致:機密外洩後,第一步是撤銷或輪替(revoke or rotate)該機密。

步驟 1:撤銷或更換每一個憑證

這份檔案出現過的每個密碼、token、金鑰,都視為已經外洩,到發行該憑證的服務重新產生並停用舊的。

  • 資料庫密碼:在資料庫端改密碼,並更新所有使用它的服務。
  • GitHub、GitLab、npm token:到各自的帳號設定頁面撤銷。
  • 雲端服務金鑰(AWS 等):到對應的主控台停用舊金鑰、建立新金鑰。
  • SSH 密碼:改密碼,並檢查主機上有沒有不認得的登入紀錄。

不能只刪檔案就當作結束。GitHub 文件指出,即使你改寫歷史並強制推送,含機密的 commit 仍可能在別處被存取;如果 commit 存在於任何 fork,在那裡仍然看得到;你也沒有辦法移除別人 clone 下來的副本。

步驟 2:讓 git 不再追蹤這個檔案

若步驟 1 之前的檢查顯示檔案在 git 裡,用下面的指令停止追蹤。這個指令只是把檔案從 git 索引移除,本機檔案還在。

git rm --cached .claude/settings.local.json

接著把它寫進 repo 自己的 .gitignore:

echo ".claude/settings.local.json" >> .gitignore

GitHub 文件說明,已經 commit 的檔案要先取消追蹤,再加忽略規則才有效。

最後用下面的指令確認規則生效,輸出會列出是哪一個檔案的哪一行規則擋住它:

git check-ignore -v .claude/settings.local.json

步驟 3:清理歷史,但輪替才是重點

GitHub 官方的「Removing sensitive data from a repository」文件,建議用 git-filter-repo 在本機改寫歷史,並說明需要支援 --sensitive-data-removal 旗標的版本,還提到可聯絡 GitHub Support 清除 pull request 上的快取畫面。

本文不示範具體的改寫指令,請依該頁當時的步驟操作。無論歷史有沒有改寫乾淨,步驟 1 的輪替都不能省。

預防:以後不要再把機密帶進這個檔案

不要把機密打進指令

這是根本做法。Apiiro 的建議是改用環境變數,讓規則記下的是變數名稱,不是密碼本身:

# 風險:密碼直接寫在指令裡,核准後會被存進規則
PGPASSWORD=實際密碼 psql -h 主機 -U 帳號

# 較好:指令只引用環境變數,規則記下的是 $PGPASSWORD
psql -h 主機 -U 帳號

第二種寫法需要你事先在自己的 shell 或密碼管理工具設定好 PGPASSWORD,不要把設定值也寫進被 commit 的檔案。

核准「模式」,不核准整行指令

Apiiro 建議核准類似 Bash(npm run:*) 這種模式,不要核准字面上帶了參數的完整指令。Claude Code 官方文件也說明,對指令前綴按「Yes, and don't ask again」時,寫入的是空格形式,:* 是等價的寫法。

每次出現選項前,看一下提示中「don't ask again for」後面實際會存成什麼,再決定要不要選。

在專案 .gitignore 加上這個檔案

不要只靠 Claude Code 寫在全域 git excludes 的那一行。把它也寫進專案的 .gitignore,clone 到別台機器或共用給團隊時,保護才會跟著專案走。Apiiro 也建議資安團隊把這個檔案加進組織的 .gitignore 範本。

定期整理 allow 清單

打開自己的 .claude/settings.local.json,刪掉含有密碼、token 的規則。Apiiro 指出,一個已經核准過的機密會一直留在檔案裡,直到有人刪掉那條規則為止。

在 pre-commit 和 CI 掃描

Apiiro 建議把 .claude/、.cursor/、.gemini/、.specstory/ 這類代理工具的資料夾,當成跟 .env 一樣的敏感資料處理,納入 pre-commit 與 CI 的機密掃描,歷史也要掃。選用的掃描工具要確認能抓出指令裡的密碼(PGPASSWORD=、sshpass -p、mysql -p、bearer header),不能只認金鑰格式。

GitHub 這邊,官方文件說明 secret scanning 會自動偵測憑證外洩,公開 repository 預設自動免費執行;push protection 則會在含機密的推送到達 repository 前阻擋,可由 repository 管理員、組織擁有者等角色啟用。

限制 Claude 讀取機密檔

Claude Code 官方的設定範例,示範了用 deny 規則禁止讀取 .env:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

這只能減少 Claude 直接讀到機密,擋不住你自己把密碼貼進對話或指令,所以仍要搭配上面的做法。

Anthropic 的回應與目前狀態

Apiiro 在報告發布前先通報了 Anthropic,並在發布後更新了報告。依報告 11 月 8 日的更新內容,Anthropic 的 Claude Code 負責人 Boris Cherny 於 11 月 7 日在 Hacker News 回應:

  • 過去 Claude Code 不做機密清除(secret scrubbing),但正在研究怎麼預防這個問題。
  • 考慮的方向包括確保 auto mode 能攔截、內建基本的機密掃描等,會先做原型再決定。
  • 他也表示 Claude Code 建立檔案時會 gitignore,因此他認為外洩的副本是手動建立後被 commit 的。

這個說法和 Apiiro 的調查結果有出入:Apiiro 認為保護只在特定情況有效,且找到由 Claude 共同署名的 commit 修改過這個檔案。目前雙方的差異我沒有辦法替任何一方下結論,修補時程也尚未公布,請以 Anthropic 官方公告為準。

小結

這次外洩的核心是一個習慣:機密被打進指令,指令被永久核准,檔案被一起 commit。

  • 先查:本機與 GitHub 上有沒有這個檔案、歷史裡有沒有出現過。
  • 先輪替:確認有機密就先換憑證,不要只刪檔案。
  • 再預防:機密改放環境變數、核准模式不核准完整指令,並在專案自己的 .gitignore 加上這個檔案。

參考資料與延伸閱讀

發佈留言