aquasecurity/trivy

Misconfiguration scanning

Active contributors: nikpivkin, Owen Rumney, knqyf263

Purpose

Misconfiguration scanning detects insecure or non-compliant settings in Infrastructure-as-Code files (Terraform, CloudFormation, Kubernetes, Helm, Dockerfile, Ansible, Azure ARM) and image configuration. It is a Rego-driven engine: the structural parsers under pkg/iac/scanners/<format>/ produce a normalized model, and the rule engine under pkg/iac/rego/ evaluates Trivy Checks policies against it.

Each finding gets an AVD- identifier (Aqua Vulnerability Database) plus severity, description, and remediation guidance.

End-to-end flow

graph LR
    Walker[fanal walker] --> ConfigA[Config-file analyzers<br/>pkg/fanal/analyzer/config/]
    ConfigA -->|Misconfiguration<br/>blob field| Cache[(cache)]
    Cache --> Applier
    Applier --> Detail[ArtifactDetail]
    Detail --> Result[Result.Misconfigurations]
    subgraph "fanal config analyzer"
        ConfigA --> Misconf[pkg/misconf]
    end
    Misconf --> Parser[pkg/iac/scanners/&lt;format&gt;/parser]
    Parser --> Adapter[pkg/iac/adapters/&lt;cloud&gt;]
    Adapter --> Rego[pkg/iac/rego]
    Rego --> Policies[Trivy Checks bundle<br/>pkg/policy]
    Rego --> Findings[Misconfiguration]
    Findings --> ConfigA

The parsers feed cloud-shaped resource models (e.g., aws.s3.Bucket, azure.storage.Account) defined under pkg/iac/providers/. Rego policies are written against those models, not raw HCL/JSON, which keeps rules portable.

Where the rules come from

The Rego rule bundle is a separate OCI artifact downloaded by pkg/policy/policy.go (defaults to ghcr.io/aquasecurity/trivy-checks:1). The rules themselves live in the trivy-checks repo. Trivy embeds a fallback bundle at build time so that air-gapped scans still have a baseline.

Custom rules can be supplied with --config-policy <dir> (a directory of .rego files plus optional metadata).

Configuration

Flag	Purpose
`--scanners misconfig`	Enable misconfiguration scanning.
`--config-policy`	Custom Rego policies.
`--config-data`	Extra data passed to Rego (`data.foo`).
`--config-trace`	Print Rego traces (debugging).
`--include-deprecated-checks`	Include rules marked deprecated.
`--policy-namespaces`	Override the default `builtin` and `user` namespaces.
`--check-bundle-repository`	Override the OCI image.
`--skip-policy-update`	Don't refresh the bundle.
`--misconfig-scanners`	Restrict to `dockerfile`, `helm`, `kubernetes`, `terraform`, `terraformplan-json`, `cloudformation`, `ansible`, `azure-arm`.

The bundle is refreshed at most once per --policy-bundle-refresh-interval.

Supported formats

Format	Scanner	Notes
Terraform (HCL)	`pkg/iac/scanners/terraform/`	Largest scanner; full-fidelity HCL parser.
Terraform plan (JSON)	`pkg/iac/scanners/terraformplan/`	Reads `terraform plan -json` output.
Terraform plan (snapshot)	`pkg/iac/scanners/terraformplan/`	Reads `.tfplan` snapshots.
CloudFormation	`pkg/iac/scanners/cloudformation/`	YAML and JSON.
Kubernetes	`pkg/iac/scanners/kubernetes/`	YAML manifests.
Helm	`pkg/iac/scanners/helm/`	Renders charts and scans the result.
Dockerfile	`pkg/iac/scanners/dockerfile/`	Layer-aware.
Ansible	`pkg/iac/scanners/ansible/`	Playbook parser.
Azure ARM	`pkg/iac/scanners/azure/`	JSON ARM templates and Bicep deployment artifacts.
YAML/JSON (generic)	`pkg/iac/scanners/generic/`	For arbitrary structured data.

Cloud providers covered

pkg/iac/providers/ defines normalized resource shapes per cloud:

AWS (~36 services — EC2, S3, IAM, RDS, EKS, ECR, etc.)
Azure (~16 service families)
Google Cloud (10 service families)
Oracle, OpenStack, Nifcloud, DigitalOcean, CloudStack, GitHub, Kubernetes, Dockerfile

This is what makes a single Rego rule like "S3 bucket public-read ACL" portable across Terraform, CloudFormation, and Pulumi: each parser maps to the same shape.

Output

Findings live in types.Result.Misconfigurations with fields like ID (AVD-AWS-0001), Title, Severity, Status (PASS, FAIL, EXCEPTION), CauseMetadata (file/line), and References. SARIF output is the most useful machine-readable format; the table writer is best for humans.

Integration points

fanal — config-file analyzers feed this engine.
Database — sibling system that distributes the policy bundle.
IaC scanning — deeper look at the IaC engine internals.
Cloud scanning — provider-specific resources.

Entry points for modification

Add a format — new scanner under pkg/iac/scanners/<format>/, parser, and adapter.
Add a cloud service — extend pkg/iac/providers/<cloud>/ with the resource shape, then add per-format adapters.
Add a rule — contribute to the trivy-checks repo (Rego rule + metadata YAML). The bundle is consumed unchanged by Trivy.
Tweak engine behavior — pkg/iac/rego/scanner.go and pkg/iac/rego/embed.go.

Key source files

File	Purpose
`pkg/misconf/scanner.go`	Glue between fanal and the IaC engine.
`pkg/iac/rego/scanner.go`	Rego evaluation.
`pkg/iac/scanners/terraform/`	Terraform parser.
`pkg/iac/scanners/cloudformation/`	CloudFormation parser.
`pkg/iac/scanners/kubernetes/`	Kubernetes parser.
`pkg/iac/scanners/helm/`	Helm parser/renderer.
`pkg/iac/scanners/dockerfile/`	Dockerfile parser.
`pkg/iac/scanners/ansible/`	Ansible parser.
`pkg/iac/providers/`	Cloud resource shapes.
`pkg/policy/policy.go`	Trivy Checks bundle download.
`pkg/types/misconfiguration.go`	`DetectedMisconfiguration` type.