使用 CodeQL 自訂程式碼掃描工作流程 - 第 2 部分

8 分鐘

使用 CodeQL 的程式碼掃描工作流程有各種可調整的組態選項，以貼近組織的需求。

在本單元中，我們會檢閱如何參考自訂設定檔中的其他查詢。

自訂組態檔中的其他查詢

自訂組態檔是一項替代方式以指定要執行的其他套件和查詢。您也可以使用該檔來停用預設查詢，並指定要在分析期間掃描的目錄。

在工作流程檔案中，使用 config-file 動作的 init 參數來指定所要使用的組態檔路徑。此範例會載入組態檔 ./.github/codeql/codeql-config.yml。

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml

組態檔可以位於所要分析的存放庫內或外部存放庫中。使用外部存放庫可讓您在單一位置指定多個存放庫的組態選項。當您參考位於外部存放庫的組態檔時，您可以使用 OWNER/REPOSITORY/FILENAME@BRANCH 語法。例如： octo-org/shared/codeql-config.yml@main 。

如果組態檔位於外部私人存放庫，請使用 external-repository-token 動作的 init 參數來指定可存取私人存放庫的權杖。

- uses: github/codeql-action/init@v3
  with:
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

組態檔中的設定是以 YAML 格式撰寫。

在自訂配置檔案中指定 CodeQL 查詢套件

備註

CodeQL 套件管理功能（包括 CodeQL 套件包）目前處於 beta 階段，功能可能會隨時變更。

您能指定陣列中的 CodeQL 查詢套件。其格式與工作流程檔案所使用的格式不同。

packs:
packs:
  # Use the latest version of 'pack1' published by 'scope'
  - scope/pack1
  # Use version 1.2.3 of 'pack2'
  - scope/pack2@1.2.3
  # Use the latest version of 'pack3' compatible with 3.2.1
  - scope/pack3@~3.2.1
  # Use pack4 and restrict it to queries found in the 'path/to/queries' directory
  - scope/pack4:path/to/queries
  # Use pack5 and restrict it to the query 'path/to/single/query.ql'
  - scope/pack5:path/to/single/query.ql
  # Use pack6 and restrict it to the query suite 'path/to/suite.qls'
  - scope/pack6:path/to/suite.qls

查詢套件的完整指定格式為 scope/name[@version][:path]。 version 和 path 都是選填的。 version 是 SemVer 版本範圍。如果遺失，則會使用最新版本。

如果所擁有的工作流程會產生多個 CodeQL 資料庫，您可以使用套件的巢狀對應來指定要在自訂組態檔中執行的任何 CodeQL 查詢套件。

packs:
  # Use these packs for JavaScript and TypeScript analysis
  javascript:
    - scope/js-pack1
    - scope/js-pack2
  # Use these packs for Java and Kotlin analysis
  java:
    - scope/java-pack1
    - scope/java-pack2@v1.0.0

指定自訂組態中的其他查詢

您能指定 queries 陣列中的其他查詢。每個陣列的元素包含 uses 參數，其中有識別單一查詢檔案的值、包含查詢檔案的目錄或查詢套件定義檔案。

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./query-suites/my-security-queries.qls

您也可以指定每個陣列元素的名稱，如下列範例組態檔所示：

name: "My CodeQL config"

disable-default-queries: true

queries:
  - name: Use an in-repository QL pack (run queries in the my-queries directory)
    uses: ./my-queries
  - name: Use an external JavaScript QL pack (run queries from an external repo)
    uses: octo-org/javascript-qlpack@main
  - name: Use an external query (run a single query from an external QL pack)
    uses: octo-org/python-qlpack/show_ifs.ql@main
  - name: Use a query suite file (run queries from a query suite in this repo)
    uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

停用預設查詢

如果只要執行自訂查詢，您可以使用 disable-default-queries: true 停用預設安全性查詢。如果您嘗試建構排除特定規則的自訂查詢套件，也應使用此旗標。這是為避免所有查詢執行兩次。

將特定查詢從分析中排除

您可以將 exclude 與 include 篩選條件新增至自訂設定檔，以指定您想要在分析中排除或包含的查詢，例如：

預設套件 (security、security-extended 和 security-and-quality) 中的特定查詢。
特定查詢，您對其結果不感興趣。
產生警告和建議的所有查詢。

您可以使用類似下列檔案設定中的 exclude 篩選條件，以排除您想要從預設分析中移除的查詢。在下列組態檔的範例中，js/redundant-assignment 和 js/useless-assignment-to-local 的查詢都會從分析中排除。

query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

若要尋找查詢的識別碼，您可以在 [安全性] 索引標籤的警示清單中按一下該警示。這會開啟警示詳細資料頁面。 [規則識別碼] 欄位包含查詢識別碼。

使用 excludes 篩選條件時要記住的事項：

篩選條件的順序很重要。查詢和查詢套件的相關指示之後出現的第一個篩選條件指示，會決定預設是否包含或排除那些查詢。
後續的指示會依序執行，而稍後在檔案中出現的指示優先於先前的指示。

指定要掃描的目錄

針對 CodeQL 支援 (Python、Ruby 和 JavaScript/TypeScript) 的解譯語言，您可以將 paths 陣列新增至設定檔，以將程式碼掃描限制於特定目錄中的檔案。您可以新增 paths-ignore 陣列，從分析中排除特定目錄中的檔案。

paths:
  - src
paths-ignore:
  - src/node_modules
  - '**/*.test.js'

備註

在程式碼掃描配置檔的上下文中使用的paths和paths-ignore關鍵字，不應與在工作流程中用於on.<push|pull_request>.paths的相同關鍵字混淆。當關鍵字用於修改工作流程中的 on.<push|pull_request> 時，會在某人修改指定目錄中的程式碼時，判斷是否要執行動作。
不支援篩選模式字元 ?、+、[、] 和 !，並將依照字面進行比對。
** 字元僅可位於行的開頭或結尾或以斜線括住，且您無法混入 ** 和其他字元。例如：foo/**、**/foo 和 foo/**/bar 皆是允許的語法，但 **foo 則否。不過，您可以搭配其他字元使用單顆星，如範例所示。您必須將包含 * 字元的任何項目加上引號。

針對已編譯的語言，如果想要將程式碼掃描限制於專案中的特定目錄，您必須在工作流程中指定適當的建置步驟。所必須用於排除組建中目錄的命令，將取決於建置系統。

當您修改特定目錄中的程式碼時，您可以快速分析 monorepo 中的某些小部分。在建置步驟中，您需要排除目錄，並在工作流程中對 paths-ignore 使用 paths 和 on.<push|pull_request> 關鍵字。

意見反應

此頁面對您有幫助嗎？