trivy-config

Overview

Trivy is Aqua Security's consolidated misconfiguration scanner (trivy config) and the forward path from tfsec. Per the tfsec skill, trivy.dev misconfiguration docs (opens in new window), and Aqua's own documentation, new projects should evaluate Trivy first; tfsec's checks ship inside Trivy under trivy config.

Pinned versions

Bump these together when updating; they are the only version-sensitive tokens in this skill. GitHub release assets are version-stamped, so the RPM URL in Step 1 pins a tag rather than using latest/download.

Step 1 - Install

Per trivy.dev installation docs (opens in new window) (the RPM URL pins the Trivy tag from the Pinned versions section above):

# macOS
brew install trivy

# Debian / Ubuntu
sudo apt-get install wget apt-transport-https gnupg
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key \
  | gpg --dearmor | sudo tee /usr/share/keyrings/trivy.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] \
  https://aquasecurity.github.io/trivy-repo/deb generic main" \
  | sudo tee /etc/apt/sources.list.d/trivy.list
sudo apt-get update && sudo apt-get install trivy

# RPM (RHEL / Fedora)
sudo rpm -ivh https://github.com/aquasecurity/trivy/releases/download/v0.72.0/trivy_0.72.0_Linux-64bit.rpm

# Docker (no local install)
docker run --rm -v $(pwd):/workspace aquasec/trivy config /workspace

Verify: trivy --version.

Step 2 - First scan

Per cli reference (opens in new window), trivy config accepts a path (file or directory). Trivy auto-detects IaC types - Terraform, CloudFormation, Kubernetes manifests, Helm charts, Dockerfiles, and Azure ARM templates can all coexist in the same directory per mc docs (opens in new window).

# Scan the current directory (all IaC types)
trivy config .

# Scan a specific subdirectory
trivy config ./infra/

# Show only HIGH and CRITICAL findings
trivy config --severity HIGH,CRITICAL .

# Fail CI when any finding is found (exit code 1)
trivy config --exit-code 1 --severity HIGH,CRITICAL .

# Include passed checks alongside failures
trivy config --include-non-failures .

Built-in checks are distributed as an OPA bundle at ghcr.io/aquasecurity/trivy-checks (per checks repo (opens in new window)). Trivy caches the bundle locally and refreshes every 24 hours. An embedded fallback is included in the binary for air-gapped environments.

Step 3 - Severity gating

Per cli reference (opens in new window), --exit-code and --severity are the two levers for CI gating:

Pattern: gate hard on CRITICAL first; expand to HIGH after the team has reviewed the initial finding set.

# Hard fail on CRITICAL only (bootstrap phase)
trivy config --exit-code 1 --severity CRITICAL .

# Ratchet: add HIGH once existing findings are triaged
trivy config --exit-code 1 --severity HIGH,CRITICAL .

Step 4 - Output formats

Per trivy.dev reporting docs (opens in new window), --format accepts:

# JSON for parsing / badge generation
trivy config --format json --output trivy.json .

# SARIF for GitHub Code Scanning
trivy config --format sarif --output trivy.sarif .

# JUnit XML for CI test reporting
trivy config --format template \
  --template "@contrib/junit.tpl" \
  --output trivy-junit.xml .

Step 5 - Suppressing findings

Per trivy.dev filtering docs (opens in new window):

.trivyignore (check-ID list)

# .trivyignore
# Suppress a specific misconfig check
AVD-DS-0002

# Suppress a CVE alongside a misconfig in the same file
CVE-2018-14618

.trivyignore.yaml (structured suppression)

Per filter docs (opens in new window), the YAML variant supports scoped expiring suppressions:

# .trivyignore.yaml
misconfigurations:
  - id: AVD-DS-0001
  - id: AVD-DS-0002
    paths:
      - "infra/legacy/Dockerfile"
    statement: "Legacy image; migration tracked in JIRA-4321"
    expired_at: "2026-12-31"

Run with: trivy config --ignorefile ./.trivyignore.yaml .

Per cli reference (opens in new window), --ignorefile defaults to .trivyignore and accepts an alternate path.

Rego-based ignore policy

Per filter docs (opens in new window), pass --ignore-policy with a Rego file that contains a trivy package and an ignore rule:

# ignore_legacy.rego
package trivy

default ignore = false

ignore {
    input.Type == "terraform"
    input.Namespace == "user.legacy"
}

trivy config --ignore-policy ignore_legacy.rego .

Step 6 - Custom Rego policies

Per trivy.dev custom checks docs (opens in new window), pass custom policies with --config-check and scope them with --namespaces:

trivy config \
  --config-check ./policies/ \
  --namespaces user \
  ./infra/

Per custom docs (opens in new window), the --namespaces value (here: user) must match the first segment of the package path. For a full policy file (METADATA block + deny rule) and the list of supported input.selector types, see references/trivy-config.md.

Step 7 - CI integration (GitHub Actions)

Per trivy.dev reporting docs (opens in new window), SARIF output integrates directly with GitHub Code Scanning. For the full GitHub Actions workflow (with security-events: write, the pinned trivy-action, and an if: always() SARIF upload so findings surface even when the scan exits non-zero), see references/trivy-config.md.

To scope the scan to a single IaC type, pass --misconfig-scanners per cli reference (opens in new window):

# Terraform only
trivy config \
  --misconfig-scanners terraform \
  ./terraform/

# Kubernetes manifests only
trivy config \
  --misconfig-scanners kubernetes \
  ./k8s/

Per cli reference (opens in new window), --misconfig-scanners accepts a comma-separated list from: azure-arm, cloudformation, dockerfile, helm, kubernetes, terraform, terraformplan-json, terraformplan-snapshot.

Anti-patterns

Limitations

• Network required on first run. Trivy downloads the checks bundle from ghcr.io/aquasecurity/trivy-checks. Air-gapped setups need the embedded binary fallback or a mirror.
• Terraform variable resolution is partial. Dynamic values computed at apply time may cause false positives; pass --tf-vars to reduce noise per cli reference (opens in new window).
• Helm rendering requires chart values. Pass --helm-values for accurate rendering of templated manifests per cli reference (opens in new window).
• Custom policy schemas must match input type. A policy with schema["cloud"] will not fire against Kubernetes manifests; use the correct selector type per custom docs (opens in new window).

References

• mc (opens in new window) - Trivy misconfiguration scanner overview, supported IaC types, auto-detection behavior, air-gap fallback, network requirements.
• inst (opens in new window) - Official install methods: Homebrew, the apt repository, direct .rpm release package, container image.
• cli (opens in new window) - trivy config CLI reference: --exit-code, --severity, --format, --output, --ignorefile, --config-check, --namespaces, --misconfig-scanners, --tf-vars, --helm-values, --cf-params, --include-non-failures.
• custom (opens in new window) - Custom Rego policy authoring: METADATA fields (title, description, schemas, custom.id, custom.severity, custom.input.selector.type), deny rule pattern, --namespaces scoping.
• filter (opens in new window) - .trivyignore and .trivyignore.yaml suppression format (id, paths, statement, expired_at), --ignore-policy Rego-based filtering.
• report (opens in new window) - Output formats: table, json, sarif, template; --output flag; SARIF 2.1.0 compliance.
• checks (opens in new window) - aquasecurity/trivy-checks - the upstream OPA bundle for all built-in checks.
• tfsec-policy - Migration context: tfsec is transitioning to Trivy; this skill is the forward path.
• checkov-policy - Sister scanner; broader Python-check framework, different rule coverage.