配置代码扫描

关于 代码扫描 配置

您可以使用 GitHub Actions 在 GitHub Enterprise Server 中运行 代码扫描，或使用 CodeQL runner 从持续集成 (CI) 系统运行它。 有关 GitHub Actions 的更多信息，请参阅“关于 GitHub Actions”。 有关 CodeQL runner 的更多信息，请参阅“在 CI 系统中运行 代码扫描”。

本文说明在 GitHub Enterprise Server 上运行 代码扫描。

在为仓库配置 代码扫描 之前，必须将 GitHub Actions 工作流程添加到仓库中以设置 代码扫描。 更多信息请参阅“为仓库设置 代码扫描”。

一般情况下无需编辑 代码扫描 的默认工作流程。 但是，如果需要，您可以编辑工作流程以自定义某些设置。 例如，您可以编辑 GitHub 的 CodeQL 分析工作流程 来指定扫描频率、要扫描的语言或目录，以及 CodeQL 代码扫描 在代码中的查找内容。 如果您使用一组特定的命令来编译代码，您可能还需要编辑 CodeQL 分析工作流程。

您可以为 代码扫描 编写配置文件。 GitHub.com 上的 GitHub Marketplace 包含您可以使用的其他 代码扫描 工作流程。 此文章中提供的具体示例与 CodeQL 分析工作流程 文件有关。

Editing a code scanning workflow

GitHub 将工作流程文件保存在仓库的 .github/workflows 目录中。 您可以通过搜索其文件名来查找已添加的工作流程。 例如，默认情况下，CodeQL 代码扫描 的工作流程文件被称为 codeql-analysis.yml。

1. 在仓库中，浏览至要编辑的工作流程文件。
2. 要打开工作流程编辑器，在文件视图右上角单击 。
3. 编辑文件后，单击 Start commit（开始提交）并完成“Commit changes（提交更改）”表单。 您可以选择直接提交到当前分支，或者创建一个新分支并启动拉取请求。

有关编辑工作流程文件的更多信息，请参阅“了解 GitHub Actions”。

配置频率

您可以按时间表或在仓库中发生特定事件时扫描代码。

每当推送到仓库以及每次创建拉取请求时，时扫描代码可防止开发者在代码中引入新的漏洞和错误。 按时间表扫描可了解 GitHub、安全研究者和社区发现的最新漏洞和错误，即使开发者并未主动维护仓库。

按推送扫描

如果使用默认工作流程，则除了事件触发的扫描之外，代码扫描 还会每周扫描一次仓库代码。 要调整此时间表，请编辑工作流程中的 cron 值。 更多信息请参阅“GitHub Actions 的工作流程语法”。

扫描拉取请求

默认 CodeQL 分析工作流程 使用 pull_request 事件在针对默认分支的拉取请求上触发代码扫描。 如果从私有复刻打开拉取请求，pull_request 事件不会触发。

有关 pull_request 事件的更多信息，请参阅“GitHub Actions 的工作流程语法”。

避免对拉取请求进行不必要的扫描

您可能希望避免针对默认分支的特定拉取请求触发代码扫描，而不管更改了哪些文件。 可以通过在 代码扫描 工作流程中指定 on:pull_request:paths-ignore or on:pull_request:paths 来进行配置。 例如，如果拉取请求中唯一的更改是文件扩展名为 .md 或 .txt 的文件，则您可以使用以下 paths-ignore 数组。

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
    paths-ignore:
      - '**/*.md'
      - '**/*.txt'

有关使用 on:pull_request:paths-ignore 和 on:pull_request:paths 确定工作流程何时对拉取请求运行的详细信息，请参阅“GitHub Actions 的工作流程语法”。

按时间表扫描

默认 代码扫描 工作流程在拉取请求的 HEAD 提交时使用 pull_request 事件触发代码扫描。 要调整此时间表，请编辑工作流程中的 cron 值。 更多信息请参阅“GitHub Actions 的工作流程语法”。

示例

GitHub saves workflow files in the .github/workflows directory of your repository. You can find the workflow by searching for its file name. For example, the default workflow file for CodeQL code scanning is called codeql-analysis.yml.

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '40 7 * * 2'

此工作流程扫描：

• 对默认分支和受保护分支的每次推送
• 对默认分支的每个拉取请求
• 默认分支（每个星期二 7:40 UTC）

指定操作系统

