CodeQL安装及使用

一、关于CodeQL

1.CodeQL简介

CodeQL是一种将查询语言的概念引入源代码分析的工具，为开发者提供了全新的方式来发现和理解代码中的潜在问题。自2019年GitHub收购Semmle并将CodeQL集成到其平台以来，CodeQL已成为GitHub Advanced Security功能的一部分，通过GitHub的Code Scanning功能，用户可以轻松地将CodeQL集成到他们的开发流程中，实现持续的代码安全检查。

2.工作原理

CodeQL的整体工作流程基于数据库的建立和查询的执行。首先，CodeQL的Extractor模块会对源代码进行分析和提取，生成一个包含代码信息的数据库（如AST、CFG等）。然后，用户可以使用CodeQL查询语言编写查询语句，这些查询语句会在数据库中搜索特定的代码模式。查询执行后，CodeQL会返回与查询模式匹配的所有实例，并提供修复建议。

3.支持的编程语言

CodeQL支持多种编程语言，包括Java、C/C++、Python、JavaScript、Go等，这使得它成为多语言项目的理想选择。

二、安装CodeQL

CodeQL的安装和配置相对简单，用户可以下载CodeQL CLI（命令行界面）和相关的QL规则库，然后按照官方文档进行配置。此外，CodeQL还提供了VS Code插件等集成工具，方便用户在IDE中直接使用。

1.下载CodeQL CLI和CodeQL SDK

（1）访问GitHub的发布页面

• CodeQL CLI的下载地址：https://github.com/github/codeql-cli-binaries/releases。
• CodeQL SDK的下载地址通常包含在CodeQL CLI的下载页面中，但也可以单独从GitHub的CodeQL仓库获取：https://github.com/github/codeql。

（2）选择合适的版本

• 根据你的操作系统（Windows、Linux、MacOS）选择相应的版本。
• 注意选择最新或适合你项目需求的版本。

（3）下载文件

• 对于国内用户，由于直接从GitHub下载可能会遇到速度较慢或中断的问题，可以考虑使用国内的镜像源或下载工具。

2.安装CodeQL CLI

（1）解压下载的文件

• 将下载的CodeQL CLI安装包解压到你选择的安装目录，例如C:\Software\codeql（Windows）或/usr/local/codeql（Linux/MacOS）。

（2）设置环境变量

• 将CodeQL CLI的安装目录添加到你的系统环境变量中，以便在命令行中直接调用codeql命令。
• 在Windows上，可以通过“系统属性”->“高级”->“环境变量”来设置。
• 在Linux/MacOS上，可以通过修改~/.bashrc、~/.zshrc或类似的shell配置文件，并添加类似export PATH=$PATH:/usr/local/codeql的行来实现。

（3）验证安装

• 打开命令行或终端，输入codeql --version，如果显示CodeQL CLI的版本信息，则表示安装成功。

3.安装CodeQL SDK

（1）解压SDK文件

• 将下载的CodeQL SDK安装包解压到你选择的目录，通常与CodeQL CLI安装在同一目录下或附近。

（2）查看支持的规则集

• 打开命令行或终端，使用codeql pack ls命令查看当前SDK中支持的规则集。

4.配置CodeQL环境（可选）

如果你打算使用Visual Studio Code（VSCode）来开发和调试CodeQL规则，你还需要在VSCode中安装CodeQL插件，并配置CodeQL CLI的路径。

VSCode插件的安装方法：在VSCode的扩展市场中搜索“CodeQL”并安装。

配置CodeQL CLI路径：在VSCode的设置中，找到CodeQL插件的相关设置，并指定CodeQL CLI的安装路径。

三、使用CodeQL进行代码分析

1.使用CodeQL生成数据库

（1）准备源代码

• 确保你有需要分析的源代码，并知道源代码的语言类型（如Java、Python等）。

（2）使用CodeQL CLI创建数据库

• 打开命令行，切换到源代码所在的目录。
• 执行创建数据库的命令，例如：codeql database create <数据库名> --language=<语言标识符> --source-root=<源码路径>。
• 如果源代码是一个Maven项目，可能需要使用Maven命令来构建项目，并在创建数据库时指定该命令--command="mvn clean install"。

Language对应关系如下：

Language	Identity
C/C++	cpp
C#	csharp
Go	go
Java	java
javascript/Typescript	javascript
Python	python

2.VSCode内使用CodeQL

（1）Vscode添加生成的数据库

（2） VSCode 打开扫描规则库，也就是sdk的解压后的包

（3）执行扫描规则

选择具体语言的规则进行扫描，例如：java语言的规则。

ql后缀的文件是规则扫描文件，比如：\codeql-main\java\ql\src\Security\CWE

3.命令行方式使用CodeQL

使用 VSCode 图形化工具如上，也可也直接使用命令，快捷、方便

执行扫描规则：

codeql database analyze <项目生成的数据库名路径> <规则库路径> --format=csv --output=result.csv

--format：结果输出格式

--output：结果文件输出路径

codeql命令的详细使用方法可查看：About the CodeQL CLI - GitHub Docs