codeql

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CodeQL Code Scanning

CodeQL 代码扫描

This skill provides procedural guidance for configuring and running CodeQL code scanning — both through GitHub Actions workflows and the standalone CodeQL CLI.

此 Skill 提供有关配置和运行 CodeQL 代码扫描的流程指南，既涵盖通过 GitHub Actions 工作流执行扫描，也涵盖使用独立的 CodeQL CLI。

When to Use This Skill

何时使用此 Skill

Use this skill when the request involves:

Creating or customizing a
```
codeql.yml
```
GitHub Actions workflow
Choosing between default setup and advanced setup for code scanning
Configuring CodeQL language matrix, build modes, or query suites

Running CodeQL CLI locally (

codeql database create

database analyze

github upload-results

)

Understanding or interpreting SARIF output from CodeQL
Troubleshooting CodeQL analysis failures (build modes, compiled languages, runner requirements)
Setting up CodeQL for monorepos with per-component scanning
Configuring dependency caching, custom query packs, or model packs

当请求涉及以下内容时使用此 Skill：

创建或自定义
```
codeql.yml
```
GitHub Actions 工作流
在代码扫描的默认设置和高级设置之间进行选择
配置 CodeQL 语言矩阵、构建模式或查询套件

在本地运行 CodeQL CLI（

codeql database create

、

database analyze

、

github upload-results

）

理解或解释 CodeQL 生成的 SARIF 输出
排查 CodeQL 分析失败问题（构建模式、编译型语言、runner 要求）
为 monorepo 设置 CodeQL，并按组件执行扫描
配置依赖项缓存、自定义查询包或 model pack

Supported Languages

支持的语言

CodeQL supports the following language identifiers:

Language	Identifier	Alternatives
C/C++	`c-cpp`	`c` , `cpp`
C#	`csharp`	—
Go	`go`	—
Java/Kotlin	`java-kotlin`	`java` , `kotlin`
JavaScript/TypeScript	`javascript-typescript`	`javascript` , `typescript`
Python	`python`	—
Ruby	`ruby`	—
Rust	`rust`	—
Swift	`swift`	—
GitHub Actions	`actions`	—

Alternative identifiers are equivalent to the standard identifier (e.g.,
javascript
does not exclude TypeScript analysis).

CodeQL 支持以下语言标识符：

语言	标识符	别名
C/C++	`c-cpp`	`c` 、 `cpp`
C#	`csharp`	—
Go	`go`	—
Java/Kotlin	`java-kotlin`	`java` 、 `kotlin`
JavaScript/TypeScript	`javascript-typescript`	`javascript` 、 `typescript`
Python	`python`	—
Ruby	`ruby`	—
Rust	`rust`	—
Swift	`swift`	—
GitHub Actions	`actions`	—

替代标识符与标准标识符等价（例如，
javascript
不会排除 TypeScript 分析）。

Core Workflow — GitHub Actions

核心工作流——GitHub Actions

Step 1: Choose Setup Type

第 1 步：选择设置类型

Default setup — Enable from repository Settings → Advanced Security → CodeQL analysis. Best for getting started quickly. Uses
```
none
```
build mode for most languages.
Advanced setup — Create a
```
.github/workflows/codeql.yml
```
file for full control over triggers, build modes, query suites, and matrix strategies.

To switch from default to advanced: disable default setup first, then commit the workflow file.

默认设置——从仓库 Settings → Advanced Security → CodeQL analysis 中启用。最适合快速上手。对大多数语言使用
```
none
```
构建模式。
高级设置——创建
```
.github/workflows/codeql.yml
```
文件，以全面控制触发器、构建模式、查询套件和矩阵策略。

要从默认设置切换到高级设置，请先禁用默认设置，然后提交工作流文件。

Step 2: Configure Workflow Triggers

第 2 步：配置工作流触发器

Define when scanning runs:

yaml

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '30 6 * * 1'  # Weekly Monday 6:30 UTC