如果您的代码需要使用特定的操作系统进行编译，您可以在工作流程中配置它。 编辑 jobs.analyze.runs-on 的值以指定运行 代码扫描 操作的机器操作系统。 在 self-hosted 之后，使用适当的标签作为双元素数组中的第二个元素来指定操作系统。

jobs:
  analyze:
    name: Analyze
    runs-on: [self-hosted, ubuntu-latest]

代码扫描 支持 macOS、Ubuntu 和 Windows 的最新版本。 因此，此设置的典型值为：ubuntu-latest、windows-latest 和 macos-latest。 更多信息请参阅“GitHub Actions 的工作流程语法”和和“将标签与自托管运行器一起使用”。

您必须确保 Git 位于自托管运行器上的 PATH 变量中。

更改分析的语言

CodeQL 代码扫描 会自动检测用受支持的语言编写的代码。

• C/C++
• C#
• Go
• Java
• JavaScript/TypeScript
• Python

默认 CodeQL 分析工作流程 文件包含一个名为 language 的构建矩阵，其中列出了仓库中被分析的语言。 将 代码扫描 添加到仓库时，CodeQL 会自动填充此矩阵。 使用 language 矩阵优化 CodeQL 以并行运行每个分析。 由于并行构建的性能优势，我们建议所有工作流程都采用此配置。 有关构建矩阵的更多信息，请参阅“管理复杂的工作流程”。

如果仓库中包含多种支持的语言的代码，您可以选择要分析的语言。 在有些情况下您可能需要阻止分析某种语言。 例如，项目中可能存在与代码主体语言不同的依赖项，并且您可能不希望看到关于这些依赖项的警报。

如果您的工作流程使用 language 矩阵，则 CodeQL 会被硬编码为仅分析矩阵中的语言。 如需更改要分析的语言，请编辑矩阵变量的值。 您可以删除某种语言以防止被分析，也可以添加在设置 代码扫描 时仓库中不存在的语言。 例如，如果在设置 代码扫描 时，仓库最初只包含 JavaScript，但您后来添加了 Python 代码，则需要将 python 添加到矩阵中。

jobs:
  analyze:
    name: Analyze
    ...
    strategy:
      fail-fast: false
      matrix:
        language: ['javascript', 'python']

如果工作流程中不包含名为 language 的矩阵，则 CodeQL 将被配置为按顺序运行分析。 如果您未在工作流程中指定语言，则 CodeQL 将自动检测并尝试分析仓库中所有受支持的语言。 如果不愿意使用矩阵选择要分析的语言，您可以使用 init 操作下的 languages 参数。

- uses: github/codeql-action/init@v1
  with:
    languages: cpp, csharp, python

运行额外查询

使用 CodeQL 扫描代码时，CodeQL 分析引擎将从代码生成数据库并对其运行查询。 CodeQL 分析使用默认的查询集，但除了默认查询外，您还可以指定更多的查询来运行。

Any additional queries you want to run must belong to a QL pack in a repository. For more information, see "About 代码扫描."

您可以指定一个 .ql 文件（一个目录中包含多个 .ql 文件）、一个 .qls 查询套件定义文件或任意组合。 有关查询套件定义的更多信息，请参阅“创建 CodeQL 查询套件”。

要添加一个或多个查询套件，请在配置文件中添加 queries 部分。 如果查询在私有仓库中，请使用 external-repository-token 参数来指定可以访问私有仓库的令牌。

- uses: github/codeql-action/init@v1
  with:
    queries: COMMA-SEPARATED LIST OF PATHS
    # Optional. 提供令牌来访问私有仓库.
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

您也可以在配置文件中指定额外查询套件以运行它们。 查询套件是查询的集合，通常按目的或语言分组。

以下查询套件内置于 CodeQL 代码扫描，可供使用。

查询套件	描述
security-extended	严重性和精度低于默认查询的查询
security-and-quality	来自 security-extended 的查询，加上可维护性和可靠性查询

在指定查询套件时，CodeQL 分析引擎将运行套件中包含的查询，以及默认查询集。

如果还使用配置文件进行自定义设置，则将使用工作流程中指定的任何额外查询，而不是配置文件中指定的任何查询。 如果您要运行此处指定的额外查询与配置文件中指定的查询的组合，请在工作流程中的 queries 值之前加上前缀 + 符号。 有关配置文件的示例，请参阅“配置文件示例”。

在下面的示例中，+ 符号可确保结合使用额外查询与所引用配置文件中指定的任何查询。

