共用方式為

程式碼掃描

  • 發行項

GitHub Advanced Security for Azure DevOps 中的 程式代碼掃描可讓您分析 Azure DevOps 存放庫中的程序代碼，以找出安全性弱點和編碼錯誤。 會以警示形式提出分析所識別的任何問題。 程式碼掃描會使用 CodeQL 識別弱點。

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

適用於 Azure DevOps 的 GitHub 進階安全性可與 Azure Repos 搭配運作。 如果您想要搭配 GitHub 存放庫使用 GitHub 進階安全性，請參閱 GitHub 進階安全性。

程式代碼掃描的其他設定

語言和查詢支援

GitHub 專家、安全性研究人員和社群參與者會撰寫和維護用於程式代碼掃描的預設 CodeQL 查詢。 查詢會定期更新，以改善分析並減少任何誤判結果。 查詢 開放原始碼，因此您可以檢視並參與 github/codeql 存放庫中的查詢。

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

語言 識別碼 選擇性替代識別碼（如果有的話）
C/C++ c-cpp c 或 cpp
C# csharp
Go go
Java/Kotlin java-kotlin
JavaScript/TypeScript javascript
Python python
Ruby ruby
Swift swift

提示

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

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

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

程式代碼掃描發佈結果工作的螢幕快照。

程式代碼掃描建置模式自定義

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

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

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

若要透過適用於 Azure DevOps 的 GitHub 進階安全性執行程式代碼掃描分析，autobuild建置模式會改為個別的建置工作。 AdvancedSecurity-CodeQL-Autobuild@1

提示

建置模式 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

搭配 CodeQL 使用自訂查詢

根據預設，如果您未在管線設定中指定自定義元件檔，CodeQL 會 security-extended 執行查詢套件來分析您的程式代碼。 您可以使用自訂 CodeQL 查詢來撰寫自己的查詢，以尋找特定的弱點和錯誤。 您也需要建立自定義組態檔來修改 CodeQL 的預設分析。

若要尋找現有的自定義查詢或參與您自己的自定義查詢，請參閱 參與 CodeQL。

使用自訂查詢進行分析

開始使用自定義查詢的最快方式是撰寫查詢，並將它儲存在本機 Azure DevOps 存放庫中。 您可以根據您的需求自定義自定義查詢的詳細數據，但至少必須有規則標識碼。 如需如何撰寫您自己的 CodeQL 查詢的詳細資訊，請參閱 撰寫 CodeQL 查詢。 您也可以將多個查詢組合在查詢套件中，或利用其他人發佈的套件。 如需詳細資訊，請參閱 發佈和使用CodeQL套件。

使用自訂組態檔

自定義組態檔是管理程式碼分析程式碼期間所執行查詢的方法。 您可以指定要執行的更多查詢或查詢套件，以及變更或停用預設 CodeQL 查詢。

若要包含您想要包含的特定查詢，請使用查詢檔案 （.ql） 在存放庫中的位置名稱和路徑來指定查詢。

若要包含您想要包含的特定套件，請指定套件名稱。 您可以指定要在元件執行的任意數目 CodeQL 查詢套件。

下一個步驟是建立 qlpack.yml 檔案。 此檔案會宣告 CodeQL 套件及其相關信息。 與 *.ql 相同目錄 （或子目錄） qlpack.yml 中的任何檔案都會被視為套件的一部分。

提示

設定檔中的 packs 篩選支援從 GitHub 中裝載的存放庫下載套件，但 queries 篩選則不支援。 如果套件在 GitHub 中是私用的，則您必須透過工作提供 GitHub 存取權杖 AdvancedSecurity-Codeql-Init@1 做為環境變數，並將變數名稱作為 GITHUB_TOKEN，令牌的範圍為 read:packages。

以下為範例設定檔：

name: "Run custom queries"

# When using a configuration file, if you do not disable default queries,
# then the default CodeQL queries in the `code-scanning` query suite will also execute upon analysis.
disable-default-queries: true
 
# To reference local queries saved to your repository,
# the path must start with `./` followed by the path to the custom query or queries.
# Names for each query referenced is optional.
queries:
  - name: Use security-extended query suite
    uses: security-extended
  - name: Use local custom query (single query)
    uses: ./customQueries/javascript/FindTestFunctions.ql
  - name: Use local custom query (directory of queries)
    uses: ./customQueries/javascript/MemoryLeakQueries  
 
packs:
 - mygithuborg/mypackname
 
paths:
 - src
 
paths-ignore:
  - src/node_modules
  - '**/*.test.js'
 
query-filters:
 - include:
    kind: problem
 - include:
     precision: medium
 - exclude:
    id:
      - js/angular/disabling-sce
      - js/angular/insecure-url-allowlist

提示

組態檔規格會忽略並優先於工作的 AdvancedSecurity-Codeql-Init@1 管線層級設定。 includepaths / ignorepaths將會忽略，如果paths/paths-ignore存在，則會以的值覆寫 。paths/paths-ignore querysuite將會以組態檔中指定的queriespacks值覆寫。

