API Key 與 Secrets Management 安全指南：儲存、輪替、Vault 與外洩應變

先講結論：Secrets Management 管的是能力，不是字串

Secret 是任何能讓持有人通過驗證、解密資料、簽署內容或取得特殊能力的資料。它可能是 API Key、資料庫密碼、Session Signing Key、TLS／SSH Private Key、Webhook Secret、OAuth Client Secret、雲端 Access Key、Kubernetes Service Account Token，或用來解開 Data Encryption Key 的 Key Encryption Key。是否看起來像密碼並不重要，重要的是洩漏後能做什麼。

把 Secret 加密存入資料庫只解決部分靜態保存問題；應用程式仍要取得解密能力，執行期間也可能從記憶體、環境變數、Log、APM、Crash Dump、CI Artifact 或管理介面外洩。完整設計要同時保護 Secret 的來源、控制平面、交付路徑、執行時使用與撤銷能力。

最好的 Secret 是不需要存在的長效 Secret。能以雲端 Instance／Workload Identity、Kubernetes Service Account Federation、OIDC 或 mTLS 短效憑證完成驗證時，就不應在程式、映像或 CI Variable 中保存固定金鑰。

• 先消除不必要的長效 Secret，再集中管理剩餘項目
• 每組 Secret 必須有 Owner、用途、Scope、環境、消費者、到期日與輪替方式
• 人員、服務、機器與加密金鑰採不同驗證與治理流程
• 任何系統都要假設 Secret 終有一天會外洩，預先具備撤銷與更換能力

先分類：API Key、Token、密碼、憑證與加密金鑰不是同一種東西

API Key 常同時扮演 Client Identifier 與 Bearer Credential，持有者即可使用；密碼通常由人員輸入並在驗證端以密碼雜湊保存；Access Token 是帶有效期與授權範圍的委派憑證；Certificate 公開部分可散布，但 Private Key 必須保護；Encryption Key 則直接關係資料是否能被解密。不同種類的產生、保存、輪替與撤銷方法不能共用一套粗略規則。

設計 API Credential 時，若供應端支援，應拆成可公開辨識與查詢的 Key ID，以及只在建立時顯示一次的 Secret Value。服務端儲存不可逆雜湊或可輪替的受保護表示，Log 只記 Key ID 與版本，避免為了查找而保存或輸出完整值。

威脅面不只 Git：Secret 會沿著整條交付鏈複製

一組固定 Secret 可能從開發者電腦進入 Git History、Pull Request、CI Log、Build Cache、Container Layer、Helm Values、Terraform State、部署平台、環境變數、Process List、Core Dump、APM Span、客服截圖與備份。只檢查目前 Branch 或 Runtime Vault，會漏掉大量副本。

攻擊者不一定直接入侵 Vault。他可能取得讀取 CI Job 的權限、提交能列印環境變數的惡意變更、利用 SSRF 讀取 Metadata Credential、攻擊 Sidecar Socket、下載 Artifact，或透過過寬的 Secret Read 權限橫向移動。因此威脅模型必須畫出產生者、儲存端、Broker、Consumer、目標服務、稽核端與管理者的每條資料流。

建立 Secret Inventory：沒有清冊，就無法證明已經輪替

Secret Inventory 不應保存 Secret Value，而是保存治理 Metadata：唯一 ID、類型、Owner、業務用途、來源系統、Consumer、Target、Environment、Scope、建立時間、有效期、最後輪替、下次輪替、撤銷方式、資料敏感度與相依服務。清冊要能從 Vault、雲端 IAM、Certificate Manager、CI 平台與 Repository Scanner 自動彙整。

Owner 不能只填離職後失效的個人帳號，應指向可接手的 Team 與 Service。無 Owner、無到期日、無最近使用紀錄或多環境共用的 Secret，應列為優先治理。盤點也要辨識同一值被複製成多個名稱的情況，否則輪替一處不代表風險已清除。

• 禁止在 CMDB、Ticket 或試算表欄位中保存 Secret Value
• 以機器可讀 Metadata 驗證 Owner、Expiry、Rotation 與 Usage
• 對 Unknown、Orphaned、Never-used、Long-lived、Cross-environment 項目建立清理佇列
• 把建立、讀取、輪替、拒絕與撤銷事件送入集中式稽核

