我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

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

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

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

本文内容

注: 代码扫描 正在测试用于 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 so that the 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 系统中配置 代码扫描”。

注: SAIF 上传支持每次上传最多 1000 个结果。 超过此限制的任何结果均被忽略。 如果工具产生太多结果,则应更新配置,以专注于最重要的规则或查询的结果。

基本示例

此示例在 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。

延伸阅读

此文档对您有帮助吗?

Privacy policy

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。