如果您使用任何自訂查詢，以下是放置在自訂查詢目錄中的範例 qlpack.yml ：

version: 1.0.1
dependencies:
  codeql/javascript-all: "*"
  codeql/javascript-queries: "*"

變數 dependencies 包含此套件及其相容版本範圍的所有相依性。 每個相依性都會參考為 scope/name CodeQL 連結庫套件的 。 定義 dependencies時，您的 qlpack.yml 相依於其中一個核心語言套件（例如 JavaScript、C#、Ruby 等），以決定查詢可以分析的語言。

如需組態檔的更具體建議和組態選項，請參閱 針對程式代碼掃描 或 qlpack.yml 設定自定義進階設定，請參閱 CodeQL 套件結構。

設定好組態檔之後，您必須自定義執行 CodeQL 分析的管線，以利用您的新檔案。 以下是指向組態檔的範例管線：

trigger: none
 
pool:
  vmImage: windows-latest

# You can either specify your CodeQL variables in a variable block... 
variables:
# `configfilepath` must be an absolute file path relative to the repository root
  advancedsecurity.codeql.configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml' 

# Or you can specify variables as variables for the task. You do not need both definitions. 
steps:
- task: AdvancedSecurity-Codeql-Init@1
  displayName: Initialize CodeQL
  inputs:
    languages: 'javascript'
    loglevel: '2'
    configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml'
# If downloading a pack from GitHub,
# you must include a GitHub access token with the scope of `read:packages`.
  env:
    GITHUB_TOKEN: $(githubtoken)

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

程式碼掃描警示

適用於 Azure DevOps 程式代碼掃描警示的 GitHub 進階安全性包含程式碼層級應用程式弱點警示的存放庫的程式代碼掃描旗標。

若要使用程式代碼掃描，您必須先設定 Azure DevOps 的 GitHub 進階安全性。

Azure DevOps 中 Repos 底下的 [進階安全性] 索引標籤是用來檢視程式代碼掃描警示的中樞。 選取 [ 程序代碼掃描] 索引 標籤以檢視掃描警示。 您可以依分支、狀態、管線、規則類型和嚴重性進行篩選。 此時，警示中樞不會顯示在PR分支上完成掃描的警示。

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

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

程式代碼掃描存放庫警示的螢幕快照。

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

警示詳細資料

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

程式代碼掃描警示詳細數據的螢幕快照。

區段 說明
Location [位置] 區段會詳細說明 CodeQL 偵測到弱點的特定實例。 如果有多個違反相同規則的程式代碼實例，就會為每個不同的位置產生新的警示。 [位置] 卡片包含受影響代碼段的直接連結，因此您可以選取要導向至 Azure DevOps Web UI 的代碼段進行編輯。
描述 根據問題，CodeQL 工具會提供描述。
建議 建議針對指定的程式代碼掃描警示進行建議修正。
範例 範例區段顯示程式代碼中已識別弱點的簡化範例。
嚴重性 嚴重性層級可以是低、中、高或嚴重。 嚴重性分數是以所識別常見弱點列舉 （CWE） 的給定常見弱點評分系統 （CVSS） 分數為基礎。 在此 GitHub 部落格文章中深入瞭解嚴重性如何評分。

檢視存放庫的警示

具有存放庫參與者許可權的任何人都可以在 [Repos] 下的 [進階安全性] 索引卷標中檢視存放庫的所有警示摘要。 選取 [ 程序代碼掃描] 索引 標籤，以檢視所有秘密掃描警示。

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

根據預設，警示頁面會顯示存放庫預設分支的相依性掃描結果。

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

關閉程式代碼掃描警示

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

若要關閉警示：

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

如何關閉程式代碼掃描警示的螢幕快照。

此動作只會關閉所選分支的警示。 包含相同弱點的其他分支會保持作用中，直到關閉為止。 先前關閉的任何警示都可以手動重新開啟。

管理提取要求的程式代碼掃描警示

如果在提取要求中為新的程式碼變更建立警示，警示將會在提取要求的 [概觀] 索引卷標的批註區段中回報為註釋，並在 [進階安全性存放庫] 索引卷標中回報為警示，併產生提取要求分支的新分支選擇器結果。

您可以影響程式代碼行、查看尋找的摘要，以及解決 [概觀] 區段中的批注。

作用中程序代碼提取要求批注的螢幕快照。

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

已關閉程序代碼提取要求批注的螢幕快照。

若要查看提取要求分支的整個結果集，請流覽至 [Repos>進階安全性]，然後選取您的提取要求分支。 選取 批註上的 [顯示更多詳細數據 ]（2），會將您導向 [進階安全性] 索引標籤中的 [警示詳細數據] 檢視。

提示

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

對程式碼掃描進行疑難排解

一般而言，如果您在 CodeQL 執行時遇到錯誤，CodeQL CLI 會報告其執行的每個命令狀態做為結束代碼。 結束代碼會提供後續命令或依賴 CodeQL CLI 之其他工具的資訊。 如需結束代碼詳細數據的詳細資訊，請參閱 結束代碼。

