設定程式碼掃描

GitHub Advanced Security for Azure DevOps 中的程式碼掃描功能，讓你能分析 Azure DevOps 資料庫中的程式碼，找出安全漏洞與程式碼錯誤。你需要啟用 GitHub Advanced Security for Azure DevOps，或者如果你使用獨立體驗，啟用 GitHub Code Security for Azure DevOps。會以警示形式提出分析所識別的任何問題。程式碼掃描會使用 CodeQL 識別弱點。

CodeQL 是由 GitHub 開發的程式碼分析引擎，用來自動化安全檢查。您可以使用 CodeQL 分析程式碼，並以程式碼掃描警示型態顯示結果。如需有關 CodeQL 的更具體檔，請參閱 CodeQL 檔。

GitHub Advanced Security for Azure DevOps 可以同 Azure Repos 合作。若要在GitHub儲存庫中使用GitHub Advanced Security，請參見 GitHub Advanced Security。

先決條件

類別	需求
許可	- 若要檢視存放庫的所有警示摘要：存放庫的參與者許可權。 - 在進階安全（Advanced Security）中關閉警報：Project administrator權限。 - 在進階安全設定中管理權限：專案集合管理員群組或進階安全：管理設定權限設定為允許。

如需進階安全性許可權的詳細資訊，請參閱管理進階安全性許可權。

關於程式碼掃描的設定類型

為你的儲存庫設定程式碼掃描主要有兩種方式： 預設設定 和 進階設定。

	預設設定	進階設定
Configuration	自動，無需管線配置	手動，需在工作流程中新增 CodeQL 任務
語言偵測	自動偵測並掃描支援 CodeQL 的語言	你在管線任務中指定語言
分行覆蓋範圍	只掃描預設分支	掃描任何觸發管線的分支
建構自訂	沒有自訂建構步驟——使用 `none` 建構模式	對編譯語言的建置步驟完全掌控
適用對象	快速啟用和標準掃描需求	多分支掃描、自訂代理池或掃描頻率

預設設定 是啟用程式碼掃描最快的方法。它在幕後建立一個受管理的掃描配置，且不需更換管線。我們建議大多數倉庫從預設設定開始。

Advanced setup 透過直接將 CodeQL 任務加入你的Azure Pipelines，讓你能完全掌控。需要時使用進階設定：

管理針對不同語言或計算需求的特定代理池
自訂編譯語言的建置步驟
掃描預設分支以外的分支
將程式碼掃描整合進現有的 CI/CD 管線中
使用特定的 CodeQL 查詢套件或自訂查詢

提示

你可以先用預設設定，如果需要更多控制，之後再切換到進階設定，或者兩者都用。關於設定預設設定的資訊，請參見配置 GitHub 進階安全功能。

設定預設設定選項

啟用 CodeQL 預設設定後，你可以從組織設定中設定代理池和 掃描排程 。這些選項適用於組織內所有使用預設設定的儲存庫。

要進入可設定選項，請到組織設定>的倉庫，展開 CodeQL 預設設定可配置選項下拉選單。

代理人集區

選擇用於在組織內所有倉庫執行 CodeQL 預設設定掃描的代理池。您可以選擇：

Azure Pipelines — 使用Microsoft託管代理。使用 Azure Pipelines agent pool 會消耗運行並行性。
自架代理池 — 使用您自己的代理。如果您的儲存庫需要存取私有網路、特定建置工具或其他託管代理無法取得的資源，請選擇自架設的池。
Managed DevOps Pools — 使用Azure管理的 Pool 並搭配自訂的虛擬機映像檔。

掃描時程

選擇 CodeQL 預設設定掃描執行的時間，適用於組織內的所有儲存庫。你可以選擇每週掃描的特定日期。下拉選單下方會顯示下一次預定的播出日期。

取消正在執行或排隊的掃描

如果你需要停止任何正在執行或排隊的預設設置掃描，可以透過組織設定中的>來手動取消。擁有儲存庫中「進階安全性：管理設定」權限的使用者可以取消正在執行或排隊中的預設安裝流程。

程式碼掃描的進階設定

CodeQL 是一款基於管線的工具，結果會依據儲存庫彙整。

提示

程式代碼掃描可能是更耗時的建置工作，因此我們建議您將程式代碼掃描工作新增至主要生產管線的個別複製管線，或建立新的管線。

YAML
經典

依下列順序新增工作：

CodeQL 進階安全性初始化（AdvancedSecurity-Codeql-Init@1）
您的自訂建置步驟
進階安全性執行 CodeQL 分析（AdvancedSecurity-Codeql-Analyze@1）

此外，請指定您要在 Initialize CodeQL 工作中分析的語言。您可以使用逗號分隔清單一次分析多種語言。支援的語言為 csharp, cpp, go, java, javascript, python, ruby, swift。如果您使用自我裝載的代理程式，您也可以新增 enableAutomaticCodeQLInstall: true 變數來自動為您的代理程式安裝最新的 CodeQL 位。

以下是入門管線範例：

