CodeQL

← 返回目录 > ← 返回总览

工具	说明
Bandit	Python 专用安全漏洞检测工具，轻量快速
Gosec	Go 语言安全静态分析工具
Gitleaks	Git 仓库中的密钥和凭证泄露检测
Detect-Secrets	Yelp 开源的密钥泄露检测工具
ShellCheck	Shell 脚本静态分析工具
Clang-Tidy	C/C++ 静态分析工具，支持安全相关检查
Semgrep	基于模式匹配的多语言安全分析工具

1. 简介

CodeQL 是 GitHub 开发的语义代码分析引擎，其前身是 Semmle 公司的 Semmle QL 技术。2019 年 GitHub 收购 Semmle 后将其开源，成为 GitHub Advanced Security（GHAS）的核心组件。CodeQL 的核心理念是"代码即数据"（Code as Data）——将源代码转换为包含抽象语法树（AST）、控制流图（CFG）和数据流图（DFG）的可查询关系型数据库，然后通过声明式 QL 查询语言进行深度语义分析。

与基于正则表达式或简单语法树匹配的传统静态分析工具不同，CodeQL 支持跨函数、跨文件的数据流追踪与上下文感知分析，能够精准识别 SQL 注入、XSS、反序列化、命令注入等复杂安全漏洞。

主要检查语言：C/C++、C#、Go、Java、Kotlin、JavaScript/TypeScript、Python、Ruby、Swift、Rust、GitHub Actions
主要检查能力：多语言语义代码分析，检测安全漏洞和代码质量问题；涵盖安全类检查（主要）、代码质量检查（辅助）
核心检查原理：基于 QL 声明式查询语言，支持数据流分析、污点追踪、控制流分析
检查规则/选项：规则以 query packs 按语言分发，通过 .qls 查询套件组合使用；内置 code-scanning（默认）、security-extended、security-and-quality 等套件，支持自定义查询，查询规则全集（按语言分类，含每条规则的元数据、所属套件和漏洞说明）
GitHub 仓库：https://github.com/github/codeql（9,904 stars）
开源协议：查询库和标准库开源（MIT），分析引擎为专有二进制发布
最新稳定版本：v2.26.1
运行环境要求：需 CodeQL CLI；GitHub Actions 集成需 codeql-action
误报率：低

CodeQL 是 GitHub 代码扫描（Code Scanning）的事实标准引擎。对于托管在 GitHub 上的项目，CodeQL 通过 codeql-action 提供了最成熟的集成方案；对于非 GitHub 环境，CodeQL CLI 支持在任何 CI/CD 系统中运行。

2. 官方文档

文档名称	链接
CodeQL 官方文档首页	CodeQL Documentation
查询规则全集（按语言）	CodeQL Query Help
支持的语言和框架	Supported Languages and Frameworks
GitHub Actions 代码扫描	Configuring Advanced Setup
CodeQL CLI 使用	Scan from the Command Line
CodeQL for VS Code	CodeQL for Visual Studio Code
CodeQL CLI bundle 下载	CodeQL Action Releases

3. 社区优秀实践

3.1 GitHub 产品安全团队 -- 超大规模代码审计体系

GitHub 产品安全工程团队在超过 10,000 个仓库中使用 CodeQL 进行安全防护，是业界最权威的 CodeQL 企业级实践案例。GitHub 官方工程博客详细记录了其 CodeQL 落地策略。

仓库：github/codeql
实践文章：How GitHub uses CodeQL to secure GitHub
核心做法：
- 默认设置（Default Setup）满足大部分仓库需求，PR 自动获得 CodeQL 安全扫描
- 大型单体应用（如 Ruby 单体）使用高级设置配合自定义查询包
- 将自定义查询包发布到 GitHub Container Registry（GCR），实现快速迭代和回滚
- 使用多仓库变种分析（MRVA）进行漏洞变体分析和快速审计
- 使用 codeql-pack.lock.yml 锁定依赖版本，避免 CI 中因库 API 变更导致查询失败
- 为自定义查询编写单元测试，确保查询稳定性和可靠性

