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

实施 GitHub Advanced Security 代码扫描

概述

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

前置条件

• 持有 GHAS 许可证的 GitHub Enterprise Cloud 或 GitHub Enterprise Server 3.0+
• 仓库管理员或组织所有者权限
• 熟悉 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. 导航到组织设置 > 代码安全和分析
2. 为所有仓库或选定仓库启用 GitHub Advanced Security
3. 确认许可证席位分配（GHAS 按活跃提交者计费）

步骤 2 — 配置默认设置以快速获益

1. 前往仓库设置 > 代码安全 > 代码扫描
2. 在 CodeQL 分析行中点击"设置"并选择"默认"
3. 检查自动检测的语言和查询套件（默认或扩展）
4. 点击"启用 CodeQL"以在 push 和 pull request 事件上激活扫描

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

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

name: "CodeQL Analysis"

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]
  schedule:
    - cron: '30 2 * * 1'  # 每周一 UTC 2:30

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
          # 对于编译语言，在下面添加构建命令

      - 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/java-custom-queries@1.0.0
      codeql/java-queries:cwe/cwe-089

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

1. 导航到仓库设置 > 分支 > 分支保护规则
2. 启用"需要状态检查通过"并添加 CodeQL 分析检查
3. 启用"需要代码扫描结果"并设置严重性阈值（例如，拦截高危/严重问题）

步骤 6 — 机密扫描和推送保护

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

步骤 7 — 依赖审查和 Dependabot

1. 启用 Dependabot 告警和安全更新
2. 配置 .github/dependabot.yml 以自动更新依赖版本
3. 在 pull request 上启用依赖审查强制执行，以阻止引入已知易受攻击依赖的 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. 忽略定期扫描 — push/PR 扫描会遗漏依赖项中的漏洞；每周定期扫描可捕获现有代码中新披露的 CVE
3. security-and-quality 过度告警 — 从 default 套件开始，逐步扩展，以避免开发者告警疲劳
4. GHAS 许可证席位不足 — 只有对启用 GHAS 的仓库的活跃提交者才会消耗许可证席位；相应规划容量

参考资料

• GitHub Code Scanning Documentation
• CodeQL Documentation
• CodeQL Query Repository
• SARIF Specification
• GitHub Security Overview