企业官网建设流程全解析

• 静态分析
• SAST
• 应用安全
• 漏洞扫描
• 代码质量

本指南围绕 CodeQL 仓库中actions/ql/src/Violations Of Best Practice/CodeQL/UnnecessaryUseOfAdvancedConfig.md这一查询文档展开，深入解析它背后的检测规则、源码实现与测试用例。读完本文，你将掌握：CodeQL 查询是如何识别"未使用任何自定义配置、本可直接采用默认设置（Default Setup）的 CodeQL 工作流"的，以及如何在自己的 GitHub Actions 仓库中运行并验证这条维护性最佳实践查询。

一、这条查询要解决什么问题

GitHub Code Scanning 的 CodeQL 分析有两种接入方式：默认设置（Default Setup）与高级配置（Advanced Setup）。默认设置由 GitHub 托管、几乎零配置，适合绝大多数仓库；高级配置则通过提交.github/workflows/codeql.yml之类的自定义工作流，引入github/codeql-action/init、autobuild、analyze等步骤，以获得对语言矩阵、查询集、构建逻辑的完全控制。

问题恰恰出现在"用了高级配置却没用到任何高级能力"的仓库上：工作流完整复制了模板，init步骤除了指定languages外没有设置任何其他参数，既承担了自定义工作流的维护成本，又没有享受默认设置的自动化和托管便利。

CodeQL Actions 查询包（codeql/actions-queries）中的UnnecessaryUseOfAdvancedConfig查询正是为此而生。其官方查询文档（即本指南对应的 Markdown 文件）给出了两条核心结论：

• Overview（概述）：如果 CodeQL 工作流未使用任何自定义设置，那么它可以简化——切换到 CodeQL 默认设置（Default Setup）即可。
• Recommendation（建议）：如果仓库没有必须使用自定义配置的理由，就切换到 CodeQL 默认设置。

文档同时还引用了 GitHub 官方文档《Configuring Default Setup for a repository》作为参考依据。换言之，这不是一条安全漏洞查询，而是一条维护性（maintainability）最佳实践查询，用于降低仓库中 GitHub Actions 工作流的冗余复杂度。

二、查询的元数据与定位

查询本体位于 UnnecessaryUseOfAdvancedConfig.ql，文件头部的元数据注释完整定义了它的身份：

/** * @name Workflow Should Use Default Setup * @description Workflows should use CodeQL Action with default setup instead of advanced configuration if there are no customizations * @kind problem * @problem.severity recommendation * @precision high * @id actions/unnecessary-use-of-advanced-config * @tags actions * maintainability */

这些元数据逐项说明了查询的性质：

从 qlpack.yml 可以看到，该查询隶属于名为codeql/actions-queries的查询包（extractor 为actions），默认套件文件指向codeql-suites/actions-code-scanning.qls。该查询同时被收录进安全与质量套件 actions-security-and-quality.qls——这一点可以从集成测试的期望清单 actions-security-and-quality.qls.expected 中看到它的完整路径条目得到印证。

三、检测逻辑源码级剖析

查询主体极其精简，全部核心逻辑都被抽到了共享库中：

import codeql.actions.Violations_Of_Best_Practices.DefaultableCodeQLInitiatlizeActionQuery from DefaultableCodeQLInitiatlizeActionQuery action select action, "CodeQL Action could use default setup instead of advanced configuration."

它导入共享库DefaultableCodeQLInitiatlizeActionQuery，遍历所有"可默认化"的init步骤，并输出固定消息"CodeQL Action could use default setup instead of advanced configuration."（CodeQL Action 可使用默认设置替代高级配置）。

真正的判定逻辑位于库文件 DefaultableCodeQLInitiatlizeActionQuery.qll，全文只有两个构件：

3.1 类：DefaultableCodeQLInitiatlizeActionQuery

