CodeQL 白盒代码审计实战指南

一、CodeQL 简介

CodeQL 是一个开源的代码分析平台和漏洞扫描工具，它通过以下方式工作：

1. 对于编译型语言：介入代码编译过程
2. 对于解释型语言：进行静态程序分析
3. 获取程序代码的语义信息(Extractor)
4. 生成数据库(CodeQL Database)
5. 使用专用语言(QL language)编写查询语句来发现漏洞风险

二、CodeQL 安装

1. 解析引擎安装

1. 官方下载地址：CodeQL CLI
2. 解压到名为CodeQL的文件夹
3. 配置codeql路径到环境变量
4. 命令行输入codeql验证是否安装成功

2. SDK安装

1. 官方下载地址：CodeQL SDK
2. 解压到CodeQL文件夹内
3. 在SDK路径下执行codeql pack ls查看默认支持的规则集

三、VSCode 配置

1. 安装CodeQL插件
2. 配置引擎路径
   • 打开VSCode设置
   • 搜索"CodeQL"
   • 设置"CodeQL > Cli: Executable Path"为CodeQL引擎路径

四、数据库生成

1. 基本命令

codeql database create db-ql --language=java --command="mvn clean install"

2. 主要参数

• --command: 编译命令和参数(不指定则使用默认)
• --source-root: 源码路径
• --overwrite: 覆盖已有database
• --language: 指定语言

3. 语言对应关系

4. 常见问题解决

问题: "A fatal error occurred: Exit status 1 from command..."
原因: 找不到mvn命令
解决方案: 安装Maven并验证mvn -v命令可用

五、VSCode中使用CodeQL

1. 添加数据库

   • 点击CodeQL插件中的"Add Database"
   • 选择生成的db-ql文件夹

2. 打开扫描规则

   • 在VSCode中打开SDK解压后的包
   • 规则文件路径示例：codeql-main/java/ql/src/Security/CWE

3. 执行扫描

   • 选择一条或多条规则(不超过20条)
   • 右键点击"CodeQL:Run Queries in Selected Files"
   • 选择"Yes"执行扫描
   • 查看右侧扫描结果

六、命令行方式使用

1. 创建数据库

codeql database create databaseName --source-root=D:/xxljob --language=java

示例：

codeql database create /Users/zangcc/Desktop/CodeQL/databases/codeql_demo \
--language="java" \
--command="mvn clean install -DskipTests --file pom.xml" \
--source-root=/Users/zangcc/Desktop/CodeQL/micro_service_seclab

2. 更新数据库

codeql database upgrade databaseName

3. 执行扫描规则

codeql database analyze databasePath codeql-repo/java --format=csv --output=result.csv

参数说明：

• databasePath: 数据库路径
• codeql-repo/java: Java扫描规则路径
• --format: 结果输出格式
• --output: 结果文件输出路径

七、实战案例

以Java靶场项目java-sec-code为例：

1. 下载靶场源代码
2. 创建数据库：

   codeql database create db-ql --language=java --command="mvn clean install"
   

3. 在VSCode中添加数据库
4. 选择Java安全规则进行扫描
5. 分析扫描结果

八、最佳实践

1. 对于大型项目，建议分批执行规则扫描
2. 定期更新CodeQL引擎和SDK以获取最新规则
3. 对于自定义项目，可以编写特定QL查询规则
4. 结合CI/CD流程实现自动化代码审计

九、总结

CodeQL作为强大的静态代码分析工具，通过将代码视为数据，能够高效地发现安全漏洞和代码缺陷。掌握CodeQL的使用方法，可以显著提升白盒审计的效率和准确性。