关于 CodeQL CLI

您可以使用 CodeQL CLI 在软件项目上本地运行 CodeQL 进程，或生成代码扫描结果以上传到 GitHub。

谁可以使用此功能？

CodeQL 可用于以下类型的存储库

本文档内容

软件开发人员和安全研究人员可以使用 CodeQL 分析来保护其代码。有关 CodeQL 的更多信息，请参阅“关于使用 CodeQL 进行代码扫描”。

CodeQL CLI 是一个独立的命令行工具，您可以使用它来分析代码。其主要目的是生成代码库的数据库表示形式，即 CodeQL 数据库。数据库准备就绪后，您可以交互式地查询它，或运行一系列查询以生成 SARIF 格式的结果集并将结果上传到 GitHub。

您可以使用 CodeQL CLI 来：

  • 使用 GitHub 工程师和开源社区提供的查询运行 CodeQL 分析
  • 生成可以上传到 GitHub 以在 GitHub 中显示的代码扫描警报
  • 创建要在 Visual Studio Code 的 CodeQL 扩展中使用的 CodeQL 数据库。
  • 开发和测试要在您自己的分析中使用的自定义 CodeQL 查询

CodeQL CLI 可以分析：

  • 动态语言，例如 JavaScript 和 Python。
  • 编译语言，例如 C/C++、C#、Go、Java、Kotlin 和 Swift
  • 用多种语言编写的代码库。

有关设置 CodeQL CLI 的信息，请参阅“设置 CodeQL CLI”。

关于使用 CodeQL CLI 进行代码扫描

您可以使用 CodeQL CLI 对在第三方持续集成 (CI) 系统中处理的代码运行代码扫描。代码扫描是用于分析 GitHub 存储库中的代码以查找安全漏洞和编码错误的功能。分析中发现的任何问题都会显示在您的存储库中。有关将代码扫描与外部 CI 系统一起使用的概述，请参阅“将代码扫描与现有 CI 系统一起使用”。有关运行 CodeQL 分析的推荐规格（RAM、CPU 内核和磁盘），请参阅“运行 CodeQL 的推荐硬件资源”。

或者，您可以使用 GitHub Actions 或 Azure DevOps 管道使用 CodeQL CLI 扫描代码。有关更多信息，请参阅“配置代码扫描的默认设置”或 Microsoft Learn 中的为 Azure DevOps 配置 GitHub 高级安全。

有关使用 CodeQL 分析进行代码扫描的所有选项的概述，请参阅“关于使用 CodeQL 进行代码扫描”。

注意

  • CodeQL CLI 可在公共存储库中免费使用。CodeQL CLI 也适用于使用 GitHub Enterprise Cloud 并拥有 GitHub 高级安全许可证的组织拥有的私有存储库。有关信息，请参阅GitHub CodeQL 条款和条件和CodeQL CLI。
  • CodeQL CLI 目前与非 glibc Linux 发行版（例如基于 musl 的 Alpine Linux）不兼容。

关于使用 CodeQL CLI 生成代码扫描结果

如果您选择直接运行 CodeQL CLI，则首先必须在本地安装 CodeQL CLI。如果您计划将 CodeQL CLI 与外部 CI 系统一起使用，则需要使 CodeQL CLI 可用于 CI 系统中的服务器。有关更多信息，请参阅“设置 CodeQL CLI”。

设置 CodeQL CLI 后，您可以使用三个不同的命令来生成结果并将其上传到 GitHub

  1. database create 用于创建 CodeQL 数据库，以表示存储库中每种受支持编程语言的分层结构。有关更多信息，请参阅“准备代码以进行 CodeQL 分析”。
  2. database analyze 用于运行查询以分析每个 CodeQL 数据库并在 SARIF 文件中汇总结果。有关更多信息，请参阅“使用 CodeQL 查询分析您的代码”。
  3. github upload-results 用于将生成的 SARIF 文件上传到 GitHub，在 GitHub 中，结果将与分支或拉取请求匹配并显示为代码扫描警报。有关更多信息，请参阅“将 CodeQL 分析结果上传到 GitHub”。

注意

上传 SARIF 数据以在 GitHub 中显示为代码扫描结果，受支持的对象为启用了 GitHub 高级安全的组织拥有的存储库以及 GitHub.com 上的公共存储库。有关更多信息，请参阅“管理存储库的安全和分析设置”。

CodeQL 分析的示例 CI 配置

这是一个使用 CodeQL CLI 分析具有两种受支持语言的代码库，然后将结果上传到 GitHub 的完整命令序列示例。

# Create CodeQL databases for Java and Python in the 'codeql-dbs' directory
# Call the normal build script for the codebase: 'myBuildScript'

codeql database create codeql-dbs --source-root=src \
    --db-cluster --language=java,python --command=./myBuildScript

# Analyze the CodeQL database for Java, 'codeql-dbs/java'
# Tag the data as 'java' results and store in: 'java-results.sarif'

codeql database analyze codeql-dbs/java java-code-scanning.qls \
    --format=sarif-latest --sarif-category=java --output=java-results.sarif

# Analyze the CodeQL database for Python, 'codeql-dbs/python'
# Tag the data as 'python' results and store in: 'python-results.sarif'

codeql database analyze codeql-dbs/python python-code-scanning.qls \
    --format=sarif-latest --sarif-category=python --output=python-results.sarif

# Upload the SARIF file with the Java results: 'java-results.sarif'
# The GitHub App or personal access token created for authentication
# with GitHub's REST API is available in the `GITHUB_TOKEN` environment variable.

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=java-results.sarif

# Upload the SARIF file with the Python results: 'python-results.sarif'

codeql github upload-results \
    --repository=my-org/example-repo \
    --ref=refs/heads/main --commit=deb275d2d5fe9a522a0b7bd8b6b6a1c939552718 \
    --sarif=python-results.sarif

关于 GitHub CodeQL 许可证

许可证声明：如果您没有 GitHub 高级安全的许可证，则安装此产品即表示您同意 GitHub CodeQL 条款和条件。

有关如何免费试用 GitHub Enterprise 和 GitHub 高级安全功能的信息，请参阅 GitHub Enterprise Cloud 文档中的“设置 GitHub Enterprise Cloud 试用版”和“设置 GitHub 高级安全试用版”。