3.2 GitHub Security Lab -- 安全研究与开源查询

GitHub Security Lab 持续贡献高质量的 CodeQL 查询，覆盖 OWASP Top 10、CWE 标准等常见漏洞模式，并发布安全研究博客展示如何使用 CodeQL 发现真实漏洞。

仓库：GitHubSecurityLab
核心做法：
- 发布针对最新 CVE 的 CodeQL 查询
- 使用 CodeQL 进行 0day 漏洞挖掘和变种分析
- 发布大量开源查询供社区使用

4. 工具配置说明

4.1 配置文件说明

CodeQL 有多种使用方式（GitHub Actions、CLI、IDE 插件），底层均基于相同的查询包和查询套件机制。本章介绍这些跨场景通用的底层配置文件，各集成方式特有的配置（如 Actions 工作流、CLI 命令参数）在第 5 章说明。

配置文件	用途	适用场景
`codeql-config.yml`	扫描行为配置（路径、查询包、查询过滤）	GitHub Actions（`config-file`）、CLI（`--codescanning-config`）
`qlpack.yml`	自定义查询包定义	所有场景（Actions、CLI、IDE）
`.qls`	查询套件定义文件	所有场景（Actions、CLI、IDE）

4.2 codeql-config.yml 配置详解

codeql-config.yml 是 CodeQL 代码扫描的行为配置文件，控制扫描路径、查询包选择和查询过滤。在 GitHub Actions 中通过 codeql-action/init 的 config-file 参数引用（见 5.1 GitHub Actions），在 CLI 中通过 codeql database create 的 --codescanning-config 参数引用（见 5.4 CodeQL CLI）。

配置项说明：

配置项	类型	说明
`name`	string	配置名称，用于标识
`paths`	string[]	要扫描的目录或文件路径列表
`paths-ignore`	string[]	排除扫描的路径列表，支持 glob 模式
`packs`	map	按语言指定 CodeQL 查询包，键为语言标识符（如 `python`、`javascript`），值为查询包列表
`queries`	list	额外查询，每项含 `uses`（可引用查询套件名称、`.ql` 文件路径或 QL pack）
`query-filters`	list	查询过滤器，支持 `exclude`（排除指定查询 ID）和 `include`（强制包含指定查询 ID）

配置示例：

# .github/codeql/codeql-config.yml
name: "CodeQL Configuration"

paths:
  - src
  - lib

paths-ignore:
  - "**/test/**"
  - "**/vendor/**"

packs:
  python:
    - codeql/python-queries
  java:
    - codeql/java-queries

queries:
  - uses: security-extended
  - uses: ./my-custom-queries/hardcoded-password.ql

query-filters:
  - exclude:
      id: js/redundant-assignment

通过 paths 和 paths-ignore 限制扫描范围可减少分析时间，更多路径过滤模式见官方文档。

官方文档：Custom Configuration Files、Specifying Directories to Scan

4.3 qlpack.yml 配置（自定义查询包）

如果需要编写自定义 CodeQL 查询，可以创建查询包：

# my-custom-queries/qlpack.yml
name: my-org/custom-security-queries
version: 1.0.0
library: false
dependencies:
  codeql/python-all: "*" # 依赖 Python 标准库

自定义查询示例（检测硬编码密码）：

// my-custom-queries/hardcoded-password.ql
import python

from StringLiteral s
where s.getValue().matches("%password%") and
      s.getValue().regexpMatch("[\"'][^\"']+[\"']") and
      not s.getLocation().getFile().getBaseName().matches("%test%")
select s, "Possible hardcoded password detected."

4.4 查询套件（.qls 文件）

查询套件是 .qls 格式的 YAML 文件，用于将多个查询组合为命名套件，避免逐个指定查询文件路径。通过查询套件，可以用一个名称引用一组查询，简化 CI 配置和命令行调用。

.qls 文件结构

.qls 文件由一系列 YAML 指令组成，每条指令含单个键，常用指令如下：

