Trivy EP09 | Generate HTML Vulnerability Report with Trivy | Docker Image Security Scan

In enterprise DevSecOps workflows, raw console outputs are insufficient for compliance reviews and stakeholder audits. This chapter explores how to transition from transient terminal logs to professional, shareable HTML vulnerability reports using Aqua Security's official Trivy templates.

1. Why Do We Need HTML Reports? (The Collaboration Problem)

Up to this point, vulnerability scans have been executed directly in the terminal, outputting text-based logs containing OS-level and package-level security flaws. However, this approach presents several operational bottlenecks:

The Sharing Barrier: Security teams, compliance officers, and engineering managers cannot easily review raw console text or terminal scrollbacks.
Lack of Artifact Persistence: Terminal outputs vanish once the session closes or the scroll buffer clears.
Visual Hierarchy Deficit: Raw text lacks intuitive color-coding, severity categorization, and structured tables required for fast triage.

CODE

Developer Terminal (Raw Console Output)
        |
        | (Problem: Hard to share, no persistence, lacks visual hierarchy)
        v
Security Team / Compliance Auditors (Needs shareable, formatted artifacts)

Note: In a mature DevSecOps pipeline, security scans must generate static artifacts that can be archived, attached to pull requests, or uploaded to artifact repositories for auditing.

2. Core Mental Model: Templates as Skeletons

Generating an HTML report with Trivy relies on a templating pattern. Think of the template file as an empty form or a skeleton structure waiting to be filled with data.

Real-Life Analogy

Imagine ordering a custom invoice or a tax document. The layout, CSS styling, and table headers are already predefined in a blank template document. When you run your scan, Trivy acts as the data provider, injecting the specific vulnerability findings (packages, CVE IDs, severities) into the empty slots of the template to generate a complete, beautifully formatted report.

3. Acquiring the Official Trivy HTML Template

To generate a styled HTML report, Trivy requires a template file (.tpl) that dictates how raw JSON or scan data translates into HTML elements. Aqua Security hosts these standard templates in their official GitHub repository.

Step-by-General Workflow

Navigate to the official Aqua Security GitHub repository.
Locate the contrib directory within the Trivy project.
Select and download the html.tpl template file.

In the terminal, retrieve the raw template file using curl:

BASH

curl -LO https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/html.tpl

Alternatively, as demonstrated in the lecture, you can download and save it explicitly:

BASH

curl -o html.tpl https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/html.tpl

Verifying the file's presence in the current working directory:

BASH

ls -la html.tpl

4. Understanding the Template File Structure

If you inspect the downloaded html.tpl file using cat html.tpl, you will see raw templating syntax containing placeholders and conditional blocks.

Structure & Concept Flow

html.tpl (The Skeleton)

+-- HTML boilerplate (<html>, <head>, CSS styles)

+-- Placeholder variables for image name, scan time, and vulnerabilities

+-- Iteration loops for CVE lists and severity badges

At this stage, the template file exists on disk as a structural shell, but it contains no vulnerability data until combined with a live Trivy scan execution.

5. Transitioning from Console Output to Custom Formats

A standard Trivy container image scan outputs directly to standard output ( $\text{stdout}$ ).

BASH

trivy image python:3.10-slim

To redirect and transform this output into our downloaded template format, we must pass three specific configuration flags to the Trivy CLI:

--format template: Instructs Trivy to use a custom template engine instead of default table or JSON outputs.
--template @html.tpl: Specifies the file path to the template (prefixed with @ to denote a template file path).
--output trivy.html: Defines the destination filename for the generated HTML artifact.

6. Step-by-Step Command Evolution & Execution

Let us construct the final, production-ready command to scan a Docker image and compile an HTML report.

BASH

trivy image --format template --template "@html.tpl" -o trivy.html python:3.10-slim

Command Breakdown Table

Flag / Argument	Purpose / Description
`trivy image`	Tells Trivy to perform a vulnerability scan on a container image.
`--format template`	Switches the output renderer from default console text to template mode.
`--template "@html.tpl"`	Points Trivy to the local template skeleton file (`html.tpl`).
`-o trivy.html`	Specifies the output file path where the compiled HTML report will be saved.
`python:3.10-slim`	The target Docker image being scanned for vulnerabilities.

7. Complete Execution Flow Walkthrough

Executing the report generation command triggers the following internal pipeline:

Structure & Concept Flow

User executes Trivy CLI command

Trivy pulls/analyzes image layers (python:3.10-slim)

Vulnerability database matches OS packages & CVEs

Trivy engine binds scan data into html.tpl template variables

Compiled HTML written to disk (trivy.html)

Upon successful execution, verify the generated file in your workspace:

BASH

ls -lh trivy.html

8. Anatomy of the Generated HTML Report

Opening trivy.html in a web browser reveals a professional dashboard containing:

Metadata Section: Image name, scanning engine version, and exact generation timestamp (Generated at [Timestamp]).
Severity Color Coding: Visual risk stratification using standard security color palettes:
- Green / Blue: Low or negligible risk items.
- Yellow / Orange: Medium to High severity vulnerabilities requiring scheduled patching.
- Red: Critical vulnerabilities requiring immediate remediation.
Actionable Links: Direct hyperlinks to CVE databases and advisory references (https://cve.mitre.org/...) attached to each vulnerability entry.

Summary and Key Takeaways

Beyond Terminal Logs: Raw console outputs are ephemeral and unsuitable for stakeholder sharing, compliance audits, or pull request attachments.
Artifact Generation: Trivy supports custom export formats, allowing security engineers to generate shareable artifacts rather than mere terminal scrollbacks.
Aqua Security Contrib Templates: Official templates like html.tpl can be retrieved directly from the Trivy GitHub repository via curl.
The Template Pattern: Templates act as structural skeletons; Trivy injects live scan data into these placeholders during execution.
Key CLI Flags: Utilizing --format template, --template "@path", and -o filename.html enables seamless conversion from scan results to rich HTML documents.
Visual Triage: Generated HTML reports provide clear color-coded severity breakdowns (Critical, High, Medium, Low) and direct links to CVE advisories.
Audit Readiness: Timestamped HTML reports ensure historical traceability for security reviews and DevSecOps pipelines.
Next Steps Preview: While manual command-line execution works well for ad-hoc checks, future lessons will automate these scans within continuous integration (CI) workflows.