Protegendo Workflows do GitHub Actions

Quando Usar

• Quando o GitHub Actions é a plataforma de CI/CD e os workflows precisam ser endurecidos contra ataques à cadeia de suprimentos.
• Quando workflows manipulam segredos, fazem deploy em produção ou possuem permissões elevadas.
• Ao prevenir injeção de scripts através de títulos de PR, nomes de branches ou mensagens de commit não confiáveis.
• Ao exigir trilhas de auditoria e portões de aprovação para modificações de workflow.
• Quando ações de terceiros representam risco à cadeia de suprimentos através de tags de versão mutáveis.

Não use para proteger outras plataformas de CI/CD (veja guias de endurecimento específicos da plataforma), para varredura de vulnerabilidades de aplicações (use SAST/DAST) ou para detecção de segredos em código (use Gitleaks).

Pré-requisitos

• Repositório GitHub com GitHub Actions habilitado.
• Acesso de administrador da organização GitHub para configurações em nível de organização.
• Compreensão da sintaxe de workflow e eventos do GitHub Actions.

Workflow

Passo 1: Fixar Ações em SHA Digests

# INSECURE: Mutable tag can be overwritten by attacker
- uses: actions/checkout@v4

# SECURE: Pinned to immutable SHA digest
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11  # v4.1.1

# Use Dependabot to auto-update pinned SHAs
# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    commit-message:
      prefix: "ci"

Passo 2: Minimizar Permissões do GITHUB_TOKEN

# Set restrictive default permissions at workflow level
name: CI Pipeline
permissions: {}  # Start with no permissions

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read  # Only what's needed
    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  # For OIDC-based cloud auth
    steps:
      - name: Deploy
        run: echo "deploying"

Passo 3: Prevenir Injeção de Scripts

# VULNERABLE: User-controlled input in run step
- run: echo "PR title is ${{ github.event.pull_request.title }}"

# SECURE: Use environment variable (properly escaped by 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}"

# SECURE: Use actions/github-script for complex operations
- uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea
  with:
    script: |
      const title = context.payload.pull_request.title;
      console.log(`PR title: ${title}`);

Passo 4: Proteger o Tratamento de Pull Requests de Forks

# DANGEROUS: pull_request_target runs with base repo permissions
# on: pull_request_target  # AVOID unless absolutely necessary

# SAFE: pull_request runs in fork context with limited permissions
on:
  pull_request:
    branches: [main]

# If pull_request_target is required, never checkout PR code:
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:
      # NEVER do: actions/checkout with ref: ${{ github.event.pull_request.head.sha }}
      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
        # This checks out the BASE branch, not the PR

Passo 5: Proteger Segredos e Variáveis de Ambiente

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production  # Requires approval
    steps:
      - name: Deploy with secret
        env:
          # Secrets are masked in logs automatically
          DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
        run: |
          # Never echo secrets
          # echo "$DEPLOY_KEY"  # BAD
          deploy-tool --key-file <(echo "$DEPLOY_KEY")

      - name: Audit secret access
        run: |
          # Log that secret was used without exposing it
          echo "::notice::Deploy key accessed for production deployment"

Passo 6: Implementar Controles de Mudança de Workflow

# Exigir aprovação do CODEOWNERS para mudanças de workflow
# .github/CODEOWNERS
.github/workflows/ @security-team @platform-team
.github/actions/ @security-team @platform-team

# Configurações da organização:
# 1. Settings > Actions > General > Fork PR policies

…