指令	作用
`description`	套件的文本描述
`queries`	指定查询文件或目录（`.` 表示当前目录下所有查询）
`apply` + `from`	引入选择器（selector）或另一个 `.qls` 文件，`from` 指定来源包
`include` / `exclude`	按 `query path`、`tags` 等条件包含或排除查询

以 cpp-security-extended.qls 为例：

- description: Security-extended queries for C and C++
- queries: .
- apply: security-extended-selectors.yml
  from: codeql/suite-helpers
- apply: codeql-suites/exclude-slow-queries.yml

该文件的含义：从当前目录所有查询中，通过 security-extended-selectors.yml 选择器筛选出扩展安全查询，再应用 exclude-slow-queries.yml 排除慢查询。

用户也可创建自定义查询套件，将自定义 .ql 查询文件组合使用：

# my-custom-queries/custom-security-suite.qls
- description: "Custom security queries for Python"
  queries:
    - hardcoded-password.ql
    - sql-injection-custom.ql
    - unsafe-deserialization.ql

内置查询套件

CodeQL 在 github/codeql 仓库中内置了两类查询套件，按语言维度划分，分别存放在不同目录下。

多语言通用查询套件

位于 unified/ql/src/codeql-suites/ 目录，命名前缀为 unified-，跨所有支持语言通用。这些套件不绑定特定语言，适用于多语言混合项目或需要统一查询标准的场景：

查询套件	检查范围
`unified-code-scanning.qls`	高精度安全查询（CWE 漏洞检测），GitHub 代码扫描默认套件，误报率低
`unified-security-extended.qls`	在 code-scanning 基础上增加精度和严重性较低的安全查询，覆盖更多潜在漏洞
`unified-security-and-quality.qls`	在 security-extended 基础上增加代码质量查询（可维护性、可靠性问题）
`unified-security-experimental.qls`	在 security-extended 基础上增加实验性安全查询，含开发中的新查询，误报率较高
`unified-code-quality.qls`	仅代码质量查询（死代码、复杂度、可维护性问题），不含安全查询
`unified-code-quality-extended.qls`	在 code-quality 基础上增加扩展代码质量查询，覆盖更多质量维度

指定语言查询套件

位于 <语言>/ql/src/codeql-suites/ 目录，命名前缀为 <语言>-（如 cpp-、python-、java-），针对特定语言定制。以 C/C++ 为例，cpp/ql/src/codeql-suites/ 目录下的内置套件：

查询套件	检查范围
`cpp-code-scanning.qls`	高精度安全查询（CWE 漏洞检测），GitHub 代码扫描默认套件，误报率低；排除慢查询
`cpp-security-extended.qls`	在 code-scanning 基础上增加精度和严重性较低的安全查询，覆盖更多潜在漏洞；排除慢查询
`cpp-security-and-quality.qls`	在 security-extended 基础上增加代码质量查询（可维护性、可靠性问题）；排除慢查询
`cpp-security-experimental.qls`	在 security-extended 基础上增加实验性安全查询，含开发中的新查询，误报率较高；排除慢查询
`cpp-code-quality.qls`	仅代码质量查询（死代码、复杂度、可维护性问题），不含安全查询
`cpp-code-quality-extended.qls`	在 code-quality 基础上增加扩展代码质量查询，覆盖更多质量维度
`cpp-lgtm.qls`	LGTM 平台默认展示的查询（lgtm-full 的子集），兼容旧版 LGTM 平台
`cpp-lgtm-full.qls`	LGTM 全量查询，含默认不展示的查询和实验性查询，覆盖最全面；排除慢查询和 IDE 专用查询
`exclude-slow-queries.yml`	慢查询排除配置（非 `.qls` 套件），供上述安全类套件引用，排除大型项目中计算成本过高的资源泄漏类查询

指定语言套件比通用套件多了 lgtm 系列和 exclude-slow-queries.yml 等语言专属配置。其他语言（Python、Java 等）的目录结构和命名规则与 C/C++ 相同，仅语言前缀不同。

