[大数据] CodeQL 使用说明（一）：下载安装和执行查询语句

开发: C++知识库 Java知识库 JavaScript Python PHP知识库人工智能区块链大数据移动开发嵌入式开发工具数据结构与算法开发测试游戏开发网络协议系统运维
教程: HTML教程 CSS教程 JavaScript教程 Go语言教程 JQuery教程 VUE教程 VUE3教程 Bootstrap教程 SQL数据库教程 C语言教程 C++教程 Java教程 Python教程 Python3教程 C#教程
数码: 电脑笔记本显卡显示器固态硬盘硬盘耳机手机 iphone vivo oppo 小米华为单反装机图拉丁

-> 大数据 -> CodeQL 使用说明（一）：下载安装和执行查询语句 -> 正文阅读

[大数据]CodeQL 使用说明（一）：下载安装和执行查询语句

文章目录

CodeQL 下载

扫描引擎：

对于 CodeQL CLI 命令行工具，支持 Linux 、 Windows 或 macOS version 10.14 (“Mojave”) 及更早的版本，下载对应版本： Releases · github/codeql-cli-binaries
对于 VS Code ，可以直接在插件商店中搜索并安装 CodeQL ，一般情况插件会自动安装 CodeQL CLI 作为引擎使用

扫描规则基础库和部分规则：

CodeQL 已有的 queries 和 libraries （不包括 Go 语言， Go 语言有单独的 repo ）： github/codeql: CodeQL: the libraries and queries that power security researchers around the world, as well as code scanning in GitHub Advanced Security (code scanning), LGTM.com, and LGTM Enterprise
如果使用 VS Code 的 CodeQL 插件来执行查询，可以下载：github/vscode-codeql-starter: Starter workspace to use with the CodeQL extension for Visual Studio Code.

命令行工具+规则库可以组织为

codeql-home
  codeql-cli
  codeql-ql

用 CodeQL CLI 创建 database

创建 database

在项目主目录下创建编译命令

vi build.sh
chmod +x build.sh

生成 database ，注意 --command 中的指定的脚本的根目录和 --source-root 即项目源代码的主目录一致：

codeql database create <database_name> --source-root=<project_root_directory> --language=<language_tag> --command='<shell_executable_or_other_methods>'

如

./codeql-home/codeql-cli/codeql database create ./spdlog-1.9.2-codeqldb --source-root=./spdlog-1.9.2 --language=cpp --command='./build.sh' --overwrite

主要参数：

--source-root
--language 指明需要分析的语言，如 cpp 、 java 、 python 、 javascript 。
--command
--overwrite 表示 create 的目标 database 对已有的 database 做覆盖

对于 --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

压缩 database

如果需要压缩生成的 database 为 archive （一般是 .zip 文件），方便导入加载到 VS Code 的 CodeQL 插件中进行分析，执行

codeql database bundle <database_name> --output=<archive_target>

如

./codeql-home/codeql-cli/codeql database bundle ./spdlog-1.9.2-codeqldb --output=./spdlog-1.9.2-codeqldb.zip

用 CodeQL CLI 对 database 批量执行 queries

CodeQL 将一系列 queries 称为 suite 。 queries 、 library files 、 query suites 都要存储于一个 QL pack 中。 QL pack 的组织结构包括：一系列目录（目录下是各种 queries 文件）和一个 qlpack.yml 文件。

现在有一个 QL pack 目录，这个 pack 名字为 my-custom-queries （如果其他 pack 想要依赖于这个 pack ，则使用这个名字）。所有自定义的 queries 和 suites 都将放在这个文件夹下。

对于 suites ，创建文件夹 my-custom-query-suites ，然后在 QL pack 的根目录的 qlpack.yml 中声明

name: my-custom-queries
version: 0.0.0
libraryPathDependencies: codeql/cpp-all
suites: my-custom-query-suites

可参考默认的 cpp/ql/src 中的 qlpack.yml 文件。

最终目录结构为

my-custom-queries
    my-custom-query-categories-1
        my-custom-query-1.ql
        my-custom-query-2.ql
    my-custom-query-categories-2
        my-custom-query-3.ql
    my-custom-query-suites
        my-custom-query-suites-1.qls
        my-custom-query-suites-2.qls
    qlpack.yml

具体的 suite 文件（ .qls 文件）为

- description: xxx
- queries: <path-to-subdirectory-from-pack-directory>
  from <if-a-different-ql-pack-name>
- include:
    tags contain: security
    kind: problem
    precision: very-high
- apply: <selector.yml>
  from: <if-a-different-ql-pack-name>

注意 queries 后面的相对路径是从 qlpack.yml 文件位置开始计算。

执行一个 query 或一个 suite （其他参数如多线程等请参考 codeql database analyze -h )

codeql database analyze <database_name> [<query|dir|suite|pack>...] --format=<format> --output=<query_results>

如

./codeql-home/codeql-cli/codeql database analyze ./spdlog-1.9.2-db ./codeql-home/codeql-ql/cpp/ql/src/Best\ Practices/RuleOfTwo.ql --format=csv --output=./RuleOfTwo.csv
./codeql-home/codeql-cli/codeql database analyze --threads 16 ./spdlog-1.9.2-db ./codeql-home/codeql-ql/cpp/ql/src/codeql-suites/cpp-security-extended.qls --format=csv --output=./cpp-security-extended.csv
./codeql-home/codeql-cli/codeql database analyze --threads 16 ./spdlog-1.9.2-db ./codeql-home/codeql-ql/cpp/ql/src/codeql-suites/my-custom-security-suite.qls --format=csv --output=./my-custom-security.csv

其中 my-custom-security-suite.qls 可以为

- description: All CWE queries
- queries: Security

注意有时候执行的一个 suite 中包含的 query 太多，可能造成 Java 堆内存不足，可以考虑增加堆内存或者分批执行。

附 CodeQL CLI 常用帮助命令

codeql -h
codeql database -h
codeql database create -h
codeql database bundle -h
codeql database analyze -h
codeql query -h

用 CodeQL for VS Code 分析 database

安装 CodeQL 插件后，支持功能：

导入 database
query 文件中右键执行查询，可以在某个 database 上，或多个 database 上执行
query 文件中测试部分查询语句—— quick evaluation 功能
保存 query history
代码右键直接查看 AST

为 CodeQL 插件设置需要的 CodeQL CLI

有时候 VS Code 安装 CodeQL 插件后自动下载 CodeQL CLI 不成功，这时候可以手动指定 CodeQL CLI 的位置。选择 Extensions -> 右键点击 CodeQL -> Extension Settings -> 填写 CodeQL CLI 的执行地址，地址填写到 codeql.exe 或 codeql 可执行文件这一级。