Trivy EP05 | Trivy Flags Explained | Full Guide with Commands & Real Output

Mastering basic container scanning is a great first step, but real-world DevSecOps requires precision: knowing how to filter noise, target specific vulnerability categories, and gate CI/CD pipelines against critical security threats. This guide explores the three most critical Trivy flags (--severity, --vuln-type, and --exit-code) to transform your vulnerability scans from overwhelming data dumps into actionable security gates.

1. Why Do We Need Advanced Trivy Flags?

By default, running a standard Trivy scan outputs every single vulnerability discovered in a container image, spanning all severity levels (LOW, MEDIUM, HIGH, CRITICAL, and UNKNOWN).

• The Information Overload Problem: In a production container with hundreds of packages, a default scan can output hundreds or thousands of lines of vulnerabilities, many of which might be minor or irrelevant to your immediate goals.
• The CI/CD Failure Gap: By default, Trivy exits with a success code (0) even if it detects severe vulnerabilities. If you plug a default scan directly into a Jenkins or GitHub Actions pipeline, the build will pass regardless of whether your image contains severe remote code execution flaws.

2. Core Mental Model: The Security Filter Pipeline

Think of Trivy's default scanner as a wide-net fisherman catching every creature in the ocean (shrimp, seaweed, sharks, and whales). Advanced flags act as precision sorting gates that let you filter by severity, isolate components by origin, and trigger automated pipeline failures.

3. Flag 1: Filtering by Severity (--severity)

When managing production security, teams rarely block deployments over a LOW or UNKNOWN severity advisory. Instead, they focus remediation efforts on high-risk issues. The --severity flag allows you to narrow down the scan output.

Supported Severity Levels

Trivy accepts the following severity categories (which should ideally be written in uppercase):

• LOW
• MEDIUM
• HIGH
• CRITICAL
• UNKNOWN

Practical Commands & Execution

A. Scanning for High and Critical Vulnerabilities Only

To surface only severe issues that demand immediate attention, pass a comma-separated list to the --severity flag:

trivy image --severity HIGH,CRITICAL python:3.10

What happens under the hood:

1. Trivy updates its vulnerability database.
2. The application analyzer inspects both OS packages and application libraries.
3. Trivy filters out everything except HIGH and CRITICAL findings.
4. Results are rendered in a clean tabular format on your screen within 10 to 20 seconds.

Note: If an image has zero CRITICAL vulnerabilities but contains HIGH vulnerabilities, Trivy will display only the HIGH items (showing 0 for critical categories).

B. Scanning for Low Vulnerabilities Only

If you are auditing minor advisories or performing baseline compliance checks, you can isolate lower-tier issues:

trivy image --severity LOW python:3.10

C. Scanning for Medium Vulnerabilities

Similarly, to check for mid-tier risks:

trivy image --severity MEDIUM python:3.10

4. Flag 2: Targeting Vulnerability Types (--vuln-type)

Container images are layered artifacts. They contain a base operating system (e.g., Debian, Alpine, Ubuntu) bundled with system packages, alongside application-specific dependency libraries (e.g., Python pip packages, Node npm modules, Java maven dependencies).

The --vuln-type flag isolates where the vulnerability lives, which dictates who is responsible for fixing it.

Vulnerability Types Breakdown

Practical Commands

A. Scanning Exclusively for Operating System Vulnerabilities

If you are an infrastructure engineer hardening base images, filter strictly for OS-level flaws:

trivy image --vuln-type os python:3.10

Output focus: System packages managed by the base image's package manager (e.g., Debian packages).

B. Scanning Exclusively for Application Library Vulnerabilities

If you are a developer looking to fix code dependencies without touching the base image, filter for library issues:

trivy image --vuln-type library python:3.10

Output focus: Package manager files (like requirements.txt), allowing developers to update dependency versions directly in source code.

5. Flag 3: Enforcing CI/CD Quality Gates (--exit-code)

The --exit-code flag is the cornerstone of integrating Trivy into automated DevSecOps pipelines.

The Status Quo vs. DevSecOps Reality

• Default Behavior: Trivy exits with code 0 (Success) even if it discovers thousands of critical vulnerabilities. A CI/CD pipeline evaluates success or failure strictly based on shell exit codes ($0 = \text{Success}$, $\neq 0 = \text{Failure}$).
• The Security Requirement: To prevent vulnerable code from reaching production, we need Trivy to return a non-zero exit code (specifically exit code 1) when unacceptable vulnerabilities are found.

Pipeline Integration Command

To configure Trivy to fail your build when HIGH or CRITICAL vulnerabilities are detected, combine the severity filter with the exit code flag:

trivy image --severity HIGH,CRITICAL --exit-code 1 python:3.10

Flow Walkthrough in a CI/CD Pipeline (e.g., Jenkins / GitHub Actions)

6. Comprehensive Flag Summary Matrix

7. Summary and Key Takeaways

• Information Control: Default Trivy scans output all vulnerability tiers; master flags allow you to isolate precisely what matters.
• Severity Filtering (--severity): Use uppercase arguments like --severity HIGH,CRITICAL to zero in on dangerous issues while ignoring low-priority background noise.
• Audience-Specific Scanning (--vuln-type): Separate os vulnerabilities (handled by infrastructure teams via base image patches) from library vulnerabilities (handled by developers via dependency file updates).
• Automated Quality Gates (--exit-code 1): Essential for DevSecOps pipelines to automatically fail builds and halt deployments when critical security thresholds are breached.
• Practical Exploration: Always test flags locally against various Docker images (such as python:3.10) to observe how report structures adapt before deploying them into shared team pipelines.