# CodeQL命令行界面 (CLI)

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

软件开发人员和安全研究人员可以使用分析来保护其代码 CodeQL 。 有关 CodeQL 的详细信息，请参阅 [使用 CodeQL 扫描代码](/zh/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql#about-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 系统上使用代码扫描](/zh/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system)。 有关运行 CodeQL 分析的建议规范（RAM、CPU 核心和磁盘），请参阅 [推荐用于运行 CodeQL 的硬件资源](/zh/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/recommended-hardware-resources-for-running-codeql)。

或者，可以使用 GitHub Actions 或 Azure DevOps 管道通过 CodeQL CLI 扫描代码。 有关详细信息，请参阅 Microsoft Learn 中的 [配置代码扫描的默认设置](/zh/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning) 或 [configure GitHub Advanced Security for Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/repos/security/configure-github-advanced-security-features)。

有关使用 CodeQL 代码扫描分析的所有选项的概述，请参阅 [使用 CodeQL 扫描代码](/zh/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql)。

> \[!NOTE]
>
> * CodeQL CLI 免费用于公共存储库。 CodeQL CLI 也可在使用 GitHub Team 或 GitHub Enterprise Cloud 并拥有 GitHub Code Security 许可证的组织所拥有的专用仓库中使用。 有关信息，请参阅 [GitHub CodeQL 条款和条件](https://securitylab.github.com/tools/codeql/license)以及 [CodeQL CLI](https://codeql.github.com/docs/codeql-cli/)。
> * CodeQL CLI 当前与非 glibc Linux 发行版不兼容，例如（基于 musl 的）Alpine Linux。

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

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

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

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

> \[!NOTE]
> 上传 SARIF 数据以显示为 code scanning 中的 GitHub 结果适用于启用了 GitHub Code Security 的组织拥有的仓库和 GitHub.com 上的公共仓库。 有关详细信息，请参阅“[管理存储库的安全和分析设置](/zh/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-security-and-analysis-settings-for-your-repository)”。

### 用于 CodeQL 分析的示例 CI 配置

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

```shell
# 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 CLI 使用特殊的程序（称为提取程序）将软件系统的源代码中的信息提取到可以查询的数据库。 您可以通过 CodeQL CLI 设置提取器配置选项，自定义提取器的行为。 请参阅“[抽取器选项](/zh/code-security/reference/code-scanning/codeql/codeql-cli/extractor-options)”。

## 关于 GitHub CodeQL 许可证

许可证声明：如果没有 GitHub Code Security 许可证，则通过安装此产品，即表示你同意 [GitHub CodeQL 条款和条件](https://github.com/github/codeql-cli-binaries/blob/main/LICENSE.md)\*\*\*\*。

有关如何使用 GitHub Enterprise 免费试用 GitHub Advanced Security 的信息，请参阅 GitHub Enterprise Cloud 文档中的 [设置 GitHub Enterprise Cloud 试用版](/zh/enterprise-cloud@latest/admin/overview/setting-up-a-trial-of-github-enterprise-cloud) 和 [安装 GitHub Advanced Security 试用版](/zh/enterprise-cloud@latest/billing/managing-billing-for-your-products/managing-billing-for-github-advanced-security/setting-up-a-trial-of-github-advanced-security#setting-up-your-trial-of-github-advanced-security)。

## 关于 CodeQL CLI 数据库包

CodeQL CLI database bundle 命令可用于创建 CodeQL 数据库的可重定位归档。

数据库包的副本可用于与您的团队成员或 GitHub 支持 共享故障排除信息。 请参阅“[创建 CodeQL CLI 数据库捆绑包](/zh/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/creating-database-bundle-for-troubleshooting)”。

## 入门

有关入门的最简单方法，请参阅 [设置 CodeQL CLI](/zh/code-security/codeql-cli/getting-started-with-the-codeql-cli/setting-up-the-codeql-cli)。

如果需要，可以使用更高级的设置选项。 例如，如果你：

* 想要为开源共享的 CodeQL 查询做贡献，并且更喜欢直接使用 CodeQL 源代码。 请参阅“[查看 CodeQL CLI 源代码](/zh/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/check-out-source-code)”。
* 需要同时安装多个版本的 CodeQL CLI。 例如，如果一个代码库需要特定版本，而另一个代码库则使用最新版本。 可以在同一父目录中下载每个版本并解压缩这两个 CLI 存档。
* 正在研究或编写查询，并希望从 GitHub.com 下载数据库。 请参阅“[从 GitHub 下载 CodeQL 数据库](/zh/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/download-databases)”。