在 CI 系统中运行 CodeQL 运行器

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

代码扫描 可用作 GitHub Advanced Security 的一部分,在测试期间免费使用。 更多信息请参阅“关于 GitHub Advanced Security”。

注意:代码扫描 目前处于测试阶段,可能会更改。

关于 CodeQL runner

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

您也可以使用 GitHub Actions 在 GitHub AE 中运行 代码扫描。 相关信息请参阅“为仓库设置 代码扫描”。

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

注:

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

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

下载 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

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://HOSTNAME/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://HOSTNAME/github/codeql-action so that the CodeQL runner 可以自动下载捆绑包。
  2. 手动下载/提取捆绑包,将其与其他中央资源一起存储,并使用 --codeql-path 标记指定捆绑包在调用中的位置,以初始化 CodeQL runner。

调用 CodeQL runner

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

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

对于这两个命令,都必须指定 GitHub AE 的 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 上传支持每次上传最多 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。

    $ 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 AE。 结果将出现在仓库的 Security(安全性)选项卡中。

    $ 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. 要将 代码扫描 结果上传为拉取请求检查,请使用 --ref 指定拉取请求 标志. 我们建议设置 CodeQL runner,以便它在发生 pull_request web 挂钩事件时运行。

    $ 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

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

编译语言示例

此示例与前面的示例相似,但此例中的仓库含有用 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 AE。 结果将出现在仓库的 Security(安全性)选项卡中。

    $ 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. 要将 代码扫描 结果上传为拉取请求检查,请使用 --ref 指定拉取请求 标志. 我们建议设置 CodeQL runner,以便它在发生 pull_request web 挂钩事件时运行。

    $ 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

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

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

延伸阅读

此文档对您有帮助吗?隐私政策

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

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

做出贡献

或, 了解如何参与。