运行 CodeQL 查询

可在 数据库上运行查询，并在 中查看结果。

本文内容

关于运行 CodeQL 查询

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

先决条件

要分析代码库，需要对从代码中提取的 数据库运行查询，因此需要选择要在扩展中使用的数据库。 可在本地（从 ZIP 存档或未存档的文件夹）、公共 URL 或 GitHub.com 上项目的 URL 中选择数据库。 有关详细信息，请参阅“管理 CodeQL 数据库”。

运行单个查询

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

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

“查询”视图的屏幕截图，其中“运行本地查询”按钮以深橙色边框显示。

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

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

运行目录中的所有查询

可运行目录中的所有查询。

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

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

运行所选查询

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

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

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

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

在没有任何设置的情况下运行查询

处理新查询时，可以打开“快速查询”选项卡以轻松执行代码并查看结果，而无需在工作区中保存 .ql 文件。 从 VS Code Command Palette 中选择 CodeQL：快速查询，然后使用 CodeQL：对所选数据库运行查询。

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

如果对快速查询满意，应将其保存在 CodeQL 包中，便于以后访问。 有关详细信息，请参阅“使用 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。 有关详细信息，请参阅“database cleanup”。

比较查询结果

编写或调试查询时，查看更改对结果的影响非常有用。 可以比较两组结果，以查看更改的确切内容。 要比较结果，必须在同一数据库上运行这两个查询。

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

  2. 快速选择菜单显示所有有效的查询进行比较。 选择查询。

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

故障排除

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

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

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

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

后续步骤

可选择使用该扩展来创建自己的自定义查询。 有关详细信息，请参阅“创建自定义查询”。

有关跨多个 数据库大规模运行分析的信息，请参阅“通过多库变体分析大规模运行 CodeQL 查询”。