docs(misconf): Document inline ignore limitations for missing resources in IaC files

[simar7]

Discussed in #9455

^{Originally posted by thomasleplus September 9, 2025}

Description

Hi,

I use two inline ignores in the following Dockerfile:

...
# trivy:ignore:AVD-DS-0001
# trivy:ignore:AVD-DS-0002
FROM kalilinux/kali-rolling:latest
...

When I run trivy 0.66.0 on Mac, I still get a finding for AVD-DS-0002. Note that this does not happen if I put an explicit USER root statement at the end of my Dockerfile and move the # trivy:ignore:AVD-DS-0002 comment there but I'd rather not do that workaround.

Thanks!

Desired Behavior

Ignore both AVD-DS-0001 and AVD-DS-0002.

Actual Behavior

AVD-DS-0001 is successfully ignored but not AVD-DS-0002.

Reproduction Steps

1. Clone the repo https://github.com/leplusorg/docker-kali or download https://github.com/leplusorg/docker-kali/raw/refs/heads/main/kali/Dockerfile

2. Run trivy 0.66.0 like this:


$ trivy filesystem --scanners misconfig kali/Dockerfile 
2025-09-09T11:37:59+02:00	INFO	[misconfig] Misconfiguration scanning is enabled
2025-09-09T11:37:59+02:00	INFO	Detected config files	num=1

Report Summary

┌────────────┬────────────┬───────────────────┐
│   Target   │    Type    │ Misconfigurations │
├────────────┼────────────┼───────────────────┤
│ Dockerfile │ dockerfile │         1         │
└────────────┴────────────┴───────────────────┘
Legend:
- '-': Not scanned
- '0': Clean (no security findings detected)

Dockerfile (dockerfile)

Tests: 26 (SUCCESSES: 25, FAILURES: 1)
Failures: 1 (UNKNOWN: 0, LOW: 0, MEDIUM: 0, HIGH: 1, CRITICAL: 0)

AVD-DS-0002 (HIGH): Specify at least 1 USER command in Dockerfile with non-root user as argument
══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════
Running containers with 'root' user can lead to a container escape situation. It is a best practice to run containers as non-root users, which can be done by adding a 'USER' statement to the Dockerfile.

See https://avd.aquasec.com/misconfig/ds002
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

### Target

Filesystem

### Scanner

Misconfiguration

### Output Format

Table

### Mode

Standalone

### Debug Output

