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

10 分鐘

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

當您使用 CodeQL 掃描程式碼時，CodeQL 分析引擎會從程式碼產生資料庫，並對其執行查詢。 CodeQL 分析會使用一組預設的查詢，但除了預設查詢之外，您還可以指定執行其他查詢。

如果這些查詢屬於發佈至 GitHub Container Registry 的程式代碼QL 套件（beta），或儲存在存放庫中的 QL 套件，您可以執行額外的查詢。

有兩個選項可用來指定您想要使用 CodeQL 程式碼掃描執行的查詢：

使用程式碼掃描工作流程
使用自訂組態檔

在此單元中，您將了解如何編輯工作流程檔案以參考其他查詢、如何使用來自查詢套件的查詢，以及如何結合來自工作流程檔案和自訂組態檔的查詢。

在工作流程檔案中指定其他查詢

您可使用下列選項，指定您想要執行的額外查詢：

使用 packs 安裝一或多個 CodeQL 查詢套裝 (Beta)，並執行這些套裝的預設查詢集合或查詢。
使用 queries 指定單一 .ql 檔案、包含多個 .ql 檔案的目錄、.qls 查詢套件定義檔案或任何組合。

您可以在相同的工作流程中使用套件和查詢。

我們不建議直接從 github/codeql 存放庫參考查詢套件，例如 github/codeql/cpp/ql/src@main。這類查詢在編譯時，使用的 CodeQL 版本可能與其他查詢不同，而這可能會導致分析期間發生錯誤。

使用 CodeQL 查詢套件

備註

CodeQL 套件管理功能 (包含 CodeQL 套件) 目前為搶鮮版 (Beta)，隨時可能變更。

若要加入一或多個 CodeQL 查詢套件 (Beta)，請在工作流程的 with: packs: 區段中加入 uses: github/codeql-action/init@v1 項目。在套件中，您能指定要使用的一或多個套件，並可選擇指定要下載的版本。如果未指定版本，則會下載最新版本。如果您想要使用未公開的套件，必須將 GITHUB_TOKEN 環境變數設定為有權存取套件的祕密。

在下列範例中，範圍是發佈套件的組織或個人帳戶。當工作流程執行時，會從 GitHub 下載三個 CodeQL 查詢套件，並執行每個套件中包含的預設查詢或查詢套件。在下列範例中，清單中的每個套件都會根據其規格下載：

最新版本 pack1 已下載，並執行所有預設查詢。
下載 1.2.3 pack2 版，並執行所有預設查詢。
下載與 3.2.1 版 pack3 相容的最新版本，並執行所有查詢。
會下載 pack4 4.5.6 版，且只會執行在 path/to/queries 中找到的查詢。

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of packs to download
    packs: scope/pack1,scope/pack2@1.2.3,scope/pack3@~3.2.1,scope/pack4@4.5.6:path/to/queries

備註

若是為多種語言產生 CodeQL 資料庫的工作流程，您則必須在組態檔中指定 CodeQL 查詢套件。

在 QL 套件中使用查詢

若要新增一或多個查詢，請在工作流程的 with: queries: 區段中新增 uses: github/codeql-action/init@v3 項目。如果查詢位於私有存放庫中，請使用external-repository-token參數指定有權存取私有存放庫的權杖。

- uses: github/codeql-action/init@v3
  with:
    # Comma-separated list of queries / packs / suites to run.
    # This may include paths or a built in suite, for example:
    # security-extended or security-and-quality.
    queries: security-extended
    # Optional. Provide a token to access queries stored in private repositories.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

您也可以在 queries 的值中指定查詢套件。查詢套件是查詢集合，通常會依用途或語言分組。

下列查詢套件內建於 CodeQL 程式碼掃描中，可供使用：

查詢套件	描述
`security-extended`	來自預設套件的查詢，加上較低的嚴重性和精確度查詢
`security-and-quality`	來自 `security-extended` 的查詢，加上可維護性和可靠性查詢

這些查詢套件每個都包含該語言內建 CodeQL 查詢套件中包含的不同查詢子集。系統會使用每個查詢的中繼資料自動產生查詢套件。

當您指定查詢套件時，CodeQL 分析引擎除了預設的查詢集之外，還會為您執行套件中包含的查詢。

結合工作流程檔案和自訂組態檔的查詢

如果您也針對自訂設定使用組態檔，則會使用工作流程中指定的任何其他套件或查詢，而不是組態檔中指定的套件或查詢。如果您想要執行合併的其他套件或查詢集，請在工作流程中的 packs 或 queries 值前面加上 + 符號。

在下列範例中，+ 符號可確保指定的額外套件和查詢，會與參考的組態檔中任何指定對象一起使用：

- uses: github/codeql-action/init@v3
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    packs: +scope/pack1,scope/pack2@1.2.3,scope/pack3@4.5.6:path/to/queries

意見反應

此頁面對您有幫助嗎？