設定程式碼掃描

  • 4 分鐘

您可以設定 GitHub 掃描您專案中的程式碼是否有弱點和錯誤的方式。 當您選擇自己的設定時，您可以節省時間，並決定您專案程式碼掃描的最佳頻率。 在此單元中，您將了解程式碼掃描設定的基本概念。 您也將了解如何設定掃描的頻率，並加以排程以符合您的存放庫和開發需求。

如上一個單元所述，您可以在 GitHub 上、使用 GitHub Actions，或從您的持續整合 (CI) 系統執行程式碼掃描。 選取 GitHub 上的 [ 進階 設定] 選項時，會生成一個可自定義的工作流程檔案，然後可以直接提交到您的存放庫。 您通常不需要編輯此工作流程。 不過，如有需要，您可以自訂一些設定。

例如，您可以編輯 GitHub 的 CodeQL 分析工作流程，以指定掃描的頻率、要掃描的語言或目錄，以及要讓 CodeQL 程式碼掃描在您程式碼中尋找的內容。 如果您使用一組特定的命令來編譯您的程式碼，您可能也需要編輯 CodeQL 分析工作流程。 CodeQL 分析只是您可以在 GitHub 中執行的其中一種程式碼掃描。 GitHub Marketplace 包含數個其他程式碼掃描工作流程。

從預設切換到進階程式碼掃描設定

如果您已經有存放庫設定，可使用預設設定方法來使用程式碼掃描，則可以切換至使用設定中的 [進階] 設定。 請前往 「設定 > 進階安全性」 下方的 程式碼掃描 區段，然後選取三點溢位圖示（...）。在下拉式選單中，選取 切換為進階。 然後，依照提示停用 CodeQL，然後使用進階安裝程式產生的工作流程檔案重新啟用它。

編輯程式碼掃描工作流程

GitHub 會將工作流程檔案儲存在存放庫的 .github/workflows 目錄中。 您可以透過搜尋檔案名稱來尋找已新增的工作流程。 例如，根據預設，CodeQL 程式代碼掃描的工作流程檔案稱為 codeql-analysis.yml。

請遵循下列步驟來編輯工作流程檔案：

  1. 若要開啟工作流程編輯器，請選取檔案檢視右上角的 [編輯 ] 圖示。

編輯按鈕的截圖，用來開啟工作流程編輯器。

  1. 儲存您的編輯。

  2. 編輯檔案後，選擇提交變更，然後填寫提交變更表單。 您可以選擇直接認可至最新分支，或建立新的分支並啟動提取要求。

提交修改表單的截圖，用以完成編輯。

如需一些常見的程式碼掃描設定選項，請檢閱下列各節。

設定頻率

針對工作流程檔案最常見的編輯，是調整程式碼掃描發生的頻率。 您可以設定 CodeQL 分析工作流程，以依排程或在存放庫中發生特定事件時掃描程式碼。 您也可以編輯工作流程檔案，以在有人推送變更時以及每當建立提取要求時掃描程序代碼。 調整頻率可防止開發人員在程式碼中引進新的弱點和錯誤。 依排程掃描程式碼時，系統會通知您有關 GitHub、安全性研究人員和社群探索到的最新弱點和錯誤。 即使開發人員未主動維護該存放庫亦然。

在推送時掃描

根據預設，CodeQL 分析工作流程會使用 on:push 事件，在每次推送至存放庫的預設分支和任何受保護的分支時觸發程式碼掃描。 若要在指定的分支上觸發程式碼掃描，工作流程必須存在於該分支中。 如果您在推送時掃描，結果會出現在存放庫的 [ 安全性 ] 索引標籤中。

此外，當 on:push 掃描傳回可對應至開啟提取要求的結果時，這些警示會自動出現在該提取要求上其他提取要求警示所在的位置。 警示是透過比較對分支前端的現有分析與對目標分支的分析來識別。

在 PR 時掃描

預設 CodeQL 分析工作流程會使用 pull_request 事件，針對以預設分支為目標的提取要求觸發程式碼掃描。 如果提取要求是來自私人分支，只有在您已於存放庫設定中選取 [從分支提取要求執行工作流程] 選項時，才會觸發 pull_request 事件。 如果您掃描提取要求，結果便會在提取要求檢查中顯示為警示。

如果您使用 pull_request 觸發程序，並將其設定為掃描提取要求的合併提交，而不是前端提交，其會產生比在每次推送時掃描分支前端更有效率且精確的結果。 不過，如果您使用無法設定為在發出提取要求時觸發的 CI/CD 系統，您仍然可以使用 on:push 觸發程序，且程式碼掃描會將結果對應至分支上的開啟提取要求，並將警示新增為提取要求上的註釋。

定義導致提取要求檢查失敗的嚴重性

