implementing-github-advanced-security-for-code-scanning

为代码扫描实施 GitHub Advanced Security

概述

GitHub Advanced Security（GHAS）将由 CodeQL 支持的静态应用程序安全测试直接集成到 GitHub 开发工作流中。CodeQL 将代码视为数据，从而支持语义分析，能够识别 SQL 注入、跨站脚本、缓冲区溢出和身份验证缺陷等安全漏洞，且误报率显著低于传统的模式匹配扫描器。GHAS 涵盖代码扫描、机密扫描、依赖项审查和 Dependabot 警报，为仓库提供全面的安全态势。

使用场景

• 在您的环境中部署或配置为代码扫描实施 GitHub Advanced Security 功能时
• 建立符合合规要求的安全控制措施时
• 为该领域构建或改进安全架构时
• 执行需要此实施的安全评估时

先决条件

• GitHub Enterprise Cloud 或 GitHub Enterprise Server 3.0+，并拥有 GHAS 许可证
• 仓库管理员或组织所有者权限
• 熟悉 GitHub Actions 工作流语法（YAML）
• 支持的语言：C/C++、C#、Go、Java/Kotlin、JavaScript/TypeScript、Python、Ruby、Swift

核心概念

CodeQL 分析引擎

CodeQL 将源代码编译为可查询的数据库，然后针对该数据库执行以安全为重点的查询。查询套件内置数百项检查，这些检查映射到 CWE 标识符，并涵盖 OWASP Top 10、SANS Top 25 以及特定语言的漏洞模式。可以使用 CodeQL 查询语言（QL）编写自定义查询，以检测特定于组织的反模式。

默认设置与高级设置

默认设置可通过仓库的代码安全设置一键启用代码扫描。GitHub 会自动确定存在的语言、选择合适的查询套件并配置扫描触发器。此方法无需工作流文件，非常适合快速上手。

高级设置会生成一个可自定义的 .github/workflows/codeql.yml 工作流文件。团队可以控制调度、语言矩阵、编译语言的构建命令、额外的查询包以及与第三方 SARIF 生成器的集成。当需要自定义构建步骤、monorepo 配置或私有查询包时，必须使用高级设置。

组织范围内的推广

对于管理数百个仓库的企业，GHAS 支持使用组织级安全概览大规模配置代码扫描。管理员可以在所有符合条件的仓库中启用默认设置、定义自定义安全配置，并通过安全覆盖率仪表板监控采用情况。

工作流

第 1 步 —— 在组织上启用 GHAS

1. 导航到 Organization Settings > Code security and analysis
2. 为所有仓库或选定仓库启用 GitHub Advanced Security
3. 确认许可证席位分配（GHAS 按活跃提交者计费）

第 2 步 —— 配置默认设置以快速见效

1. 转到 Repository Settings > Code security > Code scanning
2. 在 CodeQL 分析行中点击 "Set up" 并选择 "Default"
3. 查看自动检测到的语言和查询套件（默认或扩展）
4. 点击 "Enable CodeQL"，在推送和拉取请求事件上激活扫描

第 3 步 —— 使用自定义工作流进行高级设置

创建 .github/workflows/codeql-analysis.yml：

name: "CodeQL Analysis"

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

jobs:
  analyze:
    name: Analyze (${{ matrix.language }})
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      contents: read
      actions: read

    strategy:
      fail-fast: false
      matrix:
        language: ['javascript-typescript', 'python', 'java-kotlin']

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

      - name: Initialize CodeQL
        uses: github/codeql-action/init@v3
        with:
          languages: ${{ matrix.language }}
          queries: +security-extended,security-and-quality
          # For compiled languages, add build commands below

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

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

第 4 步 —— 自定义查询包

通过在工作流中引用组织专属查询包来安装它们：

- name: Initialize CodeQL
  uses: github/codeql-action/init@v3
  with:
    languages: java-kotlin
    packs: |
      my-org/[email protected]
      codeql/java-queries:cwe/cwe-089

第 5 步 —— 配置分支保护规则

1. 导航到 Repository Settings > Branches > Branch protection rules
2. 启用 "Require status checks to pass" 并添加 CodeQL 分析检查
3. 启用 "Require code scanning results" 并设置严重性阈值（例如，阻止 High/Critical）

第 6 步 --- 机密扫描与推送保护

1. 从代码安全设置中启用机密扫描
2. 启用推送保护，以阻止包含检测到的机密的提交
3. 为组织特定的机密（API 密钥、内部令牌）配置自定义模式

第 7 步 --- 依赖项审查与 Dependabot

1. 启用 Dependabot 警报和安全更新
2. 配置 .github/dependabot.yml 以实现依赖项版本的自动更新
3. 在拉取请求上启用依赖项审查强制执行，以阻止引入已知存在漏洞的依赖项的 PR

查询套件参考

套件	描述	使用场景
default	高置信度安全查询	误报最少的生产环境扫描
security-extended	更广泛的安全查询，包括较低严重性的发现	全面的安全覆盖
security-and-quality	安全加上代码质量查询	希望同时进行安全性和可维护性检查的团队
自定义包	组织编写的查询	检测内部反模式和合规违规

与安全工作流的集成

从第三方工具上传 SARIF

GHAS 接受来自外部工具的 SARIF（静态分析结果交换格式）上传：

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif
    category: "semgrep"

安全概览仪表板

组织级安全概览提供：

• 风险视图，按严重性显示带有未解决警报的仓库
• 覆盖视图，显示各仓库中 GHAS 功能的启用情况
• 随时间变化的警报趋势，用于跟踪修复进度
• 按团队、语言和警报类型筛选，以便进行针对性审查

监控与指标

• 跟踪代码扫描警报的平均修复时间（MTTR）
• 监控误报率并相应地调整查询配置
• 审查警报解除原因，以确定开发者培训的领域
• 使用 API（/repos/{owner}/{repo}/code-scanning/alerts）构建自定义报告仪表板

常见陷阱

1. 编译型语言构建失败 --- CodeQL 要求 C/C++、Java、C#、Go 和 Swift 成功编译；确保构建依赖项在 Actions runner 中可用
2. 忽略计划扫描 --- 推送/PR 扫描会遗漏依赖项中的漏洞；每周计划扫描可捕获现有代码中新披露的 CVE
3. 使用 security-and-quality 导致警报过多 --- 从 default 套件开始并逐步扩展，以避免开发者警报疲劳
4. 缺少 GHAS 许可证席位 --- 只有启用了 GHAS 的仓库的活跃提交者才会消耗许可证席位；请相应地规划容量

参考资料

• GitHub 代码扫描文档
• CodeQL 文档
• CodeQL 查询仓库
• SARIF 规范
• GitHub 安全概览