安全產生：足夠熵、不可預測、每個用途唯一

Secret 必須由受信任的 CSPRNG 或 KMS／HSM 產生，不以時間戳、序號、UUID v1、使用者資料或自訂雜湊拼接取代亂數。熵需求要依 Secret 可否離線猜測、有效期與速率限制決定；一組高熵值若永不到期、跨環境共用，仍會造成巨大爆炸半徑。

格式可以加入不具機密性的 Prefix、Key ID、版本與 Checksum，協助 Secret Scanner 精準辨識與營運追蹤，但不可因此縮短有效亂數。Production、Staging、Development、每個 Tenant、每個 Integration 與每個工作負載應使用不同 Credential，避免單點外洩擴散。

• 建立後只顯示一次完整值，後續管理介面僅顯示 Key ID 與尾碼
• 不同用途、環境與服務不得共用固定 Credential
• Secret 預設有 Expiry、Scope 與 Owner，不允許無期限空白欄位
• 可使用時優先由系統即時產生短效 Credential，而非人工複製

Vault、KMS、HSM 與 Password Manager 各自解決什麼？

Secrets Vault 負責集中保存、政策授權、版本、租約、動態憑證與稽核；KMS 負責集中管理加密金鑰並執行加解密或 Rewrap；HSM 以硬體邊界保護高價值 Key Material 並可做到不可匯出；Enterprise Password Manager 則適合人員登入、Break-glass 與少量互動式 Secret。它們可組合，但不能互相假冒。

應用把 Ciphertext 與固定解密 Key 一起放在相同 Repository、Image 或設定檔，並不構成有效加密。Envelope Encryption 應以 Data Encryption Key 加密資料，再由獨立權限與生命週期的 Key Encryption Key 保護 DEK；應用只獲得完成必要操作的能力，而非匯出 Master Key。

先解決 Bootstrap Secret：工作負載如何證明自己是誰

把 Vault Token 寫進環境變數只是把問題往前移。工作負載應利用平台可驗證的原生身分，例如雲端 IAM Role、Kubernetes Service Account Token Projection、SPIFFE／mTLS Identity、GitHub Actions OIDC，向 Vault 或目標服務交換短效 Credential。驗證要綁定 Repository、Branch／Environment、Namespace、Service Account、Image Identity 或部署政策。

身分證明也必須短效、具 Audience、不可跨環境重播，且 Vault Policy 只允許讀取特定路徑或簽發特定角色。若使用 Node Bootstrap Token，應限制單次使用、設備或網路範圍，首次註冊後立即換成可輪替的工作負載身分。

靜態與動態 Secret：能即時簽發，就不要永久保存

Static Secret 由人員或系統建立後長期存在，外洩窗口等於存續時間；Dynamic Secret 則由 Vault 或目標系統按請求建立，帶有短 TTL、明確 Scope 與 Lease，到期自動撤銷。資料庫帳號、雲端 Role Credential、PKI Certificate 特別適合動態化。

動態憑證並非沒有成本：目標系統要承受建立與撤銷、應用要在到期前續租或重新取得、故障時不能無限制沿用舊值。設計必須定義 Lease Renewal、最大 TTL、Grace Period、Cache、Clock Skew、Vault 暫時不可用與撤銷失敗的處理。

• TTL 依任務時間設定，不把短效 Token 續租成永久 Token
• 每個工作負載取得獨立 Credential，便於歸因與單點撤銷
• 目標端權限由 Role Template 限定，不讓 Consumer 任意要求更高權限
• 續租、失敗、到期與撤銷皆可觀測並有告警

最小權限與爆炸半徑：Secret 本身也要有授權模型

高熵只降低被猜中的機率，無法限制外洩後的權限。每組 Credential 應限制可呼叫的 API、資料庫 Schema／Operation、Tenant、環境、來源工作負載、網路位置、每日額度與有效時間。對支援條件式政策的服務，可綁定 mTLS Certificate、DPoP Key、Source VPC 或 Egress Proxy。