trigger:
  - main

pool:
  # Additional hosted image options are available: https://learn.microsoft.com/en-us/azure/devops/pipelines/agents/hosted#software
  vmImage: ubuntu-latest

steps:

  - task: AdvancedSecurity-Codeql-Init@1
    inputs:
      languages: "java"
      # Supported languages: csharp, cpp, go, java, javascript, python, ruby, swift
      # You can customize the initialize task: https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/advanced-security-codeql-init-v1?view=azure-pipelines
      # If you're using a self-hosted agent to run CodeQL, use `enableAutomaticCodeQLInstall` to automatically use the latest CodeQL bits on your agent:
      enableAutomaticCodeQLInstall: true

#   Add your custom build steps here
# - Ensure that all code to be scanned is compiled (often using a `clean` command to ensure you're building from a clean state).
# - Disable the use of any build caching mechanisms as this can interfere with CodeQL's ability to capture all the necessary data during the build.
# - Disable the use of any distributed/multithreaded/incremental builds as CodeQL needs to monitor executions of the compiler to construct an accurate representation of the application.
# - For dependency scanning, ensure you have a package restore step for more accurate results.

# If you had a Maven app:
#   - task: Maven@4
#     inputs:
#       mavenPomFile: 'pom.xml'
#       goals: 'clean package'
#       publishJUnitResults: true
#       testResultsFiles: '**/TEST-*.xml'
#       javaHomeOption: 'JDKVersion'
#       jdkVersionOption: '1.17'
#       mavenVersionOption: 'Default'

# Or a general script:
#   - script: |
#       echo "Run, Build Application using script"
#       ./location_of_script_within_repo/buildscript.sh

  - task: AdvancedSecurity-Dependency-Scanning@1 # More details on this task: https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/advanced-security-dependency-scanning-v1?view=azure-pipelines

  - task: AdvancedSecurity-Codeql-Analyze@1 # More details on this task: https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/advanced-security-codeql-analyze-v1?view=azure-pipelines

此外，請指定您要在 Initialize CodeQL 工作中分析的語言。若指定語言為 swift，則需自訂建置步驟。

提示

使用 java 來分析用 Java、Kotlin 或兩者撰寫的程式碼。
使用 javascript 來分析以 JavaScript、TypeScript 或兩者撰寫的程式代碼。

如果您是在自我裝載的代理程式上執行，如果您未手動將最新的 CodeQL 套件組合安裝到代理程式工具快取，請選取 Enable automatic CodeQL detection and installation 以自動在您的代理程式上使用最新的 CodeQL 位。

若要產生警示，請使用包含程式代碼掃描工作的管線來執行第一次掃描。

程式碼掃描的更多設定

語言和查詢支援

GitHub 專家、安全研究人員及社群貢獻者撰寫並維護用於掃描程式碼的預設 CodeQL 查詢。查詢會定期更新，以改善分析並減少任何誤判結果。查詢是open source的，所以你可以查看並貢獻 github/codeql 的查詢庫。

CodeQL 支援並使用下列語言識別碼：

語言	識別碼
C/C++	`cpp`
C#	`csharp`
Go	`go`
Java/Kotlin	`java`
JavaScript/TypeScript	`javascript`
Python	`python`
Ruby	`ruby`
Swift	`swift`

提示

使用 cpp 來分析以 C、C++或兩者撰寫的程式代碼。
使用 java 來分析用 Java、Kotlin 或兩者撰寫的程式碼。
使用 javascript 來分析以 JavaScript、TypeScript 或兩者撰寫的程式代碼。

如需詳細資訊，請參閱支援的語言和架構。

您可以在組建記錄檔中檢視 CodeQL 所執行的特定查詢和工作詳細數據。

程式碼掃描建置模式自訂

設定管線以進行掃描時，程式碼掃描支援兩種設置模式：

none- CodeQL 資料庫是直接從程式碼基底建立，而不需要建置程式碼基底（支援所有解譯語言，以及另外支援cpp、 java和csharp）。
manual - 您可以定義用於工作流程中程式代碼基底的建置步驟（支援所有編譯的語言）。

如需不同建置模式的詳細資訊，包括每個建置模式優點的比較，請參閱 CodeQL程式碼掃描編譯的語言。

提示

建置模式 none 可用於其他直譯語言，例如 JavaScript、Python、Ruby。若為 C# Java或其他不支援建置模式none 的編譯語言指定建置模式 none，管線任務會失敗。

下列程式代碼顯示具有多種語言的有效組態範例，並 none 建置模式：

trigger: none
 
pool:
  vmImage: windows-latest

steps:
- task: AdvancedSecurity-Codeql-Init@1
  displayName: Initialize CodeQL
  inputs:
# build mode `none` is supported for C# and Java, and JavaScript is an interpreted language
# and build mode `none` has no impact on JavaScript analysis
    languages: 'csharp, java, javascript' 
    buildtype: 'none'

- task: AdvancedSecurity-Codeql-Analyze@1
  displayName: Perform CodeQL Analysis

