codeql

Name: codeql
Author: github

github.com/github安全40.5k2.0k 次安装1 天前更新

代码仓库

关于 codeql

用于通过 GitHub Actions 或独立 CLI 配置并运行 CodeQL 代码扫描的操作指导技能，涵盖工作流、语言与查询配置、SARIF、扩展包和故障排查。

主要功能

01GitHub Actions 工作流配置
02CodeQL CLI 数据库与分析指导
03语言和构建模式配置
04SARIF 解读与上传指导
05自定义查询包与单体仓库配置
06扫描故障排查

适用场景

01创建或调整 codeql.yml 工作流
02在本地运行 CodeQL 分析
03配置单体仓库扫描
04排查构建或 SARIF 上传失败

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/github/awesome-copilot --skill codeql

安装后在 Claude Code 中输入/codeql确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/

alert-management.md

cli-commands.md

compiled-languages.md

sarif-output.md

troubleshooting.md

workflow-configuration.md

详细介绍

CodeQL 代码扫描

本技能为配置和运行 CodeQL 代码扫描提供流程指导——既可通过 GitHub Actions 工作流，也可使用独立的 CodeQL CLI。

何时使用本技能

当请求涉及以下内容时，请使用本技能：

创建或自定义 codeql.yml GitHub Actions 工作流
在代码扫描的默认设置与高级设置之间进行选择
配置 CodeQL 语言矩阵、构建模式或查询套件
在本地运行 CodeQL CLI（codeql database create、database analyze、github upload-results）
理解或解读 CodeQL 输出的 SARIF
排查 CodeQL 分析失败（构建模式、编译型语言、运行器要求）
为 monorepo 设置按组件扫描的 CodeQL
配置依赖缓存、自定义查询包或模型包

支持的语言

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 分析）。

核心工作流——GitHub Actions

第 1 步：选择设置类型

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

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

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

定义扫描运行时机：

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——如果仓库使用合并队列，请添加此项

要跳过仅涉及文档的 PR 扫描：

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

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

第 3 步：配置权限

设置最小权限：

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

第 4 步：配置语言矩阵

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

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——自定义构建命令（仅限高级设置）

有关各语言自动构建行为的详细说明和运行器要求，请搜索 references/compiled-languages.md。

第 5 步：配置 CodeQL Init 和分析

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 结果（例如按语言、按组件）。

第 6 步：Monorepo 配置

对于包含多个组件的 monorepo，使用 category 参数区分 SARIF 结果：

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

要将分析限制在特定目录，请使用 CodeQL 配置文件（.github/codeql/codeql-config.yml）：

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

在工作流中引用它：

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

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

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

- language: c-cpp
  build-mode: manual

然后在 init 和 analyze 之间添加显式的构建步骤：

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

核心工作流 — CodeQL CLI

步骤 1：安装 CodeQL CLI

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

# 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

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

步骤 2：创建 CodeQL 数据库

# 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

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

步骤 3：分析数据库

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。

步骤 4：将结果上传到 GitHub

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

需要具有 security-events: write 权限的 GITHUB_TOKEN 环境变量。

CLI 服务器模式

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

codeql execute cli-server

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

告警管理

严重性级别

告警有两个严重性维度：

标准严重性： Error、Warning、Note
安全严重性： Critical、High、Medium、Low（源自 CVSS 分数；优先显示）

Copilot Autofix

GitHub Copilot Autofix 会为拉取请求中的 CodeQL 告警自动生成修复建议 — 无需 Copilot 订阅。提交前请仔细审查建议。

PR 中的告警分类

告警以检查注释的形式出现在更改的行上
对于 error/critical/high 严重性告警，检查默认失败
配置合并保护规则集以自定义阈值
将有理由的误报标记为已忽略，以便进行审计追踪

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

自定义查询和包

使用自定义查询包

- uses: github/codeql-action/init@v4
  with:
    packs: |
      my-org/[email protected]
      codeql/javascript-queries:AlertSuppression.ql

创建自定义查询包

使用 CodeQL CLI 创建并发布包：

# Initialize a new pack
codeql pack init my-org/my-queries

# Install dependencies
codeql pack install

# Publish to GitHub Container Registry
codeql pack publish

CodeQL 配置文件

对于高级查询和路径配置，创建 .github/codeql/codeql-config.yml：

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

代码扫描日志

摘要指标

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

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

调试日志

要启用详细诊断：

GitHub Actions： 勾选"Enable debug logging"重新运行工作流
CodeQL CLI： 使用 --verbosity=progress++ 和 --logdir=codeql-logs

故障排除

常见问题

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

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

硬件要求（可自托管运行器）

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

所有规模：SSD，至少有 14 GB 可用磁盘空间。

Action 版本管理

将 CodeQL action 固定到特定的主版本：

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

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

参考文件

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

references/workflow-configuration.md — 完整的工作流触发器、运行器和配置选项
- 搜索模式：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 — 各语言的构建模式和自动构建行为
- 搜索模式：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、403、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

支持 Markdown

登录后评论

基本信息

作者: github
仓库: github/awesome-copilot
分类: 安全
安装次数: 1,981
GitHub Stars: 40,516

报告问题