/** * Holds if workflow step uses the github/codeql-action/init action with no customizations. * e.g. * - name: Initialize * uses: github/codeql-action/init@v2 * with: * languages: ruby, javascript */ class DefaultableCodeQLInitiatlizeActionQuery extends UsesStep { DefaultableCodeQLInitiatlizeActionQuery() { this.getCallee() = "github/codeql-action/init" and not customizedWorkflowStep(this) } }

该类的特征谓词（characteristic predicate）由两个条件组成：

1. 调用目标匹配：this.getCallee() = "github/codeql-action/init"——即该工作流步骤调用的 Action 正是github/codeql-action/init；
2. 未被自定义：not customizedWorkflowStep(this)——该步骤没有携带任何自定义参数。

只有同时满足这两点，一个init步骤才会被判定为"可以使用默认设置"。

3.2 谓词：customizedWorkflowStep

/** * Holds if the with: part of the workflow step contains any arguments for with: other than "languages". * e.g. * - name: Initialize CodeQL * uses: github/codeql-action/init@v3 * with: * languages: ${{ matrix.language }} * config-file: ./.github/codeql/${{ matrix.language }}/codeql-config.yml */ predicate customizedWorkflowStep(UsesStep codeQLInitStep) { exists(string arg | exists(codeQLInitStep.getArgument(arg)) and arg != "languages" ) }

这是整个规则最关键的细节："自定义"的判定标准是with:参数中是否存在除languages之外的任何参数。

• 查询使用exists(string arg | exists(codeQLInitStep.getArgument(arg)) and arg != "languages")遍历步骤的全部with参数；
• 只要发现任意一个参数名不等于"languages"（例如config-file、queries、packs、db-location等），customizedWorkflowStep就成立，进而init步骤不再"可默认化"，查询不会报警；
• 反过来说，只写languages（语言矩阵）的init步骤被认为是纯模板行为——语言列表本就是默认设置也能自动检测的内容，不构成"必须使用高级配置"的理由。

这个"只认 languages、其余皆自定义"的判定粒度，保证了查询的@precision high声明：只要出现任何真正的自定义痕迹，就不会误报；而完全没有自定义痕迹的模板工作流，则会被稳定地标记出来。

四、测试用例：正反两个工作流样本

查询仓库内配有完整的 QL 测试，位于 actions/ql/test/query-tests/Violations Of Best Practice/CodeQL/，包含两个工作流样本、一个.qlref引用文件和一个.expected期望输出。

4.1 反面样本（应触发告警）

defaultable_workflow.yml 是一份"照抄官方模板"的典型工作流：它配置了push、pull_request、schedule触发器，通过 matrix 指定language: ['javascript']，随后依次执行actions/checkout@v4、github/codeql-action/init@v3、autobuild@v3与analyze@v3。其中init步骤的完整写法是：

# Initializes the CodeQL tools for scanning. - name: Initialize CodeQL uses: github/codeql-action/init@v3 with: languages: ${{ matrix.language }} # If you wish to specify custom queries, you can do so here or in a config file. # By default, queries listed here will override any specified in a config file. # Prefix the list here with "+" to use these queries and those in the config file. # queries: ./path/to/local/query, your-org/your-repo/queries@main

注意queries:一行被注释掉了——with:下实际只有languages这一个参数。依据库中customizedWorkflowStep的判定，arg != "languages"无解，该步骤即被判定为"可默认化"。

期望输出文件 UnnecessaryUseOfAdvancedConfig.expected 精确记录了告警位置：

|| .github/workflows/defaultable_workflow.yml:44:9:55:6 | Uses Step | CodeQL Action could use default setup instead of advanced configuration. |

该结果行的要素包括：触发文件.github/workflows/defaultable_workflow.yml、位置区间44:9:55:6（第 44 行第 9 列起、第 55 行第 6 列止，恰好覆盖init步骤的整体范围）、元素类型Uses Step以及告警消息。.qlref文件 UnnecessaryUseOfAdvancedConfig.qlref 则把测试目录指向查询本体，供codeql test run驱动测试框架完成比对。

