security.yml

---
# Pullbox Security Pipeline
# Dependency audits, secret scanning, and static analysis hardening.
# GitHub Actions is the canonical security runner. Same-repository maintainer
# PRs run the full security gate after `ci:full`.
#
# Security: All actions pinned to full SHA. No pull_request_target.
# See: docs/development/INFRASTRUCTURE.md
#
# Tools:
#   pip-audit → PyPI advisory service (shared blocking exception policy)
#   safety    → Safety DB (secondary, different vulnerability coverage)
#   gitleaks  → blocking secret scan
#   bandit    → advisory static analysis during initial rollout
#   CodeQL    → public-repo static analysis, informational until promoted

name: Security

on:
  pull_request:
    branches:
      - develop
      - main
    types:
      - opened
      - synchronize
      - reopened
      - ready_for_review
      - labeled
      - unlabeled
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: security-${{ github.ref || github.run_id }}
  cancel-in-progress: true

jobs:
  release_sync_check:
    name: Release Sync Check
    runs-on: ubuntu-latest
    timeout-minutes: 5
    outputs:
      is_sync: ${{ steps.release-sync.outputs.is_sync }}
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0

      - name: Detect safe post-release sync PR
        id: release-sync
        env:
          RELEASE_SYNC_EVENT_NAME: ${{ github.event_name }}
          RELEASE_SYNC_BASE_REF: ${{ github.base_ref || '' }}
          RELEASE_SYNC_HEAD_REF: ${{ github.head_ref || '' }}
          RELEASE_SYNC_REPOSITORY: ${{ github.repository }}
          RELEASE_SYNC_HEAD_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name || '' }}
          RELEASE_SYNC_ACTOR: ${{ github.actor }}
        run: |
          git fetch --no-tags origin main:refs/remotes/origin/main
          if ! git cat-file -e origin/main:.github/scripts/validate-release-sync-pr.py 2>/dev/null; then
            echo "is_sync=false" >> "$GITHUB_OUTPUT"
            echo "reason=trusted release sync validator is not available on origin/main yet" >> "$GITHUB_OUTPUT"
            echo "release_sync=false"
            echo "reason=trusted release sync validator is not available on origin/main yet"
            exit 0
          fi
          git show origin/main:.github/scripts/validate-release-sync-pr.py > /tmp/pullbox-release-sync-validator.py
          python /tmp/pullbox-release-sync-validator.py

  full_ci_check:
    name: Full Security Gate
    runs-on: ubuntu-latest
    timeout-minutes: 5
    outputs:
      run_full: ${{ steps.gate.outputs.run_full }}
      label_required: ${{ steps.gate.outputs.label_required }}
    permissions:
      contents: read
    steps:
      - name: Resolve full security gate
        id: gate
        run: |
          echo "run_full=${{ github.event_name == 'workflow_dispatch' || (github.event_name == 'pull_request' && !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name != github.repository || github.actor == 'dependabot[bot]' || startsWith(github.event.pull_request.head.ref, 'dependabot/') || contains(github.event.pull_request.labels.*.name, 'ci:full'))) }}" >> "$GITHUB_OUTPUT"
          echo "label_required=${{ github.event_name == 'pull_request' && !github.event.pull_request.draft && github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]' && !startsWith(github.event.pull_request.head.ref, 'dependabot/') && !contains(github.event.pull_request.labels.*.name, 'ci:full') }}" >> "$GITHUB_OUTPUT"

  # ──────────────────────────────────────────────
  # Job 1: gitleaks (blocking secret scan)
  # ──────────────────────────────────────────────
  gitleaks:
    name: Gitleaks
    needs: [release_sync_check, full_ci_check]
    if: needs.release_sync_check.outputs.is_sync != 'true' && needs.full_ci_check.outputs.run_full == 'true'
    runs-on: ${{ fromJSON(((github.event_name == 'pull_request' && (github.event.pull_request.head.repo.full_name != github.repository || github.actor == 'dependabot[bot]')) || vars.PULLBOX_CHECKS_RUNNER == 'github-hosted') && '["ubuntu-latest"]' || '["self-hosted","Linux","X64","checks"]') }}
    timeout-minutes: 20
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0

      - name: Runner preflight
        run: .github/scripts/preflight-runner.sh docker

      - name: Resolve scan range
        id: range
        env:
          EVENT_NAME: ${{ github.event_name }}
          BEFORE_SHA: ${{ github.event.before }}
          AFTER_SHA: ${{ github.sha }}
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: |
          if [ "$EVENT_NAME" = "pull_request" ]; then
            echo "mode=git" >> "$GITHUB_OUTPUT"
            {
              echo "log_opts<<EOF"
              echo "--no-merges ${BASE_SHA}..${HEAD_SHA}"
              echo "EOF"
            } >> "$GITHUB_OUTPUT"
          elif [ "$EVENT_NAME" = "push" ] && [ "$BEFORE_SHA" != "0000000000000000000000000000000000000000" ]; then
            echo "mode=git" >> "$GITHUB_OUTPUT"
            {
              echo "log_opts<<EOF"
              echo "--no-merges ${BEFORE_SHA}..${AFTER_SHA}"
              echo "EOF"
            } >> "$GITHUB_OUTPUT"
          else
            echo "mode=dir" >> "$GITHUB_OUTPUT"
          fi

      - name: Run gitleaks on new commits
        if: steps.range.outputs.mode == 'git'
        env:
          GITLEAKS_IMAGE: ghcr.io/gitleaks/gitleaks@sha256:c00b6bd0aeb3071cbcb79009cb16a60dd9e0a7c60e2be9ab65d25e6bc8abbb7f
        run: |
          docker run --rm \
            --user "$(id -u):$(id -g)" \
            -v "$PWD:/repo" \
            -w /repo \
            "$GITLEAKS_IMAGE" \
            git . \
            --log-opts="${{ steps.range.outputs.log_opts }}" \
            --no-banner \
            --redact \
            --timeout=300 \
            --report-format sarif \
            --report-path gitleaks.sarif

      - name: Run gitleaks on current tree
        if: steps.range.outputs.mode == 'dir'
        env:
          GITLEAKS_IMAGE: ghcr.io/gitleaks/gitleaks@sha256:c00b6bd0aeb3071cbcb79009cb16a60dd9e0a7c60e2be9ab65d25e6bc8abbb7f
        run: |
          docker run --rm \
            --user "$(id -u):$(id -g)" \
            -v "$PWD:/repo" \
            -w /repo \
            "$GITLEAKS_IMAGE" \
            dir . \
            --no-banner \
            --redact \
            --timeout=300 \
            --report-format sarif \
            --report-path gitleaks.sarif

      - name: Upload gitleaks report
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: gitleaks-report
          path: gitleaks.sarif
          retention-days: 14

  # ──────────────────────────────────────────────
  # Job 2: pip-audit (PyPI advisory service)
  # ──────────────────────────────────────────────
  dependency-audit:
    name: pip-audit
    needs: [release_sync_check, full_ci_check]
    if: needs.release_sync_check.outputs.is_sync != 'true' && needs.full_ci_check.outputs.run_full == 'true'
    runs-on: ${{ fromJSON(((github.event_name == 'pull_request' && (github.event.pull_request.head.repo.full_name != github.repository || github.actor == 'dependabot[bot]')) || vars.PULLBOX_CHECKS_RUNNER == 'github-hosted') && '["ubuntu-latest"]' || '["self-hosted","Linux","X64","checks"]') }}
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.14"

      - name: Setup runner-local venv
        run: .github/scripts/setup-runner-venv.sh "dev"

      - name: Runner preflight
        run: .github/scripts/preflight-runner.sh python

      - name: Run pip-audit
        run: |
          # Generate requirements from installed packages, excluding editable pullbox
          requirements_file="$(mktemp /tmp/pullbox-requirements-audit.XXXXXX.txt)"
          trap 'rm -f "$requirements_file"' EXIT
          python -m pip freeze --exclude-editable | grep -v "^pullbox==" > "$requirements_file"
          python scripts/run_dependency_audit.py -r "$requirements_file"

      - name: Upload dependency audit report
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: dependency-audit-report
          path: dependency-audit-report.json
          retention-days: 14

  # ──────────────────────────────────────────────
  # Job 3: safety (Safety DB — secondary scanner)
  # ──────────────────────────────────────────────
  safety-check:
    name: Safety Check
    needs: [release_sync_check, full_ci_check]
    if: needs.release_sync_check.outputs.is_sync != 'true' && needs.full_ci_check.outputs.run_full == 'true'
    runs-on: ${{ fromJSON(((github.event_name == 'pull_request' && (github.event.pull_request.head.repo.full_name != github.repository || github.actor == 'dependabot[bot]')) || vars.PULLBOX_CHECKS_RUNNER == 'github-hosted') && '["ubuntu-latest"]' || '["self-hosted","Linux","X64","checks"]') }}
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.14"

      - name: Setup runner-local venv
        run: .github/scripts/setup-runner-venv.sh "dev"

      - name: Runner preflight
        run: .github/scripts/preflight-runner.sh python

      # Non-blocking initially (|| true) — safety free tier has limitations.
      # Remove || true once confirmed stable.
      - name: Run safety check
        run: safety check --save-json safety-report.json || true

      - name: Upload safety report
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: safety-report
          path: safety-report.json
          retention-days: 14

  # ──────────────────────────────────────────────
  # Job 4: bandit (advisory rollout)
  # ──────────────────────────────────────────────
  bandit:
    name: Bandit
    needs: [release_sync_check, full_ci_check]
    if: needs.release_sync_check.outputs.is_sync != 'true' && needs.full_ci_check.outputs.run_full == 'true'
    runs-on: ${{ fromJSON(((github.event_name == 'pull_request' && (github.event.pull_request.head.repo.full_name != github.repository || github.actor == 'dependabot[bot]')) || vars.PULLBOX_CHECKS_RUNNER == 'github-hosted') && '["ubuntu-latest"]' || '["self-hosted","Linux","X64","checks"]') }}
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.14"

      - name: Setup runner-local venv
        run: .github/scripts/setup-runner-venv.sh "dev"

      - name: Runner preflight
        run: .github/scripts/preflight-runner.sh python

      - name: Run Bandit
        id: bandit
        continue-on-error: true
        run: bandit -r src/pullbox/ -ll -f json -o bandit-report.json

      - name: Summarize Bandit result
        if: always()
        run: |
          if [ "${{ steps.bandit.outcome }}" = "failure" ]; then
            echo "::warning::Bandit reported medium-or-higher findings. Review the uploaded artifact."
          else
            echo "Bandit found no medium-or-higher issues."
          fi

      - name: Upload Bandit report
        if: always()
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: bandit-report
          path: bandit-report.json
          retention-days: 14

  # ──────────────────────────────────────────────
  # Job 5: CodeQL Static Analysis
  # ──────────────────────────────────────────────
  codeql:
    name: CodeQL Analysis
    needs: [release_sync_check, full_ci_check]
    if: needs.release_sync_check.outputs.is_sync != 'true' && needs.full_ci_check.outputs.run_full == 'true' && (github.repository_visibility == 'public' || vars.PULLBOX_ENABLE_CODEQL == 'true')
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: read
      actions: read
      security-events: write
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Initialize CodeQL
        uses: github/codeql-action/init@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
        with:
          languages: python
          queries: +security-extended
          config-file: ./.github/codeql/codeql-config.yml

      - name: Perform CodeQL analysis
        uses: github/codeql-action/analyze@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
        with:
          category: "/language:python"

  # Stable aggregate required check for branch rulesets.
  security-required:
    name: Security Required
    runs-on: ubuntu-latest
    needs:
      - release_sync_check
      - full_ci_check
      - gitleaks
      - dependency-audit
      - safety-check
      - bandit
      - codeql
    if: always()
    timeout-minutes: 5
    permissions:
      contents: read
    steps:
      - name: Verify required security jobs
        env:
          NEEDS_CONTEXT: ${{ toJson(needs) }}
          CODEQL_BLOCKING: ${{ vars.PULLBOX_REQUIRE_CODEQL == 'true' }}
          RELEASE_SYNC_PR: ${{ needs.release_sync_check.outputs.is_sync }}
          RUN_FULL: ${{ needs.full_ci_check.outputs.run_full }}
          LABEL_REQUIRED: ${{ needs.full_ci_check.outputs.label_required }}
        run: |
          python - <<'PY'
          import json
          import os
          import sys

          needs = json.loads(os.environ["NEEDS_CONTEXT"])
          codeql_blocking = os.environ["CODEQL_BLOCKING"].lower() == "true"
          release_sync_pr = os.environ["RELEASE_SYNC_PR"].lower() == "true"
          run_full = os.environ["RUN_FULL"].lower() == "true"
          label_required = os.environ["LABEL_REQUIRED"].lower() == "true"
          if release_sync_pr:
              release_sync = needs.get("release_sync_check", {}).get("result")
              if release_sync != "success":
                  print(f"Release sync validation failed: {release_sync}", file=sys.stderr)
                  sys.exit(1)
              unexpected = {
                  name: info.get("result")
                  for name, info in needs.items()
                  if name != "release_sync_check" and info.get("result") not in {"skipped", "success"}
              }
              if unexpected:
                  print(f"Release sync fast path saw unexpected job results: {unexpected}", file=sys.stderr)
                  sys.exit(1)
              print("Release sync fast path validated; heavyweight security jobs intentionally skipped.")
              sys.exit(0)

          if not run_full:
              if label_required:
                  print("Security gate is waiting for ci:full before running the full required checks.", file=sys.stderr)
              else:
                  print("Security gate was intentionally not requested for this PR state.", file=sys.stderr)
              sys.exit(1)

          failed = {}
          for name, info in needs.items():
              result = info.get("result")
              if name == "codeql" and not codeql_blocking:
                  if result != "success":
                      print(f"CodeQL is informational for now; observed result: {result}")
                  continue
              if result != "success":
                  failed[name] = result
          if failed:
              print(f"Required security jobs did not all pass: {failed}", file=sys.stderr)
              sys.exit(1)
          print("All required security jobs passed.")
          PY