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

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

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

代码扫描 适用于所有公共仓库以及组织拥有的启用了 GitHub Advanced Security 的所有私有仓库。 更多信息请参阅“关于 GitHub Advanced Security”。

本文内容

注意:CodeQL runner 目前处于测试阶段,可能会更改。

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

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

关于 CodeQL runner

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

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

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

注意:

  • CodeQL runner 使用 CodeQL CLI 来分析代码,因此具有相同的许可条件。 它可自由用于 GitHub.com 上维护的公共仓库,并且可用于具有 Advanced Security 许可证的客户所拥有的私有仓库。 有关信息请参阅“GitHub CodeQL 条款和条件”和“CodeQL CLI”。

  • 请勿将 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 使用的个人访问令牌。 您必须使用具有 security_events 作用域的访问令牌,或者具有 security_events 写入权限的 GitHub 应用程序。 更多信息请参阅“构建 GitHub 应用程序”和“创建个人访问令牌”。
  • 访问与此 CodeQL runner 发行版相关联的 CodeQL 包。 此包包含 CodeQL 分析所需的查询和库,以及供运行器内部使用的 CodeQL CLI。 更多信息请参阅“CodeQL CLI”。

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

  1. 允许 CI 服务器访问 GitHub.com,以便 CodeQL runner 可以自动下载包。
  2. 手动下载/提取包,将其与其他中心资源一起存储,然后使用 --codeql-path 标志指定包在调用中的位置以初始化 。 CodeQL runner.

调用 CodeQL runner

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

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

对于这两个命令,都必须指定 GitHub 的 URL、仓库所有者/名称以及 GitHub 应用程序或用于身份验证的个人访问令牌。 您还需要指定 CodeQL 包的位置,除非 CI 服务器有权直接从 GitHub.com 上的 github/codeql-action 仓库下载它。

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

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

基本示例

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

  1. 检出要分析的仓库。

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

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

    $ /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo
        --github-url https://github.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 runner 数据库、进行分析并将结果上传到 GitHub。

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

服务器有权直接从 GitHub.com 上的 github/codeql-action 仓库下载 CodeQL 包,因此无需使用 --codeql-path 标志。 分析完成后, CodeQL runner 会将结果上传到 代码扫描 视图。 更多信息请参阅“管理仓库的 代码扫描 警报”。

编译语言示例

此示例与前面的示例相似,但此例中的仓库含有用 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.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. 构建代码。

  6. 填充 CodeQL 数据库、进行分析并将结果上传到 GitHub。

    $ /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo-2
        --github-url https://github.com --github-auth TOKEN
        --commit ae7b655ef30b50fb726ae7b3daa79571a39d194d --ref refs/heads/main
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo-2/code-scanning/sarifs - 202 in 573ms
    > Successfully uploaded results

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

延伸阅读

此文档对您有帮助吗?

Privacy policy

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

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

做出贡献

或, 了解如何参与。