Read Secret 與 Manage Secret 必須分離：應用能取用特定版本，不代表能建立、列舉、修改 Policy 或讀其他環境；維運者能管理 Metadata，也不一定需要看到 Value。Break-glass 權限要短效、需理由與雙人覆核，使用後自動撤銷並觸發檢討。

安全分發：把 Secret 送到程式，比存在 Vault 更容易出錯

應用取得 Secret 時應透過雙向驗證與加密通道，優先交付到記憶體或權限受限、生命週期受控的 RAM-backed File；若 SDK 支援，可由 Agent／Sidecar 管理續租與檔案原子更新。環境變數部署簡單，但常會被 Child Process、Debug Endpoint、Container Inspect、Crash Report 或錯誤收集工具讀取，不適合所有高價值 Secret。

不要把 Secret 當 Command-line Argument、URL Query、Frontend Build-time Variable、HTML、Mobile App 常數或 Browser Local Storage。前端需要呼叫第三方服務時，應由 Backend 代理、使用使用者委派的短效 Token，或使用供應端明確設計為可公開且受 Origin／Quota 限制的 Public Key。

• 檔案使用最小 UID／GID 權限、原子替換並禁止寫入持久磁碟與備份
• 不在 Log、Trace、Metric Label、Exception、Health Endpoint 或 Support Bundle 回傳 Value
• Secret Cache 設最短必要時間，程序終止與撤銷時清除
• 禁止管理介面提供『顯示所有 Secret』或批次匯出功能

Kubernetes Secret 不是天然保險箱

Kubernetes Secret 提供與一般 ConfigMap 不同的物件類型與掛載方式，但 Base64 只是編碼。叢集必須啟用 etcd Encryption at Rest、限制 Secret API 的 get／list／watch 權限、隔離 Namespace 與 Service Account，並保護 etcd 備份與控制平面。能建立 Pod 的人，往往也能把有權限的 Secret 掛進 Pod，因此 RBAC 不能只盯著 Secret Resource。

優先以外部 Secret Store CSI／Operator 搭配 Workload Identity 取得短效值，避免把第三方長效金鑰長期複製進 etcd。仍需檢查 Node、Kubelet、Privileged Pod、HostPath、Ephemeral Container、Debug 權限與 Admission Policy，因為執行節點上的高權限可能繞過應用層隔離。

• 預設拒絕跨 Namespace 讀取，禁止不必要的 list／watch
• etcd、Snapshot 與 Backup 全部加密並限制營運存取
• Service Account Token 使用投射式短效 Token 與明確 Audience
• 以 Admission Policy 阻擋 Privileged、HostPath 與未授權 Secret Mount

CI/CD 不要保存永久 Cloud Key：改用 OIDC Federation

現代 CI 平台可對每次 Job 簽發短效 OIDC Token，Cloud IAM 或 Vault 驗證 Issuer、Audience 與 Claims 後，再交換成工作所需的短效 Credential。以 GitHub Actions 為例，Trust Policy 應限制 Organization、Repository、Branch／Tag、Environment 與 Workflow；只信任 Issuer 但不限制 Subject，會讓其他 Repository 取得相同 Role。

Fork Pull Request、第三方 Action、Self-hosted Runner 與可修改 Workflow 的權限，都會影響 Secret 邊界。高權限部署應使用受保護 Environment、人工核准、固定 Action Commit SHA、最小 GITHUB_TOKEN Permission、隔離 Runner，並禁止未受信 PR 取得 Production Credential。

輪替不是改值：要做到不中斷、可回復、確實淘汰舊版本

成熟輪替採雙版本或可重疊有效期：先建立新版本、更新 Consumer、確認新值被成功使用，再撤銷舊值。應用要能在不中斷的情況重新載入 Secret，避免把輪替等同每次重啟整個系統；對 Signing／Encryption Key，還要區分新增 Key、切換 Primary、保留驗證／解密舊資料與最終退役。

輪替頻率應依 Secret 價值、外洩可能性、TTL 與撤銷能力決定，不用固定 90 天掩蓋無法自動化的設計。任何疑似外洩、Owner／供應商變更、權限縮減、環境複製錯誤或加密演算法退役，都應觸發事件型輪替。

Secret Scanning：越早阻擋越便宜，但掃到不等於處理完

