运行 CodeQL 查询

您可以在 CodeQL 数据库上运行查询，并在 Visual Studio Code 中查看结果。

本文内容

关于运行 CodeQL 查询

该 github/codeql 代码库包含大量示例查询。您可以通过“查询”视图访问工作区中的任何现有查询。

先决条件

要分析代码库，您需要针对从代码中提取的 CodeQL 数据库运行查询，因此您需要在扩展中选择一个要使用的数据库。您可以选择本地数据库（来自 ZIP 归档文件或解压缩的文件夹）、来自公共 URL 或来自 GitHub.com 上项目的 URL。有关更多信息，请参阅“管理 CodeQL 数据库”。

运行单个查询

  1. 在侧边栏中，打开“查询”视图。

  2. 要对选定的数据库运行查询，请将鼠标悬停在所需的查询上，然后单击**运行本地查询**图标。

Screenshot of the "Queries" view, with the "Run local query" button outlined in dark orange.

CodeQL 扩展将在当前数据库上运行查询，并在应用程序的右下角报告进度。结果准备就绪后，将显示在 CodeQL“查询结果”视图中。

如果运行查询时出现任何问题，应用程序的右下角会显示一条通知。除了错误消息外，通知还包括有关如何解决问题的详细信息。

运行目录中的所有查询

您可以运行目录中的每个查询。

  1. 在侧边栏中，打开“查询”视图。

  2. 将鼠标悬停在所需的查询目录上，然后单击**运行本地查询**图标。

运行选定的查询

您可以使用单个命令运行多个查询。

  1. 转到文件资源管理器。

  2. 选择包含查询的多个文件或文件夹。

  3. 右键单击并选择**CodeQL：在选定的文件中运行查询**。

无需任何设置即可运行查询

在处理新查询时，您可以打开“快速查询”选项卡以轻松执行代码并查看结果，而无需在工作区中保存 .ql 文件。从 VS Code 命令面板中选择**CodeQL：快速查询**，然后要运行查询，请使用**CodeQL：在选定的数据库上运行查询**。

您可以在“查询历史记录”视图中查看当前会话中运行的所有快速查询。单击一个条目以查看生成结果的快速查询的确切文本。有关更多信息，请参阅“查看查询历史记录”。

对快速查询满意后，应将其保存在 CodeQL 包中，以便以后访问。有关更多信息，请参阅“使用 CodeQL 包自定义分析”。

运行查询或库的特定部分

如果您正在调试查询或库并且想要找到错误的部分，这将非常有用。

您可以使用**CodeQL: 快速评估**来运行 .ql 或 .qll 文件的特定部分，而不是使用**CodeQL: 在选定数据库上运行查询**来运行整个查询（select 子句和任何查询谓词）。

**CodeQL: 快速评估**会评估您选择的代码片段（而不是整个查询），并在“结果”视图中显示该选择的评估结果。

快速评估的可能目标包括

  • 选择 CodeQL 实体的名称（例如类或谓词）以评估该实体。

  • 选择具有自由变量的公式或表达式以评估该公式或表达式。

例如，在以下代码片段中，您可以选择谓词名称 foo 或公式 s = "bar" 进行快速评估

predicate foo(string s) { s = "bar" }

在多个数据库上运行查询

如果您想在多个代码库上测试您的查询，或在多个项目中查找漏洞，这将非常有用。

  1. 打开一个查询 (.ql) 文件。

  2. 右键单击并选择**CodeQL: 在多个数据库上运行查询**。

  3. 从下拉菜单中，选择要在其上运行查询的数据库。

查看查询历史记录

要查看您在当前会话中运行的查询，请打开“查询历史记录”视图。

“查询历史记录”视图包含以下信息：查询运行的日期和时间、查询的名称、在其上运行查询的数据库以及运行查询所需的时间。

  • 要自定义显示的信息，请右键单击一个条目并选择**重命名**。

  • 或者，可以使用语言选择器按语言筛选视图。有关更多信息，请参阅“按语言筛选数据库和查询”。

  • 单击一个条目以显示相应的结果，双击以在编辑器中显示查询本身（或右键单击并选择**查看查询**）。

  • 要显示为特定条目生成结果的确切文本，请右键单击它并选择**查看查询文本**。这可能与**查看查询**不同，因为查询文件自上次运行以来可能已修改。

  • 要从视图中删除查询，请选择要删除的所有查询，然后右键单击并选择**删除**。

了解查询结果

  1. 在“查询历史记录”视图中单击一个查询，以在“结果”视图中显示其结果。

    注意

    根据查询的不同，您还可以选择不同的视图，例如 CSV、CodeQL CLI SARIF 输出或DIL 格式。例如，要查看 DIL 格式，请右键单击结果并选择**查看 DIL**。可用的输出视图由查询的格式和元数据决定。有关更多信息，请参阅“CodeQL 查询”。

  2. 使用“结果”视图中的下拉菜单选择要显示的结果以及显示它们的格式，例如格式化的警报消息或原始结果表。

  3. 要按特定列中的条目对结果进行排序，请单击列标题。

如果结果链接到源代码元素，则可以单击它以在源代码中显示它。

要使用源代码中的标准代码导航功能，您可以右键单击一个元素并使用命令**转到定义**或**转到引用**。这将在活动文件上运行一个 CodeQL 查询，可能需要几秒钟。此查询需要为每个文件运行一次，因此来自同一文件的任何其他引用都将很快。

注意

如果您使用的是较旧的数据库，则**转到定义**和**转到引用**等代码导航命令可能无法正常工作。要使用代码导航，请尝试解压缩数据库并在解压缩的数据库上使用 CodeQL CLI 运行 codeql database cleanup <database>。然后，将数据库重新添加到 Visual Studio Code。有关更多信息，请参阅“数据库清理”。

比较查询结果

在编写或调试查询时，查看您的更改如何影响结果非常有用。您可以比较两组结果以准确查看发生了哪些变化。要比较结果，两个查询必须在同一数据库上运行。

  1. 在“查询历史记录”视图中右键单击一个查询，然后选择**比较结果**。

  2. 快速选择菜单将显示所有有效的要比较的查询。选择一个查询。

  3. “比较”视图显示两个查询结果的差异。

故障排除

要查看运行特定查询的日志，请在“查询历史记录”视图中右键单击该查询，然后选择**显示查询日志**。如果日志文件太大而无法在 VS Code 中打开，则该文件将显示在您的文件资源管理器中，以便您可以使用外部程序打开它。

有关编译和运行查询的详细信息，以及有关数据库升级的信息，请查看 CodeQL 查询服务器日志。有关更多信息，请参阅“访问日志”。

默认情况下，扩展会在每个工作区会话后删除日志。要覆盖此行为，您可以为查询服务器日志指定自定义目录。有关更多信息，请参阅“自定义设置”。

您可以使用**CodeQL: 重启查询服务器**命令来重启查询服务器。这将重启服务器，而不会影响您的 CodeQL 会话历史记录。如果您对扩展正在使用的文件进行了外部更改，则很可能需要重启查询服务器。例如，重新生成在 VS Code 中打开的 CodeQL 数据库。除了日志中的问题之外，您还可能会看到：代码突出显示中的错误、不正确的结果总数或查询正在运行的重复通知。

后续步骤

您可以选择使用扩展创建您自己的自定义查询。有关更多信息，请参阅“创建自定义查询”。

有关在许多 CodeQL 数据库中大规模运行分析的信息，请参阅“使用多仓库变体分析大规模运行 CodeQL 查询”。