CodeQL学习——CodeQL CLI入门

一、CodeQL 工作流程

CodeQL 的整体工作流程如下图所示:
codeql_workflow
(图片来源:https://blog.semmle.com/introduction-to-variant-analysis-part-2/)

CodeQL 的整体思路是把源代码转化成一个可查询的数据库,通过 Extractor 模块对源代码工程进行关键信息分析提取,构成一个关系型数据库。CodeQL 的数据库并没有使用现有的数据库技术,而是一套基于文件的自己的实现。

对于编译型语言,Extractor 会监控编译过程,编译器每处理一个源代码文件,它都会收集源代码的相关信息,如:语法信息(AST 抽象语法树)、语意信息(名称绑定、类型信息、运算操作等),控制流、数据流等,同时也会复制一份源代码文件。而对于解释性语言,Extractor 则直接分析源代码,得到类似的相关信息。

关键信息提取完成后,所有分析所需的数据都会导入一个文件夹,这个就是 CodeQL database, 其中包括了源代码文件、关系数据、语言相关的 database schema(schema 定义了数据之间的相互关系)。

接下来就可以对数据库进行查询了,CodeQL 自己定义实现了一套名为 QL 的查询语言,并提供了相应的支持库和运行环境。

最终将查询结果展示给用户,方便用户进行进一步的人工审计分析。

二、CodeQL CLI 安装和配置

1.下载CodeQL CLI 压缩包

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

2.创建CodeQL目录,如$HOME/codeql-home

3.创建CodeQL查询的本地拷贝

 

CodeQL仓库包含分析C/C++, C#, Java, JavaScript、python等所需的查询和库文件。需要拷贝一份仓库到codeql-home目录,重命名仓库文件夹为codeql-repo

仓库下载地址:https://github.com/github/codeql

  • go的仓库地址:https://github.com/github/codeql-go/
  • 假设CodeQL仓库目录为$HOME/codeql-home/codeql-repo,那么go的仓库目录可以设置为$HOME/codeql-home/codeql-go

4.解压CodeQL CLI 压缩包$HOME/codeql-home目录

5.运行CodeQL

(1)通过直接执行$HOME/codeql-home/codeql/codeql来运行CodeQL

(2)将$HOME/codeql-home/codeql目录添加到环境变量

三、创建CodeQL数据库

命令:

codeql database create <database> --language=<language-identifier>

参数说明:

<database>:创建的数据库的路径,必须是不存在的文件夹

--language:如下

 

C/C++ cpp
C# csharp
Go go
Java java
JavaScript/TypeScript javascript
Python python

其它参数:

--source-root 指定数据库创建时的源文件根目录,默认为当前目录。

--command 指定语言的编译命令,不要给python和JavaScript指定该命令。

非编译型语言创建数据库

codeql database create --language=javascript --source-root <folder-to-extract> <output-folder>/javascript-database

四、使用CodeQL CLI分析数据库

命令:

codeql database analyze <database> <queries> --format=<format> --output=<output>

参数说明:

<database> 预分析的数据库路径

<queries> 要在数据库上运行的查询。可以指定一个或多个单独的查询文件,指定将以递归方式搜索查询文件的目录,或者命名定义了一组特定查询的查询套件。

--format  分析生成的结果文件的文件格式

--output  分析结果的输出路径

还可以通过--threads指定运行查询时要使用的线程数。默认选项是1

 

示例:

codeql database analyze <javascript-database> ../ql/javascript/ql/src/Declarations/UnusedVariable.ql --format=csv --output=js-analysis/js-results.csv

上述分析的结果会在新创建的文件夹js-analysis下的js-results.csv文件中输出

运行目录中的所有查询

我们可以通过提供目录路径来运行目录中的所有查询,而没必要列出目录中的所有单个查询文件。由于是通过递归搜索读取查询文件的,因此子文件夹中包含的所有查询也将被执行。

重要

您不应在执行database analyze时指定QL pack的根目录, 因为它包含一些并非为命令使用而设计的特殊查询。如果要运行更多的有用的查询,请选择LGTM.com查询套件之一。

例如,要执行Functions 目录中包含的所有Python查询,您将运行:

codeql database analyze <python-database> ../ql/python/ql/src/Functions/ --format=sarif-latest --output=python-analysis/python-results.sarif

会生成一个SARIF结果文件。通过--format=sarif-latest可确保结果根据CodeQL支持的最新SARIF规范进行格式化。

结果

您可以将分析结果保存为多种不同格式,包括SARIF和CSV。

SARIF(数据分析结果交换格式)是定义输出文件格式的OASIS 标准。 SARIF 标准用于简化静态分析工具分享其结果的方式。 有关更多信息,请参见SARIF概述

如果将分析结果输出到CSV文件,则输出的每条告警将包含以下信息:

名称 标识结果的查询名称。 Inefficient regular expression
描述 查询的描述。 regular expression that requires exponential time to match certain inputs can be performance bottleneck, and may be vulnerable to denial-of-service attacks.
严重程度 查询的严重性。 error
信息 告警消息。 This part of the regular expression may cause exponential backtracking on strings containing many repetitions of '\\\\'.
路径 包含告警的文件的路径。 /vendor/codemirror/markdown.js
起始行 触发告警的代码开始的文件行。 617
开始列 起始行的列,用于标记告警代码的开始。第一列不包括在内。 32
结束行 触发告警的代码结束的文件行。与起始行相同时不包括在内。 64
结束列 可能的话,在结束行的列中标记告警代码的结尾。否则,将重复结束行。 617

结果文件可以集成到您自己的代码审查或调试设施中。例如,借助IDE的SARIF文件查看插件查看输出的SARIF文件时,可以让告警在源代码中突出显示。

posted @ 2020-08-22 16:17  bamb00  阅读(2651)  评论(0编辑  收藏  举报