掃描應覆蓋 IDE／Pre-commit、Push Protection、Pull Request、完整 Git History、CI Log、Artifact、Container Layer、IaC State 與協作平台。Pattern 應結合已知 Provider Format、高熵、Prefix 與驗證 API；同時以 Allowlist、測試假值規則與指紋降低誤報，但不能因噪音而關閉阻擋。

若真實 Secret 曾被 Commit，即使尚未 Merge、已 Force Push 或 Repository 是 Private，也應視為外洩。Git History、Fork、Clone、Cache、Email Notification、Code Review Bot 與備份可能已有副本。處置順序是撤銷或輪替，再清除歷史與修正來源；只用 BFG／filter-repo 改歷史不能恢復可信度。

• Scanner 告警記錄 Secret Fingerprint／Provider／位置，不把完整值複製進 Ticket
• 高可信、可用的 Production Secret 直接阻擋 Push／Build 並觸發撤銷流程
• 測試 Fixture 使用明確不可用的保留格式，避免訓練團隊忽略告警
• 定期掃描完整歷史與發布 Artifact，不只掃目前檔案

可觀測性：記錄誰在何時使用，不記錄 Secret 本身

Vault 與目標服務應記錄 Authentication Identity、Secret／Key ID、Version、Action、Target、Policy Decision、來源工作負載、時間、結果與 Request Correlation；Log 必須具完整性保護、集中保存且和管理權限分離。任何 Value、Authorization Header、Private Key 或可重建 Token 的資料都要在採集前遮罩。

有效告警包括：不常用 Secret 突然使用、異常地區／工作負載、拒絕暴增、同一 Credential 跨環境、接近到期仍被使用、已撤銷版本持續出現、批次讀取大量 Secret、管理政策變更，以及 CI Job 嘗試讀取不相關環境。

外洩應變：先讓憑證失效，再清來源與查影響

確認或合理懷疑 Secret 外洩時，不要等待完整鑑識才撤銷。先保存必要證據與 Fingerprint，停用舊版本、簽發最小權限替代值、更新 Consumer 並確認服務，再調查外洩時間、可用範圍、使用紀錄、衍生 Credential、受存取資料與橫向移動。若是 Signing／Encryption Key，需評估偽造內容、已簽 Token、歷史資料與憑證撤銷。

事件結束必須清除根因：移除 Repository／Artifact／Log／Image 中的值、修正 CI 與 Redaction、縮小 Trust Policy、增加 Scanner、盤點相同 Credential 的所有副本。最後實測舊值在每個 Target 都被拒絕，不只確認 Vault 中已刪除。

高可用、備份與 Break-glass：Vault 故障不能逼團隊繞過控制

集中式 Vault 進入所有服務的關鍵路徑後，必須設計多可用區、容量、Rate Limit、災難復原、加密備份、Restore Drill 與 Audit Pipeline。Fail-open 會把故障變成未授權存取；Fail-closed 若沒有短暫 Cache 與明確 Runbook，則可能擴大營運中斷。每類 Consumer 要定義可接受的租約與降級策略。

Break-glass Credential 應獨立保存、強 MFA、雙人控制、一次性或短效、每次使用強制理由並立即告警。演練不只確認能打開 Vault，還要驗證在控制平面失效時能恢復 Root of Trust、重新簽發工作負載憑證，且不需要把 Master Key 貼到聊天室。

• 定期執行 Restore、Unseal／Recovery、CA／KMS 故障與大規模輪替演練
• 備份包含必要 Ciphertext 與 Metadata，但加密 Key 和備份權限分離
• 應用 Cache 有明確上限，撤銷事件可強制失效
• Break-glass 使用後輪替、檢討並驗證所有副本已收回

測試與驗收：不要只驗 Vault UI 可以登入

安全驗收要從 Consumer 觀點測試：沒有權限的工作負載拿不到 Secret；有權限者只能取得指定路徑與版本；短效 Credential 到期後確實失效；輪替期間服務不中斷；舊值撤銷後每個目標都拒絕；Log、Trace、Crash 與錯誤頁沒有值；控制平面暫時不可用時行為符合 Runbook。