```bash
$ trivy filesystem --scanners misconfig --debug kali/Dockerfile 
2025-09-09T11:43:30+02:00	DEBUG	No plugins loaded
2025-09-09T11:43:30+02:00	DEBUG	Default config file "file_path=trivy.yaml" not found, using built in values
2025-09-09T11:43:30+02:00	DEBUG	Cache dir	dir="/Users/thomas/Library/Caches/trivy"
2025-09-09T11:43:30+02:00	DEBUG	Cache dir	dir="/Users/thomas/Library/Caches/trivy"
2025-09-09T11:43:30+02:00	DEBUG	Parsed severities	severities=[UNKNOWN LOW MEDIUM HIGH CRITICAL]
2025-09-09T11:43:30+02:00	DEBUG	Ignore statuses	statuses=[]
2025-09-09T11:43:30+02:00	INFO	[misconfig] Misconfiguration scanning is enabled
2025-09-09T11:43:30+02:00	DEBUG	[notification] Running version check
2025-09-09T11:43:30+02:00	DEBUG	[misconfig] Checks successfully loaded from disk
2025-09-09T11:43:30+02:00	DEBUG	[notification] Version check completed	latest_version="0.66.0"
2025-09-09T11:43:30+02:00	DEBUG	[rego] Overriding filesystem for checks
2025-09-09T11:43:30+02:00	DEBUG	[rego] Embedded libraries are loaded	count=17
2025-09-09T11:43:30+02:00	DEBUG	[rego] Embedded checks are loaded	count=519
2025-09-09T11:43:30+02:00	DEBUG	[rego] Checks from disk are loaded	count=536
2025-09-09T11:43:30+02:00	DEBUG	[rego] Overriding filesystem for data
2025-09-09T11:43:30+02:00	DEBUG	Enabling misconfiguration scanners	scanners=[azure-arm cloudformation dockerfile helm kubernetes terraform terraformplan-json terraformplan-snapshot]
2025-09-09T11:43:30+02:00	DEBUG	Initializing scan cache...	type="memory"
2025-09-09T11:43:30+02:00	DEBUG	[fs] Analyzing...	root="kali/Dockerfile"
2025-09-09T11:43:30+02:00	DEBUG	[fs] Random cache key will be used	err="failed to open git repository: stat /Users/thomas/code/docker-kali/kali/Dockerfile/.git: not a directory"
2025-09-09T11:43:30+02:00	DEBUG	Created process-specific temp directory	path="/var/folders/ck/2xvbk39d4zn86q23g4p7phd40000gn/T/trivy-99307"
2025-09-09T11:43:30+02:00	DEBUG	[misconfig] Scanning files for misconfigurations...	scanner="Dockerfile"
2025-09-09T11:43:30+02:00	DEBUG	[dockerfile scanner] Scanning files...	count=1
2025-09-09T11:43:30+02:00	DEBUG	[rego] Scanning inputs	count=1
2025-09-09T11:43:30+02:00	DEBUG	OS is not detected.
2025-09-09T11:43:30+02:00	INFO	Detected config files	num=1
2025-09-09T11:43:30+02:00	DEBUG	Scanned config file	file_path="Dockerfile"
2025-09-09T11:43:30+02:00	DEBUG	Specified ignore file does not exist	file=".trivyignore"
2025-09-09T11:43:30+02:00	DEBUG	[vex] VEX filtering is disabled

Report Summary

┌────────────┬────────────┬───────────────────┐
│   Target   │    Type    │ Misconfigurations │
├────────────┼────────────┼───────────────────┤
│ Dockerfile │ dockerfile │         1         │
└────────────┴────────────┴───────────────────┘
Legend:
- '-': Not scanned
- '0': Clean (no security findings detected)


Dockerfile (dockerfile)

Tests: 26 (SUCCESSES: 25, FAILURES: 1)
Failures: 1 (UNKNOWN: 0, LOW: 0, MEDIUM: 0, HIGH: 1, CRITICAL: 0)

AVD-DS-0002 (HIGH): Specify at least 1 USER command in Dockerfile with non-root user as argument
══════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════════
Running containers with 'root' user can lead to a container escape situation. It is a best practice to run containers as non-root users, which can be done by adding a 'USER' statement to the Dockerfile.

See https://avd.aquasec.com/misconfig/ds002
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────


2025-09-09T11:43:30+02:00	DEBUG	Cleaning up temp directory	path="/var/folders/ck/2xvbk39d4zn86q23g4p7phd40000gn/T/trivy-99307"

Operating System

macOS Sequoia 15.6.1

Version

$ trivy --version
Version: 0.66.0
Vulnerability DB:
  Version: 2
  UpdatedAt: 2025-09-09 06:29:47.446032105 +0000 UTC
  NextUpdate: 2025-09-10 06:29:47.446031854 +0000 UTC
  DownloadedAt: 2025-09-09 09:27:57.633275 +0000 UTC
Check Bundle:
  Digest: sha256:a471e90b7c7335e914ec9075b74cf8f65e4c91e6cecfa7e39c587382808d2684
  DownloadedAt: 2025-09-09 09:29:21.221658 +0000 UTC

Checklist

• Run trivy clean --all
• Read the troubleshooting

[thomasleplus]

Let me share a link to a specific revision that triggers the issue because I created a PR not to use a non-root user anymore so in the future the issue might not be reproducible with the latest revision.

[nikpivkin]

@simar7 Ignoring via inline comments works only for rules that are attached to a specific resource, whose misconfigurations need to be skipped. For example, the check AVD-DS-0002 triggers if a Dockerfile does not contain a USER instruction. Since there is no resource to attach a #trivy:ignore comment to, inline ignoring cannot be applied.

For such checks, ignore files (.trivyignore.yaml) can be used, allowing you to explicitly specify rules, files, and reasons for ignoring:

misconfigurations:
  - id: AVD-DS-0002
    paths:
      - "Dockerfile"
    statement: The image needs root privileges

Proposed idea for a new feature: We can add support for globally ignoring specific or all checks in the file using a special comment at the beginning of the file. For example:

#trivy:ignore-all:rules:AVD-DS-0002,AVD-DS-0026:exp:2024-12-31
---
#trivy:ignore-all:rules:*:exp:2024-12-31

Drawbacks of global ignoring:

• Loss of granularity: it’s impossible to know which specific resource or check is being ignored.
• Risk of missing real issues, especially in production code.
• Recommended for temporary ignoring or test files only, with an expiration date (exp).

[thomasleplus]

Understood. I like the proposed ignore-all solution. Or maybe it could be implicit: if a rule that is not attached to a resource is ignored at the top of the file then it should be ignored for the whole file?

IMHO I don't like to use a separate file to ignore specific issues because I feel like they tend to rot. Without context, it's easy to forget why an entry is in the ignore file or to forget to update it when things change. Inline comments keep the context and have a better chance of being updated/deleted when the code next to them changes.

[simar7]

Proposed idea for a new feature: We can add support for globally ignoring specific or all checks in the file using a special comment at the beginning of the file.

I think the drawbacks you mentioned are quite significant. Especially the second point where if such a blanket ignore is present, issues will continue to be ignored for the entirety of the file. You could limit it with an expiration timestamp but it would be very easy to miss real issues like you mentioned in production code. IMO blanket ignores are better suited for places like .trivyignore as they are today so at least the user is able to track them fairly easily overtime.

IMHO I don't like to use a separate file to ignore specific issues because I feel like they tend to rot. Without context, it's easy to forget why an entry is in the ignore file or to forget to update it when things change. Inline comments keep the context and have a better chance of being updated/deleted when the code next to them changes.

It could be argued that having a central place to hold such ignores is better as there's only one place to update all such ignores.

@simar7 Ignoring via inline comments works only for rules that are attached to a specific resource, whose misconfigurations need to be skipped. For example, the check AVD-DS-0002 triggers if a Dockerfile does not contain a USER instruction. Since there is no resource to attach a #trivy:ignore comment to, inline ignoring cannot be applied.

I missed this distinction. We should close this bug (or convert this into a docs issue) in this case as it's not a technical issue per-se. We can however document this a bit better as it's something that's not quite obvious to the average user. WDYT @nikpivkin?

[nikpivkin]

@simar7 I will update the section in the documentation with inline ignoring.

[thomasleplus]

I agree that inline vs separate file can be argued both ways. But i also think that not giving users a choice for some rules is rather limiting.

Also I don't quite understand the concern about ignoring all the occurrences in the file. We are talking specifically about issues that are not related to a specific resource so I don't think that there can be more than one occurrence per file anyway. Or am I missing something?

I also use Hadolint and Checkov and both accept an ignore comment at the top of the file for this finding FYI.

Cheers,

Tom

[nikpivkin]

@simar7 As an alternative, we could provide a module that extends Trivy's ignore functionality. I’ve drafted a minimal version here: trivy-ignore-ext-module.
As a bonus, this helped uncover some minor issues in the current module system.