Implement Automated Docker Image Vulnerability Scanning

[josecelano]

Overview

This epic implements automated vulnerability scanning for all Docker images used in the project using Trivy. The implementation is divided into two phases:

1. Basic Scanning: Hardcoded image list with periodic and PR-triggered scans
2. Dynamic Scanning: Automatically detect images from environment configuration

Problem Statement

Currently, the project uses multiple Docker images without automated vulnerability scanning:

• docker/provisioned-instance/Dockerfile
• docker/ssh-server/Dockerfile
• templates/docker-compose/docker-compose.yml.tera

This creates security risks as vulnerabilities in these images go undetected until discovered manually or exploited.

Container Images in Scope

Project-Built Images

1. Provisioned Instance: torrust-tracker-deployer/provisioned-instance

   • Source: docker/provisioned-instance/Dockerfile
   • Purpose: Test container for E2E deployment testing

2. SSH Server: torrust-tracker-deployer/ssh-server

   • Source: docker/ssh-server/Dockerfile
   • Purpose: Mock SSH server for integration testing

Third-Party Images

3. Torrust Tracker: torrust/tracker:develop
4. MySQL Database: mysql:8.0
5. Grafana: grafana/grafana:11.4.0
6. Prometheus: prom/prometheus:v3.0.1

Total Images: 6 (2 project-built + 4 third-party)

Current Vulnerability Status

Scan Date: 2025-12-22 | Scanner: Trivy (latest) | Filter: HIGH, CRITICAL

• ✅ provisioned-instance: CLEAN (0 vulnerabilities)
• ✅ ssh-server: CLEAN (0 vulnerabilities)
• ⚠️ torrust/tracker:develop: 5 vulnerabilities (1 CRITICAL, 4 HIGH)
• ✅ mysql:8.0: CLEAN (0 vulnerabilities)
• ✅ grafana/grafana:11.4.0: CLEAN (0 vulnerabilities)
• ✅ prometheus:v3.0.1: CLEAN (0 vulnerabilities)

Status: 5/6 images clean, 1 image with vulnerabilities requiring attention

Solution Architecture

Phase 1: Basic Scanning Workflow (Immediate Security)

Create GitHub Actions workflow with:

• Hardcoded list of 6 Docker images
• Trivy scanner with HIGH/CRITICAL severity filter
• Run on: push to main, pull requests, scheduled (weekly)
• SARIF report upload to GitHub Security tab
• Build failure on vulnerability detection

Benefits: Immediate security coverage, simple maintenance

Phase 2: Dynamic Image Detection (Long-term Maintainability)

Enhance workflow to:

• Extract Docker images from environment configuration
• Use show command to expose image information
• Automatically adapt when images change
• Eliminate manual image list maintenance

Benefits: Zero maintenance, always up-to-date

Implementation Phases

Phase 1: Basic Trivy Scanning Workflow

Epic child issue - see subissue for detailed specification

• Create .github/workflows/docker-security-scan.yml
• Scan 2 project-built images (build first, then scan)
• Scan 4 third-party images (direct scan)
• Upload SARIF results to GitHub Security
• Add workflow status badge to README

Estimated effort: 2-4 hours

Phase 2: Dynamic Image Detection

Epic child issue - see subissue for detailed specification

• Create DockerImage value object in domain model
• Add docker_image field to service configurations
• Update Docker Compose template to use Tera variables
• Extend show command to display Docker images
• Update workflow to extract images dynamically

Estimated effort: 4-6 hours (depends on issue #241 completion)

Success Criteria

• ✅ All 6 Docker images scanned automatically
• ✅ Vulnerabilities reported in GitHub Security tab
• ✅ Build fails when HIGH/CRITICAL vulnerabilities detected
• ✅ Scans run on push, PR, and weekly schedule
• ✅ Workflow adapts automatically when images change (Phase 2)
• ✅ Zero manual maintenance required (Phase 2)

Related Issues

• Subissue 1: Implement Basic Trivy Scanning Workflow
• Subissue 2: Implement Dynamic Image Detection for Scanning
• Dependency: Implement Environment Show Command #241 (Show command - required for Phase 2)

Documentation

Full specification: docs/issues/epic-docker-image-vulnerability-scanning.md