refactor: [#251] apply security-first workflow philosophy with exit-code 0

Author: josecelano

.github/workflows/docker-security-scan.yml

@@ -2,21 +2,24 @@ name: Docker Security Scan
 
 on:
   push:
-    branches:
-      - main
-      - develop
+    branches: [main, develop]
     paths:
       - "docker/**"
       - "templates/docker-compose/**"
       - ".github/workflows/docker-security-scan.yml"
+
   pull_request:
     paths:
       - "docker/**"
       - "templates/docker-compose/**"
       - ".github/workflows/docker-security-scan.yml"
+
+  # Scheduled scans are important because new CVEs appear
+  # even if the code or images didn’t change
   schedule:
     - cron: "0 6 * * *" # Daily at 6 AM UTC
-  workflow_dispatch: # Allow manual triggering
+
+  workflow_dispatch:
 
 jobs:
   scan-project-images:
@@ -25,6 +28,7 @@ jobs:
     timeout-minutes: 15
     permissions:
       contents: read
+
     strategy:
       fail-fast: false
       matrix:
@@ -35,42 +39,52 @@ jobs:
           - dockerfile: docker/ssh-server/Dockerfile
             context: docker/ssh-server
             name: ssh-server
+
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      # Build images locally so Trivy scans exactly
+      # what this repository produces
       - name: Build Docker image
         run: |
-          docker build -t torrust-tracker-deployer/${{ matrix.image.name }}:latest \
+          docker build \
+            -t torrust-tracker-deployer/${{ matrix.image.name }}:latest \
             -f ${{ matrix.image.dockerfile }} \
             .
 
+      # Human-readable output in logs
+      # This NEVER fails the job; it’s only for visibility
       - name: Display vulnerabilities (table format)
         uses: aquasecurity/[email protected]
         with:
           image-ref: torrust-tracker-deployer/${{ matrix.image.name }}:latest
           format: "table"
           severity: "HIGH,CRITICAL"
-          exit-code: "0" # Don't fail here, just display
+          exit-code: "0"
 
-      - name: Run Trivy vulnerability scanner
+      # SARIF generation for GitHub Code Scanning
+      #
+      # IMPORTANT:
+      # - exit-code MUST be 0
+      # - Trivy sometimes exits with 1 even when no vulns exist
+      # - GitHub Security UI is responsible for enforcement
+      - name: Generate SARIF (Code Scanning)
         uses: aquasecurity/[email protected]
-        continue-on-error: true
-        id: trivy-scan
         with:
           image-ref: torrust-tracker-deployer/${{ matrix.image.name }}:latest
           format: "sarif"
-          output: "trivy-results-${{ matrix.image.name }}.sarif"
+          output: "trivy-${{ matrix.image.name }}.sarif"
           severity: "HIGH,CRITICAL"
-          exit-code: "1"
-          scanners: "vuln" # Only vulnerabilities, skip secrets (test containers have legitimate SSH keys)
+          exit-code: "0"
+          scanners: "vuln"
 
       - name: Upload SARIF artifact
         uses: actions/upload-artifact@v4
         if: always()
         with:
           name: sarif-project-${{ matrix.image.name }}-${{ github.run_id }}
-          path: "trivy-results-${{ matrix.image.name }}.sarif"
+          path: trivy-${{ matrix.image.name }}.sarif
           retention-days: 30
 
   scan-third-party-images:
@@ -79,82 +93,88 @@ jobs:
     timeout-minutes: 15
     permissions:
       contents: read
+
     strategy:
       fail-fast: false
       matrix:
-        # NOTE: These images must match the ones used in templates/docker-compose/docker-compose.yml.tera
-        # TODO: Automate image detection from docker-compose templates - see https://github.com/torrust/torrust-tracker-deployer/issues/252
+        # These must match docker-compose templates
+        # in templates/docker-compose/docker-compose.yml.tera
         image:
           - torrust/tracker:develop
           - mysql:8.0
           - grafana/grafana:11.4.0
           - prom/prometheus:v3.0.1
+
     steps:
       - name: Display vulnerabilities (table format)
         uses: aquasecurity/[email protected]
         with:
           image-ref: ${{ matrix.image }}
           format: "table"
           severity: "HIGH,CRITICAL"
-          exit-code: "0" # Don't fail here, just display
+          exit-code: "0"
 
-      - name: Run Trivy vulnerability scanner
+      # Third-party images should NEVER block CI.
+      # We only report findings to GitHub Security.
+      - name: Generate SARIF (Code Scanning)
         uses: aquasecurity/[email protected]
-        continue-on-error: true
-        id: trivy-scan
         with:
           image-ref: ${{ matrix.image }}
           format: "sarif"
-          output: "trivy-results.sarif"
+          output: "trivy.sarif"
           severity: "HIGH,CRITICAL"
-          exit-code: "1"
-          scanners: "vuln" # Focus on CVEs, not secrets
+          exit-code: "0"
+          scanners: "vuln"
 
-      - name: Sanitize image name for artifact
+      # Needed to produce stable artifact names
+      - name: Sanitize image name
         id: sanitize
-        run: echo "name=$(echo '${{ matrix.image }}' | tr '/:' '-')" >> $GITHUB_OUTPUT
+        run: |
+          echo "name=$(echo '${{ matrix.image }}' | tr '/:' '-')" >> "$GITHUB_OUTPUT"
 
       - name: Upload SARIF artifact
         uses: actions/upload-artifact@v4
         if: always()
         with:
           name: sarif-third-party-${{ steps.sanitize.outputs.name }}-${{ github.run_id }}
-          path: "trivy-results.sarif"
+          path: trivy.sarif
           retention-days: 30
 
   upload-sarif-results:
     name: Upload SARIF Results to GitHub Security
     runs-on: ubuntu-latest
-    needs: [scan-project-images, scan-third-party-images]
+    needs:
+      - scan-project-images
+      - scan-third-party-images
+
+    # Always run so we don’t lose security visibility
     if: always()
+
     permissions:
       security-events: write
+
     steps:
       - name: Download all SARIF artifacts
         uses: actions/download-artifact@v4
         with:
           pattern: sarif-*-${{ github.run_id }}
-          merge-multiple: false
 
-      - name: Upload SARIF files to GitHub Security
+      # We use gh CLI because it’s easier to loop
+      # and assign stable categories per image
+      - name: Upload SARIF files
+        env:
+          GH_TOKEN: ${{ github.token }}
         run: |
-          # Upload each SARIF file with a unique category
-          find . -name "*.sarif" -type f | while read -r sarif_file; do
-            # Extract image name from directory path for category
-            category=$(basename $(dirname "$sarif_file") | sed 's/^sarif-//' | sed 's/-[0-9]*$//')
-            echo "Uploading $sarif_file with category: docker-$category"
-
-            # Use gh CLI to upload SARIF (simpler than action in loop)
-            cat "$sarif_file" | gh api \
+          find . -name "*.sarif" -type f | while read -r sarif; do
+            category=$(basename "$(dirname "$sarif")" | sed 's/^sarif-//' | sed 's/-[0-9]*$//')
+            echo "Uploading $sarif as docker-$category"
+
+            gh api \
               --method POST \
               -H "Accept: application/vnd.github+json" \
-              -H "X-GitHub-Api-Version: 2022-11-28" \
               /repos/${{ github.repository }}/code-scanning/sarifs \
-              -f sarif=@- \
+              -f sarif=@-"$sarif" \
               -f ref="${{ github.ref }}" \
               -f commit_sha="${{ github.sha }}" \
-              -f checkout_uri="${{ github.server_url }}/${{ github.repository }}" \
-              -f category="docker-$category" || echo "Failed to upload $sarif_file"
+              -f category="docker-$category" || echo "Upload failed for $sarif"
           done
-        env:
-          GH_TOKEN: ${{ github.token }}