actions/.serena/memories/github-workflow-secure-use.md

GitHub Actions Security Best Practices

Comprehensive guide for secure use of GitHub Actions workflows.

Core Security Principles

1. Principle of Least Privilege - Grant minimum necessary permissions
2. Defense in Depth - Layer multiple security controls
3. Zero Trust - Verify explicitly, never assume trust
4. Audit and Monitor - Track and review all security-relevant events

Secrets Management

Storing Secrets

✅ DO:

• Store sensitive data in GitHub Secrets
• Use organization-level secrets for shared values
• Use environment-specific secrets
• Register all secrets used in workflows

❌ DON'T:

• Hard-code secrets in workflow files
• Echo secrets to logs
• Store secrets in environment variables without masking

⚠️ USE WITH CAUTION:

• Structured secrets (JSON, YAML, multi-line keys): While sometimes necessary (e.g., service account keys, certificate bundles), they carry additional risks:
  • Risks: Parsing errors can expose content, accidental logging during manipulation, partial leaks when extracting fields
  • Mitigations:
    • Treat secrets as opaque blobs whenever possible (pass entire secret to tools without parsing)
    • Never print, echo, or log secrets during parsing/extraction
    • Use ::add-mask:: before any manipulation
    • Prefer base64-encoded single-line format for transport
    • Consider secrets managers (Vault, AWS Secrets Manager) for complex credentials
    • Write secrets to temporary files with restricted permissions rather than parsing in shell
    • Limit secret scope and access (repository-level, not organization-wide)
    • Parse/validate only in secure, well-audited code paths with proper error handling

Example:

- name: Use secret
  env:
    API_KEY: ${{ secrets.API_KEY }}
  run: |
    echo "::add-mask::$API_KEY"
    curl -H "Authorization: Bearer $API_KEY" https://api.example.com

Masking Sensitive Data

Always mask secrets before using them:

# Mask the secret
echo "::add-mask::$SECRET_VALUE"

# Use in commands; avoid printing it even when masked
curl -H "Authorization: Bearer $SECRET_VALUE" https://api.example.com

Secret Rotation

1. Immediately rotate exposed secrets
2. Delete compromised secrets from GitHub
3. Audit workflow runs that used the secret
4. Review access logs
5. Update all systems using the secret

Script Injection Prevention

The Problem

User input can inject malicious code:

# VULNERABLE
- name: Greet user
  run: echo "Hello ${{ github.event.issue.title }}"

If issue title is: "; rm -rf / #, the command becomes:

echo "Hello "; rm -rf / #"

Solution 1: Use Intermediate Environment Variables

# SAFE
- name: Greet user
  env:
    TITLE: ${{ github.event.issue.title }}
  run: echo "Hello $TITLE"

Solution 2: Use Actions Instead of Scripts

# SAFE - Use action instead of inline script
- name: Comment on PR
  uses: actions/github-script@v7
  with:
    script: |
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: `Hello ${context.payload.issue.title}`
      })

Solution 3: Proper Quoting

Always use double quotes for variables:

# VULNERABLE
echo Hello $USER_INPUT

# SAFE
echo "Hello $USER_INPUT"

High-Risk Inputs

Be especially careful with:

• github.event.issue.title
• github.event.issue.body
• github.event.pull_request.title
• github.event.pull_request.body
• github.event.comment.body
• github.event.review.body
• github.event.head_commit.message
• Any user-provided input

Third-Party Actions Security

Pinning Actions

✅ BEST: Pin to full commit SHA

- uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab # v3.5.2

⚠️ ACCEPTABLE: Pin to tag (for verified creators only)

- uses: actions/checkout@v3.5.2

❌ DANGEROUS: Use branch or mutable tag

- uses: actions/checkout@main # DON'T DO THIS

Auditing Actions

Before using third-party actions:

1. Review source code - Check the action's repository
2. Check maintainer - Look for "Verified creator" badge
3. Read reviews - Check community feedback
4. Verify permissions - Understand what the action accesses
5. Check dependencies - Review what the action installs

Verified Creators

Actions from these sources are generally safer:

