如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題
Codex

Codex 應用案例

在 CI 中自動執行安全掃描

掃描 pull requests 或 main 分支上的提交,也可以定期掃描程式碼庫。

難度 Intermediate
任務時間跨度 Long-running

將 Codex Security CLI 加入 CI 管線。選擇掃描時機與要審查的程式碼,保留掃描發現與涵蓋範圍的紀錄,並決定如何依據掃描結果調整交付流程。

最適合的對象

  • 想在 pull request 或合併請求中加入安全檢查的團隊。
  • 需要在變更合併後掃描預設分支的維護者。
  • 需要定期評估程式碼庫安全性的資安團隊。

目錄

    ← 所有應用案例

    在 CI 中自動執行安全掃描

    掃描 pull requests 或 main 分支上的提交,也可以定期掃描程式碼庫。

    將 Codex Security CLI 加入 CI 管線。選擇掃描時機與要審查的程式碼,保留掃描發現與涵蓋範圍的紀錄,並決定如何依據掃描結果調整交付流程。

    Intermediate
    Long-running
    設定 CI 掃描

    將 Codex Security CLI 加入 CI 管線。選擇掃描時機與要審查的程式碼,保留掃描發現與涵蓋範圍的紀錄,並決定如何依據掃描結果調整交付流程。

    Intermediate
    Long-running

    最適合的對象

    • 想在 pull request 或合併請求中加入安全檢查的團隊。
    • 需要在變更合併後掃描預設分支的維護者。
    • 需要定期評估程式碼庫安全性的資安團隊。

    將安全掃描納入開發流程。你可以針對 Pull Request 執行 Codex Security,在變更進入預設分支後執行掃描,或設定排程定期掃描。依觸發條件選擇合適的掃描範圍,記錄掃描發現的問題與實際涵蓋的範圍,讓團隊能依照固定流程審查結果。

    選擇掃描時機

    先選擇一個符合團隊工作流程的觸發條件。等你了解掃描所需的時間、費用,以及團隊如何運用掃描結果後,再加入其他觸發條件。

    執行時機 建議掃描範圍 可審查的內容
    定期執行 整個程式碼庫,可選用深度掃描 定期檢視整體程式碼。
    有提交推送至 main 時 以推送的提交版本為準,掃描整個程式碼庫 檢視變更進入預設分支後整合完成的程式碼。
    有 Pull Request 或合併請求時 合併基底與擬合併的提交之間的變更 在合併前檢查變更是否可能削弱既有的安全防護。

    如果程式碼庫的預設分支名稱不是 main,請使用實際的預設分支。觸發條件與掃描範圍都需要設定。針對 Pull Request 執行差異掃描時,只會掃描該次變更,不會涵蓋整個程式碼庫。等變更進入 main 後才執行掃描,就無法阻擋已合併的 Pull Request。

    開始前的準備

    你需要一個已獲授權可評估的程式碼庫、設定其 CI 管線與機密資料的權限,以及可存取 Codex Security 的 OpenAI API 金鑰。請參閱 CLI 快速入門指南,確認存取與設定需求。

    請使用符合 CI 需求的可信任執行器。掃描會以執行器的本機權限執行。請勿讓掃描作業取得無關的憑證,並遵守平台對來自分支程式碼庫(fork)的 Pull Request 及其他不受信任程式碼的限制。

    設定 CI 管線

    1. 將 Codex Security 加入管線

      選擇適用於你所用 CI 平台的範例。依照範例安裝 Codex Security CLI,並透過 CI 平台的機密資料儲存區提供 API 金鑰。

      依平台選擇適用的範例:

      • GitHub Actions: 使用 Pull Request 工作流程掃描擬合併的變更並保留結果。
      • GitLab CI/CD: 依照管線指南設定合併請求掃描、預設分支掃描及排程掃描。指南提供可下載的管線設定,並說明應啟用哪些選項。
      • 其他 CI 平台: 依照平台的觸發條件、機密資料儲存區、程式碼簽出方式與產出物處理方式,調整在 CI 中執行 Codex Security 裡的掃描與匯出指令。
    2. 設定觸發條件與掃描範圍

      當變更進入 main 時,以推送的提交版本為準掃描程式碼庫。另為選定的分支設定定期掃描。建議先從每週掃描一次開始,再依程式碼庫的變更頻率、掃描時間與費用調整。

      針對 Pull Request 或合併請求,請先擷取目標分支與來源分支的提交歷史,再掃描從兩者的合併基底到來源分支最新提交之間的差異。

      設定每項作業時,請確認掃描範圍符合預期。排程掃描與推送提交至 main 時觸發的掃描應涵蓋整個程式碼庫,Pull Request 掃描則應涵蓋擬合併的變更。請依照平台範例設定對應的掃描方式。

      依掃描範圍與頻率設定合適的預算。掃描整個程式碼庫可能比差異掃描更耗時,費用也可能更高。--max-cost 限制的是預估費用,實際支出仍可能超過該金額。達到限額時,掃描可能尚未涵蓋所有預定範圍。

    3. 執行管線並審查結果

      依照平常的審查流程提交管線設定變更,然後觸發掃描。在執行紀錄與 scan-manifest.json 中確認掃描的目標版本與範圍。

      檢閱已儲存的報告,查看掃描發現的問題與相關佐證。即使掃描未回報任何問題,也要檢查 coverage.json,確認哪些部分尚未掃描完畢或已延後掃描。在提高掃描頻率或將掃描範圍擴大到更多程式碼庫之前,請先檢視執行時間與費用。

      將報告儲存為 CI 產出物。依產出物所含的原始碼與佐證資料,設定適當的存取權限與保留期限。

      你也可以將發現的問題匯出為 SARIF,以便在平台的安全性介面中顯示結果。SARIF 是用於記錄安全問題的結構化格式。請查閱平台指南,確認支援的版本、所需權限與授權要求。

    4. 決定發現問題時是否阻擋合併

      初期先審查掃描發現的問題,暫時不要讓這些問題阻擋合併。等團隊熟悉掃描結果後,就可以要求 Pull Request 必須通過安全檢查才能合併。例如,掃描發現嚴重程度為「高」或「危急」的漏洞時,就阻擋合併。

      每次都要確認掃描是否完成,以及實際涵蓋了哪些程式碼。即使未回報任何問題,只要掃描失敗或略過了部分程式碼,就需要進一步檢查。

      如需設定詳情,請參閱設定嚴重程度門檻並解讀掃描結果。

    5. 追蹤掃描發現的問題

      依照團隊平常的流程,將發現的問題指派給相關人員調查或修正。附上掃描的提交版本、受影響的程式碼與相關佐證,方便其他開發人員調查。

      結案前先驗證修正是否有效,並在後續掃描中補查先前未完整涵蓋的部分。

    相關應用案例