Merge #256: Implement Basic Trivy Scanning Workflow

40dd234 docs: [#251] document Security tab viewing behavior (Jose Celano)
098add2 fix: [#251] use CodeQL action for SARIF upload with category support (Jose Celano)
af93704 docs: [#251] add ADR for docker security scan exit code zero philosophy (Jose Celano)
92b3325 refactor: [#251] apply security-first workflow philosophy with exit-code 0 (Jose Celano)
7ff69be fix: [#251] upload SARIF files with unique categories per image (Jose Celano)
797addf fix: [#251] upload SARIF files with unique categories per image (Jose Celano)
cebf2a7 fix: [#251] prevent workflow failure and artifact name conflicts (Jose Celano)
5b09357 fix: [#251] sanitize Docker image names for artifact naming (Jose Celano)
382f430 refactor: [#251] separate SARIF upload to dedicated job with minimal permissions (Jose Celano)
afb653c chore: [#251] update trivy-action from v0.28.0 to v0.33.1 (Jose Celano)
7013bc0 fix: [#251] focus CVE scanning only, display all issues for visibility (Jose Celano)
c13afa8 fix: [#251] disable secret scanning for test containers with SSH keys (Jose Celano)
c11eb10 feat: [#251] add human-readable vulnerability output to workflow logs (Jose Celano)
c032e71 fix: [#251] update docker build context and action versions (Jose Celano)
defaaaa feat: [#251] implement basic trivy scanning workflow (Jose Celano)

Pull request description:

  Closes #251

  ## Overview

  Implements a GitHub Actions workflow that uses Trivy to scan Docker images for vulnerabilities. This initial implementation uses a hardcoded list of images and provides immediate security coverage.

  ## Changes

  ### 1. GitHub Actions Workflow (`.github/workflows/docker-security-scan.yml`)

  Created a new workflow with two jobs:

  #### **Scan Project-Built Images**
  - Builds and scans 2 project-built images:
    - `torrust-tracker-deployer/provisioned-instance`
    - `torrust-tracker-deployer/ssh-server`

  #### **Scan Third-Party Images**
  - Scans 4 third-party images used in docker-compose:
    - `torrust/tracker:develop`
    - `mysql:8.0`
    - `grafana/grafana:11.4.0`
    - `prom/prometheus:v3.0.1`

  **Workflow Features**:
  - ✅ Scans for HIGH/CRITICAL vulnerabilities only
  - ✅ Fails builds when vulnerabilities detected (`exit-code: 1`)
  - ✅ Uploads results to GitHub Security tab (SARIF format)
  - ✅ Runs on push to main/develop
  - ✅ Runs on PRs affecting Docker files
  - ✅ Runs daily at 6 AM UTC
  - ✅ Supports manual triggering

  **Notes**:
  - Added comments linking third-party images to `templates/docker-compose/docker-compose.yml.tera`
  - Added TODO referencing issue #252 for future automation

  ### 2. README Update

  Added workflow badge to display scan status.

  ## Testing

  - ✅ Pre-commit checks passed (`./scripts/pre-commit.sh`)
  - ✅ YAML linting passed
  - ✅ All unit tests passed
  - ✅ E2E tests passed

  ## Future Work

  This is Phase 1 of the security scanning epic. Phase 2 (#252) will:
  - Dynamically detect images from environment configuration
  - Eliminate need for manual updates when images change
  - Integrate with `show` command to list scanned images

  ## Related

  - Epic: #250 - Implement Automated Docker Image Vulnerability Scanning
  - Next Phase: #252 - Implement Dynamic Image Detection for Scanning
  - [Trivy Documentation](https://github.com/aquasecurity/trivy)

ACKs for top commit:
  josecelano:
    ACK 40dd234

Tree-SHA512: 9c77b373d433f67c9ca07425b4343fed141a2d4474758475bb913c0c67518ae6664581fd9206550fd88c9c92194f0890175ba7b1cd0a936a85246aaea1ad7a5d

Author: josecelano

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

@@ -0,0 +1,218 @@
+name: Docker Security Scan
+
+on:
+  push:
+    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:
+
+jobs:
+  scan-project-images:
+    name: Scan Project-Built Docker Images
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        image:
+          - dockerfile: docker/provisioned-instance/Dockerfile
+            context: docker/provisioned-instance
+            name: provisioned-instance
+          - 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 \
+            -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"
+
+      # 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]
+        with:
+          image-ref: torrust-tracker-deployer/${{ matrix.image.name }}:latest
+          format: "sarif"
+          output: "trivy-${{ matrix.image.name }}.sarif"
+          severity: "HIGH,CRITICAL"
+          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-${{ matrix.image.name }}.sarif
+          retention-days: 30
+
+  scan-third-party-images:
+    name: Scan Third-Party Docker Images
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        # 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"
+
+      # Third-party images should NEVER block CI.
+      # We only report findings to GitHub Security.
+      - name: Generate SARIF (Code Scanning)
+        uses: aquasecurity/[email protected]
+        with:
+          image-ref: ${{ matrix.image }}
+          format: "sarif"
+          output: "trivy.sarif"
+          severity: "HIGH,CRITICAL"
+          exit-code: "0"
+          scanners: "vuln"
+
+      # Needed to produce stable artifact names
+      - name: Sanitize image name
+        id: sanitize
+        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.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
+
+    # 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 }}
+
+      # Upload each SARIF file with CodeQL Action using unique categories.
+      # The category parameter enables proper alert tracking per image.
+      # Must use CodeQL Action (not gh API) - API doesn't support category field.
+      #
+      # VIEWING RESULTS:
+      # - For pull requests: /security/code-scanning?query=pr:NUMBER+is:open
+      # - For branches: /security/code-scanning?query=is:open+branch:BRANCH-NAME
+      # - For main branch: /security/code-scanning?query=is:open+branch:main (default view)
+      # The default Security tab filters by "is:open branch:main" which only shows
+      # alerts from the main branch, not from PR branches.
+      - name: Upload project provisioned-instance SARIF
+        if: always()
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: sarif-project-provisioned-instance-${{ github.run_id }}/trivy-provisioned-instance.sarif
+          category: docker-project-provisioned-instance
+        continue-on-error: true
+
+      - name: Upload project ssh-server SARIF
+        if: always()
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: sarif-project-ssh-server-${{ github.run_id }}/trivy-ssh-server.sarif
+          category: docker-project-ssh-server
+        continue-on-error: true
+
+      - name: Upload third-party mysql SARIF
+        if: always()
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: sarif-third-party-mysql-8.0-${{ github.run_id }}/trivy.sarif
+          category: docker-third-party-mysql-8.0
+        continue-on-error: true
+
+      - name: Upload third-party tracker SARIF
+        if: always()
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: sarif-third-party-torrust-tracker-develop-${{ github.run_id }}/trivy.sarif
+          category: docker-third-party-torrust-tracker-develop
+        continue-on-error: true
+
+      - name: Upload third-party grafana SARIF
+        if: always()
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: sarif-third-party-grafana-grafana-11.4.0-${{ github.run_id }}/trivy.sarif
+          category: docker-third-party-grafana-grafana-11.4.0
+        continue-on-error: true
+
+      - name: Upload third-party prometheus SARIF
+        if: always()
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: sarif-third-party-prom-prometheus-v3.0.1-${{ github.run_id }}/trivy.sarif
+          category: docker-third-party-prom-prometheus-v3.0.1
+        continue-on-error: true

README.md

@@ -1,4 +1,4 @@
-[![Linting](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/linting.yml/badge.svg)](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/linting.yml) [![Testing](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/testing.yml/badge.svg)](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/testing.yml) [![E2E Infrastructure Tests](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/test-e2e-infrastructure.yml/badge.svg)](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/test-e2e-infrastructure.yml) [![E2E Deployment Tests](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/test-e2e-deployment.yml/badge.svg)](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/test-e2e-deployment.yml) [![Test LXD Container Provisioning](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/test-lxd-provision.yml/badge.svg)](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/test-lxd-provision.yml) [![Coverage](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/coverage.yml/badge.svg)](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/coverage.yml)
+[![Linting](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/linting.yml/badge.svg)](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/linting.yml) [![Testing](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/testing.yml/badge.svg)](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/testing.yml) [![E2E Infrastructure Tests](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/test-e2e-infrastructure.yml/badge.svg)](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/test-e2e-infrastructure.yml) [![E2E Deployment Tests](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/test-e2e-deployment.yml/badge.svg)](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/test-e2e-deployment.yml) [![Test LXD Container Provisioning](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/test-lxd-provision.yml/badge.svg)](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/test-lxd-provision.yml) [![Coverage](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/coverage.yml/badge.svg)](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/coverage.yml) [![Docker Security Scan](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/docker-security-scan.yml/badge.svg)](https://github.com/torrust/torrust-tracker-deployer/actions/workflows/docker-security-scan.yml)
 
 # Torrust Tracker Deployer
 

docs/decisions/README.md

@@ -6,6 +6,7 @@ This directory contains architectural decision records for the Torrust Tracker D
 
 | Status        | Date       | Decision                                                                                                  | Summary                                                                                    |
 | ------------- | ---------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| ✅ Accepted   | 2025-12-23 | [Docker Security Scan Exit Code Zero](./docker-security-scan-exit-code-zero.md)                           | Use exit-code 0 for security scanning - Trivy detects, GitHub Security decides, CI green   |
 | ✅ Accepted   | 2025-12-20 | [Grafana Integration Pattern](./grafana-integration-pattern.md)                                           | Enable Grafana by default with hard Prometheus dependency and environment variable config  |
 | ✅ Accepted   | 2025-12-17 | [Secrecy Crate for Sensitive Data Handling](./secrecy-crate-for-sensitive-data.md)                        | Use secrecy crate for type-safe secret handling with memory zeroing                        |
 | ✅ Accepted   | 2025-12-14 | [Database Configuration Structure in Templates](./database-configuration-structure-in-templates.md)       | Expose structured database fields in templates rather than pre-resolved connection strings |

docs/decisions/docker-security-scan-exit-code-zero.md

@@ -0,0 +1,138 @@
+# Decision: Exit Code Zero for Docker Security Scanning
+
+## Status
+
+Accepted
+
+## Date
+
+2025-12-23
+
+## Context
+
+When implementing automated Docker vulnerability scanning with Trivy in GitHub Actions, we faced a critical decision about how the CI/CD pipeline should respond to discovered vulnerabilities.
+
+Traditional approaches make CI fail when vulnerabilities are found, blocking all development until issues are resolved. However, this creates several problems:
+
+1. **False Positives**: Security scanners can report issues that don't apply to our context or are accepted risks
+2. **Third-Party Dependencies**: We cannot immediately fix vulnerabilities in upstream images (mysql, prometheus, grafana)
+3. **Scanner Quirks**: Trivy occasionally exits with code 1 even when no vulnerabilities are found
+4. **Development Flow**: Security findings should not block unrelated development work
+5. **Policy Enforcement**: Security decisions should be made by security teams, not automated tooling
+6. **Partial Data Loss**: If CI fails early, later scans never run and we lose visibility into other images
+
+The initial implementation used `exit-code: "1"` which caused the workflow to fail on any HIGH or CRITICAL vulnerability, including when scanning third-party production images with known CVEs that we cannot immediately fix.
+
+## Decision
+
+Implement a **security-first philosophy** where:
+
+1. **Exit Code Zero Everywhere**: All Trivy scan steps use `exit-code: "0"` - the scanner never fails the CI pipeline
+2. **Dual Output Strategy**:
+   - Human-readable table format in workflow logs for immediate visibility
+   - SARIF format uploaded to GitHub Security tab for tracking and alerting
+3. **Separation of Concerns**:
+   - Trivy's role: **Detect** vulnerabilities and provide data
+   - GitHub Security's role: **Decide** enforcement policies and alert routing
+   - CI's role: **Stay green** and maintain development velocity
+4. **Always Run Policy**: Upload job uses `if: always()` to ensure partial results are never lost
+5. **Unique Categories**: Each image gets a unique SARIF category for proper alert tracking and deduplication
+6. **Scheduled Scanning**: Daily cron ensures continuous monitoring without blocking code changes
+
+This philosophy is summarized as: **"Trivy detects, GitHub Security decides, CI stays green"**
+
+## Consequences
+
+### Positive
+
+- **No False Failures**: Development work never blocked by scanner quirks or edge cases
+- **Continuous Visibility**: All scans complete even if one fails, providing complete security picture
+- **Flexible Enforcement**: Security team can configure GitHub Security policies without changing code
+- **Third-Party Tolerance**: Known vulnerabilities in upstream images don't block development
+- **Developer Experience**: Green builds maintain team velocity while security team reviews findings
+- **Policy Separation**: Security enforcement decoupled from CI/CD implementation
+- **Audit Trail**: All findings recorded in GitHub Security tab for compliance and tracking
+- **Incremental Improvement**: Can address vulnerabilities based on priority without CI pressure
+
+### Negative
+
+- **Potential Complacency**: Green CI might lead to ignoring security findings (mitigated by GitHub Security alerts)
+- **Requires Monitoring**: Security team must actively monitor GitHub Security tab
+- **Policy Configuration**: Requires additional GitHub Security policy setup for enforcement
+- **Learning Curve**: Non-traditional approach may confuse developers expecting red builds for vulnerabilities
+
+### Risks Introduced
+
+- **Missed Critical Issues**: If GitHub Security is not properly configured or monitored, critical vulnerabilities might go unaddressed
+  - **Mitigation**: Daily scheduled scans ensure consistent monitoring; GitHub Security sends email notifications
+- **Organizational Resistance**: Some organizations mandate CI failure on security issues
+  - **Mitigation**: GitHub Security can be configured to block PRs or deployments if needed
+
+## Alternatives Considered
+
+### 1. Exit Code 1 (Fail on Vulnerabilities)
+
+**Approach**: Use `exit-code: "1"` to fail CI when HIGH/CRITICAL vulnerabilities are found.
+
+**Rejected Because**:
+
+- Blocks development on third-party image vulnerabilities we cannot fix immediately
+- Scanner quirks cause false CI failures even with zero vulnerabilities
+- No flexibility for security team to make risk-based decisions
+- Partial data loss when early scans fail
+
+### 2. Mixed Exit Codes (Project vs Third-Party)
+
+**Approach**: Use `exit-code: "1"` for project images but `exit-code: "0"` for third-party images.
+
+**Rejected Because**:
+
+- Inconsistent philosophy creates confusion
+- Project images can have legitimate accepted risks
+- Still susceptible to scanner quirks on project images
+- Doesn't solve the fundamental policy enforcement problem
+
+### 3. Continue-on-Error Pattern
+
+**Approach**: Use `exit-code: "1"` but add `continue-on-error: true` to allow workflow to proceed.
+
+**Rejected Because**:
+
+- Shows misleading "failed" status even though workflow continues
+- Scanner errors appear as failures in UI, creating noise
+- Doesn't fundamentally change the enforcement model
+- Confusing to developers seeing "failed" steps that don't actually fail
+
+### 4. CodeQL Action with Single Category
+
+**Approach**: Upload all SARIF files using github/codeql-action/upload-sarif with same category.
+
+**Rejected Because**:
+
+- CodeQL Action rejects multiple SARIF uploads with identical categories (as of July 2025)
+- Results in "multiple SARIF runs with same category" error
+- Cannot distinguish alerts between different images
+
+## Viewing Security Results
+
+Security scan results are uploaded to GitHub's Security tab, but the default view filters by `is:open branch:main`. This means:
+
+- **Pull Request Results**: Must use filter `pr:NUMBER is:open` (e.g., `/security/code-scanning?query=pr:256+is:open`)
+- **Branch Results**: Must use filter `is:open branch:BRANCH-NAME` for non-main branches
+- **Main Branch Results**: Visible in default view after merging to main
+
+Results uploaded from PR branches are not visible in the default Security tab view because the default filter excludes them. This is GitHub's standard behavior for code scanning across all analysis tools.
+
+## Related Decisions
+
+- [GitHub Actions Workflow Structure](https://github.com/torrust/torrust-tracker-deployer/pull/256) - How the three-job structure enables this philosophy
+- Future: Security Policy Configuration (to be documented when GitHub Security policies are configured)
+
+## References
+
+- [Issue #251: Implement basic Trivy scanning workflow](https://github.com/torrust/torrust-tracker-deployer/issues/251)
+- [Pull Request #256: Implement Basic Trivy Scanning Workflow](https://github.com/torrust/torrust-tracker-deployer/pull/256)
+- [Trivy Action Documentation](https://github.com/aquasecurity/trivy-action)
+- [GitHub Code Scanning Documentation](https://docs.github.com/en/code-security/code-scanning)
+- [GitHub Security Policy Enforcement](https://docs.github.com/en/code-security/code-scanning/managing-code-scanning-alerts)
+- [Security-First Philosophy Discussion](https://github.com/torrust/torrust-tracker-deployer/pull/256#discussion) - External review recommending exit-code 0 approach