S4Plus/QLStat

# QLStat 利用 CodeQL 提供的声明式静态分析功能对批量真实世界项目进行分析，以服务于实证研究和统计分析，从而深入洞察真实项目中的模式。 ## 功能概述 QLStat 提供了一个全面的框架，利用 CodeQL 对软件项目进行大规模实证分析。主要功能包括： - **批处理**：并行克隆、构建和分析多个代码仓库 - **灵活配置**：基于 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`：配置构建组，包括超时时间、构建命令和可选的 extgen 脚本 - `queryconfig`：设置带有并行化选项的查询执行 - `queryGrps`：使用特定的查询和目标代码仓库定义查询组 ### 2. 创建数据库 运行 `go run ./cmd/batch_clone_build stat.yaml` 以克隆代码仓库并创建 CodeQL 数据库： ``` go run ./cmd/batch_clone_build stat.yaml ``` 主要选项： - `-noclone`：如果代码仓库已存在，则跳过克隆 - `-nobuild`：如果数据库已存在，则跳过数据库创建 - `-noextgen`：跳过外部谓词的生成 该工具支持三个主要阶段： 1. **克隆**：从指定来源下载代码仓库 2. **构建**：使用适当的构建命令创建 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 的构建组中配置 `extgenScript: goescape`（其中 `goescape` 运行 `go build -a -gcflags=all=-m=2 .`）。 - 您也可以指定自己的脚本，只要它在 `$logRoot/extgen/path/to/repo/m2.log` 中生成 `m2.log` 即可。 2. 这会在构建阶段生成逃逸分析数据。 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)。 # 引用 ``` @software{Li_QLStat, author = {Li, Qingwei and Ding, Boyao and Zhang, Yu and Chen, Jinbao}, license = {Apache-2.0}, title = {{QLStat}}, url = {https://github.com/s4plus/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工具, 云安全监控, 代码分析, 代码示例, 凭证管理, 安全评估工具, 数据分析, 日志审计, 防御机制, 静态分析