```
push
```
— scans on every push to specified branches; results appear in Security tab
```
pull_request
```
— scans PR merge commits; results appear as PR check annotations
```
schedule
```
— periodic scans of the default branch (cron must exist on default branch)
```
merge_group
```
— add if repository uses merge queues

To skip scans for documentation-only PRs:

yaml

on:
  pull_request:
    paths-ignore:
      - '**/*.md'
      - '**/*.txt'

paths-ignore
controls whether the workflow runs, not which files are analyzed.

定义何时运行扫描：

yaml

on:
  push:
    branches: [main, protected]
  pull_request:
    branches: [main]
  schedule:
    - cron: '30 6 * * 1'  # Weekly Monday 6:30 UTC

```
push
```
——每次推送到指定分支时扫描；结果显示在 Security 标签页中
```
pull_request
```
——扫描 PR 合并提交；结果显示为 PR 检查注释
```
schedule
```
——定期扫描默认分支（cron 必须存在于默认分支中）
```
merge_group
```
——如果仓库使用 merge queue，则添加此项

要跳过仅包含文档的 PR 扫描：

yaml

on:
  pull_request:
    paths-ignore:
      - '**/*.md'
      - '**/*.txt'

paths-ignore
控制工作流是否运行，而不是控制要分析哪些文件。

Step 3: Configure Permissions

第 3 步：配置权限

Set least-privilege permissions:

yaml

permissions:
  security-events: write   # Required to upload SARIF results
  contents: read            # Required to checkout code
  actions: read             # Required for private repos using codeql-action

设置最小权限：

yaml

permissions:
  security-events: write   # Required to upload SARIF results
  contents: read            # Required to checkout code
  actions: read             # Required for private repos using codeql-action

Step 4: Configure Language Matrix

第 4 步：配置语言矩阵

Use a matrix strategy to analyze each language in parallel:

yaml

jobs:
  analyze:
    name: Analyze (${{ matrix.language }})
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

For compiled languages, set the appropriate

build-mode