下列程式代碼顯示具有多種語言和 none 建置模式之無效組態的範例：

trigger: none
 
pool:
  vmImage: windows-latest

steps:
- task: AdvancedSecurity-Codeql-Init@1
  displayName: Initialize CodeQL
  inputs:
# build mode `none` is supported for C# but build mode `none` is NOT supported for Swift
# so this pipeline definition will result in a failed run
    languages: 'csharp, swift'
    buildtype: 'none'

- task: AdvancedSecurity-Codeql-Analyze@1
  displayName: Perform CodeQL Analysis

程式碼掃描警示

GitHub Advanced Security for Azure DevOps 程式碼掃描警示含有依儲存庫劃分的程式碼掃描標示，用於警示程式碼層級的應用程式漏洞。

要使用程式碼掃描，首先需要設定 GitHub Advanced Security for Azure DevOps。

Azure DevOps 中 Repos 的 Advanced Security 標籤是查看程式碼掃描警示的樞紐。選取 程式碼掃描 標籤來查看掃描警示。您可以依分支、狀態、管線、規則類型和嚴重性進行篩選。此時，警示中樞不會顯示在PR分支上完成掃描的警示。

如果重新命名管線或分支，則結果不會有任何影響，最多可能需要 24 小時才會顯示新名稱。

如果您選擇執行自定義 CodeQL 查詢，則根據預設，不會針對從不同查詢套件產生的警示個別篩選。您可以依規則進行篩選，每個查詢各有不同。

如果您關閉存放庫的進階安全性，您會失去 [進階安全性] 索引標籤和建置工作中結果的存取權。建置工作不會失敗，但當停用進階安全性時，透過此工作執行的任何建置結果會被隱藏且不會保留。

警示詳細資料

如需詳細資訊，包括修正指引，請選取警示。每個警示都包含位置、描述、範例和嚴重性。

部分	說明
位置	位置部分詳細說明 CodeQL 偵測到的特定弱點實例。如果有多個違反相同規則的程式代碼實例，就會為每個不同的位置產生新的警示。位置卡包含受影響程式碼片段的直接連結，讓你可以選擇該片段導向 Azure DevOps 網頁介面進行編輯。
描述	根據問題，CodeQL 工具會提供描述。
建議	建議的修正是針對指定程式代碼掃描警示的建議解決方案。
範例	範例區段顯示程式代碼中已識別弱點的簡化範例。
嚴重性	嚴重性層級可以是低、中、高或嚴重。嚴重性分數的基礎是識別出的常見弱點列舉 (CWE) 的給定常見漏洞評分系統 (CVSS) 分數。想了解更多嚴重程度的評分方式，請參閱這篇GitHub部落格文章。

檢視存放庫的警示

任何擁有該倉庫貢獻者權限的人，都可以在 Repos 的進階安全標籤中查看該倉庫所有警報的摘要。選取 程式碼掃描 索引標籤，以檢視所有秘密掃描警示。

若要顯示結果，程式代碼掃描工作必須先執行。第一次掃描完成後，任何偵測到的弱點都會顯示在 [進階安全性] 索引卷標中。

根據預設，警示頁面會顯示存放庫預設分支的程式碼掃描結果。

指定的警示狀態會反映預設分支和最新執行管線的狀態，即使警示存在於其他分支和管線上也一樣。

消除程式碼掃描警示

若要關閉警示，您需要適當的許可權。根據預設，只有專案管理員可以關閉進階安全性警示。

若要關閉警示：

流覽至您想要關閉的警示，然後選擇該警示。
選取 [關閉警示] 下拉式清單。
如果尚未選取，請選取 [已接受風險] 或 [誤報] 作為關閉原因。
在 [批注] 文本框中新增選擇性批注。
選取 [ 關閉 ] 以提交並關閉警示。
警示狀態會從 [開啟] 變更為 [已關閉] ，並顯示關閉原因。

此動作會解除所有分支的警示。也會關閉包含相同弱點的其他分支。先前關閉的任何警示都可以手動重新開啟。

管理拉取請求的程式碼掃描警示

如果在拉取請求中為新的程式碼變更建立警示，警示會在拉取請求的 [概觀] 頁籤的批註區段中回報為批註，並在 [進階安全性存放庫] 頁籤中顯示為警示。拉取請求分支有新的分支選擇器項目。

您可以檢閱受影響的程式代碼行、查看結果摘要，以及在概覽部分中解決註解。

若要關閉提取要求警示，您必須瀏覽至警示詳細檢視，以關閉警示並解決批註問題。否則，只要變更批注狀態（1）即可解析批注，但不會關閉或修正基礎警示。

要查看你拉取請求分支的完整結果，請前往 Repos>Advanced Security，選擇你的拉取請求分支。在註釋上選取 [顯示更多詳細數據 ]，會將您導向 [進階安全性] 索引卷標的 [警示詳細數據] 檢視。

提示

只有在受影響的程式代碼行與提取要求的目標分支相比，提取要求差異完全是唯一的時，才會建立批注。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-04-14