ci-security-scan.yml

name: Security

on:
  workflow_call:
    inputs:
      should_skip:
        description: "Whether to skip the workflow"
        required: false
        type: string
        default: "false"
      release_images_changed:
        description: "Whether to scan the upstream images pinned in security/release-images.json"
        required: false
        type: string
        default: "false"

permissions: {}

jobs:
  upstream-images:
    name: "Pinned upstream images"
    runs-on: ubuntu-latest
    # The four upstream images are shipped by digest and never built here, so no build gate has a
    # subject for them and the release evidence gate was the first thing that scanned them — which
    # is how v0.75.0 discovered a days-old finding at the worst possible moment (#1741). A digest
    # needs no build, so the pull request that changes one scans it.
    if: inputs.should_skip != 'true' && inputs.release_images_changed == 'true'
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 1
          persist-credentials: false

      - uses: ./.github/actions/setup-node-pnpm
        with:
          install: "none"

      - uses: ./.github/actions/setup-release-security-tools
        with:
          install-syft: "false"

      # A blocking gate inherits Trivy's database availability as a hard dependency, so the
      # retries and the mirror fallback live in one action rather than in each caller.
      - uses: ./.github/actions/download-trivy-db

      - name: Enforce the release vulnerability policy on the pinned digests
        run: node scripts/scan-upstream-images.ts reports

      # The gate's exit status alone cannot say which digest carries which finding.
      - name: Upload the vulnerability policy results
        if: ${{ !cancelled() }}
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: vulnerability-policy-upstream
          path: reports
          if-no-files-found: warn
          retention-days: 7

  dependency-review:
    name: "New dependency risk"
    runs-on: ubuntu-latest
    if: inputs.should_skip != 'true' && github.event_name == 'pull_request'
    timeout-minutes: 5
    permissions:
      contents: read
    steps:
      - name: Review dependency changes
        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
        with:
          fail-on-severity: high
          # CI tooling is part of the release trust boundary.
          fail-on-scopes: runtime, development, unknown
          license-check: true
          show-patched-versions: true
          vulnerability-check: true

  security-scan:
    name: "Dependencies, secrets, and policy"
    runs-on: ubuntu-latest
    if: inputs.should_skip != 'true'
    timeout-minutes: 10
    permissions:
      security-events: write
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Trivy dependency scan
        id: dependencies
        continue-on-error: true
        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0
        with:
          scan-type: "fs"
          scan-ref: "."
          format: "sarif"
          output: "trivy-results.sarif"

      - name: Upload Trivy results
        if: always()
        continue-on-error: true
        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
        with:
          sarif_file: "trivy-results.sarif"

      - name: Secret detection
        id: secrets
        continue-on-error: true
        uses: trufflesecurity/trufflehog@20652fbbdefffcdaa493a5bf57ab2ac6b1db715b # v3.97.1
        with:
          path: ./
          base: ${{ github.event_name == 'pull_request' && github.base_ref || '' }}
          head: ${{ github.event_name == 'pull_request' && 'HEAD' || '' }}
          extra_args: --debug --only-verified

      # RFC 9116 requires a valid Expires date. Fail before it lapses so an
      # active branch is forced to renew it — a stale file signals abandonment.
      - name: security.txt freshness
        id: policy
        continue-on-error: true
        run: |
          file="webapp/public/.well-known/security.txt"
          expires="$(grep -i '^Expires:' "$file" | head -1 | cut -d' ' -f2)"
          if [ -z "$expires" ]; then
            echo "::error file=$file::Missing required RFC 9116 Expires field"
            exit 1
          fi

          days=$(( ( $(date -u -d "$expires" +%s) - $(date -u +%s) ) / 86400 ))
          echo "security.txt expires in $days day(s) ($expires)"
          if [ "$days" -lt 30 ]; then
            echo "::error file=$file::Expires is $days day(s) away (<30); renew it per RFC 9116"
            exit 1
          fi

      - name: Evaluate security checks
        id: security
        if: always()
        continue-on-error: true
        env:
          DEPENDENCIES: ${{ steps.dependencies.outcome }}
          SECRETS: ${{ steps.secrets.outcome }}
          POLICY: ${{ steps.policy.outcome }}
        run: |
          failed=false
          for result in "$DEPENDENCIES" "$SECRETS" "$POLICY"; do
            if [ "$result" != "success" ]; then failed=true; fi
          done
          if [ "$failed" = "true" ]; then
            echo "::error::One or more security checks failed; review the independently reported steps above."
            exit 1
          fi

      - name: Resolve released-chain baseline
        id: baseline
        continue-on-error: true
        if: always()
        env:
          PUSH_BEFORE: ${{ github.event.before }}
          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
        run: |
          set -euo pipefail
          BASE=""
          if [ "$GITHUB_EVENT_NAME" = "pull_request" ]; then
            if ! git cat-file -e "$PR_BASE_SHA^{commit}" 2>/dev/null; then
              echo "::error::PR base commit $PR_BASE_SHA is not in local history — this job needs fetch-depth: 0. Refusing to pass without checking."
              exit 1
            fi
            BASE="$PR_BASE_SHA"
          elif [ -n "$PUSH_BEFORE" ] && git cat-file -e "$PUSH_BEFORE^{commit}" 2>/dev/null; then
            BASE="$PUSH_BEFORE"
          fi
          echo "base=$BASE" >> "$GITHUB_OUTPUT"
          echo "Baseline: ${BASE:-<none — no reachable previous tip, nothing to enforce>}"

      - name: Changelog immutability guard
        id: changelog-policy
        continue-on-error: true
        if: steps.baseline.outputs.base != ''
        env:
          BASE: ${{ steps.baseline.outputs.base }}
          RELEASED_REF: ${{ github.event_name == 'pull_request' && github.base_ref || 'main' }}
        run: |
          set -euo pipefail
          CHANGELOG_DIR="server/application/src/main/resources/db/changelog"
          MASTER="server/application/src/main/resources/db/master.xml"
          FAILED=false

          VIOLATIONS=$(git diff --name-only --diff-filter=MDR "$BASE" HEAD -- "$CHANGELOG_DIR")
          if [ -n "$VIOLATIONS" ]; then
            FAILED=true
            echo "::error::Released Liquibase changesets were modified, renamed, or deleted. Ship a new follow-up changelog instead:"
            echo "$VIOLATIONS"
          fi

          git show "$BASE:$MASTER" 2>/dev/null | grep '<include ' > /tmp/includes-base || true
          grep '<include ' "$MASTER" > /tmp/includes-head || true
          if [ -s /tmp/includes-base ] && ! diff /tmp/includes-base <(head -n "$(wc -l < /tmp/includes-base)" /tmp/includes-head) >/dev/null; then
            FAILED=true
            echo "::error::master.xml is append-only: an existing <include> was removed, reordered, or edited. New changelogs go at the end of the list."
          fi

          if [ "$FAILED" = "true" ]; then
            {
              echo "### Changelog immutability"
              echo "Changesets that reached \`$RELEASED_REF\` may already be applied to production databases — editing or removing them breaks the upgrade path (checksum errors or silently orphaned changesets)."
              echo "Fix forward with a **new** changelog appended to \`master.xml\`. See \`docs/contributor/database-migration.mdx\`."
            } >> "$GITHUB_STEP_SUMMARY"
            exit 1
          fi
          echo "No released changeset was touched; master.xml stays append-only."

      - name: Assert no legacy agent-image references
        id: legacy-image-policy
        continue-on-error: true
        if: always()
        run: |
          set -euo pipefail
          NEEDLE="agent-$(printf 'open\x63ode')"
          if grep -rEnI "$NEEDLE" \
                --exclude-dir=node_modules --exclude-dir=target --exclude-dir=.git \
                . \
              | grep -vE '^\./(MIGRATION\.md|docs/admin/release-image-lock\.md):' ; then
            echo "::error::Legacy agent image is removed in issue #1076; relocate any new references to MIGRATION.md."
            exit 1
          fi
      - name: Assert no release-channel agent image references
        id: release-channel-policy
        continue-on-error: true
        if: always()
        run: |
          set -euo pipefail
          NEEDLE="agent-pi:$(printf 'lat\x65st')"
          if grep -rEnI "$NEEDLE" \
                --exclude-dir=node_modules --exclude-dir=target --exclude-dir=.git \
                . \
              | grep -vE '^\./(MIGRATION\.md|docs/admin/release-image-lock\.md|docs/decisions/0031-.*\.md|server/application/src/test/java/de/tum/cit/aet/hephaestus/agent/sandbox/AgentImageReferenceGuardTest\.java):' ; then
            echo "::error::A release-channel agent image tag resolves to another release's image (ADR 0031). Leave the reference unset so it follows this deployment's image tag, or pin a digest."
            exit 1
          fi

      - name: Assert no legacy agent-image-pin.env references
        id: legacy-pin-policy
        continue-on-error: true
        if: always()
        run: |
          set -euo pipefail
          if grep -rEnI 'docker/agent-image-pin(\.local)?\.env' \
                --exclude-dir=node_modules --exclude-dir=target --exclude-dir=.git \
                . \
              | grep -vE '^\./(MIGRATION\.md|docs/admin/release-image-lock\.md):' \
              | grep -vE '^\./scripts/check-agent-instructions\.ts:[0-9]+:[[:space:]]*value: "docker/agent-image-pin(\.local)?\.env",$' ; then
            echo "::error::Legacy pin-file names are allowed only in migration history, the digest guide, and exact instruction-checker exceptions."
            exit 1
          fi

      - name: Evaluate security and repository policy
        if: always()
        env:
          SECURITY: ${{ steps.security.outcome }}
          BASELINE: ${{ steps.baseline.outcome }}
          CHANGELOG: ${{ steps.changelog-policy.outcome }}
          LEGACY_IMAGE: ${{ steps.legacy-image-policy.outcome }}
          RELEASE_CHANNEL: ${{ steps.release-channel-policy.outcome }}
          LEGACY_PIN: ${{ steps.legacy-pin-policy.outcome }}
        run: |
          failed=false
          for result in "$SECURITY" "$BASELINE" "$CHANGELOG" "$LEGACY_IMAGE" "$RELEASE_CHANNEL" "$LEGACY_PIN"; do
            if [ "$result" = "failure" ] || [ "$result" = "cancelled" ]; then failed=true; fi
          done
          if [ "$failed" = "true" ]; then
            echo "::error::One or more security or repository policy checks failed; review the independently reported steps above."
            exit 1
          fi