securing-github-actions-workflows

# 加固 GitHub Actions 工作流

## 使用场景

- 当 GitHub Actions 是 CI/CD 平台且工作流需要针对供应链攻击进行加固时
- 当工作流处理机密、部署到生产环境或具有提升的权限时
- 当需要防止通过不受信任的 PR 标题、分支名称或提交信息进行脚本注入时
- 当需要工作流修改的审计跟踪和审批门禁时
- 当第三方 action 通过可变版本标签带来供应链风险时

**不适用于**加固其他 CI/CD 平台（参见特定平台加固指南）、应用程序漏洞扫描（使用 SAST/DAST）或代码中的机密检测（使用 Gitleaks）。

## 前置条件

- 已启用 GitHub Actions 的 GitHub 仓库
- GitHub 组织管理员访问权限（用于组织级设置）
- 了解 GitHub Actions 工作流语法和事件

## 操作流程

### 步骤 1：将 Action 固定到 SHA 摘要

```yaml
# 不安全：可变标签可能被攻击者覆盖
- uses: actions/checkout@v4

# 安全：固定到不可变的 SHA 摘要
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1

# 使用 Dependabot 自动更新固定的 SHA
# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    commit-message:
      prefix: "ci"
```

### 步骤 2：最小化 GITHUB_TOKEN 权限

```yaml
# 在工作流级别设置严格的默认权限
name: CI Pipeline
permissions: {}  # 从零权限开始

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read  # 仅授予所需权限
    steps:
      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11

  deploy:
    runs-on: ubuntu-latest
    needs: build
    if: github.ref == 'refs/heads/main'
    permissions:
      contents: read
      deployments: write
      id-token: write  # 用于基于 OIDC 的云认证
    steps:
      - name: Deploy
        run: echo "deploying"
```

### 步骤 3：防止脚本注入

```yaml
# 存在漏洞：run 步骤中包含用户控制的输入
- run: echo "PR title is ${{ github.event.pull_request.title }}"

# 安全：使用环境变量（由 shell 正确转义）
- name: Process PR
  env:
    PR_TITLE: ${{ github.event.pull_request.title }}
    PR_BODY: ${{ github.event.pull_request.body }}
  run: |
    echo "PR title is ${PR_TITLE}"
    echo "PR body is ${PR_BODY}"

# 安全：使用 actions/github-script 处理复杂操作
- uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea
  with:
    script: |
      const title = context.payload.pull_request.title;
      console.log(`PR title: ${title}`);
```

### 步骤 4：安全处理 Fork Pull Request

```yaml
# 危险：pull_request_target 以基础仓库权限运行
# on: pull_request_target  # 除非绝对必要，否则避免使用

# 安全：pull_request 在 fork 上下文中以有限权限运行
on:
  pull_request:
    branches: [main]

# 如果必须使用 pull_request_target，切勿检出 PR 代码：
on:
  pull_request_target:
    types: [labeled]

jobs:
  safe-job:
    if: contains(github.event.pull_request.labels.*.name, 'safe-to-test')
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      # 切勿执行：带 ref: ${{ github.event.pull_request.head.sha }} 的 actions/checkout
      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
        # 这会检出基础分支，而非 PR 分支
```

### 步骤 5：保护机密和环境变量

```yaml
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production  # 需要审批
    steps:
      - name: 使用机密进行部署
        env:
          # 机密在日志中自动屏蔽
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
        run: |
          # 切勿打印机密
          # echo "$DEPLOY_KEY"  # 错误做法
          deploy-tool --key-file <(echo "$DEPLOY_KEY")

      - name: 审计机密访问
        run: |
          # 记录机密使用情况而不暴露内容
          echo "::notice::已为生产部署访问部署密钥"
```

### 步骤 6：实施工作流变更控制

```yaml
# 要求 CODEOWNERS 审批工作流变更
# .github/CODEOWNERS
.github/workflows/ @security-team @platform-team
.github/actions/ @security-team @platform-team

# 组织设置：
# 1. 设置 > Actions > 常规 > Fork PR 策略
#    - 首次贡献者需要审批
#    - 所有外部协作者需要审批
# 2. 设置 > Actions > 常规 > 工作流权限
#    - 读取仓库内容和包的权限
#    - 不允许 GitHub Actions 创建和审批 PR
```

## 关键概念

| 术语 | 定义 |
|------|------|
| SHA 固定 | 通过不可变的提交 SHA 而非可变版本标签引用 GitHub Action |
| 脚本注入 | 不受信任的输入（PR 标题、分支名称）被插入到 shell 命令中的攻击 |
| GITHUB_TOKEN | 自动生成的令牌，权限范围限于当前仓库，可配置 |
| pull_request_target | 危险的事件触发器，在 fork PR 上以基础仓库的完整权限运行 |
| 环境保护 | GitHub 功能，要求在访问环境的作业运行前进行人工审批 |
| CODEOWNERS | 定义特定路径（包括工作流文件）所需审阅者的文件 |
| OIDC 联合 | 使用 GitHub 的 OIDC 令牌向云提供商认证，无需存储长期凭据 |

## 工具与系统

- **Dependabot**：自动化依赖更新器，保持固定的 action SHA 处于最新状态
- **StepSecurity Harden Runner**：监控并限制工作流出站网络调用的 GitHub Action
- **actionlint**：检测安全问题的 GitHub Actions 工作流文件代码检查器
- **allstar**：OpenSSF 的 GitHub App，对仓库强制执行安全策略
- **scorecard**：评估供应链安全实践（包括 CI/CD）的 OpenSSF 工具

## 常见场景

### 场景：防范受攻陷的第三方 Action 供应链攻击

**背景**：一个广泛使用的 GitHub Action 被攻陷，其 v3 标签被更新为包含凭据盗窃代码。使用 `@v3` 的仓库自动拉取恶意版本。

**方法**：
1. 立即在所有仓库中将所有 action 固定到 SHA 摘要
2. 为 github-actions 生态系统配置 Dependabot 以管理 SHA 更新
3. 限制 GITHUB_TOKEN 权限，使即便受攻陷的 action 也只有最小访问权限
4. 添加 StepSecurity harden-runner 以检测异常的出站网络调用
5. 审查所有第三方 action，并将不必要的替换为内联脚本
6. 要求对 `.github/workflows/` 的任何变更进行 CODEOWNERS 审批

**注意事项**：不使用 Dependabot 的 SHA 固定意味着错过 action 的合法安全更新。过于严格的权限可能破坏合法工作流。使用 `pull_request_target` 进行基于标签的门控，如果工作流检出 PR 代码仍会暴露机密。

## 输出格式

```
GitHub Actions 安全审计
================================
仓库：org/web-application
日期：2026-02-23

工作流分析：
  工作流总数：8
  Action 引用总数：34

SHA 固定：
  [失败] 12/34 个 action 使用可变标签而非 SHA 摘要
  - .github/workflows/ci.yml: actions/setup-node@v4
  - .github/workflows/deploy.yml: aws-actions/configure-aws-credentials@v4

权限：
  [失败] 3/8 个工作流没有明确权限定义（继承默认值）
  [警告] 1/8 个工作流请求 write-all 权限

脚本注入：
  [失败] 2 个工作流步骤直接插入用户输入
  - .github/workflows/pr-check.yml:23: ${{ github.event.pull_request.title }}

机密：
  [通过] 工作流日志中没有暴露机密
  [通过] 所有生产部署使用环境保护

评分：6/10（修复 5 个高危发现）
```