Lslightly/QLStat

# QLStat 利用 CodeQL 提供的声明式静态分析技术，对大量真实世界项目进行批量分析，用于实证研究与统计分析，从而深入洞察真实世界项目中的模式。 ## 功能概述 QLStat 提供了一个基于 CodeQL 进行软件项目大规模实证分析的综合性框架。主要功能包括： - **批量处理**：并行执行多个仓库的 clone、build 和分析 - **灵活配置**：基于 YAML 的配置方式，用于定义分析目标与参数 - **可扩展分析**：支持自定义的外部谓词（例如，逃逸分析数据） - **可扩展的查询执行**：跨多个仓库并行执行 CodeQL 查询 - **全面的日志记录**：在分析 pipeline 的各个阶段提供详细的日志 - **数据收集**：将多个仓库的分析结果聚合为统一的数据集 - **语言支持**：目前专注于 Go 语言，并具备扩展至 CodeQL 支持的其他语言的能力 ## 设置 - 安装 [CodeQL CLI](https://docs.github.com/en/code-security/how-tos/scan-code-for-vulnerabilities/scan-from-the-command-line/setting-up-the-codeql-cli#1-download-the-codeql-cli-tar-archive) 并将 codeql 添加到你的 PATH 中。 - 安装 [Go](https://go.dev/dl/)。 ## 演示 - [`demo.sh`](./demo.sh)：一个用于在示例配置文件上运行 QLStat 的演示脚本。 - 结果保存在 `./codeqlResult/escape_ext/heapvar_should_move` 中。你可以找到分配在堆上的优化变量。 - [`demo.yaml`](./demo.yaml)：演示 QLStat 用法的示例配置文件。 ## 使用说明 ### 1. 配置 参照 [`example.yaml`](./example.yaml)、[`demo.yaml`](./demo.yaml) 或 [`yaml-examples/`](./yaml-examples/) 目录下的 YAML 文件，创建你的 `stat.yaml` 配置文件。该配置支持以下几个关键部分： - `repositories`：通过 URL 前缀和可选的目录结构定义代码仓库 - `language`：指定用于分析的编程语言（例如：go） - `buildGrps`：配置 build 组，包含超时时间、build 命令以及可选的 extgen 脚本 - `queryconfig`：设置查询执行及其并行化选项 - `queryGrps`：定义查询组，包含特定的查询和目标仓库 ### 2. 创建数据库 运行 `go run ./cmd/batch_clone_build stat.yaml` 来 clone 仓库并创建 CodeQL 数据库： ``` go run ./cmd/batch_clone_build stat.yaml ``` 主要选项： - `-noclone`：如果仓库已存在，则跳过 clone - `-nobuild`：如果数据库已存在，则跳过数据库创建 - `-noextgen`：跳过外部谓词的生成 该工具支持三个主要阶段： 1. **Cloning**：从指定的数据源下载仓库 2. **Building**：使用相应的 build 命令创建 CodeQL 数据库 3. **外部谓词生成**：生成如逃逸分析结果等额外的数据源 ### 3. 查询开发 在 [`qlsrc`](./qlsrc/) 目录中创建你的查询。查询应遵循 CodeQL 规范，并可在需要时利用外部谓词。 ### 4. 查询执行 运行 `go run ./cmd/codeql_qdriver -collect stat.yaml` 在创建好的数据库上执行查询： ``` go run ./cmd/codeql_qdriver -collect stat.yaml ``` 可用选项： - `-format`：指定输出格式（text, csv, json, bqrs） - 默认：csv - `-decode-only`：仅解码现有的 bqrs 文件，而不运行查询 - `-collect`：将所有 CSV 结果收集到一个单独的文件中，并附带仓库名称 结果处理分为三个阶段： 1. **查询执行**：在每个数据库上运行 CodeQL 查询 2. **解码**：将 bqrs 结果转换为指定格式（CSV、JSON 等） 3. **收集**：将所有仓库的结果聚合到一个单一的数据集中 ## 扩展 ### Go 逃逸分析扩展 QLStat 支持通过 escape adapter 利用逃逸分析数据来扩展 CodeQL： 1. 在 YAML 文件的 build 组中配置 `extgenScript: goescape`（其中 `goescape` 会运行 `go build -a -gcflags=all=-m=2 .`）。 - 你也可以指定自己的脚本，只要它能在 `$logRoot/extgen/path/to/repo/m2.log` 中生成 `m2.log` 即可。 2. 这将在 build 阶段生成逃逸分析数据。 3. 在你的查询组中通过 `externals: [movedToHeap, newEscapesToHeap]` 引用外部谓词。 4. 在你的 CodeQL 查询中使用该外部谓词。 关于逃逸分析扩展工作原理的更多细节，请参阅[逃逸分析文档](doc/adapters/escape_analysis.md)。 ## 架构 有关存储结构和架构的详细信息，请参阅[架构文档](doc/arch.md)。 # 贡献 欢迎任何贡献！如果你在使用 QLStat 时遇到任何问题，或者有任何改进的想法，欢迎提交 [Issue](https://github.com/Lslightly/QLStat/issues) 或发起 [Pull Request](https://github.com/Lslightly/QLStat/pulls)。 # 引用 ``` @misc{qlstat, author = {Qingwei Li}, title = {QLStat}, howpublished = {\url{https://github.com/Lslightly/QLStat}}, } @article{li2026empiricalMemPerfSafetyGo, title = {Go语言程序的内存性能与安全问题实证研究}, author = {李清伟 and 丁伯尧 and 张昱 and 陈金宝}, journal = {软件学报}, volume = {37}, number = {3}, pages = {1197}, numpages = {28}, year = {2026}, doi = {10.13328/j.cnki.jos.007464}, publisher = {科学出版社} } ```

标签：CodeQL, Go, Ruby工具, 云安全监控, 安全评估工具, 批处理, 数据管道, 日志审计, 软件工程, 防御机制, 静态分析