git:20260724.d4db756 to git:20260728.1bce424

---

name: trivy-config

description: "Runs Trivy's misconfiguration scanner (`trivy config`) against IaC directories to detect security issues across Terraform, CloudFormation, Kubernetes manifests, Helm charts, Dockerfiles, and Azure ARM templates - installs Trivy, scans with severity gating via `--exit-code`, suppresses findings via `.trivyignore` / `.trivyignore.yaml` or inline annotations, extends built-in checks with custom Rego policies, and emits SARIF for GitHub Code Scanning. Trivy is the forward path from tfsec (per Aqua Security's own migration guidance). Use when adopting a consolidated IaC scanner for new projects, migrating away from tfsec, or scanning mixed IaC stacks with a single tool."

metadata:

keywords: "trivy, iac, misconfiguration, terraform, kubernetes, dockerfile, helm, cloudformation, rego, sarif, security"

---

# trivy-config

## Overview

[mc]: https://trivy.dev/latest/docs/scanner/misconfiguration/

[inst]: https://trivy.dev/docs/latest/getting-started/installation/

[cli]: https://trivy.dev/latest/docs/references/configuration/cli/trivy_config/

[custom]: https://trivy.dev/latest/docs/scanner/misconfiguration/custom/

[filter]: https://trivy.dev/latest/docs/configuration/filtering/

[report]: https://trivy.dev/latest/docs/configuration/reporting/

[checks]: https://github.com/aquasecurity/trivy-checks

[tfsec]: ../tfsec-policy/SKILL.md

projects should evaluate Trivy first; tfsec's checks ship inside Trivy

under `trivy config`.

## Step 1 - Install

```bash

# 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][cli], `trivy config` accepts a path (file or

directory). Trivy auto-detects IaC types - Terraform, CloudFormation,

Kubernetes manifests, Helm charts, Dockerfiles, and Azure ARM templates

```bash

# 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][checks]).

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][cli], `--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.

```bash

# 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][report], `--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/`) |

```bash

# 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][filter]:

### .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][filter], the YAML variant supports scoped expiring

suppressions:

```yaml

# .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][cli], `--ignorefile` defaults to `.trivyignore` and

accepts an alternate path.

### Rego-based ignore policy

Per [filter docs][filter], pass `--ignore-policy` with a Rego file that

contains a `trivy` package and an `ignore` rule:

```rego

# ignore_legacy.rego

package trivy

default ignore = false

ignore {

input.Type == "terraform"

input.Namespace == "user.legacy"

}

```

```bash

trivy config --ignore-policy ignore_legacy.rego .

```

## Step 6 - Custom Rego policies

Per [trivy.dev custom checks docs][custom], pass custom policies with

`--config-check` and scope them with `--namespaces`:

```bash

trivy config \

--config-check ./policies/ \

--namespaces user \

./infra/

```

Per [custom docs][custom], the `--namespaces` value (here: `user`) must

## Step 7 - CI integration (GitHub Actions)

Per [trivy.dev reporting docs][report], SARIF output integrates directly

To scope the scan to a single IaC type, pass `--misconfig-scanners` per

[cli reference][cli]:

```bash

# Terraform only

trivy config \

--misconfig-scanners terraform \

./terraform/

# Kubernetes manifests only

trivy config \

--misconfig-scanners kubernetes \

./k8s/

```

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

- **Helm rendering requires chart values.** Pass `--helm-values` for

accurate rendering of templated manifests per [cli reference][cli].

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

## References

- [mc][mc] - Trivy misconfiguration scanner overview, supported IaC

types, auto-detection behavior, air-gap fallback, network requirements.

- [inst][inst] - Official install methods: Homebrew, the apt repository,

direct `.rpm` release package, container image.

- [cli][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] - Custom Rego policy authoring: METADATA fields

(`title`, `description`, `schemas`, `custom.id`, `custom.severity`,

`custom.input.selector.type`), `deny` rule pattern, `--namespaces`

scoping.

- [filter][filter] - `.trivyignore` and `.trivyignore.yaml` suppression

format (`id`, `paths`, `statement`, `expired_at`), `--ignore-policy`

Rego-based filtering.

- [report][report] - Output formats: `table`, `json`, `sarif`,

`template`; `--output` flag; SARIF 2.1.0 compliance.

- [checks][checks] - `aquasecurity/trivy-checks` - the upstream

OPA bundle for all built-in checks.

- [`tfsec-policy`][tfsec] - Migration context: tfsec is transitioning

to Trivy; this skill is the forward path.

- `checkov-policy` - Sister scanner;

broader Python-check framework, different rule coverage.