sca-scan-and-guard.yaml

name: SCA Scan and Guard

# Shareable workflow for Software Composition Analysis (SCA) scanning
# Runs FOSSA scan with licensing and vulnerability checks
# Supports both PR (diff-based) and Release (full scan) contexts

on:
  workflow_call:
    inputs:
      git_ref:
        description: 'Git ref to checkout (e.g., 0.0.269 for releases). Leave empty for PR context.'
        required: false
        type: string
      skip_policy_gate:
        description: 'EMERGENCY: Skip policy/licensing gate (requires admin permission)'
        required: false
        type: boolean
        default: false
      skip_vulnerability_gate:
        description: 'EMERGENCY: Skip vulnerability gate (requires admin permission)'
        required: false
        type: boolean
        default: false
      bypass_justification:
        description: 'REQUIRED if either bypass gate is used: Justification for emergency bypass'
        required: false
        type: string
        default: ''
      use_vault:
        description: 'Retrieve FOSSA API key from Vault (true for private repos). If false, expects FOSSA_API_KEY secret.'
        required: false
        type: boolean
        default: false
      config_file:
        description: 'Path to workflow configuration file (workflow-config.json). Overrides individual inputs if provided.'
        required: false
        type: string
        default: '.github/workflow-config.json'
      additional_scan_params:
        description: |
          Additional scanner-specific parameters (one per line):
            fossa.debug=true
            fossa.team=Platform Team
        required: false
        type: string
        default: ''

      # Dependency Setup Configuration
      setup_actions:
        description: "JSON array of setup actions to perform (e.g., ['setup-java', 'maven-settings'])"
        required: false
        type: string
        default: ''
      vault_secrets:
        description: "Multiline string of secrets to retrieve from Vault (format: secret/path KEY | ENV_VAR)"
        required: false
        type: string
        default: ''
      custom_setup_script:
        description: |
          Custom setup script to execute before scan. Use this to run build or install commands, e.g.:
            mvn clean install -DskipTests
            npm ci
            pip install -r requirements.txt
            uv export --format requirements-txt --no-dev --output-file requirements.txt
            dotnet restore
        required: false
        type: string
        default: ''

      # Language Versions
      java_version:
        description: "Java version"
        required: false
        type: string
        default: "17"
      java_distribution:
        description: "Java distribution (default: 'temurin')"
        required: false
        type: string
        default: ''
      node_version:
        description: "Node version"
        required: false
        type: string
        default: "20"
      npm_registry_url:
        description: "NPM registry URL (default: 'https://npm.pkg.github.com')"
        required: false
        type: string
        default: ''
      python_version:
        description: "Python version"
        required: false
        type: string
        default: "3.10"
      uv_version:
        description: "uv version to install (default: latest)"
        required: false
        type: string
        default: ''
      dotnet_versions:
        description: ".NET versions (e.g. 6.0.x)"
        required: false
        type: string
        default: "6.0.x"
      nuget_source_url:
        description: "NuGet source URL to add"
        required: false
        type: string
        default: ''

      # Maven Configuration
      maven_settings_repositories:
        description: "Maven repositories configuration (JSON)"
        required: false
        type: string
        default: ''
      maven_settings_servers:
        description: "Maven servers configuration (JSON)"
        required: false
        type: string
        default: ''

    secrets:
      FOSSA_API_KEY:
        description: 'FOSSA API key (required if use_vault is false)'
        required: false
      VAULT_URL:
        description: 'Vault URL (optional - defaults to config file value)'
        required: false
      VAULT_ROLE:
        description: 'Vault role for JWT authentication (optional - defaults to config file value)'
        required: false
      NPM_AUTH_TOKEN:
        description: 'NPM auth token for private registry access (defaults to GITHUB_TOKEN)'
        required: false
      NUGET_AUTH_TOKEN:
        description: 'NuGet auth token for private feed access (defaults to GITHUB_TOKEN)'
        required: false

permissions:
  contents: read
  pull-requests: write
  id-token: write
  actions: read
  checks: write
  statuses: write