使用方式

在 codeql-config.yml 中通过 queries 字段引用查询套件（见 4.2）：

queries:
  - uses: security-extended

在 GitHub Actions 工作流中通过 queries 参数指定：

- uses: github/codeql-action/init@v4
  with:
    queries: security-extended

在 CLI 中通过 codeql database analyze 引用 .qls 文件路径：

codeql database analyze ./codeql-db \
  --format=sarif-latest --output=results.sarif \
  codeql/cpp-queries:codeql-suites/cpp-security-and-quality.qls

官方文档：Built-in CodeQL query suites、CodeQL query suites 仓库

5. 主流集成方式

CodeQL 是跨语言的安全分析工具，不绑定特定语言的构建工具链。其集成方式按生态主流排序如下：

各集成方式对第 4 章底层配置的引用关系：

集成方式	使用的第 4 章配置	特有配置
GitHub Actions（5.1）	`codeql-config.yml`（4.2）、查询套件（4.4）、自定义查询包（4.3）	工作流 YAML 文件
pre-commit（5.2）	查询套件（4.4）	`.pre-commit-config.yaml` 钩子定义
IDE 插件（5.3）	自定义查询包（4.3）、查询套件（4.4）	VS Code 扩展设置
CLI（5.4）	`codeql-config.yml`（4.2）、查询套件（4.4）、自定义查询包（4.3）	命令行参数

5.1 GitHub Actions（推荐方式，生态主流）

GitHub Actions 是 CodeQL 最原生的集成方式，通过官方 codeql-action 实现。对于托管在 GitHub 上的项目，这是业界主流的 CodeQL 使用方式。

方式一：默认设置（快速启用）

在仓库的 Settings > Code security and analysis 中，点击 "Set up code scanning"，选择 "CodeQL analysis" 即可一键启用。GitHub 会自动创建工作流文件，无需手动配置。

方式二：高级设置（自定义工作流）

# .github/workflows/codeql.yml
name: "CodeQL Advanced Setup"

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
  schedule:
    - cron: "30 1 * * 0" # 每周日凌晨 1:30 UTC 扫描
  merge_group: # 支持合并队列

permissions:
  security-events: write
  actions: read
  contents: read

jobs:
  analyze:
    name: Analyze (${{ matrix.language }})
    runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }}
    timeout-minutes: ${{ (matrix.language == 'cpp' && 120) || 360 }}
    permissions:
      security-events: write
      actions: read
      contents: read

    strategy:
      fail-fast: false
      matrix:
        include:
          - language: python
          - language: javascript-typescript
          - language: java
          - language: cpp
            build-mode: autobuild
          - language: csharp

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      # 初始化 CodeQL，指定语言和配置文件
      - name: Initialize CodeQL
        uses: github/codeql-action/init@v4
        with:
          languages: ${{ matrix.language }}
          build-mode: ${{ matrix.build-mode }}
          config-file: ./.github/codeql/codeql-config.yml

      # 对于编译型语言，如果 autobuild 失败，需要手动添加构建步骤
      # - name: Build
      #   if: matrix.language == 'cpp'
      #   run: |
      #     cmake -B build -DCMAKE_BUILD_TYPE=Debug
      #     cmake --build build

      # 执行 CodeQL 分析
      - name: Perform CodeQL Analysis
        uses: github/codeql-action/analyze@v4
        with:
          category: "/language:${{ matrix.language }}"

官方文档：Configuring Advanced Setup

增量检查：当使用 codeql-action 时，CodeQL 会自动在 PR 中进行增量分析：

PR 检查：仅报告 PR 中变更代码引入的新告警（通过对比当前分支与目标分支的分析结果）
合并队列支持：通过 merge_group 事件触发，确保合并队列中的代码也被扫描

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  merge_group: # 支持合并队列

官方文档：Code Scanning Alerts

5.2 pre-commit 集成

