Ignoring stuff

[itaysk]

There's a bit of confusion around how to ignore things, and what is supported (#3490, #3486, #3572)
I think the docs needs rewriting around that area. I had a chat with @knqyf263 and we realized this is more involved than just rewriting the doc. Here's how I currently see things. I'm sharing it here for feedback, and if there aren't objections we can create issues and follow this plan.

Terminology

The words we used around "policy", and "ignore" were ambiguous. I propose the following (for now just for this doc, in the future maybe more)

1. check: something that Trivy can detect. for example - misconfiguration issue
2. policy: some business logic to make a decision. NOT a rego check.
3. skip: tell trivy to not try to scan something
4. ignore: tell trivy to not report something that was detected

Skipping (inputs)

Skipping is supported on the following:

1. scanned files:
   1. --skip-files
   2. --skip-dir
2. checks :
   1. --policy. A rego file can contain conftest-inspired exception policy.
      1. Rename --policy to --checks
      3. TODO: Rename exceptions rule to skip
   2. --ignored-licensed

Ignoring (outputs)

Ignoring is supported on the following:

1. results:
   1. --ignorefile ~/.trivyignore: ignore by any ID
2. --ignore-policy: rego policy on results
3. --ignore-unfixed
4. //tfsec:ignore inline declaration. TODO: turn into //trivy:ignore Support Inline Filtering #2961

[AnaisUrlichs]

That makes sense to me. I just want to raise one thing that is confusing to me as a user

2. TODO: Alias as --checks as --skip-checks. If a user wants to just skip some built-in check, it's awkward they need to use the --checks flag for this.

So far, to me, the --policy flag refers to anything I define through rego -- whether that is to check something specific or to skip a check so I am not sure I follow the reasoning behind having to divide it into --checks and --skip-checks?

Also, --ignore-policy currently refers to Rego which tells the vulnerability check to ignore a vulnerability in the reported scan result, which is different to what we currently call exceptions. How does this translate, if there is a difference in scanning, would it be confusing for users if it is all names --skip-checks?

as a next step, we have to discuss the different sections in the docs that need to be updated or rewritten.

[itaysk]

not sure I follow the reasoning behind having to divide it into --checks and --skip-checks

The suggestion is not to divide them but to support both options. you are right that --checks points to a dir with both "checks to include" and "checks to skip", and I thought it might be confusing for someone who wants to just skip checks and has to use --checks for that, so I suggested to allow calling the flag with both names --checks and --skip-checks. BUT after reading your comment I realize it might be too much, we can leave --checks to be mean which checks to include or skip, depending on which files are given. I've edited my suggestion to reflect this.

would it be confusing for users if it is all names --skip-checks

not sure I understand the suggestion. to rename --ignore-policy to --skip-policy?

Regardless, you made me realize that I had a mistake in the first message, and the rego rule for ignoring results is called ignore not exception as I thought, so I removed the TODO to rename it as well.

[simar7]

Just wanted to add my 2c here. As far as ignoring particular policies are concerned, we could add support for more granular checks that could be potentially scoped per file, if need be.

So for example:

---
  AVD-DS-123
  - "path/to/dockerfile1"
  - "path/to/dockerfile2"
  CVE-2023-456
  - "someimage:latest"
  AVD-DS-789

In this case, both AVD-DS-123 and CVE-2023-456 are scoped to particular elements. Elements here can imply, docker files, image names, k8s primitives etc.

For this particular example it is the two Docker files and one image with a tag respectively. In these two cases, these two will only be ignored within the specified elements.

As for the AVD-DS-789 it is ignored on a global basis. Which is the existing behaviour today.

[AnaisUrlichs]

I like this option

[AnaisUrlichs]

How would I specify multiple IDs to be ignored in the same file
Would it be possible to write it the other way around:

---
"path/to/dockerfile1"
  -   AVD-DS-123
"someimage:latest"
 - CVE-2023-456
AVD-DS-789

just because I imagine that people would want to specify multiple vulnerabilities to be ignored in the same file vs the vulnerability to be ignored in multiple files?

[simar7]

How would I specify multiple IDs to be ignored in the same file

Something like this could work:

---
  AVD-DS-123
  - "path/to/dockerfile1"
  - "path/to/dockerfile2"
  AVD-DS-456
  - "path/to/dockerfile1"

just because I imagine that people would want to specify multiple vulnerabilities to be ignored in the same file vs the vulnerability to be ignored in multiple files?

Yes and no. If there is an "unfixable" vulnerability, it's more likely to be noise than signal, in which case you'd have the same vulnerability show up in different places. That I assume you'd like to silence/ignore with the above approach where keys are the vulnerability IDs.

But you can also argue if there are limited files (maybe 1 or 2) that are being scanned and lots of vulnerabilities amongst them, then the above approach will get unwieldy.

I think the former is more common than the latter. Usually there are more things to scan and less vulnerabilities to ignore.

[AnaisUrlichs]

Ok, that makes sense
Would we allow tho to ignore the ID in an entire directory?

[itaysk]

While reviewing #8960 (comment), I had a realization about "skipping" flags. It's semantic but important: that all skipping flags are just target specifiers. Skipping is just a way to further refine the target. And by that, perhaps skipping flags shouldn't be a global concept, but target-specific. consider the following:

