Communitygithub.com

khasky/public-client-leak-audit

用於 AI 代理的技能。稽核公開面向的客戶端(擴充功能、應用程式、SPA、CLI、SDK),找出洩漏的後端內部資訊、機密與助長濫用的揭露,並在開放原始碼或送交商店前進行強化。

public-client-leak-audit 是什麼?

此技能專為 AI 代理設計,用於稽核與私有後端通訊的公開客戶端程式碼庫。核心目標是確保公開的程式碼表面是「自包含」的——它可能揭露它所呼叫的端點以及交換的資料形狀(這是任何已出貨客戶端都無法避免的),但絕不能洩露更多。任何關於伺服器如何運作的多餘細節,都會成為攻擊者的免費偵察資訊,也是濫用的槓桿。 該技能支援多種客戶端類型,包括擴充功能、應用程式、SPA、CLI 和 SDK。它會產生一份包含檔案位置與嚴重性的發現清單、一組已套用的修復,以及一份包含殘留建議的報告。工作流程分為六個階段:界定公開/私有邊界、掃描洩漏、強化客戶端安全、修復、驗證,以及撰寫報告。此外,它還提供了參考分類法、改寫規則與報告範本,以引導 AI 代理進行深入且一致的稽核。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add khasky/public-client-leak-audit

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

公開客戶端洩漏稽核

稽核一個與 私有 後端通訊的公開客戶端程式碼庫。目標:公開表層必須是 自包含的——它可以揭露它發出的呼叫以及交換的資料形狀(這是任何已出貨客戶端都無法避免的),但除此之外不能再多。任何關於伺服器如何運作的多餘細節,都是攻擊者的免費偵察資訊,也是濫用的槓桿。

此技能產出三樣東西:一份發現清單(洩漏 + 客戶端安全性漏洞,每個都附有 file:line 與嚴重性)、一組已套用的修復,以及一份附有殘留建議的報告。

參考檔案(按需載入——請閱讀你需要的檔案,不要內聯所有檔案):

核心心智模型

將每次揭露歸類到以下兩個類別之一:

  • 必要最小限度(保留):客戶端呼叫的端點、它實際傳送和接收的請求/回應形狀、它自己的重試/退避/去抖動選擇、輸入驗證上限,以及 狀態 → 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 階段 — 修復

套用修復。影響力排序:

  1. 首先關閉祕密洩露管道(從原始碼套件中排除 .env*/機密檔案;將真實值移出已提交的相鄰檔案)。
  2. 將改寫規則套用至洩漏的註解/字串/文件;傾向於重新命名程式碼,讓註解變得不再必要,勝過改寫註解。
  3. 刪除硬編碼了伺服器策略(session TTL、配額、已移除的端點)的無用程式碼。
  4. 將測試/文件修剪至客戶端可觀察到的合約;保留流程運作正常,刪除敘述性內容。
  5. 連同測試一起實施強化變更。

預設為保留行為:保持公開 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 分鐘內過期」);刪除其旁邊非可見描述/註解中的內部框架。
  • 此技能稽核你自己的/經授權的程式碼,以減少其公開攻擊面。它是防禦性的:減少揭露並強化客戶端,而非建立攻擊手段。

相關技能