jobs:
  sca_scan:
    name: 'SCA Scan'
    runs-on: ubuntu-latest
    timeout-minutes: 30

    steps:
      - name: Check Admin Permissions for Bypass
        if: inputs.skip_policy_gate == true || inputs.skip_vulnerability_gate == true
        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
        with:
          script: |
            const actor = context.actor;
            const repo = context.repo;

            try {
              const { data: permission } = await github.rest.repos.getCollaboratorPermissionLevel({
                owner: repo.owner,
                repo: repo.repo,
                username: actor
              });

              console.log(`User ${actor} has permission: ${permission.permission}`);

              if (permission.permission !== 'admin') {
                core.setFailed(`❌ FOSSA bypass denied: User ${actor} does not have admin permissions. Only repository admins can bypass FOSSA gates.`);
              } else {
                console.log(`✅ Admin permission verified for ${actor}`);
              }
            } catch (error) {
              core.setFailed(`Failed to check permissions: ${error.message}`);
            }

      - name: Determine scan context
        id: context
        env:
          INPUT_GIT_REF: ${{ inputs.git_ref }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          HEAD_REF: ${{ github.head_ref }}
          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
          GITHUB_SHA: ${{ github.sha }}
          GITHUB_REF: ${{ github.ref }}
        run: |
          echo "### 🔍 SCA Scan Context Detection" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

          # Detect if this is a PR, Release, or Manual scan
          if [[ -n "$PR_NUMBER" ]]; then
            # PR context - diff-based scan
            echo "branch=PR" >> $GITHUB_OUTPUT
            echo "revision=${HEAD_REF}" >> $GITHUB_OUTPUT
            echo "git_ref=${GITHUB_REF}" >> $GITHUB_OUTPUT
            echo "scan_type=PR" >> $GITHUB_OUTPUT
            echo "**Context**: Pull Request #${PR_NUMBER}" >> $GITHUB_STEP_SUMMARY
            echo "**Scan Type**: Diff-based (new issues only)" >> $GITHUB_STEP_SUMMARY
            echo "**Branch**: PR" >> $GITHUB_STEP_SUMMARY
            echo "**Revision**: ${HEAD_REF}" >> $GITHUB_STEP_SUMMARY
          elif [[ -n "$INPUT_GIT_REF" ]]; then
            # Release context (called by orchestrator) - full scan
            echo "branch=${DEFAULT_BRANCH}" >> $GITHUB_OUTPUT
            echo "revision=${INPUT_GIT_REF}" >> $GITHUB_OUTPUT
            echo "git_ref=${INPUT_GIT_REF}" >> $GITHUB_OUTPUT
            echo "scan_type=Release" >> $GITHUB_OUTPUT
            echo "**Context**: Release" >> $GITHUB_STEP_SUMMARY
            echo "**Scan Type**: Full scan (all dependencies)" >> $GITHUB_STEP_SUMMARY
            echo "**Branch**: ${DEFAULT_BRANCH}" >> $GITHUB_STEP_SUMMARY
            echo "**Revision**: ${INPUT_GIT_REF}" >> $GITHUB_STEP_SUMMARY
          else
            # Manual trigger without git_ref
            echo "branch=${DEFAULT_BRANCH}" >> $GITHUB_OUTPUT
            echo "revision=${GITHUB_SHA}" >> $GITHUB_OUTPUT
            echo "git_ref=${GITHUB_REF}" >> $GITHUB_OUTPUT
            echo "scan_type=Manual" >> $GITHUB_OUTPUT
            echo "**Context**: Manual (HEAD)" >> $GITHUB_STEP_SUMMARY
            echo "**Scan Type**: Full scan" >> $GITHUB_STEP_SUMMARY
            echo "**Branch**: ${DEFAULT_BRANCH}" >> $GITHUB_STEP_SUMMARY
            echo "**Revision**: ${GITHUB_SHA}" >> $GITHUB_STEP_SUMMARY
          fi

          echo "**Git Ref**: $(cat $GITHUB_OUTPUT | grep git_ref | head -1 | cut -d'=' -f2)" >> $GITHUB_STEP_SUMMARY

      - name: Checkout code
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          ref: ${{ steps.context.outputs.git_ref }}

      - name: Detect Repository Visibility and Set Privacy Mode
        id: privacy_mode
        env:
          GH_TOKEN: ${{ github.token }}
          REPO: ${{ github.repository }}
        run: |
          # Check if repository is public using gh CLI
          IS_PUBLIC=$(gh repo view "$REPO" --json isPrivate --jq '.isPrivate == false')

          # Auto-enable privacy mode for public repositories
          if [[ "$IS_PUBLIC" == "true" ]]; then
            ENABLE_PRIVACY="true"
            echo "✅ Public repository detected - auto-enabling privacy mode for FOSSA output"
          else
            ENABLE_PRIVACY="false"
            echo "🔒 Private repository - privacy mode disabled"
          fi

          echo "enable_privacy_mode=${ENABLE_PRIVACY}" >> $GITHUB_OUTPUT
          echo "is_public=${IS_PUBLIC}" >> $GITHUB_OUTPUT

      - name: Load Workflow Configuration
        if: inputs.config_file != ''
        id: config_loader
        uses: SolaceDev/solace-public-workflows/workflow-config-loader@main
        with:
          config_file: ${{ inputs.config_file }}
          config_type: sca_scanning

      - name: Merge Configuration and Inputs
        id: config
        env:
          CONFIG_FILE: ${{ inputs.config_file }}
          # Config values
          CONFIG_VAULT_URL: ${{ steps.config_loader.outputs.vault_url }}
          CONFIG_VAULT_SECRET_PATH: ${{ steps.config_loader.outputs.vault_secret_path }}
          CONFIG_VAULT_ROLE: ${{ steps.config_loader.outputs.vault_role }}
          CONFIG_VAULT_SECRET_MAPPINGS: ${{ steps.config_loader.outputs.vault_secret_mappings }}
          CONFIG_SLACK_CHANNEL: ${{ steps.config_loader.outputs.slack_channel }}
          CONFIG_FOSSA_LICENSING_MODE: ${{ steps.config_loader.outputs.fossa_licensing_mode }}
          CONFIG_FOSSA_LICENSING_BLOCK_ON: ${{ steps.config_loader.outputs.fossa_licensing_block_on }}
          CONFIG_FOSSA_VULNERABILITY_MODE: ${{ steps.config_loader.outputs.fossa_vulnerability_mode }}
          CONFIG_FOSSA_VULNERABILITY_BLOCK_ON: ${{ steps.config_loader.outputs.fossa_vulnerability_block_on }}
          CONFIG_FOSSA_PROJECT_ID: ${{ steps.config_loader.outputs.fossa_project_id }}
          CONFIG_FOSSA_TEAM: ${{ steps.config_loader.outputs.fossa_team }}
          CONFIG_FOSSA_LABELS: ${{ steps.config_loader.outputs.fossa_labels }}
        run: |
          # Priority: config file > defaults
          if [[ -n "$CONFIG_FILE" ]]; then
            echo "📝 Using configuration from file: $CONFIG_FILE"
            echo "vault_url=${CONFIG_VAULT_URL}" >> $GITHUB_OUTPUT
            echo "vault_secret_path=${CONFIG_VAULT_SECRET_PATH}" >> $GITHUB_OUTPUT
            echo "vault_role=${CONFIG_VAULT_ROLE}" >> $GITHUB_OUTPUT

            # Pass through vault_secret_mappings (multiline format with semicolons)
            {
              echo "vault_secret_mappings<<EOF"
              echo "${CONFIG_VAULT_SECRET_MAPPINGS}"
              echo "EOF"
            } >> $GITHUB_OUTPUT

            echo "slack_channel=${CONFIG_SLACK_CHANNEL}" >> $GITHUB_OUTPUT
            echo "fossa_licensing_mode=${CONFIG_FOSSA_LICENSING_MODE}" >> $GITHUB_OUTPUT
            echo "fossa_licensing_block_on=${CONFIG_FOSSA_LICENSING_BLOCK_ON}" >> $GITHUB_OUTPUT
            echo "fossa_vulnerability_mode=${CONFIG_FOSSA_VULNERABILITY_MODE}" >> $GITHUB_OUTPUT
            echo "fossa_vulnerability_block_on=${CONFIG_FOSSA_VULNERABILITY_BLOCK_ON}" >> $GITHUB_OUTPUT
            echo "fossa_project_override=${CONFIG_FOSSA_PROJECT_ID}" >> $GITHUB_OUTPUT
            echo "fossa_team=${CONFIG_FOSSA_TEAM}" >> $GITHUB_OUTPUT
            echo "fossa_labels=${CONFIG_FOSSA_LABELS}" >> $GITHUB_OUTPUT
          else
            echo "📝 Using default configuration"
            echo "vault_url=" >> $GITHUB_OUTPUT
            echo "vault_secret_path=" >> $GITHUB_OUTPUT
            echo "vault_role=" >> $GITHUB_OUTPUT
            echo "vault_secret_mappings=" >> $GITHUB_OUTPUT
            echo "slack_channel=" >> $GITHUB_OUTPUT
            echo "fossa_licensing_mode=REPORT" >> $GITHUB_OUTPUT
            echo "fossa_licensing_block_on=policy_conflict" >> $GITHUB_OUTPUT
            echo "fossa_vulnerability_mode=REPORT" >> $GITHUB_OUTPUT
            echo "fossa_vulnerability_block_on=critical,high" >> $GITHUB_OUTPUT
            echo "fossa_project_override=" >> $GITHUB_OUTPUT
            echo "fossa_team=" >> $GITHUB_OUTPUT
            echo "fossa_labels=" >> $GITHUB_OUTPUT
          fi

      - name: Validate Vault Configuration
        if: inputs.use_vault == true
        shell: bash
        env:
          SECRET_VAULT_URL: ${{ secrets.VAULT_URL }}
          SECRET_VAULT_ROLE: ${{ secrets.VAULT_ROLE }}
          CONFIG_VAULT_URL: ${{ steps.config.outputs.vault_url }}
          CONFIG_VAULT_ROLE: ${{ steps.config.outputs.vault_role }}
        run: |
          # Determine effective Vault URL and role
          vault_url="${SECRET_VAULT_URL:-${CONFIG_VAULT_URL}}"
          vault_role="${SECRET_VAULT_ROLE:-${CONFIG_VAULT_ROLE}}"

          # Fail fast if URL is empty
          if [[ -z "${vault_url}" ]]; then
            echo "❌ Error: Vault URL is not configured for use_vault=true."
            echo ""
            echo "Troubleshooting:"
            echo "1. Set 'VAULT_URL' as a repository or organization secret, or"
            echo "2. Provide 'secrets.vault.url' in your workflow configuration file"
            exit 1
          fi

          # Fail fast if role is empty
          if [[ -z "${vault_role}" ]]; then
            echo "❌ Error: Vault role is not configured for use_vault=true."
            echo ""
            echo "Troubleshooting:"
            echo "1. Set 'VAULT_ROLE' as a repository or organization secret, or"
            echo "2. Provide 'secrets.vault.role' in your workflow configuration file"
            exit 1
          fi

          echo "✅ Vault configuration validated"
          echo "   URL: ${vault_url}"
          echo "   Role: ${vault_role}"

      - name: Retrieve Secrets from Vault
        id: vault_secrets
        if: inputs.use_vault == true
        uses: hashicorp/vault-action@4c06c5ccf5c0761b6029f56cfb1dcf5565918a3b # v3.4.0
        with:
          url: ${{ secrets.VAULT_URL != '' && secrets.VAULT_URL || steps.config.outputs.vault_url }}
          role: ${{ secrets.VAULT_ROLE != '' && secrets.VAULT_ROLE || steps.config.outputs.vault_role }}
          method: jwt
          path: jwt-github
          jwtGithubAudience: https://github.com/${{ github.repository_owner }}
          exportToken: true
          secrets: |
            ${{ steps.config.outputs.vault_secret_path }} FOSSA_FULL_API_TOKEN | FOSSA_API_KEY ;
            ${{ inputs.vault_secrets != '' && inputs.vault_secrets || steps.config.outputs.vault_secret_mappings }}

      - name: Setup SCA Dependencies
        id: setup_deps
        uses: SolaceDev/solace-public-workflows/sca-setup-deps@sca_setup_guard_doc_updates
        with:
          setup_actions: ${{ inputs.setup_actions }}
          java_version: ${{ inputs.java_version }}
          java_distribution: ${{ inputs.java_distribution }}
          maven_settings_repositories: ${{ inputs.maven_settings_repositories }}
          maven_settings_servers: ${{ inputs.maven_settings_servers }}
          node_version: ${{ inputs.node_version }}
          npm_registry_url: ${{ inputs.npm_registry_url }}
          npm_auth_token: ${{ secrets.NPM_AUTH_TOKEN != '' && secrets.NPM_AUTH_TOKEN || github.token }}
          python_version: ${{ inputs.python_version }}
          uv_version: ${{ inputs.uv_version }}
          dotnet_versions: ${{ inputs.dotnet_versions }}
          nuget_source_url: ${{ inputs.nuget_source_url }}
          nuget_auth_token: ${{ secrets.NUGET_AUTH_TOKEN != '' && secrets.NUGET_AUTH_TOKEN || github.token }}
          custom_setup_script: ${{ inputs.custom_setup_script }}
      - name: Validate FOSSA API Key
        id: fossa_key
        shell: bash
        env:
          USE_VAULT: ${{ inputs.use_vault }}
          VAULT_FOSSA_KEY: ${{ steps.vault_secrets.outputs.FOSSA_API_KEY }}
          SECRET_FOSSA_KEY: ${{ secrets.FOSSA_API_KEY }}
        run: |
          if [[ "$USE_VAULT" == "true" ]]; then
            # Vault mode - key from Vault
            if [[ -z "$VAULT_FOSSA_KEY" ]]; then
              echo "❌ Error: FOSSA_API_KEY not retrieved from Vault"
              echo "Vault URL: ${{ steps.config.outputs.vault_url }}"
              echo "Secret Path: ${{ steps.config.outputs.vault_secret_path }}"
              echo ""
              echo "Troubleshooting:"
              echo "1. Verify Vault URL is accessible"
              echo "2. Check JWT authentication role: ${{ secrets.VAULT_ROLE || 'cicd-workflows-secret-read-role' }}"
              echo "3. Verify secret exists at path: ${{ steps.config.outputs.vault_secret_path }}"
              echo "4. Ensure secret has key: FOSSA_FULL_API_TOKEN"
              exit 1
            fi
            echo "FOSSA_KEY=${VAULT_FOSSA_KEY}" >> $GITHUB_OUTPUT
            echo "✅ FOSSA API key retrieved from Vault"
          else
            # GitHub Secrets mode - key from secrets
            if [[ -z "$SECRET_FOSSA_KEY" ]]; then
              echo "❌ Error: FOSSA_API_KEY secret not provided"
              echo "Please provide FOSSA_API_KEY as a secret to the workflow"
              exit 1
            fi
            echo "FOSSA_KEY=${SECRET_FOSSA_KEY}" >> $GITHUB_OUTPUT
            echo "✅ FOSSA API key retrieved from GitHub Secrets"
          fi

      - name: Determine FOSSA Project ID
        id: fossa_project
        env:
          FOSSA_PROJECT_OVERRIDE: ${{ steps.config.outputs.fossa_project_override }}
          REPO_OWNER: ${{ github.repository_owner }}
          REPO_NAME: ${{ github.event.repository.name }}
        run: |
          if [[ -n "$FOSSA_PROJECT_OVERRIDE" ]]; then
            FOSSA_PROJECT_ID="$FOSSA_PROJECT_OVERRIDE"
            echo "Using override project ID: $FOSSA_PROJECT_ID"
          else
            FOSSA_PROJECT_ID="${REPO_OWNER}_${REPO_NAME}"
            echo "Using default project ID: $FOSSA_PROJECT_ID"
          fi
          echo "FOSSA_PROJECT_ID=${FOSSA_PROJECT_ID}" >> $GITHUB_OUTPUT

      - name: Build FOSSA Scan Parameters
        id: fossa_params
        env:
          FOSSA_PROJECT_ID: ${{ steps.fossa_project.outputs.FOSSA_PROJECT_ID }}
          FOSSA_BRANCH: ${{ steps.context.outputs.branch }}
          FOSSA_REVISION: ${{ steps.context.outputs.revision }}
          FOSSA_TEAM: ${{ steps.config.outputs.fossa_team }}
          FOSSA_LABELS: ${{ steps.config.outputs.fossa_labels }}
          ADDITIONAL_PARAMS: ${{ inputs.additional_scan_params }}
        run: |
          # Build base parameters
          PARAMS="fossa.project=${FOSSA_PROJECT_ID}"
          PARAMS="${PARAMS}"$'\n'"fossa.branch=${FOSSA_BRANCH}"
          PARAMS="${PARAMS}"$'\n'"fossa.revision=${FOSSA_REVISION}"

          # Add team if configured
          if [[ -n "$FOSSA_TEAM" ]]; then
            PARAMS="${PARAMS}"$'\n'"fossa.team=${FOSSA_TEAM}"
            echo "✓ Adding FOSSA team: $FOSSA_TEAM"
          fi

          # Add labels if configured
          if [[ -n "$FOSSA_LABELS" ]]; then
            PARAMS="${PARAMS}"$'\n'"fossa.project_label=${FOSSA_LABELS}"
            echo "✓ Adding FOSSA labels: $FOSSA_LABELS"
          fi

          # Add user-provided additional params
          if [[ -n "$ADDITIONAL_PARAMS" ]]; then
            PARAMS="${PARAMS}"$'\n'"${ADDITIONAL_PARAMS}"
          fi

          # Extract effective revision and branch for guard steps.
          # additional_scan_params may override fossa.revision/fossa.branch,
          # so we take the last occurrence (last one wins in the FOSSA CLI).
          EFFECTIVE_REVISION=$(echo "$PARAMS" | grep "^fossa\\.revision=" | tail -1 | cut -d'=' -f2-)
          EFFECTIVE_BRANCH=$(echo "$PARAMS" | grep "^fossa\\.branch=" | tail -1 | cut -d'=' -f2-)

          # Fallback to context defaults if extraction failed
          if [[ -z "$EFFECTIVE_REVISION" ]]; then
            EFFECTIVE_REVISION="${FOSSA_REVISION}"
          fi
          if [[ -z "$EFFECTIVE_BRANCH" ]]; then
            EFFECTIVE_BRANCH="${FOSSA_BRANCH}"
          fi

          echo "effective_revision=${EFFECTIVE_REVISION}" >> $GITHUB_OUTPUT
          echo "effective_branch=${EFFECTIVE_BRANCH}" >> $GITHUB_OUTPUT

          # Export to output
          {
            echo "params<<EOF"
            echo "$PARAMS"
            echo "EOF"
          } >> $GITHUB_OUTPUT

      - name: SCA Scan - FOSSA
        uses: SolaceDev/solace-public-workflows/.github/actions/sca/sca-scan@main
        with:
          scanners: "fossa"
          additional_scan_params: ${{ steps.fossa_params.outputs.params }}
          fossa_api_key: ${{ steps.fossa_key.outputs.FOSSA_KEY }}

      - name: FOSSA Policy/Licensing Check
        id: fossa_licensing
        uses: SolaceDev/solace-public-workflows/.github/actions/fossa-guard@main
        continue-on-error: true
        with:
          fossa_api_key: ${{ steps.fossa_key.outputs.FOSSA_KEY }}
          fossa_project_id: ${{ steps.fossa_project.outputs.FOSSA_PROJECT_ID }}
          fossa_branch: ${{ steps.fossa_params.outputs.effective_branch }}
          fossa_revision: ${{ steps.fossa_params.outputs.effective_revision }}
          fossa_category: licensing
          fossa_mode: ${{ steps.config.outputs.fossa_licensing_mode }}
          block_on: ${{ steps.config.outputs.fossa_licensing_block_on }}
          enable_diff_mode: ${{ github.event_name == 'pull_request' }}
          enable_pr_comment: ${{ github.event_name == 'pull_request' }}
          enable_status_check: ${{ github.event_name == 'pull_request' }}
          status_check_name: "FOSSA SCA Licensing"
          enable_privacy_mode: ${{ steps.privacy_mode.outputs.enable_privacy_mode }}
          github_token: ${{ github.token }}

      - name: FOSSA Vulnerability Check
        id: fossa_vulnerabilities
        uses: SolaceDev/solace-public-workflows/.github/actions/fossa-guard@main
        continue-on-error: true
        with:
          fossa_api_key: ${{ steps.fossa_key.outputs.FOSSA_KEY }}
          fossa_project_id: ${{ steps.fossa_project.outputs.FOSSA_PROJECT_ID }}
          fossa_branch: ${{ steps.fossa_params.outputs.effective_branch }}
          fossa_revision: ${{ steps.fossa_params.outputs.effective_revision }}
          fossa_category: vulnerability
          fossa_mode: ${{ steps.config.outputs.fossa_vulnerability_mode }}
          block_on: ${{ steps.config.outputs.fossa_vulnerability_block_on }}
          enable_diff_mode: ${{ github.event_name == 'pull_request' }}
          enable_pr_comment: ${{ github.event_name == 'pull_request' }}
          enable_status_check: ${{ github.event_name == 'pull_request' }}
          status_check_name: "FOSSA SCA Vulnerabilities"
          enable_privacy_mode: ${{ steps.privacy_mode.outputs.enable_privacy_mode }}
          github_token: ${{ github.token }}

      - name: Report SCA Scan Results
        if: always()
        env:
          LICENSING_OUTCOME: ${{ steps.fossa_licensing.outcome }}
          LICENSING_MODE: ${{ steps.config.outputs.fossa_licensing_mode }}
          LICENSING_BLOCK_ON: ${{ steps.config.outputs.fossa_licensing_block_on }}
          VULNERABILITY_OUTCOME: ${{ steps.fossa_vulnerabilities.outcome }}
          VULNERABILITY_MODE: ${{ steps.config.outputs.fossa_vulnerability_mode }}
          VULNERABILITY_BLOCK_ON: ${{ steps.config.outputs.fossa_vulnerability_block_on }}
          SKIP_POLICY_GATE: ${{ inputs.skip_policy_gate }}
          SKIP_VULNERABILITY_GATE: ${{ inputs.skip_vulnerability_gate }}
          BYPASS_JUSTIFICATION: ${{ inputs.bypass_justification }}
          FOSSA_PROJECT_ID: ${{ steps.fossa_project.outputs.FOSSA_PROJECT_ID }}
          FOSSA_BRANCH: ${{ steps.fossa_params.outputs.effective_branch }}
          FOSSA_REVISION: ${{ steps.fossa_params.outputs.effective_revision }}
          SCAN_TYPE: ${{ steps.context.outputs.scan_type }}
        run: |
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "---" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "### 📊 SCA Scan Results" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

          # Licensing Check Results
          if [[ "$LICENSING_OUTCOME" == "success" ]]; then
            echo "✅ **Licensing Check**: PASSED" >> $GITHUB_STEP_SUMMARY
            echo "   _Mode: $LICENSING_MODE, Block on: $LICENSING_BLOCK_ON_" >> $GITHUB_STEP_SUMMARY
          elif [[ "$LICENSING_OUTCOME" == "failure" ]]; then
            if [[ "$LICENSING_MODE" == "BLOCK" ]]; then
              echo "❌ **Licensing Check**: FAILED (policy conflicts detected) - BLOCKING" >> $GITHUB_STEP_SUMMARY
            else
              echo "⚠️ **Licensing Check**: FAILED (policy conflicts detected) - REPORT ONLY" >> $GITHUB_STEP_SUMMARY
            fi
            echo "   _Mode: $LICENSING_MODE, Block on: $LICENSING_BLOCK_ON_" >> $GITHUB_STEP_SUMMARY
          elif [[ "$SKIP_POLICY_GATE" == "true" ]]; then
            echo "⚠️ **Licensing Check**: SKIPPED (emergency bypass)" >> $GITHUB_STEP_SUMMARY
            echo "**Justification**: $BYPASS_JUSTIFICATION" >> $GITHUB_STEP_SUMMARY
          else
            echo "⚠️ **Licensing Check**: UNKNOWN" >> $GITHUB_STEP_SUMMARY
          fi

          echo "" >> $GITHUB_STEP_SUMMARY

          # Vulnerability Check Results
          if [[ "$VULNERABILITY_OUTCOME" == "success" ]]; then
            echo "✅ **Vulnerability Check**: PASSED" >> $GITHUB_STEP_SUMMARY
            echo "   _Mode: $VULNERABILITY_MODE, Block on: $VULNERABILITY_BLOCK_ON_" >> $GITHUB_STEP_SUMMARY
          elif [[ "$VULNERABILITY_OUTCOME" == "failure" ]]; then
            if [[ "$VULNERABILITY_MODE" == "BLOCK" ]]; then
              echo "❌ **Vulnerability Check**: FAILED ($VULNERABILITY_BLOCK_ON vulnerabilities detected) - BLOCKING" >> $GITHUB_STEP_SUMMARY
            else
              echo "⚠️ **Vulnerability Check**: ISSUES FOUND ($VULNERABILITY_BLOCK_ON vulnerabilities detected) - REPORT ONLY" >> $GITHUB_STEP_SUMMARY
            fi
            echo "   _Mode: $VULNERABILITY_MODE, Block on: $VULNERABILITY_BLOCK_ON_" >> $GITHUB_STEP_SUMMARY
          elif [[ "$SKIP_VULNERABILITY_GATE" == "true" ]]; then
            echo "⚠️ **Vulnerability Check**: SKIPPED (emergency bypass)" >> $GITHUB_STEP_SUMMARY
          else
            echo "⚠️ **Vulnerability Check**: UNKNOWN" >> $GITHUB_STEP_SUMMARY
          fi

          echo "" >> $GITHUB_STEP_SUMMARY
          echo "**FOSSA Project**: $FOSSA_PROJECT_ID" >> $GITHUB_STEP_SUMMARY
          echo "**Branch**: $FOSSA_BRANCH" >> $GITHUB_STEP_SUMMARY
          echo "**Revision**: $FOSSA_REVISION" >> $GITHUB_STEP_SUMMARY
          echo "**Scan Type**: $SCAN_TYPE" >> $GITHUB_STEP_SUMMARY

          # URL encode the revision for the dashboard link
          ENCODED_REVISION=$(echo "$FOSSA_REVISION" | jq -sRr @uri)
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "**Dashboard**: [View in FOSSA](https://app.fossa.com/projects/custom%2B48578%2F$FOSSA_PROJECT_ID/refs/branch/$FOSSA_BRANCH/${ENCODED_REVISION})" >> $GITHUB_STEP_SUMMARY

      - name: Block on FOSSA Policy Failures
        if: |
          always() &&
          !inputs.skip_policy_gate &&
          steps.fossa_licensing.outcome == 'failure' &&
          steps.config.outputs.fossa_licensing_mode == 'BLOCK'
        env:
          LICENSING_BLOCK_ON: ${{ steps.config.outputs.fossa_licensing_block_on }}
        run: |
          echo "❌ FOSSA licensing check failed. Policy conflicts detected ($LICENSING_BLOCK_ON)."
          echo "Review the FOSSA dashboard for details and remediate policy violations."
          echo ""
          echo "Dashboard: https://app.fossa.com/projects/custom%2B48578%2F${{ steps.fossa_project.outputs.FOSSA_PROJECT_ID }}"
          exit 1

      - name: Block on FOSSA Vulnerability Failures
        if: |
          always() &&
          !inputs.skip_vulnerability_gate &&
          steps.fossa_vulnerabilities.outcome == 'failure' &&
          steps.config.outputs.fossa_vulnerability_mode == 'BLOCK'
        env:
          VULNERABILITY_BLOCK_ON: ${{ steps.config.outputs.fossa_vulnerability_block_on }}
        run: |
          echo "❌ FOSSA vulnerability check failed. $VULNERABILITY_BLOCK_ON severity vulnerabilities detected."
          echo "Review the FOSSA dashboard for details and remediate vulnerabilities."
          echo ""
          echo "Dashboard: https://app.fossa.com/projects/custom%2B48578%2F${{ steps.fossa_project.outputs.FOSSA_PROJECT_ID }}"
          exit 1

      - name: Log Emergency Bypass
        if: inputs.skip_policy_gate == true || inputs.skip_vulnerability_gate == true
        env:
          SKIP_POLICY: ${{ inputs.skip_policy_gate }}
          SKIP_VULN: ${{ inputs.skip_vulnerability_gate }}
          BYPASS_JUSTIFICATION: ${{ inputs.bypass_justification }}
          ACTOR: ${{ github.actor }}
          SERVER_URL: ${{ github.server_url }}
          REPOSITORY: ${{ github.repository }}
          RUN_ID: ${{ github.run_id }}
        run: |
          echo "⚠️ EMERGENCY BYPASS USED"
          echo "========================================"
          echo "Gates bypassed:"
          if [[ "$SKIP_POLICY" == "true" ]]; then
            echo "  - Policy/Licensing Gate"
          fi
          if [[ "$SKIP_VULN" == "true" ]]; then
            echo "  - Vulnerability Gate"
          fi
          echo ""
          echo "Justification: $BYPASS_JUSTIFICATION"
          echo "Triggered by: $ACTOR"
          echo "Workflow run: $SERVER_URL/$REPOSITORY/actions/runs/$RUN_ID"
          echo "========================================"

# ---
# Usage Notes:
#
# This shareable workflow performs FOSSA-based SCA scanning with:
# - Automatic context detection (PR vs Release vs Manual)
# - Licensing policy enforcement (configurable BLOCK/REPORT)
# - Vulnerability reporting (configurable BLOCK/REPORT)
# - Emergency bypass capability with granular control
# - Flexible secret management (Vault or GitHub Secrets)
#
# Secret Management:
# - Default: GitHub Secrets (use_vault: false) - for public repos
# - Optional: Vault (use_vault: true) - for private repos with Vault access
#
# Context Detection:
# - PR: Diff-based scan (only new issues), branch=PR, revision=head_ref
# - Release: Full scan with version tag, branch=default_branch, revision=git_ref input
# - Manual: Full scan with SHA, branch=default_branch, revision=github.sha
#
# Gates:
# - Licensing: Configurable (BLOCK or REPORT) on policy conflicts
# - Vulnerabilities: Configurable (BLOCK or REPORT) on critical/high CVEs
# - Emergency bypass available via workflow_dispatch/orchestrator (admin only)
#
# Configuration File:
# - Uses .github/workflow-config.json (or custom path)
# - Supports sca_scanning section with FOSSA settings
# - See documentation for schema details
#
# Example usage in PUBLIC repos (GitHub Secrets):
#
# PR Scanning:
#   sca_scan:
#     uses: SolaceDev/solace-public-workflows/.github/workflows/sca-scan-and-guard.yaml@main
#     secrets:
#       FOSSA_API_KEY: ${{ secrets.FOSSA_API_KEY }}
#     # git_ref not needed - auto-detects PR context
#
# Release Scanning:
#   sca_scan:
#     needs: version_bump
#     uses: SolaceDev/solace-public-workflows/.github/workflows/sca-scan-and-guard.yaml@main
#     secrets:
#       FOSSA_API_KEY: ${{ secrets.FOSSA_API_KEY }}
#     with:
#       git_ref: ${{ needs.version_bump.outputs.version }}  # e.g., 0.0.269
#
# Example usage in PRIVATE repos (Vault):
#
# Release Scanning with Vault:
#   sca_scan:
#     needs: version_bump
#     uses: SolaceDev/solace-public-workflows/.github/workflows/sca-scan-and-guard.yaml@main
#     with:
#       git_ref: ${{ needs.version_bump.outputs.version }}
#       use_vault: true
#
# With Emergency Bypass (Admin Only):
#   sca_scan:
#     uses: SolaceDev/solace-public-workflows/.github/workflows/sca-scan-and-guard.yaml@main
#     secrets:
#       FOSSA_API_KEY: ${{ secrets.FOSSA_API_KEY }}
#     with:
#       skip_vulnerability_gate: true
#       bypass_justification: "FOSSA service outage - INC12345"
#
# With Configuration File:
#   sca_scan:
#     uses: SolaceDev/solace-public-workflows/.github/workflows/sca-scan-and-guard.yaml@main
#     secrets:
#       FOSSA_API_KEY: ${{ secrets.FOSSA_API_KEY }}
#     with:
#       config_file: '.github/workflow-config.json'
#       additional_scan_params: |
#         fossa.debug=true
#         fossa.only_path=src/
# ---