CodeQL 本身不提供官方 pre-commit 钩子。由于 CodeQL 数据库创建和分析耗时较长（通常数分钟到数十分钟），pre-commit 集成不适合作为常规开发流程的一部分，仅在特殊场景下可考虑。

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: codeql-scan
        name: CodeQL Security Scan
        entry: bash -c 'codeql database create ./codeql-db --language=python --source-root=. && codeql database analyze ./codeql-db --format=sarif-latest --output=results.sarif codeql/python-queries:codeql-suites/python-security-extended.qls'
        language: system
        pass_filenames: false
        verbose: true

注意：此配置依赖系统中已安装 CodeQL CLI，且分析耗时较长，可能严重影响开发体验。推荐在 CI/CD 中运行完整分析，本地开发阶段依赖 IDE 插件进行交互式查询。

增量检查：CodeQL 需要先构建整个代码库的语义数据库（CodeQL database）才能进行分析，构建过程耗时较长（通常数分钟到数十分钟），不适合放入 pre-commit 提交前检查。CodeQL 的增量分析通过 GitHub Actions 的 codeql-action 在 PR 中自动完成（仅报告变更代码引入的新告警），应在 CI 门禁中执行而非本地提交前链路。

5.3 IDE 集成（VS Code CodeQL 扩展）

CodeQL 提供官方的 VS Code 扩展，支持交互式查询编写、调试和结果可视化。

扩展名称：CodeQL（由 GitHub 发布）
扩展市场链接：CodeQL Extension
官方文档：CodeQL for Visual Studio Code

主要功能：

功能	说明
数据库管理	创建、导入和管理 CodeQL 数据库
查询编辑	智能补全、语法高亮、QL 语言支持
查询运行	在数据库上执行查询并查看结果
结果导航	点击结果跳转到源码位置，查看数据流路径
AST 查看器	查看代码的抽象语法树结构
查询调试器	逐步调试查询执行过程
查询测试	运行查询的单元测试

安装步骤：

在 VS Code 扩展市场搜索 "CodeQL" 并安装
通过命令面板（Ctrl+Shift+P / Cmd+Shift+P）执行 "CodeQL: Set CodeQL CLI Path" 指定 CLI 路径
通过命令面板执行 "CodeQL: Download Pack" 下载对应语言的查询包
通过命令面板执行 "CodeQL: Create Database" 创建代码数据库

5.4 CodeQL CLI 命令行（非 GitHub 环境主流方式）

对于不使用 GitHub Actions 的团队，CodeQL CLI 是在自有 CI/CD 系统中运行 CodeQL 分析的主要方式。

安装 CodeQL CLI

官方推荐下载 CodeQL bundle 包，其中包含 CLI、兼容版本的查询库和预编译查询，无需单独克隆查询库：

# 从 codeql-action releases 下载 bundle 包
# https://github.com/github/codeql-action/releases
wget https://github.com/github/codeql-action/releases/latest/download/codeql-bundle-linux64.tar.gz
tar -xzf codeql-bundle-linux64.tar.gz
export PATH="$PWD/codeql:$PATH"

# 验证安装（应列出所有语言的 qlpack）
codeql resolve packs

官方文档：Set Up the CodeQL CLI

核心命令

# 1. 创建数据库（解释型语言，如 Python、JavaScript）
codeql database create ./codeql-db \
  --language=python \
  --source-root=.

# 2. 创建数据库（编译型语言，需要指定构建命令）
codeql database create ./codeql-db \
  --language=java \
  --command="mvn clean compile -DskipTests" \
  --source-root=.

# 3. 分析数据库（使用默认安全查询套件）
codeql database analyze ./codeql-db \
  codeql/python-queries:codeql-suites/python-security-extended.qls \
  --format=sarif-latest \
  --output=results.sarif \
  --sarif-add-query-ids

# 4. 分析数据库（使用 security-and-quality 查询套件）
codeql database analyze ./codeql-db \
  codeql/python-queries:codeql-suites/python-security-and-quality.qls \
  --format=sarif-latest \
  --output=results.sarif