錯誤：'database finalize' CodeQL 命令 （32）

此錯誤表示完成 CodeQL 資料庫建立時發生問題，可能是因為擷取錯誤或缺少建置步驟。

疑難排解步驟：

  1. 確認程序代碼存在且已編譯
    • 針對已編譯的語言，請確認建置程式正在編譯程序代碼，並在和工作AdvancedSecurity-Codeql-Analyze之間AdvancedSecurity-Codeql-Init發生。 您可以在指定組建命令中找到常見的建置命令和必要旗標（例如乾淨的無快取/無精靈）。
    • 針對解譯的語言，請確認專案中指定語言有一些原始程式碼。
  2. 檢查擷取錯誤
    • 確認擷取錯誤是否會影響CodeQL資料庫的健全狀況。
    • 檢閱記錄檔中是否有擷取錯誤和警告，以評估整體資料庫健康情況。
  3. 調查壓倒性錯誤
    • 如果大部分檔案遇到擷取器錯誤，請進一步調查以瞭解擷取不當的根本原因。

錯誤：自動建置文稿 （1）

此錯誤描述自動建置失敗，並建議程式代碼掃描設定或設定的問題。

疑難排解步驟：

  1. 設定建置步驟
    • 拿掉 AutoBuild 步驟，並改為在管線中設定已編譯語言的特定建置步驟。
    • 請參閱設定 Azure DevOps 的 GitHub 進階安全性中提供的設定指導方針。

錯誤：代理程式工具快取中找不到 CodeQL 目錄

此錯誤表示為自我裝載代理程式安裝CodeQL時發生問題。

疑難排解步驟：

  1. 請參閱設定 Azure DevOps 的 GitHub 進階安全性中提供的設定指導方針或設定腳本。

錯誤：未設定語言管線變數

嘗試執行 CodeQL 但未設定管線變數來指定要掃描哪些語言時，就會發生此錯誤。

疑難排解步驟：

  1. 設定語言管線變數
    • 請確定已正確設定語言管線變數。 請參閱設定 Azure DevOps 的 GitHub 進階安全性中提供的設定指導方針。
    • 支援的語言包括csharp、、cpp、gojavajavascript、、python、ruby、 和 swift。

CodeQL 不會傳回任何結果

本節提供 CodeQL 分析不會產生任何結果的情況指引。

疑難排解步驟：

  1. 檢查偵測到的弱點
    • 請考慮您的程式代碼可能確實沒有弱點的可能性。 如果預期但未偵測到弱點，請繼續進行進一步驗證。
  2. 檢閱查詢套件組態
  3. 調整檢視結果的許可權
    • 請確定至少在參與者層級授與適當的許可權，才能存取分析結果。 如需詳細資訊，請參閱 進階安全性許可權。

CodeQL 逾時

如果工作 AdvancedSecurity-Codeql-Analyze@1 正在顯示 This job was abandoned ... we lost contact with the agent ，而且您使用的是託管Microsoft代理程式，則工作會達到付費託管代理程式的內建六小時逾時。 您可以改為嘗試在自我裝載的代理程式上執行分析。

程式代碼掃描工作許可權

程式代碼掃描建置工作會使用管線身分識別來呼叫進階安全性 REST API。 根據預設，相同專案中的管線可以存取執行 CodeQL 分析所產生的 SARIF 檔案。 如果這些許可權已從組建服務帳戶中移除，或者如果您有自定義設定（例如，裝載在與存放庫不同的專案中的管線），則必須手動授與這些許可權。

疑難排解步驟：

  • 授 Advanced Security: View alerts 與和 Advanced Security: Manage and dismiss alerts 許可權給管線中使用的建置服務帳戶，其中專案範圍的管線為 [Project Name] Build Service ([Organization Name])，而集合範圍的管線為 Project Collection Build Service ([Organization Name])。

將 CodeQL 套件組合手動安裝到自我裝載的代理程式

使用 GitHub 上提供的架構設定文稿，將 CodeQL 套件組合安裝到代理程式工具快取。 這些文稿需要$AGENT_TOOLSDIRECTORY將環境變數設定為代理程式上代理程式工具目錄的位置，例如 。 C:/agent/_work/_tool 或者，您可以手動實作下列步驟：

  1. 從 GitHub 挑選最新的 CodeQL 版本套件組合。
  2. 將套件組合下載並解壓縮到代理程式工具目錄內的下列目錄，通常位於 底下 _work/_tool： ./CodeQL/0.0.0-[codeql-release-bundle-tag]/x64/。 使用的目前版本 v2.16.0，資料夾名稱會標題為 ./CodeQL/0.0.0-codeql-bundle-v2.16.0/x64/。 深入瞭解 代理程式工具目錄。
  3. 建立標題在 x64.complete ./CodeQL/0.0.0-[codeql-release-bundle-tag] 資料夾內的空白檔案。 使用上述範例，檔案 x64.complete 的結束檔案路徑應該是 ./CodeQL/0.0.0-codeql-bundle-v2.16.0/x64.complete。