1. trivy k8s --exclude-namespaces is skipping resources, but isn't treated as a skipping flag.
2. trivy k8s --skip-images was intentionally named using the word "skip" (I remember the discussion) but isn't documented as "skipping" flag, probably because it's k8s specific.
3. we got some questions/complaints about skip-files/skip-dirs not working as expected. It's hard to support them consistently in every target since technical implementation is target-specific.
4. --file-patterns was in the skipping doc, but it's not just skipping, it's also including, and customizing included fiules behavior (in other words it's not about skipping, it's about specifying the target).
5. our skipping docs shows skipping flags support by scanner, not by target.
6. and of course the example that made me think of this, which is about specifying what k8s resources to scan, but is also kind of skipping flag.

If I had to rethink this I would say we should remove the skipping flags category and make those flags just special target flags. They will be documented in the targets doc, they won't be supported universally, and their behavior might vary between targets.

[knqyf263]

In my view, Trivy's core targets are container images, Git repositories, file systems (+ VM images). These share common processing logic internally, which makes it easier to implement unified flags and options. On the other hand, Kubernetes is a unique feature that was added later, and I feel that incorporating Kubernetes into the design makes it more challenging to create consistent flags.

As I’ve suggested before, I think it makes sense to treat Kubernetes as a plugin, similar to AWS scanning. By separating Kubernetes, I believe it would become easier to structure the rest of the targets.

Regarding SBOM scanning, this is also a special target that has already been analyzed. Rather than documenting flags like --skip-files separately for container images, Git repositories, and file system targets, I think it would be better to indicate that SBOM scanning is the exception.

[knqyf263]

Also, regarding reporting, Kubernetes has a fundamentally different report format, so some of the output formats supported for other targets are not supported. In other words, not limited to the skipping flag, the flag system and features provided in K8s scanning differ from those of other core targets.

[itaysk]

we just removed --skip-files and --skip-dirs from docs and help

it was removed from help but not from docs. the docs classify the flags by scanner, not by target (as mentioned in my point #5):

[itaysk]

I feel that incorporating Kubernetes into the design makes it more challenging to create consistent flags

agree. that is my suggestion as well - to make all those flags target-pecific.

Trivy's core targets ... share common processing logic internally, which makes it easier to implement unified flags and options

ok, some follow up questions:

1. if those flags are global, they work in targets like k8s? what is the behavior then?
2. does the supportability matrix in docs need to add targets?
3. is it really as simple as supported or not. or there are slightly different behavior based on the target/scanner? (due to implementation differences).
4. do you consider --file-patterns also under this group?

better to indicate that SBOM scanning is the exception

also --image-config right?

[knqyf263]

Sorry, I missed it.

1. if those flags are global, they work in targets like k8s? what is the behavior then?

IMO, traversing and scanning on the file system is a core feature of Trivy. Therefore, targets such as container images and Git repositories fall under this category. On the other hand, Kubernetes scanning is positioned as a plugin and does not fall into this category, so flags like --skip-files and --skip-dirs, which apply to file system scanning, are unnecessary in this case.

2. does the supportability matrix in docs need to add targets?

After separating K8s scanning, wouldn’t it be sufficient to mention in the documentation that these flags apply only to the scanning commands?

Scanning Commands
  config      Scan config files for misconfigurations
  filesystem  Scan local filesystem
  image       Scan a container image
  repository  Scan a repository
  rootfs      Scan rootfs
  sbom        Scan SBOM for vulnerabilities and licenses
  vm          [EXPERIMENTAL] Scan a virtual machine image

3. is it really as simple as supported or not. or there are slightly different behavior based on the target/scanner? (due to implementation differences).

--skip-files and --skip-dirs are implemented in essentially the same way regardless of the target, and since the processing takes place before the scan is executed, there should be no differences depending on the scanner.

4. do you consider --file-patterns also under this group?

I think it’s possible to classify --file-patterns into the same group in terms of altering the behavior of searching for files on the filesystem. The only difference is whether they skip files or include them.

[Nepo26]

In the same pattern on how to ignore some checks/policies. How could someone enforce a check/policy? Is it possible to define a level or a list of checks/policies that CANNOT be ignored?

[simar7]

We don't have such capabilities in the OSS offering today. To me this also feels like an enterprise feature where enforcement of checks is required for reasons such as ensuring compliance. cc @itaysk

[itaysk]

perhaps I'm missing something but as far as I understand a finding can only be enforced or ignored. By default it's enforced (meaning the scanner will report IF there's a violation), and the user can opt to ignore it.

[simar7]

@itaysk I believe the idea is to unconditionally require a check, even if, there's an ignore defined.

My understanding is that this could be the use case where there are organizational level compliance policies defined but individual contributors may define the IaC requirements. In order to enforce the organizational requirements, certain checks cannot be suppressed.

Correct me if I'm wrong @Nepo26

[Nepo26]

@simar7 is correct. Although there are policies in place for developers, they cannot change them, and for now, they can simply ignore them.

I suggest we implement a way to define enforcement checks, so they can't ignore the policies.

[itaysk]

Trivy is supposed to be a local simple standalone scanner. Use cases that involve roles, policies and organization level implementation, are reserved for the commercial product built on top of Trivy