关于 CodeQL CLI

软件开发者和安全研究员可以使用 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、Rust 和 Swift
由多种语言混合编写的代码库。

关于在代码扫描中使用 CodeQL CLI

您可以使用 CodeQL CLI 在第三方持续集成（CI）系统中对正在处理的代码进行代码扫描。代码扫描是一项功能，您可用它分析 GitHub 仓库中的代码，以发现安全漏洞和编码错误。分析识别的任何问题都会显示在您的仓库中。有关在外部 CI 系统中使用代码扫描的概览，请参阅使用现有 CI 系统进行代码扫描。有关运行 CodeQL 分析的推荐规格（内存、CPU 核心和磁盘），请参阅运行 CodeQL 的推荐硬件资源。

或者，您也可以使用 GitHub Actions 或 Azure DevOps 流水线通过 CodeQL CLI 对代码进行扫描。更多信息，请参阅配置代码扫描的默认设置或 Microsoft Learn 中的为 Azure DevOps 配置 GitHub 高级安全功能。

欲了解使用 CodeQL 分析进行代码扫描的所有选项概览，请参阅关于使用 CodeQL 进行代码扫描。

注意

CodeQL CLI 在公共仓库中免费使用。对于使用 GitHub Team 或 GitHub Enterprise Cloud 且拥有 GitHub 代码安全许可证的组织，其私有仓库也可以使用 CodeQL CLI。更多信息，请参阅 GitHub CodeQL 条款和条件和 CodeQL CLI。
CodeQL CLI 目前不兼容非 glibc 的 Linux 发行版，例如基于 musl 的 Alpine Linux。

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

如果您选择直接运行 CodeQL CLI，首先必须在本地安装 CodeQL CLI。如果计划在外部 CI 系统中使用 CodeQL CLI，则需要让 CI 系统的服务器能够访问 CodeQL CLI。

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

database create 用于创建 CodeQL 数据库，以表示仓库中每种受支持编程语言的层次结构。更多信息，请参阅为 CodeQL 分析准备代码。
database analyze 用于运行查询，对每个 CodeQL 数据库进行分析，并将结果汇总到 SARIF 文件中。更多信息，请参阅使用 CodeQL 查询分析代码。
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

想为开源共享的 CodeQL 查询做出贡献，并且更倾向于直接使用 CodeQL 源代码。请参阅检出 CodeQL CLI 源代码。
需要在同一机器上并排安装多个版本的 CodeQL CLI。例如，一个代码库需要特定版本，而另一个需要最新版本。您可以下载每个版本并将两个 CLI 压缩包解压到同一父目录中。
正在研究或开发查询，并希望从 GitHub.com 下载数据库。请参阅从 GitHub 下载 CodeQL 数据库。

谁可以使用此功能？

本文内容

关于在代码扫描中使用 CodeQL CLI

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

CodeQL 分析的 CI 配置示例

数据库提取

关于 GitHub CodeQL 许可证

关于 CodeQL CLI 数据库包

入门指南