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's
Grype workflow is a two-step
SBOM-then-scan pattern.
Per tv-img the scanner toggles:
| Scanner | Default? | Use |
|---|
vuln | yes | Known CVEs in OS + language packages |
secret | yes | Exposed credentials (env vars, config files) |
misconfig | no | Docker / Kubernetes config best-practices |
license | no | License compliance scanning |
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 the Grype workflow in
syft-generation 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:
| Format | Use |
|---|
json | For multi-scanner finding prioritization |
sarif | GitHub Code Scanning upload |
cyclonedx | CycloneDX SBOM with vuln annotations |
spdx-json | SPDX SBOM (vuln-only metadata) |
template | Custom Go template |
| (default) | Table format human-readable |
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, --ignore-unfixed excludes vulnerabilities without an
available fix - the practical first-line filter for actionable findings:
trivy image --ignore-unfixed python:3.4-alpine
Combine with a severity threshold for the recommended PR-blocking config (fail
only on actionable, high-severity vulns):
trivy image --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 my-image:1.0
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
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
trivy-config
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:
| Mechanism | Use |
|---|
.trivyignore file | Per-CVE / per-misconfig-rule ID list |
--ignore-unfixed flag | Filter to actionable findings only |
--vex (VEX file) | Standardized status assertions (CycloneDX-VEX or OpenVEX) |
--ignore-policy Rego policy | Programmatic ignore via OPA Rego |
.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
Wrap the CLI with the aquasecurity/trivy-action GHA to scan the built image
and upload SARIF to GitHub Code Scanning. The full GitHub Actions workflow is
in references/ci-and-composition.md.
Step 10 - Composition with sister tools
Trivy is the all-in-one first line; compose it with syft-generation for a
standalone SBOM plus the Grype scan for cross-DB consensus on findings, and
checkov-policy for deeper IaC scanning. The full composition table is in
references/ci-and-composition.md.
Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|
Skip --ignore-unfixed | Stuck findings (no fix available) flood report | Always for PR gating (Step 5) |
.trivyignore without justification comment | No audit trail | Mandatory template (Step 8) |
| Run all scanners on every PR | Slow; misconfig + license noise on small changes | Default vuln+secret on PR; full scan nightly |
| Skip severity filter | LOW noise drowns CRITICAL signal | --severity CRITICAL,HIGH for PR (Step 3) |
Pin to aquasec/trivy:latest Docker tag | Breaking changes mid-release | Pin specific version |
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 (
syft-generation Step 7) 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)
- references/ci-and-composition.md - full CI workflow + sister-tool composition
syft-generation,
sbom-formats - sister tools