• GitHub Official (actions/*)
• Major cloud providers (AWS, Azure, Google)
• Well-known organizations with verified badges

Token and Permission Management

GITHUB_TOKEN Permissions

Set restrictive defaults:

permissions:
  contents: read # Default to read-only

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write # Only elevate what's needed
    steps:
      - uses: actions/checkout@v3

Available Permissions

• actions: read|write
• checks: read|write
• contents: read|write
• deployments: read|write
• issues: read|write
• packages: read|write
• pages: read|write
• pull-requests: read|write
• repository-projects: read|write
• security-events: read|write
• statuses: read|write

Principle of Least Privilege

# GOOD - Minimal permissions
permissions:
  contents: read
  pull-requests: write  # Only what's needed

# BAD - Overly permissive
permissions: write-all

Runner Security

GitHub-Hosted Runners (Recommended)

✅ Advantages:

• Isolated, ephemeral environments
• Automatic patching and updates
• No infrastructure management
• Better security by default

Self-Hosted Runners

⚠️ Use with extreme caution:

Risks:

• Persistent environments can retain secrets
• Accessible to all workflows in repository (public repos)
• Requires security hardening
• Manual patching and updates

If you must use self-hosted:

1. Use JIT (Just-In-Time) runners

   • Ephemeral, created on-demand
   • Automatically destroyed after use

2. Never use self-hosted runners for public repositories

3. Organize into groups with restricted access

4. Implement network isolation

5. Use minimal, hardened OS images

6. Rotate regularly

Runner Groups

# Restrict workflow to specific runner group
runs-on:
  group: private-runners
  labels: ubuntu-latest

Code Scanning and Vulnerability Detection

Enable CodeQL

name: 'Code Scanning'
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v3
      - uses: github/codeql-action/init@v2
      - uses: github/codeql-action/autobuild@v2
      - uses: github/codeql-action/analyze@v2

Dependabot for Actions

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: 'github-actions'
    directory: '/'
    schedule:
      interval: 'weekly'

OpenID Connect (OIDC)

Use OIDC for cloud authentication (no long-lived credentials):

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # Required for OIDC
      contents: read
    steps:
      - uses: aws-actions/configure-aws-credentials@v2
        with:
          role-to-assume: arn:aws:iam::123456789012:role/MyRole
          aws-region: us-east-1

Environment Protection Rules

Use environments for sensitive deployments:

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://example.com
    steps:
      - name: Deploy
        run: ./deploy.sh

Configure in repository settings:

• Required reviewers
• Wait timer
• Deployment branches
• Environment secrets

Security Checklist

For Every Workflow

• Pin all third-party actions to commit SHAs
• Set minimal permissions at workflow/job level
• Use intermediate environment variables for user input
• Mask all secrets with ::add-mask::
• Never echo secrets to logs
• Use double quotes for shell variables
• Prefer actions over inline scripts
• Use GitHub-hosted runners when possible
• Enable code scanning (CodeQL)
• Configure Dependabot for actions

For Self-Hosted Runners

• Never use for public repositories
• Use JIT runners when possible
• Implement network isolation
• Use minimal, hardened OS images
• Rotate runners regularly
• Organize into restricted groups
• Monitor and audit runner activity
• Implement resource limits

For Secrets

• Use GitHub Secrets (not environment variables)
• Rotate secrets regularly
• Delete exposed secrets immediately
• Audit secret usage
• Use environment-specific secrets
• Never use structured data as secrets
• Implement secret scanning

Common Vulnerabilities

Command Injection

# VULNERABLE
run: echo "${{ github.event.comment.body }}"

# SAFE
env:
  COMMENT: ${{ github.event.comment.body }}
run: echo "$COMMENT"

Secret Exposure

# VULNERABLE
run: |
  echo "API Key: ${{ secrets.API_KEY }}"

# SAFE
run: |
  echo "::add-mask::${{ secrets.API_KEY }}"
  curl -H "Authorization: Bearer ${{ secrets.API_KEY }}" https://api.example.com

Privilege Escalation

# VULNERABLE - Too permissive
permissions: write-all

# SAFE - Minimal permissions
permissions:
  contents: read
  pull-requests: write

Supply Chain Security

OpenSSF Scorecard

Monitor your security posture:

name: Scorecard
on:
  schedule:
    - cron: '0 0 * * 0'

jobs:
  analysis:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      id-token: write
    steps:
      - uses: actions/checkout@v3
      - uses: ossf/scorecard-action@v2
      - uses: github/codeql-action/upload-sarif@v2

Software Bill of Materials (SBOM)

Track dependencies:

- name: Generate SBOM
  uses: anchore/sbom-action@v0
  with:
    path: ./
    format: spdx-json

Incident Response

If a security incident occurs:

1. Immediately rotate all potentially compromised secrets
2. Disable affected workflows
3. Review workflow run logs
4. Audit repository access
5. Check for unauthorized changes
6. Investigate all workflow runs during incident window
7. Document findings and remediation
8. Update security controls to prevent recurrence

Additional Resources

• GitHub Security Advisories
• Actions Security Hardening
• OIDC with Cloud Providers
• Self-Hosted Runner Security