# 5. 分析数据库（运行自定义查询）
codeql database analyze ./codeql-db \
  ./my-custom-queries/ \
  --format=csv \
  --output=results.csv

# 6. 运行单个查询
codeql query run ./my-query.ql \
  --database=./codeql-db \
  --output=results.csv

# 7. 上传结果到 GitHub
codeql github upload-results \
  --repository=owner/repo \
  --ref=refs/heads/main \
  --commit=abc123 \
  --sarif=results.sarif \
  --github-auth-stdin

# 8. 数据库升级（增量更新）
codeql database upgrade ./codeql-db

# 9. 数据库清理（减少磁盘占用）
codeql database cleanup ./codeql-db

官方文档：Scan from the Command Line

增量检查 -- 对于使用 CodeQL CLI 的非 GitHub CI 系统，CodeQL 提供两种增量分析模式：

Diff-informed 分析（差异感知分析）：仅报告 PR 变更行中发现的告警，查询运行更快且结果更聚焦。需要 CodeQL CLI 2.21.0 或更高版本。

核心步骤：

识别 PR diff 范围（文件路径、行号范围）
创建数据扩展包（Data Extension Pack），将 diff 范围传递给 CodeQL
运行查询时通过 --additional-packs 和 --extension-packs 参数传入扩展包
过滤 SARIF 输出，仅保留 diff 范围内的告警

Overlay 分析（覆盖分析）：复用主分支的缓存数据库，仅处理变更文件，大幅减少数据库创建和查询评估时间。可将扫描时间缩短最多 10 倍。需要 CodeQL CLI 2.23.8 或更高版本。

核心步骤：

在主分支构建 overlay-base 数据库（完整数据库 + 缓存中间结果）
记录文件 Git OID 快照
在 PR 分支下载缓存的 base 数据库，计算变更文件
使用 --overlay-changes 参数仅处理变更文件

官方文档：Incremental Analysis

数据库增量更新：CodeQL 支持对已有数据库进行增量更新，避免每次全量重建：

# 升级已有数据库到最新版本
codeql database upgrade ./codeql-db

# 清理数据库（减少磁盘占用，保留增量信息）
codeql database cleanup ./codeql-db

CI 脚本调用：

GitLab CI 集成

CodeQL CLI 可在 GitLab CI 中运行，分析完成后将 SARIF 结果上传到 GitHub（或使用 GitLab SAST 集成）。

# .gitlab-ci.yml
codeql-scan:
  stage: test
  image: ubuntu:22.04
  variables:
    CODEQL_HOME: /opt/codeql
  before_script:
    - apt-get update && apt-get install -y wget tar
    - wget -q https://github.com/github/codeql-action/releases/latest/download/codeql-bundle-linux64.tar.gz
    - tar -xzf codeql-bundle-linux64.tar.gz -C /opt
    - export PATH="/opt/codeql:$PATH"

  script:
    # 创建数据库
    - codeql database create /tmp/codeql-db
      --language=python
      --source-root=.

    # 分析数据库
    - codeql database analyze /tmp/codeql-db
      codeql/python-queries:codeql-suites/python-security-extended.qls
      --format=sarif-latest
      --output=/tmp/results.sarif

  artifacts:
    paths:
      - /tmp/results.sarif
    reports:
      codequality: /tmp/results.sarif

官方文档：Using Code Scanning with Your Existing CI System

其他 CI/CD 系统

CodeQL CLI 支持任何 CI/CD 平台（Jenkins、CircleCI、Azure DevOps 等），核心流程均为三步：

创建数据库：codeql database create
分析数据库：codeql database analyze
上传结果：codeql github upload-results（上传到 GitHub）或导出 SARIF 文件

增量检查 -- GitHub Actions 中按 PR 变更文件触发增量检查：

on:
  pull_request:
    branches: [main]
    # 仅当变更文件包含非文档文件时触发扫描
    paths-ignore:
      - "**/*.md"
      - "**/*.txt"
      - "**/docs/**"

