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`：

```yaml
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 — 自定义查询包

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

```yaml
- 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（静态分析结果交换格式）上传：

```yaml
- 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](https://docs.github.com/en/code-security/code-scanning)
- [CodeQL Documentation](https://codeql.github.com/docs/)
- [CodeQL Query Repository](https://github.com/github/codeql)
- [SARIF Specification](https://sarifweb.azurewebsites.net/)
- [GitHub Security Overview](https://docs.github.com/en/code-security/security-overview/about-security-overview)