此版本的 GitHub Enterprise 已停止服务 2021-09-23. 即使针对重大安全问题,也不会发布补丁。 要获得更好的性能、改进的安全性和新功能,请升级到 GitHub Enterprise 的最新版本。 如需升级方面的帮助,请联系 GitHub Enterprise 支持

在 CI 系统中运行 CodeQL 代码扫描

您可以使用 CodeQL runner 在第三方持续集成系统中执行 CodeQL 代码扫描。

代码扫描 在您拥有 GitHub Advanced Security 的许可证时可用。

Note: The CodeQL runner is being deprecated. Please use the CodeQL CLI version 2.6.2 or greater instead. GitHub Enterprise Server 3.3 will be the final release series that supports the CodeQL runner. On GitHub Enterprise Cloud, the CodeQL runner will be supported until March 2022. For more information, see the CodeQL runner deprecation.

注: 代码扫描 正在测试用于 GitHub Enterprise Server 2.22。 对于代码扫描的一般可用版本,请升级到最新版本的 GitHub Enterprise Server。

注:站点管理员必须为 您的 GitHub Enterprise Server 实例 启用 代码扫描,然后您才可使用此功能。 更多信息请参阅“为设备配置 代码扫描”。

将 CodeQL 代码扫描 与现有的 CI 系统一起使用

如果您使用 GitHub Actions 以外的持续集成或持续交付/部署 (CI/CD) 系统,您可以使用现有系统运行 GitHub 的 CodeQL,并将结果上传到 GitHub。 为此,请使用 CodeQL runner。

关于 CodeQL runner

代码扫描 是一项功能,可用于分析 GitHub 仓库中的代码,以查找安全漏洞和编码错误。 分析发现的任何问题都显示在 GitHub Enterprise Server 中。 更多信息请参阅“关于 代码扫描”。

您可以使用 CodeQL runner 在第三方持续集成 (CI) 系统中处理的代码上运行 代码扫描。 您也可以使用 GitHub Actions 在 GitHub Enterprise Server 上运行 代码扫描。 相关信息请参阅“为仓库设置 代码扫描”。

CodeQL runner 是在 GitHub 仓库的检出上运行 CodeQL 分析的命令行工具。 您可以将运行器添加到第三方系统,然后调用运行器以分析代码并将结果上传到 GitHub Enterprise Server。 这些结果在仓库中显示为 代码扫描 警报。

注意:

  • CodeQL runner 可用于拥有 Advanced Security 许可证的客户。
  • 请勿将 CodeQL runner 与 CodeQL CLI 混淆。 CodeQL CLI 是一个交互式命令行接口,允许您创建用于安全研究的 CodeQL 数据库并运行 CodeQL 查询。 更多信息请参阅“CodeQL CLI”。

下载 CodeQL runner

您可以从 https://github.com/github/codeql-action/releases 下载 CodeQL runner。 在某些操作系统上,您可能需要更改下载文件的权限才能运行它。

在 Linux 上:

chmod +x codeql-runner-linux

在 macOS 中:

chmod +x codeql-runner-macos
sudo xattr -d com.apple.quarantine codeql-runner-macos

You should call the CodeQL runner from the checkout location of the repository you want to analyze. The two main commands are:

将 CodeQL runner 添加到 CI 系统

下载 CodeQL runner 并确认它可执行后,应将运行器提供给您打算用于 代码扫描 的每个 CI 服务器。 例如,您可以配置每台服务器从中央内部位置复制运行器。 或者,您也可以使用 REST API 直接从 GitHub 获取运行器,例如:

wget https://github.com/github/codeql-action/releases/latest/download/codeql-runner-linux
chmod +x codeql-runner-linux

除此之外,每个 CI 服务器还需要:

  • GitHub 应用程序 或供 CodeQL runner 使用的个人访问令牌。 您必须使用范围为 repo 的访问令牌,或者具有 security_events 写入权限以及 metadatacontents 读取权限的 GitHub 应用程序。 更多信息请参阅“构建 GitHub 应用程序”和“创建个人访问令牌”。
  • 访问与此 CodeQL runner 发行版相关联的 CodeQL 包。 此包包含 CodeQL 分析所需的查询和库,以及供运行器内部使用的 CodeQL CLI。 更多信息请参阅“CodeQL CLI”。

提供 CodeQL 包访问权限的选项:

  1. 允许 CI 服务器访问 https://github.com/github/codeql-action,以便 CodeQL runner 可以自动下载包。
  2. 在 GitHub Enterprise Server 上镜像 github/codeql-action 仓库。 除非您指定 --codeql-path 标志,否则运行器将在此位置和 GitHub.com上自动检查包。
  3. 手动下载/提取捆绑包,将其与其他中央资源一起存储,并使用 --codeql-path 标记指定捆绑包在调用中的位置,以初始化 CodeQL runner。

调用 CodeQL runner

您应该从要分析的仓库的检出位置调用 CodeQL runner。 两个主要命令是:

  1. init 需要初始化运行器并为需要分析的每种语言创建一个 CodeQL 数据库。 这些数据库由后续命令填充和分析。
  2. analyze 需要填充 CodeQL 数据库、进行分析并将结果上传到 GitHub Enterprise Server。