注意：CodeQL 的增量分析主要在 PR 级别工作，而非单个文件级别。这是因为 CodeQL 的数据流分析需要理解整个代码库的语义关系，单文件级别的增量分析可能导致跨文件漏洞被遗漏。

5.5 编译型语言构建集成

对于编译型语言（C/C++、C#、Java），CodeQL 需要在编译过程中捕获代码的语义信息。CodeQL CLI 的 database create 命令支持通过 --command 参数指定构建命令。

Java/Maven 项目：

codeql database create ./codeql-db \
  --language=java \
  --command="mvn clean compile -DskipTests" \
  --source-root=.

Java/Gradle 项目：

codeql database create ./codeql-db \
  --language=java \
  --command="./gradlew compileJava" \
  --source-root=.

C/C++/CMake 项目：

codeql database create ./codeql-db \
  --language=cpp \
  --command="cmake -B build && cmake --build build" \
  --source-root=.

C#/.NET 项目：

codeql database create ./codeql-db \
  --language=csharp \
  --command="dotnet build" \
  --source-root=.

对于解释型语言（Python、JavaScript），无需指定构建命令：

codeql database create ./codeql-db \
  --language=python \
  --source-root=.

6. 告警抑制（屏蔽）方法

CodeQL 提供多种告警抑制方式，适用于不同场景。

6.1 通过 GitHub 界面关闭告警（Dismiss Alert）

在 GitHub 仓库的 Security 选项卡中，可以对单个告警执行关闭操作。

操作路径：Security > Code scanning > 选择告警 > Dismiss alert
关闭原因选项：
- False positive（误报）
- Won't fix（不修复）
- Used in tests（测试代码中使用）
- Risk accepted（接受风险）
关闭效果：该告警在所有分支上标记为已关闭，下次扫描不会再次生成

官方文档：Resolving Code Scanning Alerts - Dismissing Alerts

6.2 通过配置文件排除路径（paths-ignore）

在 codeql-config.yml 中配置排除路径，CodeQL 将不会分析指定目录中的代码：

# .github/codeql/codeql-config.yml
paths-ignore:
  - "**/test/**"
  - "**/vendor/**"
  - "**/node_modules/**"
  - "**/generated/**"
  - "**/third-party/**"

官方文档：Workflow Configuration Options - Specifying Directories to Scan

6.3 通过 query-filters 排除特定查询

在 codeql-config.yml 中使用 query-filters 排除或包含特定查询：

# 排除特定查询（按查询 ID）
query-filters:
  - exclude:
      id: js/redundant-assignment
  - exclude:
      id: js/useless-assignment-to-local

  # 包含特定查询（覆盖排除规则）
  - include:
      id: py/hardcoded-password

  # 按标签排除
  - exclude:
      tags: exclude-from-incremental

查询 ID 可以在 GitHub Security 选项卡的告警详情页中找到（"Rule ID" 字段）。

官方文档：Workflow Configuration Options - Non-default Queries

6.4 通过禁用默认查询（disable-default-queries）

如果只需要运行自定义查询，可以完全禁用默认查询套件：

# .github/codeql/codeql-config.yml
disable-default-queries: true

queries:
  - uses: ./my-custom-queries

官方文档：Workflow Configuration Options - Custom Configuration Files

6.5 通过指定查询套件控制告警范围

通过在工作流中指定不同的查询套件，控制分析的深度和广度（详见 4.4 使用方式）：

- uses: github/codeql-action/init@v4
  with:
    # 默认安全查询（高精度，低误报）
    queries: default

    # 或使用 security-extended（扩展安全查询，告警更多）
    # queries: security-extended

    # 或使用 security-and-quality（安全+代码质量查询，覆盖最全面，需 advanced setup）
    # queries: security-and-quality

内置查询套件说明：

查询套件	说明
`default`	默认安全查询，高精度低误报
`security-extended`	扩展安全查询，包含低严重性查询，误报较多
`security-and-quality`	安全+代码质量查询，覆盖最全面，需 advanced setup 或 CLI