4.2 正面样本（不应触发告警）

should_be_using_advanced_setup.yml 则是一份"确实需要高级配置"的对照工作流，其init步骤为：

- name: Initialize CodeQL uses: github/codeql-action/init@v3 with: languages: ${{ matrix.language }} config-file: ./.github/codeql/${{ matrix.language }}/codeql-config.yml

这里出现了第二个参数config-file，指向仓库内的codeql-config.yml配置文件，并按语言（matrix.language）区分配置。由于customizedWorkflowStep在遍历参数时命中config-file，该步骤被判定为"已自定义"，因此不会被查询标记。这个文件出现在同一测试目录但从未出现在.expected结果中，正反两例共同验证了查询"只报警真正无自定义的工作流"这一行为边界。

五、如何在自己的仓库中运行这条查询

5.1 通过套件整体运行

最直接的方式是随 CodeQL Actions 查询套件一起运行。在仓库根目录执行 CodeQL CLI 即可对某一 GitHub Actions 数据库运行安全与质量套件：

codeql database create actions-db --language=actions codeql database analyze actions-db \ --format=sarif-latest --output=results.sarif \ actions/ql/src/codeql-suites/actions-security-and-quality.qls

UnnecessaryUseOfAdvancedConfig会随该套件被加载（见集成测试期望清单 actions-security-and-quality.qls.expected 中第 28 行条目）。也可以只运行代码质量相关套件或直接指定查询文件：

codeql database analyze actions-db \ --format=sarif-latest --output=results.sarif \ "actions/ql/src/Violations Of Best Practice/CodeQL/UnnecessaryUseOfAdvancedConfig.ql"

5.2 通过测试框架验证

针对该查询已有的正反样本，可以用 CodeQL 的测试机制做回归验证：

codeql test run \ "actions/ql/test/query-tests/Violations Of Best Practice/CodeQL"

测试框架会依据 UnnecessaryUseOfAdvancedConfig.qlref 找到查询，对两个工作流样本做分析，并将实际输出与 UnnecessaryUseOfAdvancedConfig.expected 逐行比对——任何输出变化都会以测试失败的形式呈现，这正是保证查询precision: high长期有效的机制。

六、实战建议：什么时候该听这条查询的

结合查询文档的建议与实现细节，可以给出如下落地方案：

1. 优先采用默认设置：新仓库或现有仓库若无特殊需求，直接在 GitHub 仓库 Settings → Code security → Code scanning 中启用 Default Setup，由 GitHub 托管 CodeQL 运行，无需维护任何工作流文件，这是文档 Recommendation 的直接落地。
2. 自查"模板病"工作流：如果仓库目前用的是从模板生成的高级配置工作流，且init步骤的with:里只有languages（其余如queries、config-file全部保持注释或未使用），就属于本查询的告警对象，可考虑删除工作流文件、切换到默认设置。
3. 保留高级配置的合法场景：查询并非要求所有仓库都放弃高级配置——只要with:中出现config-file、queries、packs等任一参数，即视为有自定义需求而放行。需要自定义查询集、编译构建或精细语言矩阵的仓库，继续使用高级配置是合理的。
4. 把维护性纳入质量门槛：这类recommendation级别的查询适合加入代码扫描的定期评估流程，配合maintainability标签在结果面板中统一筛选，持续发现"配置复杂度悄悄累积"的工作流。

一句话总结：这条查询用极简的源码实现（一个类、一个谓词）捕捉了一个高频的仓库维护性问题——高级配置一旦失去自定义内容，就应当回归默认设置；而仓库内配套的正反测试样本，则把这一最佳实践固化成了可回归、可验证的自动化规则。

• 静态分析
• SAST
• 应用安全
• 漏洞扫描
• 代码质量