关于运行 CodeQL 查询
存储库 github/codeql
包含大量示例查询。 可通过“查询”视图访问工作区中的任何现有查询。
先决条件
要分析代码库,需要对从代码中提取的 数据库运行查询,因此需要选择要在扩展中使用的数据库。 可在本地(从 ZIP 存档或未存档的文件夹)、公共 URL 或 GitHub.com 上项目的 URL 中选择数据库。 有关详细信息,请参阅“管理 CodeQL 数据库”。
运行单个查询
-
在边栏中,打开“查询”视图。
-
要对所选数据库运行查询,请将鼠标悬停在所需查询上,然后单击运行本地查询图标。
CodeQL 扩展对当前数据库运行查询,并在应用程序的右下角报告进度。 结果准备就绪后,它们将显示在 CodeQL“查询结果”视图中。
如果运行查询时出现任何问题,则会在应用程序的右下角显示通知。 除了错误消息,通知还包括有关如何解决问题的详细信息。
运行目录中的所有查询
可运行目录中的所有查询。
-
在边栏中,打开“查询”视图。
-
将鼠标悬停在所需的查询目录上,然后单击运行本地查询图标。
运行所选查询
可使用单个命令运行多个查询。
-
转到文件资源管理器。
-
选择包含查询的多个文件或文件夹。
-
右键单击并选择 CodeQL:在所选文件中运行查询。
在没有任何设置的情况下运行查询
处理新查询时,可以打开“快速查询”选项卡以轻松执行代码并查看结果,而无需在工作区中保存 .ql
文件。 从 VS Code Command Palette 中选择 CodeQL:快速查询,然后使用 CodeQL:对所选数据库运行查询。
可在“查询历史记录”视图中查看在当前会话中运行的所有快速查询。 单击条目可查看生成结果的快速查询的确切文本。 有关详细信息,请参阅“查看查询历史记录”。
如果对快速查询满意,应将其保存在 CodeQL 包中,便于以后访问。 有关详细信息,请参阅“使用 CodeQL 包自定义分析”。
运行查询或库的特定部分
如果你正在调试查询或库,并且想要找到错误的部件,这将很有帮助。
与使用 :对所选数据库运行查询来运行整个查询(选择子句和任意查询谓词)不同,可使用 :快速评估将评估你选择的代码片段,而不是整个查询,并在“结果”视图中显示该选择的结果。
快速评估可用于:
例如,在以下代码片段中,可以选择谓词名称 foo
或公式 s = "bar"
进行快速评估:
predicate foo(string s) { s = "bar" }
对多个数据库运行查询
如果要在多个代码库上测试查询,或在多个项目中查找漏洞,该操作可能很有帮助。
-
打开一个查询 (
.ql
) 文件。 -
右键单击并选择 CodeQL:对多个数据库运行查询。
-
从下拉菜单中,选择要运行查询的数据库。
查看查询历史记录
要查看在当前会话中运行的查询,请打开“查询历史记录”视图。
“查询历史记录”视图包含的信息包括运行查询的日期和时间、查询的名称、运行查询的数据库以及运行查询所花费的时间:
-
要自定义显示的信息,请右键单击条目,然后选择重命名。
-
(可选)使用语言选择器按语言筛选视图。 有关详细信息,请参阅“按语言筛选数据库和查询”。
-
单击一个条目以显示相应的结果,然后双击以在编辑器中显示查询本身(或右键单击并选择查看查询)。
-
要显示为特定条目生成结果的确切文本,请右键单击它并选择查看查询文本。 这可能与视图查询不同,因为自上次运行查询以来,查询文件可能已被修改。
-
要从视图中删除查询,请选择要删除的所有查询,然后右键单击并选择删除。
理解查询结果
-
单击“查询历史记录”视图中的查询,在“结果”视图中显示其结果。
注意: 根据查询,还可以选择不同的视图,例如 CSV、CodeQL CLI SARIF 输出 或 DIL 格式。 例如,要查看 DIL 格式,请右键单击结果并选择查看 DIL。 可用的输出视图由查询的格式和元数据确定。 有关详细信息,请参阅“CodeQL 查询”。
-
使用“结果”视图中的下拉菜单选择要显示的结果以及以何种形式显示这些结果,例如格式化的警报消息或原始结果表。
-
要按特定列中的条目对结果进行排序,请单击列标题。
如果结果链接到源代码元素,则可以单击该结果以在源代码中显示该元素。
要在源代码中使用标准代码导航功能,可以右键单击元素,然后使用命令转到定义或转到引用。 这将对活动文件运行 CodeQL 查询,可能需要几秒钟。 此查询需要对每个文件运行一次,因此来自同一文件的任何其他引用都将更快。
注意: 如果使用较旧的数据库,则代码导航命令(如转到定义和转到引用)可能不起作用。
要使用代码导航,请尝试使用 CodeQL CLI 解压缩数据库并在解压缩的数据库上运行 codeql database cleanup <database>
。 然后,将数据库重新添加到 Visual Studio Code。 有关详细信息,请参阅“database cleanup”。
比较查询结果
编写或调试查询时,查看更改对结果的影响非常有用。 可以比较两组结果,以查看更改的确切内容。 要比较结果,必须在同一数据库上运行这两个查询。
-
右键单击“查询历史记录”视图中的查询,然后选择比较结果。
-
快速选择菜单显示所有有效的查询进行比较。 选择查询。
-
“比较”视图显示两个查询结果的差异。
故障排除
要查看运行特定查询的日志,请右键单击“查询历史记录”视图中的查询,然后选择显示查询日志。 如果日志文件太大,无法在 VS Code 中打开,则该文件将显示在文件资源管理器中,以便使用外部程序打开。
有关编译和运行查询以及有关数据库升级的信息的详细信息,请查看 CodeQL 查询服务器日志。 有关详细信息,请参阅“访问日志”。
默认情况下,扩展会在每个工作区会话后删除日志。 要保存日志,可以为查询服务器日志指定自定义目录。 有关详细信息,请参阅“自定义设置”。
可以使用 CodeQL:重启查询服务器命令来重启查询服务器。 该操作将重启服务器,但不会影响 CodeQL 会话历史记录。 如果对扩展正在使用的文件进行外部更改,则很可能需要重新启动查询服务器。 例如,重新生成在 VS Code 中打开的 CodeQL 数据库。 除了日志中的问题之外,你可能还会看到:代码突出显示错误、结果总计不正确或查询正在运行的重复通知。
后续步骤
可选择使用该扩展来创建自己的自定义查询。 有关详细信息,请参阅“创建自定义查询”。