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

Running CodeQL code scanning in your CI system

You can use the CodeQL runner to perform CodeQL 代码扫描 in a third-party continuous integration system.

代码扫描 可用于您有 Advanced Security 许可的组织拥有的私有仓库。

本文内容

注意:代码扫描 目前处于测试阶段,可能会更改。 有关参加公测的更多信息,请在此注册

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

Using CodeQL 代码扫描 with your existing CI system

If you use a continuous integration or continuous delivery/deployment (CI/CD) system other than GitHub Actions, you can use your existing system to run GitHub's CodeQL analysis and upload the results to GitHub. To do this, use the CodeQL runner.

关于 CodeQL runner

代码扫描 是一项功能,可用于分析 GitHub 仓库中的代码,以查找安全漏洞和编码错误。 Any problems identified by the analysis are shown in GitHub Enterprise Server. 更多信息请参阅“关于 代码扫描”。

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

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

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

下载 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 服务器。 It is important to notice that each CI server that you intend to use for 代码扫描 needs to have the CodeQL runner. You might configure each server to copy the runner from a central, internal location, or you could use the REST API to get the runner direct from GitHub, for example:

$ /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 the build can be traced, for example by running "
      . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".

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

  • GitHub 应用程序 或供 CodeQL runner 使用的个人访问令牌。 对于私有仓库,令牌必须具有 repo 作用域。 对于公共仓库,令牌只需要 public_reporepo:security_events 作用域。 更多信息请参阅“构建 GitHub 应用程序”和“创建个人访问令牌”。
  • 访问与此 CodeQL runner 发行版相关联的 CodeQL 包。 此包包含 CodeQL 分析所需的 CodeQL CLI、查询和库。 更多信息请参阅“CodeQL CLI”。

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

  1. 允许 CI 服务器访问 GitHub.com,以便 CodeQL runner 可以自动下载包。

  2. Manually download/extract the bundle, store it with other central resources, and use the --codeql-path flag to specify the location of the bundle in calls to initialize the CodeQL runner.

  3. 您可以在 your GitHub Enterprise Server instance 上镜像 github/codeql-action 仓库。 除非您指定 --codeql-path 标志,否则运行器将在此位置和 GitHub.com上自动检查包。

调用 CodeQL runner

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

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

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

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

要查看运行器的命令行引用,请使用 -h 标志。 例如,要列出所有运行的命令:codeql-runner-OS -h,或列出所有可用于 init 命令运行的标志:codeql-runner-OS init -h(其中 OS 因使用的可执行文件而异)。 For more information, see "Configuring 代码扫描 in your CI system."

基本示例

此示例在 Linux CI 服务器上对托管在 https://github.example.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.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 runner 数据库、进行分析并将结果上传到 GitHub Enterprise Server。

    $ /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/main
    > Finalizing database creation
    > ...
    > POST /repos/octo-org/example-repo/code-scanning/sarifs - 202 in 786ms
    > Successfully uploaded results

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

编译语言示例

此示例与前面的示例相似,但此例中的仓库含有用 C/C++、C# 或 Java 编写的代码。 To create a CodeQL database for these languages, the CLI needs to monitor the build. 在初始化过程结束时,运行器会报告您需要在构建代码之前设置环境的命令。 您需要在调用正常的 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 the build can be traced, for example by running "
      . /srv/checkout/example-repo-2/codeql-runner/codeql-env.sh".
  4. Run the script generated by the init action to set up the environment to monitor the build.

    $ . /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.example.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 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。