Skip to main content

在 CI 系统中运行 CodeQL 运行器

您可以使用 CodeQL runner 在第三方持续集成系统中执行 CodeQL code scanning。

Code scanning is available for organization-owned repositories in GitHub Enterprise Server. This feature requires a license for GitHub Advanced Security. 有关详细信息,请参阅“关于 GitHub Advanced Security”。

注意:CodeQL runner 将被弃用。 对于 GitHub Enterprise Server 3.0及更高版本,可以安装 CodeQL CLI 版本 2.6.3 来替换 CodeQL runner。

有关详细信息,请参阅 CodeQL 运行器弃用。 有关迁移到 CodeQL CLI 的信息,请参阅从 CodeQL 运行器迁移到 CodeQL CLI

注意:站点管理员必须为 your GitHub Enterprise Server instance 启用 code scanning,你才能使用这些功能。 有关详细信息,请参阅“为设备配置 code scanning”。

关于 CodeQL runner

CodeQL runner 是可以用来在第三方持续集成 (CI) 系统中处理的代码上运行 code scanning 的工具。 Code scanning 是一项功能,可用于分析 GitHub 仓库中的代码,以查找安全漏洞和编码错误。 分析发现的任何问题都显示在 GitHub Enterprise Server 中。 有关信息,请参阅“关于使用 CodeQL 进行 code scanning”。

在许多情况下,在 CI 系统中直接使用 CodeQL CLI 设置 CodeQL code scanning 更简单。

您也可以使用 GitHub Actions 在 GitHub Enterprise Server 中运行 code scanning。 有关信息,请参阅“为存储库设置 code scanning”。

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

注意:

  • CodeQL runner 可用于拥有 Advanced Security 许可证的客户。

下载 CodeQL runner

可以从 https://HOSTNAME/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

在 Windows 中,codeql-runner-win.exe 文件通常无需更改权限。

将 CodeQL runner 添加到 CI 系统

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

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

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

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

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

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

调用 CodeQL runner

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

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

对于这两个命令,都必须指定 GitHub Enterprise Server 的 URL、存储库 OWNER/NAME 以及 GitHub Apps 或用于身份验证的个人访问令牌。 还需要指定 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 系统中配置 code scanning”。

注意:

  • SARIF 上传最多支持每次上传 5000 个结果。 任何超过此限制的结果都将被忽略。 如果工具生成太多结果,则应更新配置,以将重点放在最重要的规则或查询的结果上。

  • 对于每次上传,SARIF 上传支持最大大小为 10 MB 的 gzip 压缩 SARIF 文件。 任何超过此限制的上传都将被拒绝。 如果 SARIF 文件由于包含太多结果而过大,则应更新配置,以将重点放在最重要的规则或查询的结果上。

基本示例

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

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth-stdin
    > 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。 结果将显示在存储库的“安全”选项卡中。

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth-stdin
        --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. 要将 code scanning 结果作为拉取请求检查上传,请使用 --ref 标志指定拉取请求。 我们建议设置 CodeQL runner 以便它在 pull_request Webhook 事件上运行。

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth-stdin
        --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

有关查看 code scanning 警报的详细信息,请参阅“在拉取请求中会审代码扫描警报”和“管理存储库的代码扫描警报”。

编译语言示例

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

  1. 检出要分析的仓库。

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

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

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux init --repository octo-org/example-repo-2
        --github-url https://github.example.com --github-auth-stdin
    > 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 runner 进行故障排除”。

  6. 填充 CodeQL 数据库、进行分析并将结果上传到 GitHub Enterprise Server。 结果将显示在存储库的“安全”选项卡中。

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth-stdin
        --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. 要将 code scanning 结果作为拉取请求检查上传,请使用 --ref 标志指定拉取请求。 我们建议设置 CodeQL runner 以便它在 pull_request Webhook 事件上运行。

    $ echo "$TOKEN" | /path/to-runner/codeql-runner-linux analyze --repository octo-org/example-repo
        --github-url https://github.example.com --github-auth-stdin
        --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

有关查看 code scanning 警报的详细信息,请参阅“在拉取请求中会审代码扫描警报”和“管理存储库的代码扫描警报”。

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

延伸阅读