CodeQL自定义查询包创建与多场景使用技术咨询

我正在学习CodeQL，针对团队的Java库写了几个自定义查询，在VSCode里单个运行正常，想放到GitHub Workflow里用。知道要建query pack或query suite，但搞不清区别。看CodeQL CLI文档没找到怎么用命令行跑查询包，github/codeql-action的资料里好像要逐个列查询，肯定有更高效的方法。想先本地测试再推仓库，当前目录结构：

my-codeql-queries/
+ query1.ql
+ query2.ql
+ query3.ql
+ queries.xml
+ qlpack.yml

queries.xml内容：

<queries language="java"/>

qlpack.yml内容：

name: my-codeql-queries
version: 1.0.0
dependencies:
  codeql/java-all: "*"
suites: my-codeql-queries

咨询以下问题：

1. 如何创建CodeQL查询包，并使用CodeQL CLI从命令行运行它；
2. 如何借助github/codeql-action在GitHub Workflow中运行该查询包；
3. 为了让查询包可复用并能被其他仓库及GitHub Workflow导入，Git仓库应采用何种目录结构；
4. 这些查询是否需要编译？若需要，该如何操作？

1. 创建查询包并通过CodeQL CLI运行 #

你当前的qlpack.yml已经具备查询包的基础框架，只需补充完善配置并定义查询套件即可：

先明确两个概念 #

• 查询包（Query Pack）：带qlpack.yml配置的独立目录，包含查询、套件、依赖声明，是打包分发查询的基本单元。
• 查询套件（Query Suite）：.qls或.xml格式的文件，用来批量组织要运行的查询集合，属于查询包的一部分。

步骤1：完善查询包配置 #

更新qlpack.yml，明确这是查询包而非库包：

name: my-codeql-queries
version: 1.0.0
dependencies:
  codeql/java-all: "*"
library: false  # 标记为查询包，默认true是库包

步骤2：定义查询套件 #

创建my-codeql-queries.qls文件（和qlpack.yml同目录），指定要运行的查询：

name: "my-codeql-queries"
description: "Custom queries for our team's Java library"
queries:
  - ./query1.ql
  - ./query2.ql
  - ./query3.ql

如果想用queries.xml，可以修改为：

<queries language="java">
  <include>query1.ql</include>
  <include>query2.ql</include>
  <include>query3.ql</include>
</queries>

然后在.qls套件文件里引用这个xml：

name: "my-codeql-queries"
description: "Custom queries for our team's Java library"
queries:
  - ./queries.xml

步骤3：本地CLI运行 #

先确保已生成目标Java项目的CodeQL数据库（未生成则用codeql database create <数据库路径>命令），然后执行：

# 假设目标数据库路径为../my-java-project-db
codeql database analyze ../my-java-project-db --format=sarif-latest --output=results.sarif my-codeql-queries:my-codeql-queries

格式说明：查询包名:套件名，若套件与包同名，也可直接写包名，但明确指定套件更清晰。

2. 在GitHub Workflow中用codeql-action运行查询包 #

无需逐个列出查询，直接引用查询包的套件即可，Workflow示例：

name: CodeQL Custom Queries
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout target code
        uses: actions/checkout@v4

      # 若查询包在外部仓库，需先拉取；同仓库则跳过此步骤
      - name: Checkout custom queries
        uses: actions/checkout@v4
        with:
          repository: your-org/my-codeql-queries
          path: my-codeql-queries

      - name: Initialize CodeQL
        uses: github/codeql-action/init@v3
        with:
          languages: java
          # 引用查询包套件
          queries: ./my-codeql-queries:my-codeql-queries

      - name: Autobuild
        uses: github/codeql-action/autobuild@v3

      - name: Perform CodeQL Analysis
        uses: github/codeql-action/analyze@v3

3. 可复用的查询包Git仓库结构 #

要让查询包能被其他仓库轻松复用，建议采用标准化结构：

my-codeql-queries-repo/
+ java/  # 按语言分目录，方便扩展多语言查询
  + query1.ql
  + query2.ql
  + query3.ql
  + my-codeql-queries.qls  # 套件定义文件
  + qlpack.yml  # Java查询包的配置文件
+ README.md  # 说明查询用途、使用方法
+ .github/
  + workflows/
    + test-queries.yml  # 自身测试Workflow，确保查询可用

每个语言目录下单独放置查询和对应的qlpack.yml，符合CodeQL包规范，其他仓库可通过checkout拉取，或发布到CodeQL包注册表后直接引用。

4. 查询是否需要编译？ #

CodeQL查询不需要手动编译，运行codeql database analyze或通过action执行时，CodeQL会自动处理编译和执行流程。

如果想提前验证查询语法正确性，可使用CLI命令：

codeql query compile query1.ql

该命令会生成编译后的.qlx文件，但实际运行时无需手动执行此步骤。

内容的提问来源于stack exchange，提问作者carlspring