CodeQL安装与使用教程Linux+Windows

---

该文章参考以下文章总结提炼而成
CodeQL从入门到放弃
白盒审计工具codeql的安装踩坑
CodeQL基础知识

---

CodeQL简介

Github为了解决其托管的海量项目的安全性问题收购了CodeQL的创业公司并宣布开源CodeQL的规则部分这样全世界的安全工程师就可以贡献高效的QL审计规则给Github帮助它解决托管项目的安全问题。

对于安全工程师也就多了一个非商业的开源代码自动化审计工具。
CodeQL支持非常多的语言在官网有如下支持的语言和框架列表。

CodeQL原理

代码转化成类似数据库的形式并基于该database进行分析。

在 CodeQL 中代码被视为数据。安全漏洞、Bug 和其他错误被建模为可针对从代码中提取的数据库执行的查询。

CodeQL 的整体思路是把源代码转化成一个可查询的数据库通过 Extractor 模块对源代码工程进行关键信息分析提取构成一个关系型数据库。CodeQL 的数据库并没有使用现有的数据库技术而是一套基于文件的自己的实现。
对于编译型语言Extractor 会监控编译过程编译器每处理一个源代码文件它都会收集源代码的相关信息如语法信息AST 抽象语法树、语意信息名称绑定、类型信息、运算操作等控制流、数据流等同时也会复制一份源代码文件。而对于解释性语言Extractor 则直接分析源代码得到类似的相关信息。
关键信息提取完成后所有分析所需的数据都会导入一个文件夹这个就是 CodeQL database, 其中包括了源代码文件、关系数据、语言相关的 database schemaschema 定义了数据之间的相互关系。

CodeQL安装

CodeQL本身包含两部分 解析引擎 + SDK 。

• 解析引擎不开源解析我们编写的规则但是可以直接在官网下载二进制文件直接使用。
• SDK(规则库)完全开源里面包含大部分现成的漏洞规则我们也可以利用其编写自定义规则。

解析引擎安装

URL: https://github.com/github/codeql-cli-binaries/releases

下载已经编译好的codeql执行程序解压之后把codeql文件夹放入/CodeQL。

为了方便测试我们需要把ql可执行程序加入到环境变量当中

#Windows
加入系统path

#Linux
cd /usr/bin
sudo ln -s /root/Codeql/codeql/codeql codeql
source /etc/profile

检验命令行输入codeql出现如下内容就表示引擎设置完成。

SDK安装

我们使用Git下载QL语言工具包也放入/CodeQL文件夹。

git clone https://github.com/github/codeql.git

这样在/CodeQL目录下就包含了2个文件夹引擎文件夹(codeql)和SDK文件夹(ql)。

➜  CodeQL ls
codeql ql

VSCode开发插件安装命令行方法可不用

CodeQL需要使用Visual Studio Code来开发和调试规则所以我们需要在VSCode上面安装CodeQL的插件。
我们安装好Visual Studio Code后在它的扩展里面搜索codeql, 点击安装。
然后我们配置一下上面我们安装的codeql引擎路径。

到此我们就设置好了CodeQL的开发环境。

生成数据库

codeql只可以对解析引擎编译生成的数据库进行扫描所以需要先生成目标数据库。

本地生成推荐

codeql database create 数据库名 --language=cpp --source-root=源码路径 --command="编译命令"

比如现在要对xxl-job这个项目进行漏洞扫描

下载项目源码并进入该目录

#下载源代码
git clone https://gitee.com/xuxueli0323/xxl-job 

#创建源码数据库
codeql database create DatabaseName --language=java --command="mvn clean install" --source-root=D:\xxl-job 
#eg:codeql database create libtiff1_dbjob --language=cpp --command="make -j$(nproc)"

主要参数

• –command 参数如果不指定会使用默认的编译命令和参数
• –source-root 源码路径
• –overwrite 表示 create 的目标 database 对已有的 database 做覆盖
• –language 要根据具体项目的编译语言指定
  对应关系如下

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

PS–command 中指定的脚本的要求

• Confirm that there is some source code for the specified language in the project.
• For codebases written in Go, JavaScript, TypeScript, and Python, do not specify an explicit --command.
• For other languages, the --command must specify a “clean” build which compiles all the source code files without reusing existing build artefacts. 即如果项目中原本有任何编译产生的临时或最终文件都需要删除一定保证编译过程完全“ clean ”。
• 如某个项目的 build.sh

rm -r build && mkdir build
cd build && cmake .. && make -j

成功生成

线上生成

urlhttps://lgtm.com/dashboard
codeql database create openjdk8u322-db  --language=java --command='make images JOBS=4'
PS适合不需要打包的如python等    
此方法只是为了生成数据库和上述第三步一样区别只是在线生成和本地生成。

1.输入链接,点击follow生成

2.生成完成后点击下方进入下载到本地

进行项目漏洞扫描

VSCode

​ 主要参考

• 在 VSCode 打开扫描规则 CodeQL libraries and queriesql并保存工作区文件 —> 工作区另存

• VSCode 添加数据库

• 打开工作区选择要使用的扫描 CodeQL RUN Query
  

• 执行规则扫描
  右键选择具体语言的规则进行扫描例如java语言的规则。ql后缀的文件是规则扫描文件
  

• 点击 CodeQL:Run Queries in Selected Files 后弹出一个对话框选择Yes即可执行扫描操作。
  PS可以一次选择一条或者多条规则就行扫描但是一次性不能超过 20 条规则。

• 结果查看
  

命令行方法(好用)

#创建数据库
codeql database create databaseName --source-root=D:/xxljob --language=java

#更新数据库
codeql database upgrade databaseName

#执行扫描规则
codeql database analyze databasePath codeql-repo/java --format=csv --output=result.csv
#eg:codeql database analyze ./libtiff1_dbjob /root/Codeql/ql/codeql/cpp/ql/src/Security/CWE --format=csv --output=result.csv

• codeql-repo/java java 扫描规则路径
• –format结果输出格式
• –output结果文件输出路径
  

---

有感最后发现命令行真香因为可以一次性扫很多条规则但是vscode最多只支持20条而且需要手动一个个选择很麻烦。而且很多开发环境都涉及到Linux所以建议抛弃vscode直接用命令行。到这里基本上可以正常使用了~如果有问题欢迎一起来沟通

---