About the CodeQL CLI

You can use the CodeQL CLI to run CodeQL processes locally on software projects or to generate code scanning results for upload to GitHub.

谁可以使用此功能？

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

本文内容

Software developers and security researchers can secure their code using CodeQL analysis. For more information about CodeQL, see About code scanning with CodeQL.

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

You can use the CodeQL CLI to:

  • Run CodeQL analyses using queries provided by GitHub engineers and the open source community
  • Generate code scanning alerts that you can upload to display in GitHub
  • Create CodeQL databases to use in the CodeQL for Visual Studio Code extension.
  • Develop and test custom CodeQL queries to use in your own analyses

The CodeQL CLI can analyze:

  • Dynamic languages, for example, JavaScript and Python.
  • Compiled languages, for example, C/C++、C#、Go、Java、Kotlin、Rust（公共预览版）、和 Swift
  • Codebases written in a mixture of languages.

For information about setting up the CodeQL CLI, see 设置 CodeQL CLI.

About using the CodeQL CLI for code scanning

You can use the CodeQL CLI to run code scanning on code that you're processing in a third-party continuous integration (CI) system. Code scanning 是一项功能，可用于分析 GitHub 仓库中的代码，以查找安全漏洞和编码错误。 分析标识的任何问题都显示在存储库中。 For an overview of using code scanning with external CI systems, see 在现有 CI 系统上使用代码扫描. For recommended specifications (RAM, CPU cores, and disk) for running CodeQL analysis, see 推荐用于运行 CodeQL 的硬件资源.

Alternatively, you can use GitHub Actions or Azure DevOps pipelines to scan code using the CodeQL CLI. For more information, see 配置代码扫描的默认设置 or Configure GitHub Advanced Security for Azure DevOps in Microsoft Learn.

For an overview of all the options for using CodeQL analysis for code scanning, see About code scanning with CodeQL.

注意

  • CodeQL CLI 可用于拥有 GitHub Code Security 许可证的客户。
  • CodeQL CLI 当前与非 glibc Linux 发行版不兼容，例如（基于 musl 的）Alpine Linux。

About generating code scanning results with the CodeQL CLI

If you choose to run the CodeQL CLI directly, you first have to install the CodeQL CLI locally. If you are planning to use the CodeQL CLI with an external CI system, you need to make the CodeQL CLI available to servers in your CI system. For more information, see 设置 CodeQL CLI.

Once the CodeQL CLI is set up, you can use three different commands to generate results and upload them to GitHub:

  1. database create to create a CodeQL database to represent the hierarchical structure of each supported programming language in the repository. For more information, see 为 CodeQL 分析准备代码.
  2. database analyze to run queries to analyze each CodeQL database and summarize the results in a SARIF file. For more information, see 使用 CodeQL 查询分析代码.
  3. github upload-results to upload the resulting SARIF files to GitHub where the results are matched to a branch or pull request and displayed as code scanning alerts. For more information, see 将 CodeQL 分析结果上传到 GitHub.

注意

上传 SARIF 数据以显示为 GitHub 中的 code scanning 结果适用于启用了 GitHub Code Security 的组织拥有的仓库。 有关详细信息，请参阅“管理存储库的安全和分析设置”。

Example CI configuration for CodeQL analysis

This is an example of the full series of commands for the CodeQL CLI that you might use to analyze a codebase with two supported languages and then upload the results to 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 Code Security 许可证，则通过安装此产品，即表示你同意 GitHub CodeQL 条款和条件****。