trivy-config

Overview

Trivy is Aqua Security's consolidated misconfiguration scanner (trivy config) and the forward path from tfsec. Per the tfsec legacy reference, trivy.dev misconfiguration docs, 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.

Component	Pin	Used in
Trivy	v0.72.0 (latest as of 2026-06-30)	Step 1 install
aquasecurity/trivy-action	0.31.0	CI workflow (Step 7)
actions/checkout	v5	CI workflow (Step 7)
github/codeql-action/upload-sarif	v3	CI workflow (Step 7)

Step 1 - Install

Per trivy.dev installation docs:

# macOS
brew install trivy

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

Debian / Ubuntu and RHEL / Fedora hosts can also install Trivy from the project's apt repository or a release .rpm package (pin the tag from the Pinned versions section above), per inst. Both add a system package source and need root, so bake them into the runner image or config management rather than running them from a scan session. In CI, use the pinned aquasecurity/trivy-action from Step 7 instead.

Verify: trivy --version.

Step 2 - First scan

Per cli reference, 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.

# 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). 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, --exit-code and --severity are the two levers for CI gating:

Flag	Purpose	Example
--exit-code int	Exit code when findings match	--exit-code 1
--severity strings	Comma-separated severity filter	HIGH,CRITICAL

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, --format accepts:

Value	Use case
table (default)	Human-readable terminal output
json	Machine-parseable; pipe to jq
sarif	GitHub Code Scanning / SARIF 2.1.0
template	Custom templates (JUnit, ASFF, HTML via contrib/)

# 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:

.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, 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, --ignorefile defaults to .trivyignore and accepts an alternate path.

Rego-based ignore policy

Per filter docs, 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, pass custom policies with --config-check and scope them with --namespaces:

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

Per custom docs, 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, 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:

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

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

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

Anti-patterns

Anti-pattern	Why it fails	Fix
--exit-code 0 in CI	Misconfigs are logged but never block	Use --exit-code 1 with --severity HIGH,CRITICAL (Step 3)
.trivyignore entries without a statement	Invisible to reviewers; silent security debt	Use .trivyignore.yaml with statement + expired_at (Step 5)
Running trivy config and tfsec in parallel without a unifier	Duplicate findings flood CI output	Route both through a single unifying reporter
Custom policies missing METADATA block	No severity, no title in report output	Always include METADATA with id, severity, schemas (Step 6)
Skipping bundle updates (--skip-check-update) permanently	Stale checks miss new misconfig rules	Use for caching in CI; re-enable updates on a scheduled run

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.
• Helm rendering requires chart values. Pass --helm-values for accurate rendering of templated manifests per cli reference.
• 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.

References

• mc - Trivy misconfiguration scanner overview, supported IaC types, auto-detection behavior, air-gap fallback, network requirements.
• inst - Official install methods: Homebrew, the apt repository, direct .rpm release package, container image.
• cli - 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 - Custom Rego policy authoring: METADATA fields (title, description, schemas, custom.id, custom.severity, custom.input.selector.type), deny rule pattern, --namespaces scoping.
• filter - .trivyignore and .trivyignore.yaml suppression format (id, paths, statement, expired_at), --ignore-policy Rego-based filtering.
• report - Output formats: table, json, sarif, template; --output flag; SARIF 2.1.0 compliance.
• checks - aquasecurity/trivy-checks - the upstream OPA bundle for all built-in checks.
• tfsec legacy reference - Migration context: tfsec is transitioning to Trivy; this skill is the forward path. tfsec custom rules + CI live in references/tfsec-custom-rules-and-ci.md.
• checkov-policy - Sister scanner; broader Python-check framework, different rule coverage.