From 8bc94afef403673ea1fa62762f5f60d15f4e9363 Mon Sep 17 00:00:00 2001 From: William Yardley Date: Wed, 26 Jul 2023 22:30:43 -0700 Subject: [PATCH 1/2] 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 --- docs/docs/configuration/skipping.md | 49 +++++++++++++++---- .../configuration/cli/trivy_config.md | 4 +- .../configuration/cli/trivy_filesystem.md | 4 +- .../configuration/cli/trivy_image.md | 4 +- .../configuration/cli/trivy_kubernetes.md | 4 +- .../configuration/cli/trivy_repository.md | 4 +- .../configuration/cli/trivy_rootfs.md | 4 +- .../configuration/cli/trivy_sbom.md | 4 +- .../references/configuration/cli/trivy_vm.md | 4 +- pkg/flag/scan_flags.go | 4 +- 10 files changed, 58 insertions(+), 27 deletions(-) diff --git a/docs/docs/configuration/skipping.md b/docs/docs/configuration/skipping.md index fb87e27358e3..b1168a2e3946 100644 --- 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 | @@ -82,4 +113,4 @@ A file pattern contains the analyzer it is used for, and the pattern itself, joi --file-patterns "dockerfile:.*.docker" --file-patterns "kubernetes:*.tpl" --file-patterns "pip:requirements-.*\.txt" ``` -The prefixes are listed [here](https://github.com/aquasecurity/trivy/tree/{{ git.commit }}/pkg/fanal/analyzer/const.go) +The prefixes are listed [here](../../../pkg/fanal/analyzer/const.go) diff --git a/docs/docs/references/configuration/cli/trivy_config.md b/docs/docs/references/configuration/cli/trivy_config.md index 0ed13c1722c7..76a0bf91cb3b 100644 --- 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 index 6f133483fe83..8c681b57c6b2 100644 --- 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 index d644239d8961..1effd26cacf4 100644 --- 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 index d550474139a7..52f7a53f14ec 100644 --- 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 index 0f499b5b8fbe..8cb611bd82e6 100644 --- 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 index 683acba441ce..69bcdb282d5c 100644 --- 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 index 664a8c12f302..d031f61e4cff 100644 --- 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 index 95e409680a9f..e294f010cfca 100644 --- 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 index f3d2d3d6a914..66280ecb255e 100644 --- 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", From 923010bb7404e5fd6c92a4f6644deefbf14afc8c Mon Sep 17 00:00:00 2001 From: knqyf263 Date: Wed, 2 Aug 2023 14:00:28 +0300 Subject: [PATCH 2/2] docs: revert --- docs/docs/configuration/skipping.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/configuration/skipping.md b/docs/docs/configuration/skipping.md index b1168a2e3946..2537a529ff54 100644 --- a/docs/docs/configuration/skipping.md +++ b/docs/docs/configuration/skipping.md @@ -113,4 +113,4 @@ A file pattern contains the analyzer it is used for, and the pattern itself, joi --file-patterns "dockerfile:.*.docker" --file-patterns "kubernetes:*.tpl" --file-patterns "pip:requirements-.*\.txt" ``` -The prefixes are listed [here](../../../pkg/fanal/analyzer/const.go) +The prefixes are listed [here](https://github.com/aquasecurity/trivy/tree/{{ git.commit }}/pkg/fanal/analyzer/const.go)