docs(cli): update help string for file and dir skipping (#4872)

* docs(cli): update help string for file and dir skipping - Update the contextual help messages - Add some additional examples (and clarify YAML file configuration) for globbing - Update docs - Fix broken link in skipping docs See also #3754 Signed-off-by: William Yardley <[email protected]> * docs: revert --------- Signed-off-by: William Yardley <[email protected]> Co-authored-by: knqyf263 <[email protected]>
aquasecurity · Aug 2, 2023 · 6d3ae3b · 6d3ae3b
1 parent 7d7a1ef
commit 6d3ae3b
Show file tree

Hide file tree

Showing 10 changed files with 57 additions and 26 deletions.
diff --git a/docs/docs/configuration/skipping.md b/docs/docs/configuration/skipping.md
@@ -11,19 +11,34 @@ This section details ways to specify the files and directories that Trivy should
 |     License      |     ✓     |
 
 By default, Trivy traverses directories and searches for all necessary files for scanning.
-You can skip files that you don't maintain using the `--skip-files` flag.
+You can skip files that you don't maintain using the `--skip-files` flag, or the equivalent Trivy YAML config option.
 
-```
+Using the `--skip-files` flag:
+```bash
 $ trivy image --skip-files "/Gemfile.lock" --skip-files "/var/lib/gems/2.5.0/gems/http_parser.rb-0.6.0/Gemfile.lock" quay.io/fluentd_elasticsearch/fluentd:v2.9.0
 ```
 
+Using the Trivy YAML configuration:
+```yaml
+image:
+  skip-files:
+    - foo
+    - "testdata/*/bar"
+```
+
 It's possible to specify globs as part of the value.
 
 ```bash
 $ trivy image --skip-files "./testdata/*/bar" .
 ```
 
-Will skip any file named `bar` in the subdirectories of testdata.
+This will skip any file named `bar` in the subdirectories of testdata.
+
+```bash
+$ trivy config --skip-files "./foo/**/*.tf" .
+```
+
+This will skip any files with the extension `.tf` in subdirectories of foo at any depth.
 
 ## Skip Directories
 |     Scanner      | Supported |
@@ -34,32 +49,48 @@ Will skip any file named `bar` in the subdirectories of testdata.
 |     License      |     ✓     |
 
 By default, Trivy traverses directories and searches for all necessary files for scanning.
-You can skip directories that you don't maintain using the `--skip-dirs` flag.
+You can skip directories that you don't maintain using the `--skip-dirs` flag, or the equivalent Trivy YAML config option.
 
-```
+Using the `--skip-dirs` flag:
+```bash
 $ trivy image --skip-dirs /var/lib/gems/2.5.0/gems/fluent-plugin-detect-exceptions-0.0.13 --skip-dirs "/var/lib/gems/2.5.0/gems/http_parser.rb-0.6.0" quay.io/fluentd_elasticsearch/fluentd:v2.9.0
 ```
 
+Using the Trivy YAML configuration:
+```yaml
+image:
+  skip-dirs:
+    - foo/bar/
+    - "**/.terraform"
+```
+
 It's possible to specify globs as part of the value.
 
 ```bash
 $ trivy image --skip-dirs "./testdata/*" .
 ```
 
-Will skip all subdirectories of the testdata directory.
+This will skip all subdirectories of the testdata directory.
+
+```bash
+$ trivy config --skip-dirs "**/.terraform" .
+```
+
+This will skip subdirectories at any depth named `.terraform/`. (Note: this will match `./foo/.terraform` or
+`./foo/bar/.terraform`, but not `./.terraform`.)
 
 !!! tip
     Glob patterns work with any trivy subcommand (image, config, etc.) and can be specified to skip both directories (with `--skip-dirs`) and files (with `--skip-files`).
 
 
 ### Advanced globbing
-Trivy also supports the [globstar](https://www.gnu.org/savannah-checkouts/gnu/bash/manual/bash.html#Pattern-Matching) pattern matching. 
+Trivy also supports bash style [extended](https://www.gnu.org/savannah-checkouts/gnu/bash/manual/bash.html#Pattern-Matching) glob pattern matching.
 
 ```bash
 $ trivy image --skip-files "**/foo" image:tag
 ```
 
-Will skip the file `foo` that happens to be nested under any parent(s). 
+This will skip the file `foo` that happens to be nested under any parent(s). 
 
 ## File patterns
 |     Scanner      | Supported |

diff --git a/docs/docs/references/configuration/cli/trivy_config.md b/docs/docs/references/configuration/cli/trivy_config.md
@@ -40,8 +40,8 @@ trivy config [flags] DIR
       --report string                     specify a compliance report format for the output (all,summary) (default "all")
       --reset-policy-bundle               remove policy bundle
   -s, --severity strings                  severities of security issues to be displayed (UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL) (default [UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL])
-      --skip-dirs strings                 specify the directories where the traversal is skipped
-      --skip-files strings                specify the file paths to skip traversal
+      --skip-dirs strings                 specify the directories or glob patterns to skip
+      --skip-files strings                specify the files or glob patterns to skip
       --skip-policy-update                skip fetching rego policy updates
   -t, --template string                   output template
       --tf-exclude-downloaded-modules     remove results for downloaded modules in .terraform folder

diff --git a/docs/docs/references/configuration/cli/trivy_filesystem.md b/docs/docs/references/configuration/cli/trivy_filesystem.md
@@ -72,8 +72,8 @@ trivy filesystem [flags] PATH
       --server string                     server address in client mode
   -s, --severity strings                  severities of security issues to be displayed (UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL) (default [UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL])
       --skip-db-update                    skip updating vulnerability database
-      --skip-dirs strings                 specify the directories where the traversal is skipped
-      --skip-files strings                specify the file paths to skip traversal
+      --skip-dirs strings                 specify the directories or glob patterns to skip
+      --skip-files strings                specify the files or glob patterns to skip
       --skip-java-db-update               skip updating Java index database
       --skip-policy-update                skip fetching rego policy updates
       --slow                              scan over time with lower CPU and memory utilization

diff --git a/docs/docs/references/configuration/cli/trivy_image.md b/docs/docs/references/configuration/cli/trivy_image.md
@@ -93,8 +93,8 @@ trivy image [flags] IMAGE_NAME
       --server string                     server address in client mode
   -s, --severity strings                  severities of security issues to be displayed (UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL) (default [UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL])
       --skip-db-update                    skip updating vulnerability database
-      --skip-dirs strings                 specify the directories where the traversal is skipped
-      --skip-files strings                specify the file paths to skip traversal
+      --skip-dirs strings                 specify the directories or glob patterns to skip
+      --skip-files strings                specify the files or glob patterns to skip
       --skip-java-db-update               skip updating Java index database
       --skip-policy-update                skip fetching rego policy updates
       --slow                              scan over time with lower CPU and memory utilization

diff --git a/docs/docs/references/configuration/cli/trivy_kubernetes.md b/docs/docs/references/configuration/cli/trivy_kubernetes.md
@@ -82,8 +82,8 @@ trivy kubernetes [flags] { cluster | all | specific resources like kubectl. eg:
       --secret-config string              specify a path to config file for secret scanning (default "trivy-secret.yaml")
   -s, --severity strings                  severities of security issues to be displayed (UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL) (default [UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL])
       --skip-db-update                    skip updating vulnerability database
-      --skip-dirs strings                 specify the directories where the traversal is skipped
-      --skip-files strings                specify the file paths to skip traversal
+      --skip-dirs strings                 specify the directories or glob patterns to skip
+      --skip-files strings                specify the files or glob patterns to skip
       --skip-java-db-update               skip updating Java index database
       --skip-policy-update                skip fetching rego policy updates
       --slow                              scan over time with lower CPU and memory utilization

diff --git a/docs/docs/references/configuration/cli/trivy_repository.md b/docs/docs/references/configuration/cli/trivy_repository.md
@@ -69,8 +69,8 @@ trivy repository [flags] REPO_URL
       --server string                     server address in client mode
   -s, --severity strings                  severities of security issues to be displayed (UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL) (default [UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL])
       --skip-db-update                    skip updating vulnerability database
-      --skip-dirs strings                 specify the directories where the traversal is skipped
-      --skip-files strings                specify the file paths to skip traversal
+      --skip-dirs strings                 specify the directories or glob patterns to skip
+      --skip-files strings                specify the files or glob patterns to skip
       --skip-java-db-update               skip updating Java index database
       --skip-policy-update                skip fetching rego policy updates
       --slow                              scan over time with lower CPU and memory utilization

diff --git a/docs/docs/references/configuration/cli/trivy_rootfs.md b/docs/docs/references/configuration/cli/trivy_rootfs.md
@@ -73,8 +73,8 @@ trivy rootfs [flags] ROOTDIR
       --server string                     server address in client mode
   -s, --severity strings                  severities of security issues to be displayed (UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL) (default [UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL])
       --skip-db-update                    skip updating vulnerability database
-      --skip-dirs strings                 specify the directories where the traversal is skipped
-      --skip-files strings                specify the file paths to skip traversal
+      --skip-dirs strings                 specify the directories or glob patterns to skip
+      --skip-files strings                specify the files or glob patterns to skip
       --skip-java-db-update               skip updating Java index database
       --skip-policy-update                skip fetching rego policy updates
       --slow                              scan over time with lower CPU and memory utilization

diff --git a/docs/docs/references/configuration/cli/trivy_sbom.md b/docs/docs/references/configuration/cli/trivy_sbom.md
@@ -52,8 +52,8 @@ trivy sbom [flags] SBOM_PATH
       --server string               server address in client mode
   -s, --severity strings            severities of security issues to be displayed (UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL) (default [UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL])
       --skip-db-update              skip updating vulnerability database
-      --skip-dirs strings           specify the directories where the traversal is skipped
-      --skip-files strings          specify the file paths to skip traversal
+      --skip-dirs strings           specify the directories or glob patterns to skip
+      --skip-files strings          specify the files or glob patterns to skip
       --skip-java-db-update         skip updating Java index database
       --slow                        scan over time with lower CPU and memory utilization
   -t, --template string             output template

diff --git a/docs/docs/references/configuration/cli/trivy_vm.md b/docs/docs/references/configuration/cli/trivy_vm.md
@@ -65,8 +65,8 @@ trivy vm [flags] VM_IMAGE
       --server string                     server address in client mode
   -s, --severity strings                  severities of security issues to be displayed (UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL) (default [UNKNOWN,LOW,MEDIUM,HIGH,CRITICAL])
       --skip-db-update                    skip updating vulnerability database
-      --skip-dirs strings                 specify the directories where the traversal is skipped
-      --skip-files strings                specify the file paths to skip traversal
+      --skip-dirs strings                 specify the directories or glob patterns to skip
+      --skip-files strings                specify the files or glob patterns to skip
       --skip-java-db-update               skip updating Java index database
       --slow                              scan over time with lower CPU and memory utilization
   -t, --template string                   output template

diff --git a/pkg/flag/scan_flags.go b/pkg/flag/scan_flags.go
@@ -10,13 +10,13 @@ var (
 		Name:       "skip-dirs",
 		ConfigName: "scan.skip-dirs",
 		Default:    []string{},
-		Usage:      "specify the directories where the traversal is skipped",
+		Usage:      "specify the directories or glob patterns to skip",
 	}
 	SkipFilesFlag = Flag{
 		Name:       "skip-files",
 		ConfigName: "scan.skip-files",
 		Default:    []string{},
-		Usage:      "specify the file paths to skip traversal",
+		Usage:      "specify the files or glob patterns to skip",
 	}
 	OfflineScanFlag = Flag{
 		Name:       "offline-scan",