公開客戶端洩漏稽核
稽核一個與 私有 後端通訊的公開客戶端程式碼庫。目標:公開表層必須是 自包含的——它可以揭露它發出的呼叫以及交換的資料形狀(這是任何已出貨客戶端都無法避免的),但除此之外不能再多。任何關於伺服器如何運作的多餘細節,都是攻擊者的免費偵察資訊,也是濫用的槓桿。
此技能產出三樣東西:一份發現清單(洩漏 + 客戶端安全性漏洞,每個都附有 file:line 與嚴重性)、一組已套用的修復,以及一份附有殘留建議的報告。
參考檔案(按需載入——請閱讀你需要的檔案,不要內聯所有檔案):
references/leak-taxonomy.md— 要追獵的揭露類別、每類別為何重要,以及起始搜尋模式。references/rewrite-rules.md— 註解/字串改寫規則,附有前/後範例;如何決定保留 vs 刪除。references/client-hardening.md— 客戶端安全檢查清單(權限、IPC、Token、DOM、網路、建置設定、供應鏈)。references/report-template.md— 輸出報告的結構。scripts/leak-sweep.sh— 一個參數化的 ripgrep 掃描腳本,用於啟動搜尋(請根據產品自訂模式陣列)。
核心心智模型
將每次揭露歸類到以下兩個類別之一:
- 必要最小限度(保留):客戶端呼叫的端點、它實際傳送和接收的請求/回應形狀、它自己的重試/退避/去抖動選擇、輸入驗證上限,以及
狀態 → UI 行為的對應。公開客戶端無法隱藏這些;假裝可以隱藏只是安全上的門面功夫。 - 過度揭露(修復):任何描述伺服器如何處理請求的內容、客戶端並非嚴格需要的伺服器端限制/配額、已出貨客戶端從未呼叫的端點、反映內部伺服器邏輯的錯誤分支、反濫用機制、基礎設施/技術棧識別碼、私有儲存庫/路徑,以及編碼了後端行為的測試腳手架。
改寫規則。 客戶端程式碼和測試可以陳述合約(「HTTP 422 → 顯示不支援的提供者訊息」)。它們不能解釋伺服器為何或如何執行此操作(「伺服器執行一次性網域檢查並以 422 拒絕」)。當註解解釋了伺服器行為時,要嘛刪除它,要嘛將其縮減為客戶端可觀察到的合約。請參閱 references/rewrite-rules.md。
工作流程
根據請求調整工作量:快速的「這東西會洩漏嗎?」是第 1-2 階段;「開放原始碼前清理」或「完整稽核」則是全部六個階段。對於大型程式碼庫,將第 2 階段分散到多個並行的唯讀代理(每個分類法叢集一個),並合併它們的 file:line 發現——但第 1 階段的範圍界定請務必先自己完成。
第 1 階段 — 界定公開/私有邊界
在開始搜尋之前,先為這個產品確立「私有」的定義。不要跳過此步驟——整個稽核都是相對於這個邊界來進行的。
- 識別正在稽核的公開成品以及私有的對應部分(後端、管理工具、基礎設施、單一儲存庫的兄弟專案)。如果界線不明顯,詢問使用者或從
AGENTS.md/README/CONTRIBUTING推斷。 - 列出該產品的後端技術棧、代管服務、資料庫、反濫用機制,以及任何測試/預備環境的輔助設施——這樣你才能在有洩漏時認出它。如果你不知道這些,這是你應該先向使用者提出的第一個問題。
- 寫下什麼是此客戶端的必要最小限度(它真實的端點和負載),這樣你就不會浪費精力去標記那些無可避免的內容。
第 2 階段 — 掃描洩漏
走查 references/leak-taxonomy.md 中的分類法。覆蓋整個儲存庫,而不僅僅是 src/:測試/e2e、文件、README/CHANGELOG、CI/工作流程檔案、.env* 及其 .example 副本、建置/設定檔、套件清單(腳本、postinstall),以及語系/i18n 字串(它們會內建在套件內部)。先執行 scripts/leak-sweep.sh <target-dir> 作為起始掃描,然後在上下文中閱讀命中結果——模式匹配是一個線索,而不是最終判決。對於每個真實的發現,記錄 file:line、一段簡短的引用文字,以及一句話的理由。同時也維護一個「已檢查,乾淨」的清單,以便報告顯示覆蓋範圍。
特別注意兩個高價值但容易被忽略的類別:
- 只差一步就會曝光的機密——在
git-ignore的.env*檔案中的真實值,但因為打包工具不遵守.gitignore,所以原始碼套件(商店/應用程式商店的「可審查原始碼」zip、npm pack、目錄備份)會包含它們。未追蹤 ≠ 安全。 - 測試/e2e 程式碼——確定性的測試憑證、特殊的查詢參數、已出貨客戶端從未呼叫的端點,以及敘述伺服器內部運作的註解。這是後端行為最常洩露的地方,因為測試文件記錄了預期的伺服器回應。
第 3 階段 — 客戶端強化
執行 references/client-hardening.md。這與洩漏是正交的:重點在於客戶端本身是否可被利用,無論它揭露了什麼。優先處理特權 IPC 上的發送者/來源驗證、認證 Token 的儲存與輸出、由頁面或伺服器衍生資料所餵養的 DOM/XSS 接收點、過於寬鬆的權限,以及允許被污染的建置重新指向後端或捆綁機密的建置時期設定。
第 4 階段 — 修復
套用修復。影響力排序:
- 首先關閉祕密洩露管道(從原始碼套件中排除
.env*/機密檔案;將真實值移出已提交的相鄰檔案)。 - 將改寫規則套用至洩漏的註解/字串/文件;傾向於重新命名程式碼,讓註解變得不再必要,勝過改寫註解。
- 刪除硬編碼了伺服器策略(session TTL、配額、已移除的端點)的無用程式碼。
- 將測試/文件修剪至客戶端可觀察到的合約;保留流程運作正常,刪除敘述性內容。
- 連同測試一起實施強化變更。
預設為保留行為:保持公開 API 合約、儲存金鑰、訊息名稱以及請求/回應形狀穩定,除非任務明確要求功能上的變更。
第 5 階段 — 驗證
證明你沒有破壞任何東西,也沒有遺漏任何東西:
- 執行專案的型別檢查、單元測試、lint 以及生產環境建置。捕捉真實的退出碼(一個
cmd | tail管道會報告 tail 的狀態,隱藏失敗的建置——請不要使用管道執行,或使用PIPESTATUS/set -o pipefail)。 - 重新執行洩漏掃描;確認預期的模式現在數量為零(故意的模式除外)。
- 掃描建置成品以及任何原始碼套件,檢查是否有機密、sourcemap 和內部字串——對
dist//建置輸出以及原始碼 zip 進行 grep。不要僅依賴原始碼樹的乾淨度。 - 確認合法的流程仍然有效(例如,一個允許有所不同的預備環境/e2e 建置仍然能正確解析)。
第 6 階段 — 報告
依照 references/report-template.md 撰寫報告:按嚴重性分類的發現、已套用的變更、殘留建議(機密輪換、git 歷史暴露、刻意延後的取捨),以及驗證證據。請注意:git 歷史無法追溯性地修復——一個被刪除的機密或一個描述性的提交主題會留在日誌中;建議進行輪換和未來的提交訊息衛生,而不是重寫公開儲存庫的歷史。
護欄
- 不要過度標記無可避免的內容。端點、負載形狀以及
狀態 → UI的對應是必要最小限度;標記它們會侵蝕報告的可信度。 - 模式匹配是線索。在將其稱為洩漏之前,請在上下文中閱讀它——「epoch」通常是時間戳記、「worker」可能是 Web Worker、「durable」可能是佇列,而不是 Durable Objects。
- 保留那些陳述與使用者相關策略的使用者面向字串(例如「驗證碼在 10 分鐘內過期」);刪除其旁邊非可見描述/註解中的內部框架。
- 此技能稽核你自己的/經授權的程式碼,以減少其公開攻擊面。它是防禦性的:減少揭露並強化客戶端,而非建立攻擊手段。