trivy

What it does

Trivy (Aqua Security, open source) finds vulnerabilities in OS packages and app dependencies, misconfigurations in Dockerfiles, Kubernetes YAML, Terraform, Helm and CloudFormation, secrets in code, and licenses. It can make an SBOM (CycloneDX, SPDX) and scan one. It downloads its vulnerability database on the first run.

In CI it is the usual "security gate": --exit-code 1 --severity HIGH,CRITICAL fails the build when serious problems are found.

How to write it

trivy TARGET [OPTIONS] ARG
trivy image|fs|repo|config|k8s|sbom|vm ...

Main parts

Targets

image IMG: Scan a container image.
fs DIR: Scan a project folder (dependencies, secrets, IaC).
config DIR: Only misconfigurations in IaC files.
repo URL: Scan a remote Git repository.
k8s --report summary: Scan a running cluster.
sbom FILE: Scan an SBOM.
vm: Scan a VM image or disk.
clean --all: Remove cached databases.

Options 10

Most used

Common flags

--severity CRITICAL, HIGH: Only these levels.
--exit-code 1: Fail when something is found (CI gate).
--ignore-unfixed: Hide CVEs without a fix yet.
--scanners vuln, misconfig, secret, license: Which checks.
-f table|json|sarif|cyclonedx|spdx-json|template: Output format.
-o FILE: Output file.
--ignorefile .trivyignore: Accepted findings (with reasons).
--skip-dirs DIR / --skip-files FILE: Skip paths.
--db-repository / --skip-db-update: Offline or mirror use.
--timeout 10m: Longer timeout for big images.

Examples 10

$ run as a normal user# run as root (or with sudo)

1Scan an image

$trivy image nginx:1.27
$trivy image --severity HIGH,CRITICAL --ignore-unfixed ghcr.io/s0sta/shop:1.4.0

2Fail the CI build on serious CVEs

$trivy image --exit-code 1 --severity CRITICAL --ignore-unfixed ghcr.io/s0sta/shop:1.4.0
$echo $?
1

3Scan the project folder (dependencies + secrets)
```
$trivy fs --scanners vuln,secret .
```

4Check Terraform, Dockerfiles and Kubernetes YAML

$trivy config .
$trivy config --severity HIGH,CRITICAL infra/

5Make an SBOM and scan it later

$trivy image -f cyclonedx -o shop-1.4.0.cdx.json ghcr.io/s0sta/shop:1.4.0
$trivy sbom shop-1.4.0.cdx.json

6Upload results to GitHub code scanning

$trivy fs -f sarif -o trivy.sarif .
$cat .github/workflows/scan.yml
      - uses: aquasecurity/trivy-action@0.28.0
        with: { scan-type: fs, format: sarif, output: trivy.sarif, severity: "CRITICAL,HIGH" }
      - uses: github/codeql-action/upload-sarif@v3
        with: { sarif_file: trivy.sarif }

7Accept a finding with a reason
```
$cat .trivyignore
CVE-2024-12345 exp:2027-01-31
```
Write the reason in the PR or next to the ID; exp: makes the ignore end on that date.

8Scan the running cluster

$trivy k8s --report summary
$trivy k8s --include-namespaces shop --report all

9Scan a remote repository

$trivy repo https://github.com/s0sta/platform

10JSON for scripts

$trivy image -f json -q nginx:1.27 | jq '[.Results[].Vulnerabilities[]? | select(.Severity=="CRITICAL")] | length'

Watch out

"0 vulnerabilities" can mean an unknown distro or an old database — check the header lines.
Every ignore needs a reason and a review date.
Scanning is not fixing: rebuild images often to get patched base layers.

Files

~/.cache/trivy/: Vulnerability database and cache.
.trivyignore: Accepted findings.
trivy.yaml: Default options for a project.

Tips to remember

Scan in three places: the PR (fs + config), the build (image), and the registry/cluster (scheduled), because new CVEs appear every day.

Exit codes

`0`	No findings (or no --exit-code).
`1`	Findings with --exit-code 1 (or an error).

`trivy`

What it does

How to write it

Main parts

Targets

Options 10

Common flags

Examples 10

1Scan an image

2Fail the CI build on serious CVEs

3Scan the project folder (dependencies + secrets)

4Check Terraform, Dockerfiles and Kubernetes YAML

5Make an SBOM and scan it later

6Upload results to GitHub code scanning

7Accept a finding with a reason

8Scan the running cluster

9Scan a remote repository

10JSON for scripts

Watch out

Files

Tips to remember

Exit codes

Full manual

What it does

How to write it

Main parts

Targets

Options 10

Common flags

Examples 10

1Scan an image

2Fail the CI build on serious CVEs

3Scan the project folder (dependencies + secrets)

4Check Terraform, Dockerfiles and Kubernetes YAML

5Make an SBOM and scan it later

6Upload results to GitHub code scanning

7Accept a finding with a reason

8Scan the running cluster

9Scan a remote repository

10JSON for scripts

Watch out

Files

Tips to remember

Exit codes

Related commands

Used in these lessons

Full manual

`trivy`