同層級檢閱相符性

同層級程式碼檢閱是提供安全與合規軟體的關鍵元件。 DevSecOps參考實作有助於在程式碼變更合併並提升到生產環境之前強制對其進行審查。

管理 CI/CD 工具鏈中的同層級檢閱檢查

本文件提供在 Continuous Integration (CI) 內啟用及停用 Peer-review 檢查的指示，以及在 Continuous Delivery (CD) 工具鏈內的選用項目。

持續整合 (CI) 工具鏈

依預設，會在 CI 工具鏈中啟用同層級檢閱檢查。 如果要修改這項設定，請執行下列動作:

  • 若要啟用同層級檢閱檢查，請將 peer-review-compliance 環境變數的值設為 1。
  • 若要停用同層級檢閱檢查，請將 peer-review-compliance 環境變數的值設為 0。

Continuous Delivery (CD) 工具鏈

下列環境變數可讓您管理 CD 工具鏈內的「同層級檢閱」檢查:

  • 若要擷取進行中部署的取回要求及其相關聯標題的清單，請將 peer-review-collection 環境變數設為 1。 請注意，依預設，此變數設為 1。 若要取消啟動此清單，請將 peer-review-collection 設為 0。

  • 若要對與現行部署相關聯的所有取回要求啟用對等節點檢閱驗證，請將 peer-review-compliance 環境變數設為 1。 預設情況下，此變數設為 0。 若要略過此驗證，請將 peer-review-compliance 設為 0。

重要要點

您必須只在受保護 (基本) 分支上進行同層級檢閱，這是更新庫存的位置。 如果您在特性分支上執行 CI 管線，請將該特定觸發程式的環境變數 peer-review-compliance 設為 0，以防止對特性分支進行同層級檢閱檢查。

是否遵守同行審查法規，取決於順利完成「連續整合 (CI)」管線執行及後續進入庫存。 因此，CI 管線的起始執行將跳過同層級檢閱相符性檢查。

為了確保符合對等檢閱標準，假設 master 分支上發生 ci-finish 階段中的庫存更新。 不過，如果您的庫存更新是在 master 以外的其他分支上執行，您可以設定環境變數 inventory-repo-branch，以指出進行庫存更新的分支。

預計在持續部署 (CD) 管道中，對庫存儲存庫進行的所有庫存更新都將提升到正在部署的目標分支，確保不會錯過任何提交。 預設情況下，在部署期間，庫存儲存庫將檢出到目標分支。 但是，如果您的庫存升級目標分支錯過了基礎分支和目標分支之間的一些提交，您可以設定 inventory-repo-branch 環境變數來指定所有庫存提交所在的基礎分支。

依預設，「連續整合 (CI)」管線將在執行結束時自動對庫存儲存庫執行確定，並使用應用程式名稱作為庫存項目。 不過，如果您想要在發行階段期間修改庫存項目，建議將名為 inventory-entry-name 的環境內容納入工具鏈中。 此內容應該包含已修改的庫存名稱，以用於同層級檢閱程序。

如果您有一個自動化功能，可以將提交直接推送到受保護的分支，並且您希望避免同儕審查合規性檢查出現問題，請確保您的提交訊息包含 ##AUTOMATED_COMMIT##。

參照實作會探索未同層級檢閱的程式碼實例，收集 證明，並建立發生事件問題以追蹤這些項目。

在您可以合併主要 (受保護) 分支中的程式碼之前，必須由未上傳已修改程式碼的人員來檢閱程式碼。

程式碼儲存庫 (repo) 必須至少有兩個成員: 一個成員具有管理專用權，另一個成員具有寫入專用權。 如果程式碼合併至沒有檢閱的儲存庫，則動作必須在程式碼儲存庫審核追蹤中可見。 定期掃描審核追蹤，以識別並分析這些異常狀況。

在建置及部署期間，管線會收集同層級檢閱相符性資料，以從程式碼取回/合併要求合併至變更要求來建立審核追蹤。

