# 代码扫描的工作流配置选项 编辑工作流文件，以配置高级安装程序如何扫描项目中的代码是否存在漏洞和错误。 ## 先决条件 必须为 code scanning 使用高级设置，并能够编辑定义了配置的工作流文件。 本文中提供的示例与 CodeQL 分析工作流程 该文件相关。 默认情况下，该文件定义在 `.github/workflows/codeql-analysis.yml`。 ## 扫描频率 可以将CodeQL 分析工作流程 配置为按照计划时间表或存储库中发生特定事件来扫描代码。 每当推送到仓库以及每次创建拉取请求时，时扫描代码可防止开发者在代码中引入新的漏洞和错误。 按计划扫描代码会通知你最新的漏洞和错误，即使开发人员没有主动维护存储库，安全研究人员和社区也会发现这些漏洞和错误 GitHub。 ### 按推送扫描 默认情况下，CodeQL 分析工作流程 使用 `on:push` 事件在每次将代码推送到存储库的默认分支和任何受保护的分支时触发代码扫描。 若要 code scanning 在指定的分支上触发工作流，工作流必须存在于该分支中。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#on)”。 如果在推送时扫描，则结果将显示在存储库的 ** Security and quality** 选项卡中。 有关详细信息，请参阅“[访问存储库的代码扫描警报](/zh/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/assess-alerts#viewing-the-alerts-for-a-repository)”。 此外，当 `on:push` 扫描返回可映射到打开的拉取请求的结果时，这些警报将自动出现在拉取请求中，与其他拉取请求警报位于同一位置。 警报是通过比较对分支头的现有分析与对目标分支的分析来确定的。 有关拉取请求中code scanning警报的详细信息，请参阅[鉴定拉取请求中的代码扫描警报](/zh/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/triage-alerts-in-pull-requests)。 ### 扫描拉取请求 默认情况下，CodeQL 分析工作流程 使用 `pull_request` 事件触发代码扫描，以处理针对默认分支的拉取请求。 如果拉取请求来自专用分支，`pull_request`则只有在存储库设置中选择了“从分叉拉取请求运行工作流”选项时，才会触发该事件。 有关详细信息，请参阅 [管理存储库的GitHub Actions设置](/zh/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-forks-of-private-repositories)。 有关 `pull_request` 事件的详细信息，请参阅 [触发工作流的事件](/zh/actions/reference/workflows-and-actions/events-that-trigger-workflows#pull_request)。 如果扫描拉取请求，结果将在拉取请求检查中显示为警报。 有关详细信息，请参阅“[鉴定拉取请求中的代码扫描警报](/zh/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/triage-alerts-in-pull-requests)”。 使用 `pull_request` 触发器（配置为扫描拉取请求的合并提交，而不是头提交）与每次推送时扫描分支头相比，可产生更高效且准确的结果。 但是，如果使用的 CI/CD 系统无法配置为发生拉取请求时触发，你仍然可以使用 `on:push` 触发器和 code scanning 会将结果映射到在分支上打开的拉取请求，并将警报作为注释添加到拉取请求。 有关详细信息，请参阅 [推送时扫描](#scanning-on-push)。 > \[!NOTE] > 如果存储库配置了合并队列，则需要将 `merge_group` 事件作为附加触发器包含在 code scanning 中。 这将确保在将拉取请求添加到合并队列时也会对其进行扫描。 有关详细信息，请参阅“[管理合并队列](/zh/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue)”。 ### 避免对拉取请求进行不必要的扫描 你可能希望避免触发针对默认分支的特定拉取请求的代码扫描，而不考虑哪些文件已更改。 可以在`on:pull_request:paths-ignore`工作流中通过指定`on:pull_request:paths`或code scanning来配置。 例如，如果拉取请求中仅更改了文件扩展名为 `.md` 或 `.txt` 的文件，你可以使用以下 `paths-ignore` 数组。 ```yaml copy on: push: branches: [main, protected] pull_request: branches: [main] paths-ignore: - '**/*.md' - '**/*.txt' ``` > \[!NOTE] > `on:pull_request:paths-ignore` 和 `on:pull_request:paths` 可设置用于决定工作流中的操作是否将在发生拉取请求时运行的条件。 它们不会决定操作\_运行\_时将分析哪些文件。 当拉取请求包含任何未被 `on:pull_request:paths-ignore` 或 `on:pull_request:paths` 匹配的文件时，工作流会运行操作并扫描拉动请求中更改的所有文件，包括那些被 `on:pull_request:paths-ignore` 或 `on:pull_request:paths` 匹配的文件，除非这些文件已被排除。 有关如何从分析中排除文件的信息，请参阅[指定要扫描的目录](#specifying-directories-to-scan)。 有关使用 `on:pull_request:paths-ignore` 和 `on:pull_request:paths` 确定工作流何时为拉取请求运行的详细信息，请参阅 [GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore)。 ### 按时间表扫描 如果使用默认值 CodeQL 分析工作流程，除了事件触发的扫描之外，工作流每周都会扫描存储库中的代码一次。 要调整此计划，请在工作流中编辑 `cron` 事件对应的 `on.schedule` 值。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onschedule)”。 > \[!NOTE] > 仅当工作流文件存在于默认分支上时，此事件才会触发工作流运行。 ### 示例 下面的示例演示了一个 CodeQL 分析工作流程 特定存储库，该存储库具有一个名为 `main` 的默认分支和一个受保护的 `protected` 分支。 ```yaml copy on: push: branches: [main, protected] pull_request: branches: [main] schedule: - cron: '20 14 * * 1' ``` 此工作流扫描： * 对默认分支和受保护分支的每次推送 * 对默认分支的每个拉取请求 * 默认分支（每周一 14:20 UTC） ## 操作系统 > \[!NOTE] > > * Swift 代码扫描默认使用 macOS 运行器。 GitHub-托管的 macOS 运行程序比 Linux 和 Windows 运行程序更昂贵，因此应考虑仅扫描生成步骤。 有关如何为 Swift 配置代码扫描的详细信息，请参阅 [对编译语言进行 CodeQL 代码扫描](/zh/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/codeql-for-compiled-languages)。 有关 GitHub 托管运行器定价的详细信息，请参阅 [GitHub Actions计费](/zh/billing/concepts/product-billing/github-actions)。 > * Code scanning Swift 代码不受属于 Actions Runner Controller（ARC）的运行器支持，因为 ARC 运行器仅使用 Linux，而 Swift 需要 macOS 运行器。 但是，你可以混合使用 ARC 运行器和自托管 macOS 运行器。 有关详细信息，请参阅“[操作运行器控制器](/zh/actions/concepts/runners/actions-runner-controller)”。 如果代码需要特定操作系统进行编译，可以在你的 CodeQL 分析工作流程中配置操作系统。 编辑值`jobs.analyze.runs-on`以指定运行您的code scanning操作的计算机的操作系统。 ```yaml copy jobs: analyze: name: Analyze runs-on: [ubuntu-latest] ``` 如果您选择使用自托管的运行器进行代码扫描，可以在`self-hosted`后使用适当的标签作为由两个元素组成的数组中的第二个元素，以指定操作系统。 ```yaml copy jobs: analyze: name: Analyze runs-on: [self-hosted, ubuntu-latest] ``` CodeQL code scanning 支持最新版本的 Ubuntu、Windows 和 macOS。 因此，此设置的典型值为：`ubuntu-latest`、`windows-latest` 和 `macos-latest`。 有关详细信息，请参阅 [选择作业的运行器](/zh/actions/how-tos/write-workflows/choose-where-workflows-run/choose-the-runner-for-a-job) 和 [将标签与自托管运行程序结合使用](/zh/actions/how-tos/manage-runners/self-hosted-runners/apply-labels)。 如果使用自承载运行程序，则必须确保 Git 位于 PATH 变量中。 有关详细信息，请参阅 [自托管运行程序](/zh/actions/concepts/runners/self-hosted-runners) 和 [添加自托管的运行器](/zh/actions/how-tos/manage-runners/self-hosted-runners/add-runners)。 有关在自托管计算机CodeQL上运行 分析的建议规范（RAM、CPU 核心和磁盘），请参阅 [推荐用于运行 CodeQL 的硬件资源](/zh/code-security/reference/code-scanning/codeql/hardware-resources-for-codeql)。 ## CodeQL 数据库位置 一般来说，您无需担心CodeQL 分析工作流程数据库的放置位置CodeQL，因为后续步骤会自动查找在前面步骤中创建的数据库。 但是，如果要编写一个自定义工作流步骤，该步骤要求 CodeQL 数据库位于特定的磁盘位置，例如将数据库作为工作流项目上传，则可以使用 `db-location` 操作下 `init` 的参数指定该位置。 ```yaml copy - uses: github/codeql-action/init@v4 with: db-location: '${{ github.runner_temp }}/my_location' ``` CodeQL 分析工作流程 预期 `db-location` 提供的路径是可写的，并且要么不存在，要么是一个空目录。 当在运行自托管运行器或使用 Docker 容器的作业中使用此参数时， 用户有责任确保所选目录在运行之间被清空， 或数据库一旦不再需要即予移除。 对于运行在托管 GitHub 的运行程序上的作业来说，这不是必要的，因为它们每次运行时都会获取一个新的实例和一个干净的文件系统。 有关详细信息，请参阅“[GitHub 托管的运行程序](/zh/actions/concepts/runners/github-hosted-runners)”。 如果未使用此参数，CodeQL 分析工作流程 将在其自己选择的临时位置创建数据库。 目前，默认值为 `${{ github.runner_temp }}/codeql_databases`. ## 要分析的语言 CodeQL code scanning 支持使用以下语言编写的代码： * C/C++ * C# * Go * Java/Kotlin * JavaScript/TypeScript * Python * Ruby * Rust * 切换 \* GitHub Actions工作流 > \[!NOTE] > > * 使用 `java-kotlin` 分析用 Java 或/和 Kotlin 编写的代码。 > * 使用 `javascript-typescript` 分析用 JavaScript 和/或 TypeScript 编写的代码。 有关详细信息，请参阅 CodeQL 网站上的文档：“[支持的语言和框架](https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/)”。 CodeQL 使用以下语言标识符： | 语言 | Identifier | 可选替代标识符（如果有） | | --------------------------- | ----------------------- | ------------ | | C/C++ | `c-cpp` | | | `c` 或 `cpp` | | | | C# | `csharp` | | | | | | | GitHub Actions 工作流程 | `actions` | | | | | | | Go | `go` | | | Java/Kotlin | `java-kotlin` | | | `java` 或 `kotlin` | | | | JavaScript/TypeScript | `javascript-typescript` | | | `javascript` 或 `typescript` | | | | Python | `python` | | | Ruby | `ruby` | | | | | | | Rust | `rust` | | | | | | | Swift | `swift` | | > \[!NOTE] > 如果指定替代标识符之一，则等效于使用标准语言标识符。 例如，指定 `javascript` 而不是 `javascript-typescript` 不排除对 TypeScript 代码的分析。 相反，可以使用自定义配置文件来使用 `paths-ignore` 设置从分析中排除文件。 有关详细信息，请参阅[使用自定义配置文件](/zh/code-security/reference/code-scanning/workflow-configuration-options#custom-configuration-files)和[指定要扫描的目录](/zh/code-security/reference/code-scanning/workflow-configuration-options#specifying-directories-to-scan)。 这些语言标识符可用作 `languages` 操作的 `init` 输入的参数。 建议仅提供一种语言作为参数： ```yaml copy - uses: github/codeql-action/init@v4 with: languages: javascript-typescript ``` 使用 CodeQL 配置代码扫描的高级设置后创建的默认CodeQL 分析工作流程文件定义了一个矩阵，其中包含一个名为[](/zh/code-security/how-tos/find-and-fix-code-vulnerabilities/configure-code-scanning/configuring-advanced-setup-for-code-scanning#configuring-advanced-setup-for-code-scanning-with-codeql)的属性，该属性列出了存储库中要分析的语言。 此矩阵已自动预填充在存储库中检测到的受支持语言。 `language`使用矩阵可以CodeQL并行运行每个语言分析，并自定义每个语言的分析。 在单个分析中，矩阵中语言的名称将作为 `init` 输入的参数提供给 `languages` 操作。 建议所有工作流都采用此配置。 有关矩阵的详细信息，请参阅“[在工作流中运行作业变体](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/run-job-variations)”。 ```yaml copy - uses: github/codeql-action/init@v4 with: languages: ${{ matrix.language }} ``` 如果工作流使用 `language` 矩阵，则 CodeQL 只会分析矩阵中的语言。 若要更改要分析的语言，请编辑矩阵配置。 可以删除语言以避免对其进行分析。 有几种原因可能使你想阻止对某种语言进行分析。 例如，项目中可能有其他语言的代码主体依赖项，你可能不想看到这些依赖项的警报。 您还可以添加一种在配置code scanning时不在存储库中的语言。 例如，如果存储库最初在配置 code scanning 时仅包含 JavaScript，而您后来添加了 Python 代码，那么您需要将其添加到 `python` 矩阵中。 ```yaml copy jobs: analyze: name: Analyze ... strategy: fail-fast: false matrix: include: - language: javascript-typescript build-mode: none - language: python build-mode: none ``` 对于已编译的语言，矩阵还可用于通过更改 `build-mode` 属性的值来配置应用于分析的生成模式。 有关生成模式的详细信息，请参阅“[对编译语言进行 CodeQL 代码扫描](/zh/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/codeql-for-compiled-languages#use-none-build-mode-for-codeql)”。 如果工作流未为操作的`languages`输入提供参数`init`，则CodeQL配置为按顺序运行分析。 在这种情况下，会自动 CodeQL 检测并尝试分析存储库中任何受支持的语言。 根据存储库的大小和语言数量，这可能需要很长时间。 如果一种语言的分析在此模式下失败，则所有语言的分析都将失败。 因此不建议使用此配置。 > \[!NOTE] > 按顺序分析语言时，系统将默认使用每种语言的默认生成模式。 另一种情况是，如果你提供了显式的 `autobuild` 步骤，则所有支持 `autobuild` 模式的语言都将使用该模式，而其他语言则使用其默认模式。 如果需要比这更复杂的生成模式配置，则需要配置矩阵。 ## 检测失败警报的严重性 当满足以下条件之一时，可以使用规则集防止合并拉取请求： * 某个必需的工具发现了一个 code scanning 警报，且该警报的严重程度符合规则集中的定义。 * 所需的工具分析仍在进行中。 * 未为存储库配置所需的工具。 有关详细信息，请参阅“[设置代码扫描合并保护](/zh/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/set-merge-protection)”。 有关规则集的更多常规信息，请参阅“[关于规则集](/zh/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets)”。 ## 分析类别 使用 `category` 区分针对同一工具和提交的多个分析，但在不同的语言或代码的不同部分执行。 你在工作流程中指定的类别将包含在 SARIF 结果文件中。 如果你使用单一仓库，并且对单一仓库的不同部分有多个对应的 SARIF 文件，此参数是特别有用。 ```yaml copy - name: Perform CodeQL Analysis uses: github/codeql-action/analyze@v4 with: # Optional. Specify a category to distinguish between multiple analyses # for the same tool and ref. If you don't use `category` in your workflow, # GitHub will generate a default category name for you category: "my_category" ``` 如果未在工作流中指定 `category` 参数， GitHub 将基于触发操作的工作流文件的名称、操作名称和任何矩阵变量生成类别名称。 例如： * `.github/workflows/codeql-analysis.yml` 工作流和 `analyze` 操作将生成类别 `.github/workflows/codeql.yml:analyze`。 * `.github/workflows/codeql-analysis.yml` 工作流、`analyze` 操作和 `{language: javascript-typescript, os: linux}` 矩阵变量将生成类别 `.github/workflows/codeql-analysis.yml:analyze/language:javascript-typescript/os:linux`。 `category` 值将显示为 `.automationDetails.id` SARIF v2.1.0 中的属性。 有关详细信息，请参阅“[对代码扫描的 SARIF 支持](/zh/code-security/reference/code-scanning/sarif-files/sarif-support#runautomationdetails-object)”。 指定的类别不会覆盖 SARIF 文件中 `runAutomationDetails` 对象的详细信息（如果已包含）。 ## CodeQL 模型包 如果代码库依赖于标准查询CodeQL无法识别的库或框架，则可以通过指定已发布CodeQL的模型包来扩展code scanning工作流中的CodeQL覆盖范围。 有关创建自己的模型包的详细信息，请参阅 [创建并使用 CodeQL 包](/zh/code-security/tutorials/customize-code-scanning/create-and-work-with-codeql-packs#creating-a-codeql-model-pack)。 > \[!NOTE] > CodeQL 模型包目前包含在 公开预览 中，可能会更改。 C/C++、C#、Java/Kotlin、Python、Ruby 和 Rust 分析支持模型包。 > > CodeQL 的 CodeQL 扩展中的 Visual Studio Code 支持对 C#、Java/Kotlin、Python 和 Ruby 的依赖项建模。 ### 使用 CodeQL 模型包 要添加一个或多个已发布的CodeQL模型包，请在工作流的`with: packs:`部分的`uses: github/codeql-action/init@v4`条目中指定它们。 在 `packs` 中，可以指定要使用的一个或多个包，还可以指定要下载的版本。 在未指定版本的情况下，将下载最新版本。 如果要使用不可公开使用的包，则需要将 `GITHUB_TOKEN` 环境变量设置为有权访问包的机密。 有关详细信息，请参阅 [在工作流中使用 GITHUB\_TOKEN 进行身份验证](/zh/actions/tutorials/authenticate-with-github_token) 和 [在 GitHub Actions 中使用机密](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)。 ```yaml copy - uses: github/codeql-action/init@v4 with: config-file: ./.github/codeql/codeql-config.yml queries: security-extended packs: my-company/my-java-queries@~7.8.9,my-repo/my-java-model-pack ``` 在此示例中，将针对Java运行默认查询，以及对于查询包`7.8.9`中版本号大于或等于`7.9.0`且小于`my-company/my-java-queries`的查询进行运行。 在最新版本的模型包 `my-repo/my-java-model-pack` 中建模的依赖项可用于默认查询和 `my-company/my-java-queries` 中的查询。 ## 非默认查询 用于 CodeQL 扫描代码时， CodeQL 分析引擎会从代码生成数据库，并在其中运行查询。 CodeQL 分析使用默认查询集，但除了默认查询之外，还可以指定要运行的更多查询。 > \[!TIP] > 还可以指定要从分析中排除或是包含在分析中的查询。 这需要使用自定义配置文件。 有关详细信息，请参阅 [自定义配置文件](#custom-configuration-files) 和 [从下面的分析中排除特定查询](#excluding-specific-queries-from-analysis) 。 如果这些额外查询属于发布到CodeQLGitHub的Container registry包，或属于存储在存储库中的CodeQL包，则可以运行它们。 有关详细信息，请参阅“[使用 CodeQL 扫描代码](/zh/code-security/concepts/code-scanning/codeql/codeql-code-scanning#running-additional-queries)”。 可用于指定要运行的其他查询的选项有： * ``` 使用 `packs` 安装一个或多个 CodeQL 查询包 (beta) 并运行这些包的默认查询套件或查询。 ``` * `queries`，可指定单个 .ql 文件、包含多个 .ql 文件的目录、.qls 查询套件定义文件或任意组合 。 有关查询套件定义的详细信息，请参阅 [创建 CodeQL 查询套件](https://codeql.github.com/docs/codeql-cli/creating-codeql-query-suites/)。 可以在同一工作流中同时使用 `packs` 和 `queries`。 我们不建议直接引用 `github/codeql` 存储库中的查询套件，例如 `github/codeql/cpp/ql/src@main`。 此类查询必须重新编译，并且可能与当前处于活动状态CodeQL的版本GitHub Actions不兼容，这可能会导致分析期间出错。 ### 使用查询包 若要添加一个或多个CodeQL查询包，请在工作流的部分中添加`with: packs:``uses: github/codeql-action/init@v4`条目。 在 `packs` 中，可以指定要使用的一个或多个包，还可以指定要下载的版本。 在未指定版本的情况下，将下载最新版本。 如果要使用不可公开使用的包，则需要将 `GITHUB_TOKEN` 环境变量设置为有权访问包的机密。 有关详细信息，请参阅 [在工作流中使用 GITHUB\_TOKEN 进行身份验证](/zh/actions/tutorials/authenticate-with-github_token) 和 [在 GitHub Actions 中使用机密](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)。 > \[!NOTE] > 对于为多种语言生成 CodeQL 数据库的工作流，必须改为在配置文件中指定 CodeQL 查询包。 有关详细信息，请参阅下面的 [指定 CodeQL 查询包](#specifying-codeql-query-packs) 。 在下面的示例中，`scope` 是发布包的组织或个人帐户。 运行工作流时，从CodeQL下载四个GitHub查询包，并运行每个包的默认查询或查询套件。 * 下载最新版本的 `pack1` 并运行所有默认查询。 * 下载版本 1.2.3 的 `pack2` 并运行所有默认查询。 * 下载与版本 3.2.1 兼容的最新版本 `pack3`，并运行所有查询。 * 下载 4.5.6 版本的 `pack4`，并且仅运行在 `path/to/queries` 中找到的查询。 ```yaml copy - uses: github/codeql-action/init@v4 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 ``` > \[!NOTE] > 如果您指定使用查询包的特定版本，请注意，您指定的版本可能会逐渐变得过时，无法被默认用于CodeQL操作的CodeQL引擎高效使用。 为了确保最佳性能，如果需要指定确切的查询包版本，应考虑定期查看是否需要前移所固定的查询包版本。 > > 有关包兼容性的详细信息，请参阅 [CodeQL 查询包参考](/zh/code-security/reference/code-scanning/codeql/codeql-cli/codeql-query-packs#codeql-pack-compatibility)。 ### 正在从 CodeQL 下载 GitHub Enterprise Server 包 如果工作流使用在 GitHub Enterprise Server 安装上发布的包，你需要告诉工作流在哪里可以找到它们。 可以通过使用 `registries` 操作的 github/codeql-action/init\@v4 输入来实现这一点。 此输入接受 `url`、`packages` 和 `token` 属性的列表，如下所示。 ```yaml copy - uses: github/codeql-action/init@v4 with: registries: | # URL to the container registry, usually in this format - url: https://containers.GHEHOSTNAME1/v2/ # List of package glob patterns to be found at this registry packages: - my-company/* - my-company2/* # Token, which should be stored as a secret token: ${{ secrets.GHEHOSTNAME1_TOKEN }} # URL to the default container registry - url: https://ghcr.io/v2/ # Packages can also be a string packages: "*/*" token: ${{ secrets.GHCR_TOKEN }} ``` 注册表列表中的包模式按顺序进行检查，因此通常应将最具体的包模式放在最前面。 `token` 的值必须是通过 personal access token (classic) 权限从中下载的 GitHub 实例生成的 `read:packages`。 注意 `|` 属性名称之后的 `registries`。 这很重要，因为 GitHub Actions 输入只能接受字符串。 使用`|`将后续文本转换为字符串，该字符串稍后由github/codeql-action/init\@v4动作解析。 ### 在 QL 包中使用查询 若要添加一个或多个查询，请在工作流的 `with: queries:` 部分中添加一个 `uses: github/codeql-action/init@v4` 条目。 如果查询在专用存储库中，请使用 `external-repository-token` 参数来指定具有签出专用存储库访问权限的令牌。 还可以在 `queries` 的值中指定查询套件。 查询套件是查询的集合，通常按用途或语言进行分组。 ```yaml copy - uses: github/codeql-action/init@v4 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 }} ``` 以下查询套件内置于 CodeQL code scanning，可供使用。 | 查询套件 | 描述 | | :--------------------- | :--------------------------------------- | | `security-extended` | 来自默认套件的查询，以及严重性较低和精度较低的查询 | | `security-and-quality` | 来自 `security-extended` 的查询，以及可维护性和可靠性查询。 | 有关详细信息，请参阅“[CodeQL 查询套件](/zh/code-security/concepts/code-scanning/codeql/codeql-query-suites)”。 其中每个查询套件都包含该语言的内置 CodeQL 查询包中随附的不同查询子集。 查询套件是使用每个查询的元数据自动生成的。 有关详细信息，请参阅“[CodeQL 查询的元数据](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/)”。 指定查询套件时，CodeQL 分析引擎将运行默认查询集和其他查询套件中定义的任何其他查询。 ### 使用自定义配置文件 如果还使用配置文件进行自定义设置，则将使用工作流中指定的任意其他包或查询，而不是配置文件中指定的包或查询。 如何要运行一组额外的包或查询的组合，请在工作流中的 `packs` 或 `queries` 的值前面加上 `+` 符号。 有关详细信息，请参阅 [自定义配置文件](#custom-configuration-files)。 在下面的示例中，`+` 符号确保指定的附加包和查询与引用的配置文件中指定的任何包和查询一起使用。 ```yaml copy - uses: github/codeql-action/init@v4 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 ``` ## 自定义配置文件 自定义配置文件是指定要运行的其他包和查询的替代方法。 还可以使用该文件禁用默认查询，排除或包含特定查询，并指定在分析期间要扫描的目录。 在工作流文件中，使用 `config-file` 操作的 `init` 参数指定要使用的配置文件的路径。 此示例加载配置文件 *./.github/codeql/codeql-config.yml*。 ```yaml copy - uses: github/codeql-action/init@v4 with: config-file: ./.github/codeql/codeql-config.yml ``` 配置文件可以位于正在分析的存储库中，也可以位于外部存储库中。 使用外部存储库可以在一个位置为多个存储库指定配置选项。 引用位于外部存储库中的配置文件时，可以使用 OWNER/REPOSITORY/FILENAME\@BRANCH 语法。 例如， *octo-org/shared/codeql-config.yml\@main* 。 如果配置文件位于外部专用存储库中，请使用 `external-repository-token` 操作的 `init` 参数指定有权访问专用存储库的令牌。 ```yaml copy - uses: github/codeql-action/init@v4 with: external-repository-token: ${{ secrets.ACCESS_TOKEN }} ``` 配置文件中的设置以 YAML 格式编写。 ### 指定 CodeQL 查询包 在数组中定义 CodeQL 查询包。 请注意，格式与工作流文件使用的格式不同。 ```yaml copy 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 版本范围。 如果缺少该版本，则使用最新版本。 有关 semver 范围的详细信息，请参阅 [npm 上的 semver 文档](https://docs.npmjs.com/cli/v6/using-npm/semver#ranges)。 如果有生成多个 CodeQL 数据库的工作流，则可以指定任何 CodeQL 查询包，以使用嵌套包映射在自定义配置文件中运行。 ```yaml copy 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 ``` ### 使用威胁模型扩展 CodeQL 覆盖范围 > \[!NOTE] > 风险模型功能目前为 公开预览，可能随时更改。 在 公开预览 期间，风险模型仅支持 Java/Kotlin 和 C# 分析。 默认威胁模型包括不受信任的数据的远程源。 可以通过在自定义配置文件中指定CodeQL，扩展`threat-models: local`威胁模型以包含不受信任的数据的本地源（例如命令行参数、环境变量、文件系统和数据库）。 如果扩展威胁模型，还将使用默认的威胁模型。 ### 指定额外查询 在 `queries` 数组中指定其他查询。 数组的每个元素都包含一个 `uses` 参数，其值标识单个查询文件、包含查询文件的目录或查询套件定义文件。 ```yaml copy queries: - uses: ./my-basic-queries/example-query.ql - uses: ./my-advanced-queries - uses: ./query-suites/my-security-queries.qls ``` （可选）你可以给每个数组元素一个名称，如下面的示例配置文件所示。 有关其他查询的详细信息，请参阅上面的 [非默认查询](#non-default-queries) 。 ### 禁用默认查询 如果只想运行自定义查询，可以使用 `disable-default-queries: true` 禁用默认安全查询。 ### 从分析中排除特定查询 可以向自定义配置文件添加 `exclude` 和 `include` 筛选器，以指定要在分析中排除或包含的查询。 这在要排除诸如以下内容时非常有用： * 来自默认套件的特定查询（`security`、`security-extended` 和`security-and-quality`）。 * 对其结果不感兴趣的特定查询。 * 生成警告和建议的所有查询。 可以使用 `exclude` 筛选器（类似于以下配置文件中的筛选器）来排除要从默认分析中移除的查询。 在以下配置文件示例中，`js/redundant-assignment` 和 `js/useless-assignment-to-local` 查询都从分析中排除。 ```yaml copy query-filters: - exclude: id: js/redundant-assignment - exclude: id: js/useless-assignment-to-local ``` 若要查找查询的 ID，可以在选项卡中的警报列表中单击警报 ** Security and quality** 。这会打开警报详细信息页。 `Rule ID` 字段包含查询 ID。有关警报详细信息页的详细信息，请参阅 [代码扫描警报](/zh/code-security/concepts/code-scanning/code-scanning-alerts#about-alert-details)。 > \[!TIP] > > * 筛选器的顺序非常重要。 在有关查询和查询包的指令之后出现的第一个筛选器指令确定在默认情况下是包含还是排除查询。 > * 后续指令按顺序执行，在文件后面出现的指令优先于前面的指令。 可以在[示例配置文件](#example-configuration-files)部分中找到说明这些筛选器的使用的另一个示例。 有关在自定义配置文件中使用 `exclude` 和 `include` 筛选器的详细信息，请参阅 [创建 CodeQL 查询套件](/zh/code-security/tutorials/customize-code-scanning/create-query-suites#filtering-the-queries-in-a-query-suite)。 有关可以筛选的查询元数据的信息，请参阅 [CodeQL 查询的元数据](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/)。 ### 指定要扫描的目录 在不生成代码的情况下分析代码库时，可以通过向配置文件添加code scanning数组来限制`paths`到特定目录中的文件。 还可以通过添加 `paths-ignore` 数组来从分析中排除特定目录中的文件。 在解释语言（Python、Ruby 和 JavaScript/TypeScript）上运行 CodeQL 操作时，或者在分析已编译语言而不生成代码（当前受 C/C++、C#， Java和 Rust支持）时，可以使用此选项。 ```yaml copy paths: - src paths-ignore: - src/node_modules - '**/*.test.js' ``` > \[!NOTE] > > * 在`paths`配置文件的上下文中使用的`paths-ignore`和code scanning关键词，不应与在工作流`on..paths`中使用的相同关键词混淆。 当它们用于修改工作流中的 `on.` 时，它们确定当有人修改指定目录中的代码时是否会运行这些操作。 有关详细信息，请参阅“[GitHub Actions 的工作流语法](/zh/actions/reference/workflows-and-actions/workflow-syntax#onpushpull_requestpull_request_targetpathspaths-ignore)”。 > * 筛选模式字符 `?`、`+`、`[`、`]` 和 `!` 不受支持，将按字面意思进行匹配。 > * `**` 字符只能位于行首或行尾，或被斜线包围，并且不能混用 `**` 和其他字符。 例如，`foo/**`、`**/foo` 和 `foo/**/bar` 都是允许的语法，但 `**foo` 不是。 但是，可以将单星与其他字符一起使用，如示例中所示。 需要引用包含 `*` 字符的任何内容。 若要分析生成代码的位置，如果要限制 code scanning 为项目中的特定目录，则必须在工作流中指定适当的生成步骤。 需要用于从构建中排除目录的命令取决于你的构建系统。 有关详细信息，请参阅“[对编译语言进行 CodeQL 代码扫描](/zh/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/codeql-for-compiled-languages#specify-build-steps-manually)”。 修改特定目录中的代码时，可以快速分析单存储库的一小部分。 需要在构建步骤中排除目录，并在工作流中为 `paths-ignore` 使用 `paths` 和 `on.` 关键字。 ### 示例配置文件 当扫描代码时，此配置文件将 `security-and-quality` 查询套件添加到 CodeQL 运行的查询列表中。 有关可用的查询套件的详细信息，请参阅 [非默认查询](#non-default-queries)。 ```yaml name: "My CodeQL config" queries: - uses: security-and-quality ``` 以下配置文件禁用默认查询，并指定一组要运行的自定义查询。 它还配置 CodeQL 以扫描 src 目录（相对于根目录）中的文件，除了 src/node\_modules 目录和名称以 .test.js 结尾的文件 。 因此，src/node\_modules 中的文件和名称以 .test.js 结尾的文件被排除在分析之外 。 ```yaml name: "My CodeQL config" disable-default-queries: true queries: - name: Use an in-repository CodeQL pack (run queries in the my-queries directory) uses: ./my-queries - name: Use an external JavaScript CodeQL pack (run queries from an external repo) uses: octo-org/javascript-codeql-pack@main - name: Use an external query (run a single query from an external CodeQL pack) uses: octo-org/python-codeql-pack/show_ifs.ql@main - name: Use a query suite file (run queries from a query suite in this repo) uses: ./codeql-packs/complex-python-codeql-pack/rootAndBar.qls paths: - src paths-ignore: - src/node_modules - '**/*.test.js' ``` 以下配置文件仅运行生成严重性错误警报的查询。 该配置首先选择所有默认查询、`./my-queries` 中的所有查询以及 `codeql/java-queries` 中的默认套件，然后排除生成警告或建议的所有查询。 ```yaml queries: - name: Use an in-repository CodeQL query pack (run queries in the my-queries directory) uses: ./my-queries packs: - codeql/java-queries query-filters: - exclude: problem.severity: - warning - recommendation ``` ## 配置详细信息 如果希望在工作流文件中指定其他配置详细信息，可以使用 `config` 操作的 `init` 命令的 CodeQL 输入。 此输入的值必须是 YAML 字符串，该字符串遵循上述 [自定义配置文件](#custom-configuration-files) 中记录的配置文件格式。 ### 配置示例 工作流文件中的 GitHub Actions 此步骤使用 `config` 输入来禁用默认查询、添加 `security-extended` 查询套件和排除标记的 `cwe-020`查询。 ```yaml - uses: github/codeql-action/init@v4 with: languages: ${{ matrix.language }} config: | disable-default-queries: true threat-models: local queries: - uses: security-extended query-filters: - exclude: tags: /cwe-020/ ``` 可以使用同一方法在工作流文件中指定任何有效的配置选项。 > \[!TIP] > 可以使用变量在多个存储库 GitHub Actions 之间共享一个配置。 此方法的一个好处是，无需编辑工作流文件即可在单个位置更新配置。 > > 在下面的示例中， `vars.CODEQL_CONF` 是一个 GitHub Actions 变量。 其值可以是任何有效配置文件的内容。 有关详细信息，请参阅“[在变量中存储信息](/zh/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables#defining-configuration-variables-for-multiple-workflows)”。 > > ```yaml > - uses: github/codeql-action/init@v4 > with: > languages: ${{ matrix.language }} > config: ${{ vars.CODEQL_CONF }} > ``` ## 已编译的语言 对于已编译的语言，可以决定操作 CodeQL 如何创建 CodeQL 数据库进行分析。 有关可用生成选项的信息，请参阅“[对编译语言进行 CodeQL 代码扫描](/zh/code-security/how-tos/find-and-fix-code-vulnerabilities/manage-your-configuration/codeql-for-compiled-languages)”。 ## 数据上传 GitHub 可以显示由第三方工具外部生成的代码分析数据。 可以使用 `upload-sarif` 操作上传代码分析数据。 有关详细信息，请参阅“[将 SARIF 文件上传到 GitHub](/zh/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/upload-sarif-file)”。