CodeQL命令行界面 (CLI)

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

CodeQL CLI这是一种独立的命令行工具，可用于分析代码。其主要用途是生成代码库（数据库 CodeQL ）的数据库表示形式。数据库准备就绪后，可以以交互方式查询它，或运行一组查询以 SARIF 格式生成一组结果，并将结果 GitHub上传到其中。

您可以使用 CodeQL CLI 来：

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

CodeQL CLI 可以分析：

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

关于使用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 中的配置代码扫描的默认设置或 configure GitHub Advanced Security for Azure DevOps。

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

注意

CodeQL CLI 可免费用于 GitHub.com 上维护的公共仓库，也可用于具有 GitHub Code Security 许可证的客户所拥有的专用仓库。有关信息，请参阅 GitHub CodeQL 条款和条件以及 CodeQL CLI。
CodeQL CLI 当前与非 glibc Linux 发行版不兼容，例如（基于 musl 的）Alpine Linux。

关于使用 </> 生成代码扫描结果

如果选择直接运行 CodeQL CLI ，首先必须在本地安装 CodeQL CLI 。如果您计划将 CodeQL CLI 与外部 CI 系统一起使用，则需要使 CodeQL CLI 对 CI 系统中的服务器可用。

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

database create 以创建一个 CodeQL 数据库来表示存储库中每个受支持的编程语言的分层结构。有关详细信息，请参阅“为 CodeQL 分析准备代码”。
database analyze 以运行查询来分析每个 CodeQL 数据库，并汇总 SARIF 文件中的结果。有关详细信息，请参阅“Analyzing your code with CodeQL queries”。
使用 github upload-results 将生成的 SARIF 文件上传到 GitHub，其中结果会与分支或拉取请求匹配，并显示为 code scanning 警报。有关详细信息，请参阅“将 CodeQL 分析结果上传到GitHub”。

注意

上传 SARIF 数据以显示为 code scanning 中的 GitHub 结果适用于启用了 GitHub Code 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

想要为开源共享的 CodeQL 查询做贡献，并且更喜欢直接使用 CodeQL 源代码。请参阅“查看 CodeQL CLI 源代码”。
需要同时安装多个版本的 CodeQL CLI。例如，如果一个代码库需要特定版本，而另一个代码库则使用最新版本。可以在同一父目录中下载每个版本并解压缩这两个 CLI 存档。
正在研究或编写查询，并希望从 GitHub.com 下载数据库。请参阅“从 GitHub 下载 CodeQL 数据库”。

谁可以使用此功能？

在本文中

关于使用CodeQL CLI来code scanning

关于使用 </> 生成代码扫描结果

用于 CodeQL 分析的示例 CI 配置

数据库提取

关于 GitHub CodeQL 许可证

关于 CodeQL CLI 数据库包

入门