对于这两个命令,都必须指定 GitHub Enterprise Server 的 URL、仓库 OWNER/NAME以及 GitHub 应用程序 或用于身份验证的个人访问令牌。 您还需要指定 CodeQL 捆绑包的位置,除非 CI 服务器能够直接从 github/codeql-action 仓库下载它。

您可以配置 CodeQL runner 存储 CodeQL 包的位置以便将来在服务器上进行分析,使用: --tools-dir 标志;并配置在分析过程中存储临时文件的位置,使用: --temp-dir.

要查看运行器的命令行引用,请使用 -h 标志。 例如,要列出所有运行的命令:codeql-runner-OS -h,或列出所有可用于 init 命令运行的标志:codeql-runner-OS init -h(其中 OS 因使用的可执行文件而异)。 更多信息请参阅“在 CI 系统中配置 代码扫描”。

注意:

  • SARIF upload supports a maximum of 1000 results per upload. 超过此限制的任何结果均被忽略。 如果工具产生太多结果,则应更新配置,以专注于最重要的规则或查询的结果。

  • For each upload, SARIF upload supports a maximum size of 10 MB for the gzip-compressed SARIF file. Any uploads over this limit will be rejected. If your SARIF file is too large because it contains too many results, you should update the configuration to focus on results for the most important rules or queries.

基本示例

此示例在 Linux CI 服务器上对托管在 https://github.example.com 上的 octo-org/example-repo 仓库运行 CodeQL 分析。 这个过程非常简单,因为仓库只包含可通过 CodeQL 直接分析的语言,而无需构建(例如 Go、JavaScript、Python 和 TypeScript)。

在此示例中,服务器可以直接从 github/codeql-action 仓库下载 CodeQL 捆绑包,因此无需使用 --codeql-path 标记。

  1. 检出要分析的仓库。

  2. 移至检出仓库的目录。

  3. 初始化 CodeQL runner 并为检测到的语言创建 CodeQL。

    $ /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth TOKEN
    > Cleaning temp directory /srv/checkout/example-repo/codeql-runner
    > ...
    > Created CodeQL database at /srv/checkout/example-repo/codeql-runner/codeql_databases/javascript.
  4. 填充 CodeQL 数据库、进行分析并将结果上传到 GitHub Enterprise Server。 结果将出现在仓库的 Security(安全性)选项卡中。

    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth TOKEN
        --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/my-branch
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results
  5. 要将 代码扫描 结果上传为拉取请求检查,请使用 --ref 指定拉取请求 标志. 我们建议设置 CodeQL runner,以便它在发生 pull_request web 挂钩事件时运行。

    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth TOKEN
        --commit 1dc7a1346e5ce7b86835b68bbda3078b37d6abbe --ref refs/pull/123/merge
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results

有关查看 代码扫描 警报的更多信息,请参阅“对拉取请求中的代码扫描警报分类”和“管理仓库的代码扫描警报”。

编译语言示例

此示例与前面的示例相似,但此例中的仓库含有用 C/C++、C# 或 Java 编写的代码。 要为这些语言创建 CodeQL 数据库,CLI 需要监控构建。 在初始化过程结束时,运行器会报告您需要在构建代码之前设置环境的命令。 您需要在调用正常的 CI 构建进程之前运行此命令,然后运行 analyze 命令。

  1. 检出要分析的仓库。

  2. 移至检出仓库的目录。

  3. 初始化 CodeQL runner 并为检测到的语言创建 CodeQL。

    $ /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo-2
        --github-url https://github.example.com --github-auth TOKEN
    > Cleaning temp directory /srv/checkout/example-repo-2/codeql-runner
    > ...
    > CodeQL environment output to "/srv/checkout/example-repo-2/codeql-runner/codeql-env.json"
      and "/srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
      Please export these variables to future processes so that CodeQL can monitor the build, for example by running 
      ". /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
  4. 获取通过 init 操作生成的脚本,以设置监控构建的环境。 请注意以下代码片段中的先导点和空间。

    $ . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh
  5. 构建代码。 在 macOS 上,您需要使用环境变量 $CODEQL_RUNNER 构建命令前缀。 更多信息请参阅“CI 系统中 CodeQL 代码扫描故障排除”。

  6. 填充 CodeQL 数据库、进行分析并将结果上传到 GitHub Enterprise Server。 结果将出现在仓库的 Security(安全性)选项卡中。

    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth TOKEN
        --commit 5b6a3078b31dc346e5ce7b86837d6abbe7a18bbd --ref refs/heads/my-branch
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results
  7. 要将 代码扫描 结果上传为拉取请求检查,请使用 --ref 指定拉取请求 标志. 我们建议设置 CodeQL runner,以便它在发生 pull_request web 挂钩事件时运行。

    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth TOKEN
        --commit 1dc7a1346e5ce7b86835b68bbda3078b37d6abbe --ref refs/pull/123/merge
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results

有关查看 代码扫描 警报的更多信息,请参阅“对拉取请求中的代码扫描警报分类”和“管理仓库的代码扫描警报”。

注:如果使用容器化构建,您需要在进行构建任务的容器中运行 CodeQL runner。

延伸阅读