也要測試政策變更、跨 Namespace／Tenant、CI Fork、惡意 Pull Request、Debug Container、SSRF、備份還原與 Secret Scanner Bypass。測試資料使用不可用假值，任何 Production Credential 都不得進入測試工具輸出或 Issue 附件。

• 以 Negative Test 驗證跨服務、跨環境、跨 Tenant 都被拒絕
• 以短 TTL 測試 Renewal、Expiry、Clock Skew 與撤銷
• 輪替演練包含建立、分發、切換、觀察、撤銷與回復
• 掃描 Source、History、Image、Artifact、Log 與 IaC State
• Red Team／Tabletop 模擬 CI、SSRF、Runner 與管理帳號外洩

分階段導入：先處理爆炸半徑最大、最難撤銷的 Secret

第一階段建立 Inventory、Owner 與禁止新 Secret 進 Git 的 Gate；第二階段把 Production Cloud Key、CI/CD、共享資料庫管理帳號與 Signing Key 移入 Vault／KMS／HSM；第三階段導入 Workload Identity、OIDC 與動態憑證；第四階段自動輪替、撤銷、異常偵測與事件演練。

遷移不能只把現有值原封不動搬進 Vault。每一批都應趁機拆分環境與 Consumer、縮小 Scope、設定 TTL、建立 Rotation Runbook、清除舊副本並驗證舊值失效。否則只是把集中式 Vault 變成存放高權限永久密碼的單一風險中心。

常見迷思：加密、遮罩與 Private Repository 都不是完整控制

『Repository 是 Private 所以可以放 Key』忽略協作者、Fork、CI、備份與帳號接管；『平台會 Mask』只對已登記且格式一致的值有效，編碼、切片、錯誤物件與 Artifact 仍可能洩漏；『每 90 天改一次就安全』忽略外洩後 89 天的風險與人工輪替錯誤；『Kubernetes Secret 已加密』也常只代表 Base64。

另一個迷思是『所有 Secret 都應由安全團隊人工保管』。人工發送造成等待、複製與不可稽核的旁路。安全團隊應治理信任模型、平台與政策，讓受信工作負載在最小權限下自助取得短效 Credential，而不是成為把密碼貼給每個人的瓶頸。

上線前檢查清單

下列項目應轉成平台 Policy、CI Gate、Dashboard 與定期演練，不只留在文件。若任何關鍵 Secret 無法回答 Owner、Consumer、Scope、Expiry、Rotation、Revocation 與 Audit，便不能視為已受控。

• Inventory 不保存 Value，且所有 Production Secret 有 Team Owner、用途、Scope、Expiry 與 Consumer
• Repository、History、CI Log、Artifact、Container、IaC State 與協作平台都有 Secret Scanning
• 工作負載優先使用 OIDC／Cloud／Kubernetes／mTLS Identity，沒有固定 Bootstrap Key
• Vault、KMS、HSM 與 Password Manager 依用途分工，Master Key 不可與 Ciphertext 同域
• 每個環境與服務使用獨立 Credential，應用只能讀需要的路徑與版本
• 分發過程不經 URL、Command Line、Frontend Bundle、Log、Trace 或持久磁碟
• 輪替可雙版本、不中斷、自動觀察並實測舊值撤銷
• 外洩 Playbook 以撤銷為優先，能查 Key ID 使用紀錄與衍生權限
• Vault 高可用、備份、Restore、Break-glass 與大規模撤銷都定期演練

Redmark 在 Secrets Management 流程中的角色

Secrets Management 平台負責 Credential 的生命週期；Redmark 的網站弱點掃描則從對外應用角度，協助發現可能暴露 Secret 的公開檔案、錯誤頁、前端資源、設定遺留與可被利用的網站弱點，並持續驗證修復後的攻擊面是否收斂。兩者互補，但網站掃描不能取代 Repository、CI Artifact、Container、Cloud IAM 與 Vault Audit 的專用檢查。

實務上可把 Secret Leak、SSRF、任意檔案讀取、目錄暴露與 Debug Endpoint 等結果，連結到 Credential 撤銷與輪替 Runbook；修復後重新掃描，確認公開面不再暴露，再由 IAM／Vault／目標服務 Log 驗證舊憑證失效與未遭濫用。