```
none
```
— no build required (supported for C/C++, C#, Java, Rust)
```
autobuild
```
— automatic build detection
```
manual
```
— custom build commands (advanced setup only)

For detailed per-language autobuild behavior and runner requirements, search
references/compiled-languages.md
.

使用矩阵策略并行分析每种语言：

yaml

jobs:
  analyze:
    name: Analyze (${{ matrix.language }})
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        include:
          - language: javascript-typescript
            build-mode: none
          - language: python
            build-mode: none

对于编译型语言，请设置适当的

build-mode

：

```
none
```
——无需构建（支持 C/C++、C#、Java、Rust）
```
autobuild
```
——自动检测构建
```
manual
```
——自定义构建命令（仅限高级设置）

有关各语言 autobuild 行为和 runner 要求的详细信息，请搜索
references/compiled-languages.md
。

Step 5: Configure CodeQL Init and Analysis

第 5 步：配置 CodeQL 初始化和分析

yaml

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

  - name: Initialize CodeQL
    uses: github/codeql-action/init@v4
    with:
      languages: ${{ matrix.language }}
      build-mode: ${{ matrix.build-mode }}
      queries: security-extended
      dependency-caching: true

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

Query suite options:

```
security-extended
```
— default security queries plus additional coverage
```
security-and-quality
```
— security plus code quality queries

Custom query packs via

packs:

input (e.g.,

codeql/javascript-queries:AlertSuppression.ql

)

Dependency caching: Set

dependency-caching: true

on the

init

action to cache restored dependencies across runs.

Analysis category: Use

category

to distinguish SARIF results in monorepos (e.g., per-language, per-component).

yaml

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

  - name: Initialize CodeQL
    uses: github/codeql-action/init@v4
    with:
      languages: ${{ matrix.language }}
      build-mode: ${{ matrix.build-mode }}
      queries: security-extended
      dependency-caching: true

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

查询套件选项：

```
security-extended
```
——默认安全查询以及额外覆盖范围
```
security-and-quality
```
——安全查询和代码质量查询

通过

packs:

输入自定义查询包（例如

codeql/javascript-queries:AlertSuppression.ql

）

依赖项缓存： 在

init

action 中设置

dependency-caching: true

，以在多次运行之间缓存恢复的依赖项。

分析类别： 使用

category

区分 monorepo 中的 SARIF 结果（例如按语言或组件区分）。

Step 6: Monorepo Configuration

第 6 步：配置 Monorepo

For monorepos with multiple components, use the

category

parameter to separate SARIF results:

yaml

category: "/language:${{ matrix.language }}/component:frontend"

To restrict analysis to specific directories, use a CodeQL configuration file (

.github/codeql/codeql-config.yml

yaml

paths:
  - apps/
  - services/
paths-ignore:
  - node_modules/
  - '**/test/**'

Reference it in the workflow:

yaml

- uses: github/codeql-action/init@v4
  with:
    config-file: .github/codeql/codeql-config.yml

对于包含多个组件的 monorepo，请使用

category

参数分隔 SARIF 结果：

yaml

category: "/language:${{ matrix.language }}/component:frontend"

要将分析限制在特定目录中，请使用 CodeQL 配置文件（

.github/codeql/codeql-config.yml

）：

yaml

paths:
  - apps/
  - services/
paths-ignore:
  - node_modules/
  - '**/test/**'

在工作流中引用该文件：

yaml

- uses: github/codeql-action/init@v4
  with:
    config-file: .github/codeql/codeql-config.yml

Step 7: Manual Build Steps (Compiled Languages)

第 7 步：手动构建步骤（编译型语言）

autobuild

fails or custom build commands are needed:

yaml

- language: c-cpp
  build-mode: manual

Then add explicit build steps between

init

and

analyze

yaml

- if: matrix.build-mode == 'manual'
  name: Build
  run: |
    make bootstrap
    make release

如果

autobuild

失败或需要自定义构建命令：

yaml

- language: c-cpp
  build-mode: manual

然后在

init

和

analyze

之间添加明确的构建步骤：

yaml

- if: matrix.build-mode == 'manual'
  name: Build
  run: |
    make bootstrap
    make release

Core Workflow — CodeQL CLI

核心工作流——CodeQL CLI

Step 1: Install the CodeQL CLI

第 1 步：安装 CodeQL CLI

Download the CodeQL bundle (includes CLI + precompiled queries):

bash

undefined

下载 CodeQL bundle（包含 CLI 和预编译查询）：

bash

undefined

Download from https://github.com/github/codeql-action/releases

Extract and add to PATH

export PATH="$HOME/codeql:$PATH"

Verify installation

codeql resolve packs codeql resolve languages


> Always use the CodeQL bundle, not a standalone CLI download. The bundle ensures query compatibility and provides precompiled queries for better performance.

codeql resolve packs codeql resolve languages


> 始终使用 CodeQL bundle，而不是单独下载的 CLI。bundle 可确保查询兼容性，并提供预编译查询以提升性能。

Step 2: Create a CodeQL Database

第 2 步：创建 CodeQL 数据库

bash

undefined

bash

undefined

Single language

codeql database create codeql-db
--language=javascript-typescript
--source-root=src

Multiple languages (cluster mode)

codeql database create codeql-dbs
--db-cluster
--language=java,python
--command=./build.sh
--source-root=src


For compiled languages, provide the build command via `--command`.

codeql database create codeql-dbs
--db-cluster
--language=java,python
--command=./build.sh
--source-root=src


对于编译型语言，请通过 `--command` 提供构建命令。

Step 3: Analyze the Database

第 3 步：分析数据库

bash

codeql database analyze codeql-db \
  javascript-code-scanning.qls \
  --format=sarif-latest \
  --sarif-category=javascript \
  --output=results.sarif

Common query suites:

<language>-code-scanning.qls

<language>-security-extended.qls

<language>-security-and-quality.qls

bash

codeql database analyze codeql-db \
  javascript-code-scanning.qls \
  --format=sarif-latest \
  --sarif-category=javascript \
  --output=results.sarif

常用查询套件：

<language>-code-scanning.qls

、

<language>-security-extended.qls

、

<language>-security-and-quality.qls

。

Step 4: Upload Results to GitHub

第 4 步：将结果上传到 GitHub

bash

codeql github upload-results \
  --repository=owner/repo \
  --ref=refs/heads/main \
  --commit=<commit-sha> \
  --sarif=results.sarif

Requires

GITHUB_TOKEN

environment variable with

security-events: write

permission.

bash

codeql github upload-results \
  --repository=owner/repo \
  --ref=refs/heads/main \
  --commit=<commit-sha> \
  --sarif=results.sarif

需要设置

GITHUB_TOKEN

环境变量，并授予

security-events: write

权限。

CLI Server Mode

CLI Server 模式

To avoid repeated JVM initialization when running multiple commands:

bash

codeql execute cli-server

For detailed CLI command reference, search
references/cli-commands.md
.

要在运行多个命令时避免重复初始化 JVM：

bash

codeql execute cli-server

有关详细的 CLI 命令参考，请搜索
references/cli-commands.md
。

Alert Management

警报管理

Severity Levels

严重性级别

Alerts have two severity dimensions:

Standard severity:
```
Error
```
,
```
Warning
```
,
```
Note
```
Security severity:
```
Critical
```
,
```
High
```
,
```
Medium
```
,
```
Low
```
(derived from CVSS scores; takes display precedence)

警报具有两个严重性维度：

标准严重性：
```
Error
```
、
```
Warning
```
、
```
Note
```
安全严重性：
```
Critical
```
、
```
High
```
、
```
Medium
```
、
```
Low
```
（根据 CVSS 分数推导；显示时优先采用）

Copilot Autofix

GitHub Copilot Autofix generates fix suggestions for CodeQL alerts in pull requests automatically — no Copilot subscription required. Review suggestions carefully before committing.

GitHub Copilot Autofix 会自动为 PR 中的 CodeQL 警报生成修复建议，无需 Copilot 订阅。提交前应仔细审查这些建议。

Alert Triage in PRs

PR 中的警报分诊

Alerts appear as check annotations on changed lines
Check fails by default for
```
error
```
/
```
critical
```
/
```
high
```
severity alerts
Configure merge protection rulesets to customize the threshold
Dismiss false positives with a documented reason for audit trail

For detailed alert management guidance, search
references/alert-management.md
.

警报会显示为变更行上的检查注释
对于
```
error
```
/
```
critical
```
/
```
high
```
严重性警报，检查默认会失败
配置合并保护 ruleset，以自定义失败阈值
关闭误报时填写书面理由，以保留审计记录

有关详细的警报管理指南，请搜索
references/alert-management.md
。

Custom Queries and Packs

自定义查询和查询包

Using Custom Query Packs

使用自定义查询包

yaml

- uses: github/codeql-action/init@v4
  with:
    packs: |
      my-org/my-security-queries@1.0.0
      codeql/javascript-queries:AlertSuppression.ql

yaml

- uses: github/codeql-action/init@v4
  with:
    packs: |
      my-org/my-security-queries@1.0.0
      codeql/javascript-queries:AlertSuppression.ql

Creating Custom Query Packs

创建自定义查询包

Use the CodeQL CLI to create and publish packs:

bash

undefined

使用 CodeQL CLI 创建并发布查询包：

bash

undefined

Initialize a new pack

codeql pack init my-org/my-queries

Install dependencies

codeql pack install

Publish to GitHub Container Registry

codeql pack publish

undefined

codeql pack publish

undefined

CodeQL Configuration File

CodeQL 配置文件

For advanced query and path configuration, create

.github/codeql/codeql-config.yml

yaml

paths:
  - apps/
  - services/
paths-ignore:
  - '**/test/**'
  - node_modules/
queries:
  - uses: security-extended
packs:
  javascript-typescript:
    - my-org/my-custom-queries

要配置高级查询和路径，请创建

.github/codeql/codeql-config.yml

：

yaml

paths:
  - apps/
  - services/
paths-ignore:
  - '**/test/**'
  - node_modules/
queries:
  - uses: security-extended
packs:
  javascript-typescript:
    - my-org/my-custom-queries

Code Scanning Logs

代码扫描日志

Summary Metrics

汇总指标

Workflow logs include key metrics:

Lines of code in codebase — baseline before extraction
Lines extracted — including external libraries and auto-generated files
Extraction errors/warnings — files that failed or produced warnings during extraction

工作流日志包含以下关键指标：

代码库中的代码行数——提取前的基线
已提取的行数——包括外部库和自动生成的文件
提取错误/警告——提取过程中失败或产生警告的文件

Debug Logging

调试日志

To enable detailed diagnostics:

GitHub Actions: re-run the workflow with "Enable debug logging" checked

CodeQL CLI: use

--verbosity=progress++

and

--logdir=codeql-logs

要启用详细诊断信息：

GitHub Actions： 勾选“Enable debug logging”后重新运行工作流

CodeQL CLI： 使用

--verbosity=progress++

和

--logdir=codeql-logs

Troubleshooting

故障排查

Common Issues

常见问题

Problem	Solution
Workflow not triggering	Verify `on:` triggers match event; check `paths` / `branches` filters; ensure workflow exists on target branch
`Resource not accessible` error	Add `security-events: write` and `contents: read` permissions
Autobuild failure	Switch to `build-mode: manual` and add explicit build commands
No source code seen	Verify `--source-root` , build command, and language identifier
C# compiler failure	Check for `/p:EmitCompilerGeneratedFiles=true` conflicts with `.sqlproj` or legacy projects
Fewer lines scanned than expected	Switch from `none` to `autobuild` / `manual` ; verify build compiles all source
Kotlin in no-build mode	Disable and re-enable default setup to switch to `autobuild`
Cache miss every run	Verify `dependency-caching: true` on `init` action
Out of disk/memory	Use larger runners; reduce analysis scope via `paths` config; use `build-mode: none`
SARIF upload fails	Ensure token has `security-events: write` ; check 10 MB file size limit
SARIF results exceed limits	Split across multiple uploads with different `--sarif-category` ; reduce query scope
Two CodeQL workflows	Disable default setup if using advanced setup, or remove old workflow file
Slow analysis	Enable dependency caching; use `--threads=0` ; reduce query suite scope

For comprehensive troubleshooting with detailed solutions, search
references/troubleshooting.md
.

问题	解决方案
工作流未触发	验证 `on:` 触发器是否与事件匹配；检查 `paths` / `branches` 过滤器；确保工作流存在于目标分支中
出现 `Resource not accessible` 错误	添加 `security-events: write` 和 `contents: read` 权限
Autobuild 失败	切换到 `build-mode: manual` 并添加明确的构建命令
未检测到源代码	验证 `--source-root` 、构建命令和语言标识符
C# 编译器失败	检查 `/p:EmitCompilerGeneratedFiles=true` 是否与 `.sqlproj` 或旧版项目冲突
扫描行数少于预期	从 `none` 切换到 `autobuild` / `manual` ；验证构建是否编译了所有源代码
no-build 模式下的 Kotlin 问题	禁用并重新启用默认设置，以切换到 `autobuild`
每次运行都未命中缓存	验证 `init` action 中是否设置了 `dependency-caching: true`
磁盘空间或内存不足	使用更大的 runner；通过 `paths` 配置减少分析范围；使用 `build-mode: none`
SARIF 上传失败	确保 token 具有 `security-events: write` 权限；检查 10 MB 文件大小限制
SARIF 结果超出限制	使用不同的 `--sarif-category` 拆分多次上传；缩小查询范围
存在两个 CodeQL 工作流	使用高级设置时禁用默认设置，或删除旧工作流文件
分析速度缓慢	启用依赖项缓存；使用 `--threads=0` ；缩小查询套件范围

如需全面的故障排查和详细解决方案，请搜索
references/troubleshooting.md
。

Hardware Requirements (Self-Hosted Runners)

硬件要求（自托管 Runner）

Codebase Size	RAM	CPU
Small (<100K LOC)	8 GB+	2 cores
Medium (100K–1M LOC)	16 GB+	4–8 cores
Large (>1M LOC)	64 GB+	8 cores

All sizes: SSD with ≥14 GB free disk space.

代码库规模	内存	CPU
小型（<100K LOC）	8 GB+	2 核
中型（100K–1M LOC）	16 GB+	4–8 核
大型（>1M LOC）	64 GB+	8 核

所有规模均需配备至少有 14 GB 可用磁盘空间的 SSD。

Action Versioning

Action 版本控制

Pin CodeQL actions to a specific major version:

yaml

uses: github/codeql-action/init@v4      # Recommended
uses: github/codeql-action/autobuild@v4
uses: github/codeql-action/analyze@v4

For maximum security, pin to a full commit SHA instead of a version tag.

将 CodeQL actions 固定到特定主版本：

yaml

uses: github/codeql-action/init@v4      # Recommended
uses: github/codeql-action/autobuild@v4
uses: github/codeql-action/analyze@v4

为了获得最高安全性，应固定到完整的 commit SHA，而不是版本标签。

Reference Files

参考文件

For detailed documentation, load the following reference files as needed:

references/workflow-configuration.md

— Full workflow trigger, runner, and configuration options

Search patterns:

trigger

schedule

paths-ignore

db-location

model packs

alert severity

merge protection

concurrency

config file

references/cli-commands.md

— Complete CodeQL CLI command reference

Search patterns:

database create

database analyze

upload-results

resolve packs

cli-server

installation

CI integration

references/sarif-output.md

— SARIF v2.1.0 object model, upload limits, and third-party support

Search patterns:

sarifLog

result

location

region

codeFlow

fingerprint

suppression

upload limits

third-party

precision

security-severity

references/compiled-languages.md

— Build modes and autobuild behavior per language

Search patterns:

C/C++

C#

Java

Go

Rust

Swift

autobuild

build-mode

hardware

dependency caching

references/troubleshooting.md

— Comprehensive error diagnosis and resolution

Search patterns:

no source code

out of disk

out of memory

C# compiler

analysis too long

fewer lines

Kotlin

extraction errors

debug logging

SARIF upload

SARIF limits

references/alert-management.md

— Alert severity, triage, Copilot Autofix, and dismissal

Search patterns:

severity

security severity

CVSS

Copilot Autofix

dismiss

triage

PR alerts

data flow

merge protection

REST API

如需详细文档，请按需加载以下参考文件：

references/workflow-configuration.md

——完整的工作流触发器、runner 和配置选项

搜索模式：

trigger

、

schedule

、

paths-ignore

、

db-location

、

model packs

、

alert severity

、

merge protection

、

concurrency

、

config file

references/cli-commands.md

——完整的 CodeQL CLI 命令参考

搜索模式：

database create

、

database analyze

、

upload-results

、

resolve packs

、

cli-server

、

installation

、

CI integration

references/sarif-output.md

——SARIF v2.1.0 对象模型、上传限制和第三方支持

搜索模式：

sarifLog

、

result

、

location

、

region

、

codeFlow

、

fingerprint

、

suppression

、

upload limits

、

third-party

、

precision

、

security-severity

references/compiled-languages.md

——各语言的构建模式和 autobuild 行为

搜索模式：

C/C++

、

C#

、

Java

、

Go

、

Rust

、

Swift

、

autobuild

、

build-mode

、

hardware

、

dependency caching

references/troubleshooting.md

——全面的错误诊断和解决方案

搜索模式：

no source code

、

out of disk

、

out of memory

、

C# compiler

、

analysis too long

、

fewer lines

、

Kotlin

、

extraction errors

、

debug logging

、

SARIF upload

、

SARIF limits

references/alert-management.md

——警报严重性、分诊、Copilot Autofix 和关闭警报

搜索模式：

severity

、

security severity

、

CVSS

、

Copilot Autofix

、

dismiss

、

triage

、

PR alerts

、

data flow

、

merge protection

、

REST API