根據預設，只有具有 Error 的嚴重性層級，或是具有 Critical 或 High 的安全性嚴重性層級的警示才會導致提取要求檢查失敗。

這些失敗不會阻止程式碼掃描執行，但根據儲存庫規則可能會阻擋合併。你可以在安全性下的程式碼掃描警示標籤中查看拉取請求失敗的詳細資訊。

你可以在儲存庫設定中，或透過儲存庫規則集的「要求程式碼掃描結果」規則，設定哪些嚴重程度等級會導致拉取請求檢查失敗。 兩種機制皆可運作，但規則集是現代且首選的配置方式。

  1. 在 GitHub.com 上，瀏覽至存放庫主頁面。 在您的存放庫名稱下，選取 [ 設定]。

設定按鈕的截圖，用來設定嚴重程度等級。

  1. 在左側邊欄，選擇 進階安全。

[程式代碼安全性和分析] 按鈕的螢幕快照。

  1. 在 [保護規則] 下的 [程序代碼掃描] 區段中，使用下拉功能表來選取您想要觸發提取要求檢查失敗的嚴重性層級。

程式碼掃描警示嚴重性下拉式功能表的螢幕擷取畫面。

以負責任的方式分類處理並解除程式碼掃描警示

修復程式碼是解決掃描代碼警示的首選方式。 不過，有些警示可能不需要更改程式碼。 例如，警示可能是誤報、僅出現在測試程式碼中，或代表團隊決定不修正的風險。

只有在審查警報細節並確認原因後，才可取消警報。 當你關閉警報時，GitHub 會記錄刪除原因，將該警報從目前的警報數量中移除，移至關閉清單，並防止同一段程式碼在未來掃描中產生相同的警報。 解僱適用於所有軍種。

謹慎選擇駁回原因，因為它會成為資料庫安全紀錄的一部分。 你也可以加上駁回評論來說明這個決定。 此評論已加入警示時程，並可支持未來的稽核、報告及合規審查。

使用註解來記錄如下細節：

  • 為什麼警報不需要更改程式碼

  • 審查該決定的人

  • 無論決定是暫時還是永久

  • 任何補償性控制措施或後續工作

為了強化治理，組織可以使用委派警示關閉權限，來控管允許哪些人關閉程式碼掃描警示。 這有助於防止開發者在未經審查的情況下關閉安全發現，並建立更負責任的分流流程。

避免不必要的提取要求掃描

建議您避免針對以預設分支為目標的特定提取要求上觸發程式碼掃描，無論已變更哪些檔案。 您可以在程式碼掃描工作流程中指定 on:pull_request:paths-ignore 或 on:pull_request:paths 來設定此設定。 例如，如果提取要求中唯一的變更是針對副檔名為 .md 或 .txt 的檔案，您可以使用下列 paths-ignore 陣列。


on: 

push: 

branches: [main, protected] 

pull_request: 

branches: [main] 

paths-ignore: 

- '**/*.md' 

- '**/*.txt'

調整掃描排程

如果您使用預設的 CodeQL 分析工作流程，除了事件所觸發的掃描之外，工作流程會在隨機產生的日期和時間，每週掃描一次存放庫中的程式碼。 若要調整此排程，請編輯工作流程中的 cron 值。

下列範例顯示適用於具有名為 main 的預設分支，以及一個名為 protected 的受保護分支之存放庫的 CodeQL 分析工作流程:


on: 

push: 

branches: [main, protected] 

pull_request: 

branches: [main] 

schedule: 

- cron: '20 14 * * 1'

此工作流程會在下列時機掃描：

  • 每次推送至預設分支和受保護分支時

  • 每次針對預設分支發出提取要求時

  • 於每個星期一的 14:20 UTC 掃描預設分支

使用 Copilot Autofix 建議

GitHub Copilot Autofix 透過建議針對性的程式碼變更，協助開發者解決程式碼掃描警示。 自動修正會利用警示、程式碼庫和拉取請求的資訊來產生潛在的修正。 使用 Copilot Autofix 不需要另外訂閱 GitHub Copilot。 它適用於 GitHub.com 上的公開倉庫，以及啟用GitHub程式碼安全（ Code Security）的組織擁有的倉庫。

自動修正建議並非自動修正。 它們是提出的變更，必須像其他程式碼變更一樣經過審查、測試和核准。

在檢視自動修正建議時：

  1. 閱讀警示並了解安全問題。

  2. 檢視建議的程式碼變更。

  3. 確認修補能處理警報且不改變預期行為。

  4. 執行專案測試及必要的安全檢查。

  5. 如果需要，可以修改建議。

  6. 將該修正提交到拉取請求中。

  7. 再次執行檢查後，請確認程式碼掃描警報已解決。

如果自動修正建議不合適，請直接忽略該建議，而不是直接套用。 如果警示本身不需要修正，請以正確的理由和明確的說明來駁回警示。