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][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][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][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][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][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.

Step 7 - Misconfiguration scanning

Per [tv-img][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][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][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

When to use

Step 1 - Install

Step 2 - Basic image scan

Step 3 - Severity filtering

Step 4 - Output formats

Step 5 - --ignore-unfixed for actionable filter

Step 6 - Secret scanning

Step 7 - Misconfiguration scanning

Step 8 - False-positive triage (MANDATORY)

Step 9 - CI integration

Step 10 - Composition with sister tools

Anti-patterns

Limitations

References

Step 5 - `--ignore-unfixed` for actionable filter

trivy-image

trivy-image

Overview