关于 CodeQL CLI

可以使用 CodeQL CLI 对软件项目本地运行 CodeQL 进程，或生成 code scanning 结果以上传到 GitHub。

谁可以使用此功能？

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

本文内容

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

CodeQL CLI 是可用于分析代码的独立代码行工具。 其主要用途是生成代码空间的数据库表示形式，即 CodeQL 数据库。 数据库准备就绪后，你可以进行交互式查询，或者运行一系列查询以生成一组 SARIF 格式的结果，然后将结果上传到 GitHub。

可以使用 CodeQL CLI 来执行以下操作：

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

CodeQL CLI 可以分析：

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

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

关于将 CodeQL CLI 用于 code scanning

可以使用 CodeQL CLI 在第三方持续集成 (CI) 系统中处理的代码上运行 code scanning。 Code scanning 是一项功能，可用于分析 GitHub 仓库中的代码，以查找安全漏洞和编码错误。 分析标识的任何问题都显示在存储库中。 有关使用外部 CI 系统进行代码扫描的概述，请参阅“在现有 CI 系统上使用代码扫描”。 有关运行 CodeQL 分析的建议规范（RAM、CPU 核心和磁盘），请参阅“推荐用于运行 CodeQL 的硬件资源”。

或者，可以使用 GitHub Actions 或 Azure DevOps 管道通过 CodeQL CLI 扫描代码。 有关详细信息，请参阅 Microsoft Learn 中的“配置代码扫描的默认设置”或配置 GitHub Advanced Security for Azure DevOps。

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

Note

  • CodeQL CLI 免费用于公共存储库。 CodeQL CLI 也可在使用 GitHub Enterprise Cloud 并拥有 GitHub Advanced Security 许可证的组织所拥有的专用存储库中使用。 有关信息，请参阅“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 文件上传到结果与分支或拉取请求匹配并显示为 code scanning 警报的 GitHub。 有关详细信息，请参阅“将 CodeQL 分析结果上传到 GitHub”。

Note

上传 SARIF 数据以显示为 GitHub 中的 code scanning 结果适用于启用了 GitHub Advanced Security 的组织拥有的数据库 和 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 Advanced Security 许可证，则通过安装此产品，即表示你同意 GitHub CodeQL 条款和条件。

有关如何使用 GitHub Advanced Security 免费试用 GitHub Enterprise 的信息，请参阅 GitHub Enterprise Cloud 文档中的“设置 GitHub Enterprise Cloud 试用版”和“安装 GitHub Advanced Security 试用版”。