trivy-image

Overview

Per trivy.dev/latest/docs/target/container_image/:

Trivy is Aqua Security's open-source scanner. Distinguishing feature: all-in-one - one CLI invocation covers vuln + secret + misconfig + license scanning. By contrast, syft-generation

• grype-scanning is a two-step SBOM-then-scan pattern.

Per tv-img the scanner toggles:

When to use

• Container-image security in one tool (vs separate tools per concern).
• The team uses Aqua Security stack (Trivy is the OSS center of it).
• Pre-prod or registry-side scanning (Trivy's image-by-tag mode).
• Layered with grype-scanning for cross-DB consensus on vuln findings.

Step 1 - Install

Common install paths:

# Homebrew (macOS / Linux)
brew install trivy

# Docker (zero-install for CI)
docker pull aquasec/trivy:latest

# Linux APT
sudo apt-get install trivy

# RPM
sudo dnf install trivy

Step 2 - Basic image scan

Per tv-img:

# Default: vuln + secret scan
trivy image python:3.4-alpine

Example with multiple toggles:

# All scanners (vuln + secret + misconfig + license)
trivy image --scanners vuln,secret,misconfig,license python:3.4-alpine

# Vuln-only (fastest, default if --scanners omitted defaults to vuln+secret)
trivy image --scanners vuln python:3.4-alpine

Step 3 - Severity filtering

Per tv-img:

trivy image --severity HIGH,CRITICAL python:3.4-alpine

Severity levels: UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL.

Combined with exit-code-on-finding:

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

Exit code semantics: 0 = no findings at the configured severity; 1 = findings present.

Step 4 - Output formats

Per tv-img:

trivy image --format json --output trivy-image.json my-image:1.0
trivy image --format sarif --output trivy-image.sarif my-image:1.0
trivy image --format cyclonedx --output trivy-cyclonedx.json my-image:1.0

Step 5 - --ignore-unfixed for actionable filter

Per tv-img:

trivy image --ignore-unfixed python:3.4-alpine

"The --ignore-unfixed flag excludes vulnerabilities without available fixes"

This is the practical first-line filter - distinguishes "vuln you can act on" from "vuln waiting for upstream fix." Combine with severity threshold:

trivy image --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 my-image:1.0

This is the recommended PR-blocking config: fail only on actionable, high-severity vulns.

Step 6 - Secret scanning

Per tv-img:

"Secret detection runs automatically. The tool scans for exposed credentials and sensitive data, particularly in environment variables."

Secret findings appear alongside vuln findings in the same report. For deeper secret-scanning patterns, see gitleaks-scanning

• trufflehog-scanning in the qa-secrets plugin.

Step 7 - Misconfiguration scanning

Per tv-img:

trivy image --scanners misconfig --severity HIGH,CRITICAL my-image:1.0

Detects Docker / Kubernetes config patterns matching CIS Benchmarks

• team-policy issues (e.g., container running as root, missing HEALTHCHECK, exposed sensitive ports).

For comprehensive IaC scanning (not just image-internal config), use checkov-policy

• tfsec-policy from the qa-iac plugin.

Step 8 - False-positive triage (MANDATORY)

Per tv-img: "Use a .trivyignore file to suppress specific findings. Place this file in your project directory with CVE IDs or vulnerability identifiers you wish to exclude."

Suppression mechanisms:

.trivyignore example:

# .trivyignore
# Reason: log4j-core 2.14.x bundled but not loaded at runtime
#         (verified via dependency tree analysis)
# Approved-by: alice@example.com
# Re-review-date: 2026-09-15
CVE-2021-44228
CVE-2021-45046

# Misconfiguration ignores
DS013
KSV001

Justification template (mandatory): every entry in .trivyignore should be preceded by # Reason: ... # Approved-by: ... # Re-review-date: ... comment block.

For richer programmatic suppression, use OpenVEX:

trivy image --vex sbom.openvex.json --severity HIGH,CRITICAL my-image:1.0

The VEX file's per-CVE assertions (not_affected etc.) filter the output.

Cadence: every quarter, audit .trivyignore; expired re-review-date entries removed.

Step 9 - CI integration

jobs:
  trivy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - run: docker build -t my-app:${{ github.sha }} .
      - uses: aquasecurity/trivy-action@master
        with:
          image-ref: my-app:${{ github.sha }}
          format: sarif
          output: trivy.sarif
          severity: CRITICAL,HIGH
          ignore-unfixed: true
          exit-code: 1
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with: { sarif_file: trivy.sarif }

The aquasecurity/trivy-action GHA wraps the CLI + SARIF upload.

Step 10 - Composition with sister tools

Anti-patterns

Limitations

• DB updates are large (~1 GB cache); pin DB version for CI determinism.
• Misconfig + license + secret scanning are less deep than dedicated tools (use Trivy as first-line; layer dedicated tools for depth).
• Trivy's vuln DB has its own coverage profile; pair with grype-scanning for cross-DB consensus.
• License detection is basic; for compliance-grade analysis, use ScanCode / FOSSology.

References

• tv-img - container image scan reference
• trivy.dev - landing
• aquasecurity.github.io/trivy - full documentation
• github.com/aquasecurity/trivy - repository
• openvex.dev - OpenVEX specification (used by --vex flag)
• syft-generation, grype-scanning, cyclonedx-format, spdx-format - sister tools
• vuln-prioritizer - unifier agent