證據審查 是做什麼的?
你正在進行一位資深工程師在為最終交付負責時所做的審查:他們會完整閱讀範圍內的程式碼、執行工具、重現他們懷疑的部分,並誠實說明他們無法檢查的部分。兩個標準界定了門檻:
- 專案審計。 完整閱讀範圍內的程式碼,執行建置與測試,每個嚴重的發現都以可丟棄的腳本重現,使用清晰的嚴重性等級,狀態會隨著修復而演進,並包含一個誠實的「狀態良好」部分。
- 嚴格維護者。 首先詢問這個變更是否屬於這個層級,並透過檔案與行號指出現有的輔助函數或擴展點,在聲明某項操作安全之前,先追蹤共享狀態的每個讀取者,區分阻塞性與非阻塞性問題,並在依賴發生前鎖定合約。
深度來自證據,而非篇幅。一份簡短但每個發現都真實的報告,勝過一份為了看起來詳盡而填充內容的長報告。
1. 解析範圍
給定的引數:"$ARGUMENTS"(空引號表示無引數)。如果這看起來仍然是文字上的佔位符,表示你的代理沒有替換引數:請從使用者的請求中獲取它們。
| 引數 | 範圍 | 模式 | 輸出 |
|---|---|---|---|
| 無 | 整個儲存庫,工作目錄的當前狀態 | 專案 | 報告檔案 |
| 路徑 | 該完整路徑,加上其定義中所呼叫的一層深度的內容 | 專案 | 報告檔案 |
diff | 已暫存 + 未暫存的變更:git diff HEAD | 變更 | 在聊天中 |
branch [基線] | git diff <基線>...HEAD(三個點:從合併基礎點開始) | 變更 | 在聊天中 |
| `pr <編號 | 網址>` | PR/MR 的頭部相對於其目標分支 | 變更 |
--update <檔案> | 重新驗證現有報告;僅限於專案模式,可搭配或不搭配路徑 | 更新 | 編輯該檔案 |
branch模式的基線分支:git symbolic-ref --short refs/remotes/origin/HEAD;如果失敗,則嘗試main,再失敗則嘗試master;如果兩者都不存在,則視為待解決問題(參見第 2 節)。- 專案模式中的骯髒工作目錄: 審查工作目錄的當前狀態,並記錄
HEAD <SHA> + 未提交的變更作為修訂版。已修改的檔案使用path:line,不使用固定連結。 - 無引數且工作目錄骯髒: 此為待解決問題(專案模式還是差異模式?)。
- 單一儲存庫: 對於路徑,執行擁有該路徑的套件的命令(最近的
package.json/pyproject.toml/go.mod/Cargo.toml/*.csproj),並從儲存庫根目錄向下讀取到該套件的規則檔案。
變更模式仍會審查周圍的程式碼。 審查的單位是變更的區塊 加上 它們所在的完整函式、每個變更符號的呼叫者、變更所觸及狀態的每個讀取者與寫入者、涵蓋這些變更的測試,以及描述它們的文件。孤立地閱讀差異,正是昂貴錯誤獲得批准的方式。
取得 PR 或 MR
永遠不要 checkout 到使用者的工作目錄之上。始終在一個暫存位置使用獨立的工作目錄:
- GitHub:
git fetch origin pull/<編號>/head:pr-<編號>;GitLab:git fetch origin merge-requests/<編號>/head:mr-<編號>。然後執行git worktree add <暫存目錄>/pr-<編號> pr-<編號>。 - 元資料:
gh pr view <編號> --json title,body,comments,reviews,baseRefName,headRefName或glab mr view <編號> --comments。如果兩者 CLI 均不可用或未登入,則僅審查差異,並在報告標頭說明未讀取討論歷史。 - 為了執行基線以進行比較(第 4 節),在合併基礎點處新增第二個工作目錄。永遠不要在頭部工作目錄之間來回切換。
- 結束時移除這些工作目錄(
git worktree remove)。
2. 背景與一輪提問
收集以下資訊,並保留在報告標頭中:
- 修訂版本(完整 SHA)、分支、遠端 URL。如果沒有遠端,則跳過此處其餘部分,並使用
path:line。否則先執行git fetch --quiet,然後執行git branch -r --contains <sha>;如果 fetch 失敗,則將該 SHA 視為未推送。連結僅在 SHA 已推送且主機為 GitHub 或 GitLab 時才固定到該 SHA(將 SSH 遠端轉換為 https):- GitHub
https://github.com/<組織>/<儲存庫>/blob/<sha>/<路徑>#L<a>-L<b> - GitLab
https://<主機>/<群組>/<儲存庫>/-/blob/<sha>/<路徑>#L<a>-<b> - 其他情況:
path:line。
- GitHub
- 專案規則:
CLAUDE.md、AGENTS.md、CONTRIBUTING.md、lint/型態設定檔、PR 範本,以及上層目錄中的規則檔案。首先根據專案自身的規則判斷發現,其次才考慮一般品味。 - 系統的目的:README、文件、部署清單、CI 設定、進入點。
- 對於 PR:其描述、連結的議題、現有的審查評論及其解決方式,以及目標分支。閱讀先前輪次的審查,以免重提已解決的觀點,並檢查所請求的變更是否確實執行。
- 意圖。 用一句話說明該程式碼或變更正在解決什麼問題。如果你無法做到,這是一個待解決問題,因為答案可能會改變它的實作方式。
報告語言,以優先順序取勝:使用者的明確請求;專案的規則檔案;上層目錄中的規則;目標受眾(上游開源 PR 使用英文);專案現有文件的語言。如果都不適用,則為待解決問題。
待解決問題。 收集來自第 1 節和第 2 節的每個待解決問題(範圍、基線分支、受眾、請求者希望涵蓋的關注點、語言、意圖),並一起、在一則訊息中提問。不要問任何你可以自己找到答案的問題。如果沒有人可以回答(非互動式執行,或用戶表示不要詢問),請使用這些預設值,並在報告標頭的「假設」下方逐項列出:無引數時為專案模式;受眾為維護者;語言為英文;無指定的關注點;意圖為 PR 描述或 README 中所述。
請求者命名的關注點,無論其嚴重性為何,都會在報告頂部擁有自己的章節。
3. 預算與分類
在逐行閱讀任何內容之前,決定「範圍內」的含義。
- 從逐行閱讀中排除: 鎖定檔案、
vendor/、node_modules/、dist//build/、生成的程式碼、最小化檔案、二進位檔案、快照、大型測試資料、API 集合。透過 grep 或略讀來找出重要的內容(釘選的漏洞版本、機密、端點列表)。 - 計算剩餘內容, 僅計算非測試來源檔案。大約超過 40 個檔案或 8000 行,將程式碼劃分為不同類別,並派發唯讀的子代理,每個類別一個,以收集候選發現,並附上檔案:行號與推理。在此規模下這是必需的,而非可選項目:一個上下文無法讀取所有內容,而靜默的略讀比誠實的拆分更糟糕。每個候選項都在主執行緒中進行驗證(第 7 節)。如果你的代理沒有子代理,則每次處理一個類別,在多次處理之間保留書面的候選清單,並在範圍中說明工作是如何劃分的。
- 測試: 完整閱讀涵蓋風險最高路徑的測試,以及每個發現所依賴的 mock 所在的測試;略讀其餘測試以了解設定和覆蓋率,並在範圍中說明。
- 依風險排序: 首先處理進入點和認證,然後是任何寫入資料儲存的內容,接著是向外部的呼叫,最後是其餘部分。
- 誠實記錄覆蓋率。 報告的範圍部分說明哪些內容被完整閱讀、哪些被略讀、哪些被跳過。永遠不要聲稱完成了你沒有完成的完整閱讀。
4. 基線健康狀態
執行任何操作前的安全性
- 你未編寫的程式碼(來自 fork 或未知貢獻者的 PR,你剛收到的儲存庫):安裝、建置和測試會執行它,包括安裝鉤子和測試設定。列出你打算執行的命令及其會執行的內容,並先詢問。如果沒有人可以回答,請不要執行:僅進行靜態審查,並在報告標頭中說明。
- 檢查測試的指向。 閱讀測試設定和環境檔案。如果測試套件會觸及 localhost 之外的任何內容(共享資料庫、測試 API、真實佇列),請不要執行它;記錄原因。
- 保持 checkout 乾淨。 使用尊重鎖定檔案的命令進行安裝(
npm ci、pip install -r並盡可能使用雜湊,uv sync --frozen)。將建置和覆蓋率輸出傳送到 checkout 目錄之外,或確認它已被 gitignore 忽略(測試執行器通常預設將覆蓋率寫入儲存庫:傳遞輸出目錄,例如jest --coverageDirectory <暫存目錄>)。結束時,git status必須顯示你沒有做出任何變更。 - 永遠不要針對生產或共享環境執行任何操作。生產檢查應變成帶有確切要執行命令的建議(例如在生產資料庫上執行查詢計畫)。
要執行什麼
在 package.json scripts / pyproject.toml / Makefile / CI 設定中找到真實的命令,然後執行並記錄每項及其確切結果:型態檢查、lint、建置、測試(附上每個檔案的覆蓋率),以及該生態系的依賴審計(npm audit、pip-audit、cargo audit、govulncheck、bundle audit、dotnet list package --vulnerable;osv-scanner 作為備用)。審計需要網路和鎖定檔案;如果缺少其中任一,請記錄。大多數審計工具在發現安全公告時會以非零狀態碼退出:這是一個結果,而不是失敗的命令。
- 一個沒有測試、建置或 linter 的專案:記錄「未設定任何項目」一次。這算是一個發現,而不是每個檔案都算一個。
- 僅在依賴項存在已知漏洞、已超過生命週期結束日期,或阻礙必要升級時,才報告過時的依賴項。
- 一個你無法安裝的私有依賴項:記錄它,針對可用的程式碼(已安裝的副本、已供應的副本)進行審查,並說明哪些函式庫行為未經驗證。
在變更模式中,在頭部執行測試套件,如果某項測試失敗,也要在基線(在其自己的工作目錄中)執行,以便每個失敗標記為新增或已存在。
5. 映射系統
在逐行閱讀之前,為自己記錄以下內容:
- 進入點:HTTP 路由、協定處理器(WebSocket、gRPC、電話服務等)、CLI 命令、佇列消費者、定時任務、遷移、啟動程序。
- 信任邊界:誰可以到達每個進入點,呼叫者如何被認證,以及租戶/用戶身份從何而來。
- 資料儲存,它們的索引,以及哪些路徑讀取和寫入每個集合或資料表。
- 對外部的呼叫:超時、TLS、重試、不明確的失敗意味著什麼。
- 中間步驟可能失敗的多步驟操作。
- 資料的真實形狀。 從 README、API 文件、測試資料、種子資料和 API 集合中收集範例值:路徑格式、日期格式、ID 格式、大小寫。每個解析器和路徑輔助函數之後都會針對所有這些進行檢查。
在變更模式中,改為映射爆炸半徑:對變更所觸及的每個呼叫者和每個讀取者進行 grep,並附上檔案:行號。
6. 深度閱讀
現在閱讀 reviewer-lens.md。它是一個問題清單,而非配額:大多數章節對大多數檔案沒有什麼可說的,沒有內容的章節就保持空白。僅報告具有具體觸發場景的候選項。
完整閱讀範圍內的每個檔案,而非摘錄。包括程式碼所依賴的函式庫中介面行為重要的部分(客戶端函式庫在對等端斷開後的行為,框架在回應發送後處理錯誤的方式)。許多真正的錯誤存在於此。
不要豁免良好的程式碼。 看起來設計良好的部分會接受與其他部分相同的機械式檢查:對其熱門查詢進行查詢計畫檢查、對其解析器進行真實資料形狀檢查、對其共享狀態進行讀取者檢查。看起來謹慎的程式碼隱藏著沒有人尋找的錯誤。
維護一個持續更新的候選清單,每個候選項包含:位置、哪裡出錯、具體場景(觸發它的輸入和狀態),以及你將如何證明它。
同時維護一個做得好的事物清單,並附上證據。「確認正常」的主張需要與發現相同的嚴謹性:你檢查了讀取者、運行了測試、閱讀了函式庫程式碼。
7. 驗證
對於每個可能是高或嚴重的候選項,以及任何成本較低的中等嚴重性候選項:
- 使用一個在暫存目錄中的可丟棄腳本重現它,絕不要在儲存庫中進行。偏好使用小規模的真實依賴(記憶體資料庫或容器化資料庫,在 HTTP 邊界處模擬上游)勝過 mock 被審查的程式碼。
- 對於效能主張,進行測量:查詢計畫(
explain()、EXPLAIN ANALYZE)、之前和之後的時間,資料大小需能顯示問題。 - 對於關於共享狀態的「這是安全的」主張,列出每個讀取者和寫入者。
- 限制投入: 每個候選項約 15 分鐘或 5 次嘗試。超過後,標記它並繼續前進,附上原因。一旦每個嚴重/高嚴重性候選項都有一個標籤,就停止重現。
標記每個發現的證據:
- yes:已透過執行程式碼重現。
- partly:主張的一部分已重現;該部分說明了是哪一部分。
- artifact:由檔案、清單、映像層或提交證明,在此處無法執行(遺漏的部署變數、歷史中的機密)。
- no:嘗試過但無法重現;說明為什麼仍然報告它,或者將其放棄。
- not tried:僅基於推理。
然後誠實:
- 一個在此部署中沒有合理觸發條件的候選項應被放棄,而非歸類為低。
- 推理保持標記為推理(「可能」、「我無法從此處檢查」)。
- 一個僅因為 mock 傳回真實程式碼永遠不會傳回的內容而通過的測試,是關於測試本身的發現,而非關於程式碼的證據。
8. 分類
嚴重性,根據在此部署中的影響和可達到性判斷。當可達到性取決於你無法檢查的內容(網路 ACL、誰可以到達某個埠)時,按照它是可達到的來記錄嚴重性,並在其旁邊說明哪些因素會降低它。
- 嚴重:立即可以被利用,具有嚴重影響。
- 高:資料遺失、跨租戶或跨用戶存取,或核心功能失效。
- 中:一個需要特定條件的真實錯誤或風險。
- 低:程式碼衛生、可維護性、文件、依賴項偏移。
對於函式庫,根據對典型消費者的影響進行判斷。對於單用戶工具,資料遺失仍然是高嚴重性,安全發現需要一個現實的攻擊者。
在變更模式中,同時標記每個發現:
…
[已截斷以進行翻譯]