- uses: github/codeql-action/init@v1
  with:
    config-file: ./.github/codeql/codeql-config.yml
    queries: +security-and-quality,octo-org/python-qlpack/show_ifs.ql@main
    external-repository-token: ${{ secrets.ACCESS_TOKEN }}

使用第三方代码扫描工具

除了在工作流程文件中指定要运行的查询之外，您还可以在单独的配置文件中执行此操作。 您还可以使用配置文件禁用默认查询，并指定分析过程中要扫描的目录。

在工作流程文件中，使用 init 操作的 config-file 参数指定要使用的配置文件的路径。 此示例加载配置文件 ./.github/codeql/codeql-config.yml。

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

配置文件可以放在您分析的仓库内或外部仓库中。 使用外部仓库允许您在一个位置指定多个仓库的配置选项。 引用位于外部仓库中的配置文件时，您可以使用 OWNER/REPOSITORY/FILENAME@BRANCH 语法。 例如 octo-org/shared/codeql-config.yml@main。

如果配置文件位于外部私有仓库中，请使用 init 操作的 external-repository-token 参数来指定可以访问私有仓库的令牌。

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

配置文件中的设置以 YAML 格式编写。

指定额外查询

您可以在 queries 数组中指定额外查询。 数组的每个元素都包含一个 uses 参数，该参数的值标识单个查询文件、包含查询文件的目录或查询套件定义文件。

queries:
  - uses: ./my-basic-queries/example-query.ql
  - uses: ./my-advanced-queries
  - uses: ./codeql-qlpacks/complex-python-qlpack/rootAndBar.qls

（可选）您可以给每个数组元素一个名称，如下面的示例配置文件所示。

有关额外查询的更多信息，请参阅上面的“运行额外查询”。

禁用默认查询

如果只想运行自定义查询，您可以通过在配置文件中添加 disable-default-queries: true 来禁用默认安全查询。

指定要扫描的目录

对于 CodeQL 支持的解释语言（Python 和 JavaScript/TypeScript），您可以通过在配置文件中添加 paths 数组将 代码扫描 限制到特定目录中的文件。 添加 paths-ignore 数组可从分析排除特定目录中的文件。

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

对于编译的语言，如果要将 代码扫描 限制到项目中的特定目录，您必须在工作流程中指定适当的构建步骤。 用于在构建过程中排除目录的命令将取决于您的构建系统。 更多信息请参阅“为编译语言配置 CodeQL 工作流程”。

在修改特定目录中的代码时，您可以快速分析单个仓库中的小部分。 您需要在构建步骤中排除目录并在工作流程文件中对 on.<push|pull_request> 使用 paths-ignore 和 paths 关键字。

配置文件示例

当您扫描代码时，此配置文件将 security-and-quality 查询套件添加到 CodeQL 运行的查询列表。 有关可供使用的查询套件的更多信息，请参阅“运行其他查询”。

name: "My CodeQL config"

queries:
  - uses: security-and-quality

以下配置文件禁用默认查询，并指定一组要运行的自定义查询。 它还配置 CodeQL 扫描 src 目录中的文件（相对于根目录），并且排除 src/node_modules 目录以及名称以 .test.js 结尾的任何文件。 因此，src/node_modules 中的文件以及名称以 .test.js 结尾的文件被排除在分析之外。

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'

为编译语言配置 代码扫描

对于受支持的编译语言，您可以使用 CodeQL 分析工作流程 中的 autobuild 操作来构建代码。 这样您无需为 C/C++、C# 和 Java 指定显式构建命令。 CodeQL 也运行 Go 项目的构建来设置项目。 但是，与其他编译语言相比，仓库中的所有 Go 文件都是提取的，而不仅仅是构建的文件。 您可以使用自定义构建命令跳过提取未受构建影响的 Go 文件。

如果仓库中的 C/C++、C# 或 Java 代码含有非标准的构建过程，autobuild 可能会失败。 您需要从工作流程中删除 autobuild 步骤，然后手动添加构建步骤。 如果您要指定仓库中的哪个 Go 文件要提取，则需要添加生成步骤。 有关如何为编译语言配置 CodeQL 代码扫描 的更多信息，请参阅“为编译语言配置 CodeQL 工作流程”。

将 代码扫描 数据上传到 GitHub

GitHub 可显示通过第三方工具在外部生成的代码分析数据。 通过在工作流程中添加 upload-sarif 操作，您可以在 GitHub 中显示第三方工具的代码分析。 更多信息请参阅“将 SARIF 文件上传到 GitHub”。