# 使用 CodeQL 扫描代码

可用于 CodeQL 识别代码中的漏洞和错误。 结果在code scanning中显示为GitHub警报。

> \[!NOTE]
> 网站管理员必须启用 code scanning，然后你才能使用此功能。 有关详细信息，请参阅“[为您的设备配置代码扫描](/zh/enterprise-server@3.19/admin/code-security/managing-github-advanced-security-for-your-enterprise/configuring-code-scanning-for-your-appliance)”。
>
> 如果企业所有者在企业级别设置了 code scanning 策略，则你可能无法启用或禁用 GitHub Code Security。 有关详细信息，请参阅“[强制实施企业的代码安全性和分析策略](/zh/enterprise-server@3.19/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise)”。

CodeQL 是 GitHub 开发的代码分析引擎，用于自动执行安全检查。 可使用 CodeQL 分析代码，并将结果显示为 code scanning 警报。

使用CodeQL针对code scanning进行分析的三种主要方式如下：

* 使用默认设置快速为你的存储库上的 CodeQL 配置 code scanning 分析。 默认设置自动选择要分析的语言、要运行的查询套件和触发扫描的事件。 如果需要，可以手动选择要运行的查询套件和要分析的语言。 启用 CodeQL后， GitHub Actions 将执行工作流运行以扫描代码。 有关详细信息，请参阅“[配置代码扫描的默认设置](/zh/enterprise-server@3.19/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning)”。

* 使用高级设置将 CodeQL 工作流添加到存储库。 这会生成一个可自定义的工作流文件，该文件使用 [github/codeql-action](https://github.com/github/codeql-action/) 来运行 CodeQL CLI。 有关详细信息，请参阅“[配置代码扫描的高级设置](/zh/enterprise-server@3.19/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning#configuring-advanced-setup-for-code-scanning-with-codeql)”。

* 直接在外部 CI 系统中运行 CodeQL CLI，并将结果上传到 GitHub。 有关详细信息，请参阅“[在现有 CI 系统上使用代码扫描](/zh/enterprise-server@3.19/code-security/code-scanning/integrating-with-code-scanning/using-code-scanning-with-your-existing-ci-system)”。

> \[!NOTE]
> 在 GitHub Enterprise Server3.19 上，CodeQL 操作默认使用 CodeQL CLI2.22.4 版本。 我们建议，如果您在外部 CI 系统中运行分析，请使用相同版本的 CodeQL CLI。

有关 code scanning 警报的信息，请参阅 [代码扫描警报](/zh/enterprise-server@3.19/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts)。

## 关于 CodeQL

CodeQL 是一种编程语言和相关工具，用于处理代码（如数据）。 它是显式创建的，以便比传统静态分析器更容易分析代码并更有信心地发现代码中的潜在漏洞。

1. 生成一个 CodeQL 数据库来表示代码库。
2. 然后，在该 CodeQL 数据库上运行查询，以识别代码库中的问题。
3. 将 code scanning 与 GitHub 一起使用时，查询结果会在 CodeQL 中显示为 code scanning 警报。

CodeQL 支持已编译和解释的语言，并且可以在以支持的语言编写的代码中查找漏洞和错误。

CodeQL 支持以下语言：

<!-- If you update the list of supported languages for CodeQL, update docs-internal/content/get-started/learning-about-github/github-language-support.md to reflect the changes. -->

* C/C++
* C#
* Go
* Java/Kotlin
* JavaScript/TypeScript
* Python
* Ruby
* Rust（公共预览版）
* 切换 \* GitHub Actions工作流

> \[!NOTE]
>
> * 使用 `java-kotlin` 分析用 Java 或/和 Kotlin 编写的代码。
> * 使用 `javascript-typescript` 分析用 JavaScript 和/或 TypeScript 编写的代码。

有关详细信息，请参阅 CodeQL 网站上的文档：“[支持的语言和框架](https://codeql.github.com/docs/codeql-overview/supported-languages-and-frameworks/)”。

> \[!IMPORTANT]
> CodeQL**不支持**上面未列出的语言。 这包括但不限于 PHP、Scala 等。\*\*\*\*\*\*\*\* 尝试将 CodeQL 用于不受支持的语言时，可能会导致无法生成任何警报，并且分析结果不完整。

## 为自定义框架或利基框架建模

GitHub 专家、安全研究人员和社区参与者编写库来为常用框架和库中的数据流建模。 如果使用未建模的自定义依赖项，则可以使用 CodeQL 扩展来创建 Visual Studio Code 这些依赖项的模型，并使用它们扩展分析。 有关详细信息，请参阅“[使用 CodeQL 模型编辑器](/zh/enterprise-server@3.19/code-security/codeql-for-vs-code/using-the-advanced-functionality-of-the-codeql-for-vs-code-extension/using-the-codeql-model-editor)”。

## CodeQL 查询

GitHub 专家、安全研究人员和社区贡献者编写并维护用于 CodeQL 的默认 code scanning 查询。 这些查询会定期更新，以改进分析效果并减少误报。
有关默认包和扩展包中可用的查询的详细信息，请参阅 [默认查询套件和安全扩展查询套件中包含的查询](/zh/enterprise-server@3.19/code-security/code-scanning/managing-your-code-scanning-configuration/codeql-query-suites#queries-included-in-the-default-and-security-extended-query-suites)。

### 编写自己的查询

这些查询是开源查询，因此可以在 [github/codeql](https://github.com/github/codeql) 存储库中查看它们并向其贡献内容。 有关更多信息，请参阅 CodeQL 文档中的[“关于 CodeQL 查询”](https://codeql.github.com/docs/writing-codeql-queries/about-codeql-queries/)。

### 运行额外查询

如果使用高级设置或外部 CI 系统扫描代码，则可以在分析过程中运行其他查询。

这些查询必须属于已发布 CodeQL 的查询包或 CodeQL 存储库中的包。

* 当 CodeQL 查询包发布到 GitHubContainer registry 时，包中会包含这些查询所需的所有传递依赖项以及一个编译缓存。 这可以提高性能，并确保在包中运行查询每次都会提供相同的结果，直到升级到新版本的包或 CLI。

* CodeQL 可以从多个 GitHub 容器注册表下载查询包。 有关详细信息，请参阅“[代码扫描的工作流配置选项](/zh/enterprise-server@3.19/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#downloading-codeql-packs-from-github-enterprise-server)”。

有关详细信息，请参阅“[使用 CodeQL 包自定义分析](/zh/enterprise-server@3.19/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs)”。