feat(vuln): add --pkg-relationships (#7237)

Signed-off-by: knqyf263 <knqyf263@gmail.com>

docs/docs/references/configuration/cli/trivy_filesystem.md

@@ -63,7 +63,8 @@ trivy filesystem [flags] PATH
       --output-plugin-arg string          [EXPERIMENTAL] output plugin arguments
       --parallel int                      number of goroutines enabled for parallel scanning, set 0 to auto-detect parallelism (default 5)
       --password strings                  password. Comma-separated passwords allowed. TRIVY_PASSWORD should be used for security reasons.
-      --pkg-types strings                 comma-separated list of package types (os,library) (default [os,library])
+      --pkg-relationships strings         list of package relationships (unknown,root,direct,indirect) (default [unknown,root,direct,indirect])
+      --pkg-types strings                 list of package types (os,library) (default [os,library])
       --redis-ca string                   redis ca file location, if using redis as cache backend
       --redis-cert string                 redis certificate file location, if using redis as cache backend
       --redis-key string                  redis key file location, if using redis as cache backend

docs/docs/references/configuration/cli/trivy_image.md

@@ -81,7 +81,8 @@ trivy image [flags] IMAGE_NAME
       --output-plugin-arg string          [EXPERIMENTAL] output plugin arguments
       --parallel int                      number of goroutines enabled for parallel scanning, set 0 to auto-detect parallelism (default 5)
       --password strings                  password. Comma-separated passwords allowed. TRIVY_PASSWORD should be used for security reasons.
-      --pkg-types strings                 comma-separated list of package types (os,library) (default [os,library])
+      --pkg-relationships strings         list of package relationships (unknown,root,direct,indirect) (default [unknown,root,direct,indirect])
+      --pkg-types strings                 list of package types (os,library) (default [os,library])
       --platform string                   set platform in the form os/arch if image is multi-platform capable
       --podman-host string                unix podman socket path to use for podman scanning
       --redis-ca string                   redis ca file location, if using redis as cache backend

docs/docs/references/configuration/cli/trivy_kubernetes.md

@@ -78,7 +78,8 @@ trivy kubernetes [flags] [CONTEXT]
       --output-plugin-arg string          [EXPERIMENTAL] output plugin arguments
       --parallel int                      number of goroutines enabled for parallel scanning, set 0 to auto-detect parallelism (default 5)
       --password strings                  password. Comma-separated passwords allowed. TRIVY_PASSWORD should be used for security reasons.
-      --pkg-types strings                 comma-separated list of package types (os,library) (default [os,library])
+      --pkg-relationships strings         list of package relationships (unknown,root,direct,indirect) (default [unknown,root,direct,indirect])
+      --pkg-types strings                 list of package types (os,library) (default [os,library])
       --qps float                         specify the maximum QPS to the master from this client (default 5)
       --redis-ca string                   redis ca file location, if using redis as cache backend
       --redis-cert string                 redis certificate file location, if using redis as cache backend

docs/docs/references/configuration/cli/trivy_repository.md

@@ -63,7 +63,8 @@ trivy repository [flags] (REPO_PATH | REPO_URL)
       --output-plugin-arg string          [EXPERIMENTAL] output plugin arguments
       --parallel int                      number of goroutines enabled for parallel scanning, set 0 to auto-detect parallelism (default 5)
       --password strings                  password. Comma-separated passwords allowed. TRIVY_PASSWORD should be used for security reasons.
-      --pkg-types strings                 comma-separated list of package types (os,library) (default [os,library])
+      --pkg-relationships strings         list of package relationships (unknown,root,direct,indirect) (default [unknown,root,direct,indirect])
+      --pkg-types strings                 list of package types (os,library) (default [os,library])
       --redis-ca string                   redis ca file location, if using redis as cache backend
       --redis-cert string                 redis certificate file location, if using redis as cache backend
       --redis-key string                  redis key file location, if using redis as cache backend

docs/docs/references/configuration/cli/trivy_rootfs.md

@@ -65,7 +65,8 @@ trivy rootfs [flags] ROOTDIR
       --output-plugin-arg string          [EXPERIMENTAL] output plugin arguments
       --parallel int                      number of goroutines enabled for parallel scanning, set 0 to auto-detect parallelism (default 5)
       --password strings                  password. Comma-separated passwords allowed. TRIVY_PASSWORD should be used for security reasons.
-      --pkg-types strings                 comma-separated list of package types (os,library) (default [os,library])
+      --pkg-relationships strings         list of package relationships (unknown,root,direct,indirect) (default [unknown,root,direct,indirect])
+      --pkg-types strings                 list of package types (os,library) (default [os,library])
       --redis-ca string                   redis ca file location, if using redis as cache backend
       --redis-cert string                 redis certificate file location, if using redis as cache backend
       --redis-key string                  redis key file location, if using redis as cache backend

docs/docs/references/configuration/cli/trivy_sbom.md

@@ -43,7 +43,8 @@ trivy sbom [flags] SBOM_PATH
       --offline-scan                do not issue API requests to identify dependencies
   -o, --output string               output file name
       --output-plugin-arg string    [EXPERIMENTAL] output plugin arguments
-      --pkg-types strings           comma-separated list of package types (os,library) (default [os,library])
+      --pkg-relationships strings   list of package relationships (unknown,root,direct,indirect) (default [unknown,root,direct,indirect])
+      --pkg-types strings           list of package types (os,library) (default [os,library])
       --redis-ca string             redis ca file location, if using redis as cache backend
       --redis-cert string           redis certificate file location, if using redis as cache backend
       --redis-key string            redis key file location, if using redis as cache backend

docs/docs/references/configuration/cli/trivy_vm.md

@@ -56,7 +56,8 @@ trivy vm [flags] VM_IMAGE
   -o, --output string                     output file name
       --output-plugin-arg string          [EXPERIMENTAL] output plugin arguments
       --parallel int                      number of goroutines enabled for parallel scanning, set 0 to auto-detect parallelism (default 5)
-      --pkg-types strings                 comma-separated list of package types (os,library) (default [os,library])
+      --pkg-relationships strings         list of package relationships (unknown,root,direct,indirect) (default [unknown,root,direct,indirect])
+      --pkg-types strings                 list of package types (os,library) (default [os,library])
       --redis-ca string                   redis ca file location, if using redis as cache backend
       --redis-cert string                 redis certificate file location, if using redis as cache backend
       --redis-key string                  redis key file location, if using redis as cache backend

docs/docs/scanner/vulnerability.md

@@ -202,7 +202,8 @@ Currently, specifying a username and password is not supported.
 This section describes vulnerability-specific configuration.
 Other common options are documented [here](../configuration/index.md).
 
-### Enabling a subset of package types
+### Enabling a Subset of Package Types
+
 It's possible to only enable certain package types if you prefer.
 You can do so by passing the `--pkg-types` option.
 This flag takes a comma-separated list of package types.
@@ -268,6 +269,45 @@ Total: 7 (UNKNOWN: 0, LOW: 1, MEDIUM: 1, HIGH: 3, CRITICAL: 2)
 
 </details>
 
+!!! info
+    This flag filters the packages themselves, so it also affects the `--list-all-pkgs` option and SBOM generation.
+
+### Filtering by Package Relationships
+
+
+Trivy supports filtering vulnerabilities based on the relationship of packages within a project.
+This is achieved through the `--pkg-relationships` flag.
+This feature allows you to focus on vulnerabilities in specific types of dependencies, such as only those in direct dependencies.
+
+In Trivy, there are four types of package relationships:
+
+1. `root`: The root package being scanned
+2. `direct`: Direct dependencies of the root package
+3. `indirect`: Transitive dependencies
+4. `unknown`: Packages whose relationship cannot be determined
+
+The available relationships may vary depending on the ecosystem.
+To see which relationships are supported for a particular project, you can use the JSON output format and check the `Relationship` field:
+
+```
+$ trivy repo -f json --list-all-pkgs /path/to/project
+```
+
+To scan only the root package and its direct dependencies, you can use the flag as follows:
+
+```
+$ trivy repo --pkg-relationships root,direct /path/to/project
+```
+
+By default, all relationships are included in the scan.
+
+!!! info
+    This flag filters the packages themselves, so it also affects the `--list-all-pkgs` option and SBOM generation.
+
+!!! warning
+    As it may not provide a complete package list, `--pkg-relationships` cannot be used with `--dependency-tree`, `--vex` or SBOM generation.
+
+
 [^1]: https://github.com/GoogleContainerTools/distroless
 
 [nvd-CVE-2023-0464]: https://nvd.nist.gov/vuln/detail/CVE-2023-0464