在此圖表中，PR1、PR2 是在合併之前核准的取回/合併要求。 同樣地，對於 PR4、PR5和 PR7。 不過，以紅色強調顯示的 PR3 和 PR6會在未經核准的情況下合併，這是同層級檢閱相符性違規。 這被記錄為證據。

資料收集
資料收集

依預設，CI 工具鏈中的範例應用程式會嘗試將檢閱人員數目下限設為 1。 如果您要變更檢閱人員數目，請視需要設定 peer_review_approvers 環境內容。 如需設定取回/合併要求所需的檢閱人員數目下限的相關資訊，請參閱下列 GitHub 及 GitLab 資源:

在連續整合建置執行中收集的資料

此資料集合包含自前次建置以來在應用程式儲存庫中合併之取回/合併要求的所有確定清單。

直接從應用程式儲存庫收集取回要求資料。 在觸發前一個建置的儲存庫確定與目前可用的確定之間，會收集與確定相關的每一個取回/合併要求的資料。

不包含取回/合併要求的確定會在下列管線版本中建立相符性發生事件問題。 您無法直接確定至主要分支。

相符性事件通常會保留下列資訊:

  • 相關聯確定 ID 的取回/合併要求 URL 清單。
  • 應用程式儲存庫。
  • 確定 ID。
  • 核准的必要數目。

拉取請求事件內容
拉取請求事件內容

收集的資料會儲存為 證明 構件，上傳至證明櫃，然後在證明本身中參照。 最終證明結果由已核准的取回/合併要求決定。 未核准，但合併的取回/合併要求失敗此類型的證明。

在連續部署執行中收集的資料

此資料集合包含自前次部署以來在應用程式儲存庫中合併的所有取回/合併要求清單。

從證明櫃及事件問題儲存庫收集取回要求資料。

  • 自前次部署之後，庫存會從相關構件上的所有建置收集資料。
  • 證明櫃會從建置中收集已儲存的同層級檢閱資料。
  • 發生事件問題儲存庫會收集開啟取回/合併要求發生事件的相關資訊。

在此資料收集期間不會存取應用程式儲存庫。 因為連續部署管線假設位於隔離環境中，所以您無法跨越那些界限。

變更要求內容

下列資料包含在自動產生的變更要求中:

  • 未補救的取回/合併要求發生事件清單。 這些資料包括資產詳細資訊和事件 URL。

未補救的取回/合併要求事件會影響變更要求的部署就緒狀態。 如果找到任何取回/合併要求事件，則會將它們視為漏洞，且必須手動檢閱並核准 變更要求。

更改請求內容
更改請求內容

取回要求事件補救

取回要求事件被視為漏洞，因為它們指出已發行構件中包含未勾選的程式碼。 若要重新修補這些發生事件，請完成下列步驟:

  1. 追溯檢閱合併的變更。
  2. 建立如何修正程式碼的任何現有問題的相關問題。
  3. 新增 exempt 標籤或關閉取回/合併要求發生事件問題。

拉/合併要求的作者和關閉拉/合併要求事件問題的人員不能是同一個人。

疑難排解

案例 1:

問題

在 CD 管線的 prod-start 階段中 collect_peer_review_commits 失敗會導致其他階段失敗，並發生錯誤。 當 prod_start 階段中發生下列錯誤時

| ERROR | 2023-12-20T07:00:48.978Z | index.ts:25:14 | The inventory entry has no such property ('pipeline_run_id').
解決方案

擁有單管線不支援之庫存項目的使用者必須在庫存中新增 忽略檔案。 此動作可確保在任何計算時不會考量這些檔案。

已知問題

  • 同層級檢閱相符性依賴於在「連續整合 (CI)」管線的每一個反覆運算之後的發行步驟中併入庫存項目。 跳過以包括任何失敗 CI 管線執行的庫存項目，可能會導致在 Continuous Delivery (CD) 管線中不處理該特定 CI 管線執行的對等檢閱證明。