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

Signed-off-by: knqyf263 <[email protected]>

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

pkg/commands/app.go

@@ -243,9 +243,6 @@ func NewRootCommand(globalFlags *flag.GlobalFlagGroup) *cobra.Command {
 }
 
 func NewImageCommand(globalFlags *flag.GlobalFlagGroup) *cobra.Command {
-	scanFlagGroup := flag.NewScanFlagGroup()
-	scanFlagGroup.IncludeDevDeps = nil // disable '--include-dev-deps'
-
 	reportFlagGroup := flag.NewReportFlagGroup()
 	report := flag.ReportFormatFlag.Clone()
 	report.Default = "summary"                                   // override the default value as the summary is preferred for the compliance report
@@ -256,27 +253,28 @@ func NewImageCommand(globalFlags *flag.GlobalFlagGroup) *cobra.Command {
 	compliance.Values = []string{types.ComplianceDockerCIS160}
 	reportFlagGroup.Compliance = compliance // override usage as the accepted values differ for each subcommand.
 
-	misconfFlagGroup := flag.NewMisconfFlagGroup()
-	misconfFlagGroup.CloudformationParamVars = nil // disable '--cf-params'
-	misconfFlagGroup.TerraformTFVars = nil         // disable '--tf-vars'
-
 	imageFlags := &flag.Flags{
 		GlobalFlagGroup:        globalFlags,
 		CacheFlagGroup:         flag.NewCacheFlagGroup(),
 		DBFlagGroup:            flag.NewDBFlagGroup(),
 		ImageFlagGroup:         flag.NewImageFlagGroup(), // container image specific
 		LicenseFlagGroup:       flag.NewLicenseFlagGroup(),
-		MisconfFlagGroup:       misconfFlagGroup,
+		MisconfFlagGroup:       flag.NewMisconfFlagGroup(),
 		ModuleFlagGroup:        flag.NewModuleFlagGroup(),
+		PackageFlagGroup:       flag.NewPackageFlagGroup(),
 		RemoteFlagGroup:        flag.NewClientFlags(), // for client/server mode
 		RegistryFlagGroup:      flag.NewRegistryFlagGroup(),
 		RegoFlagGroup:          flag.NewRegoFlagGroup(),
 		ReportFlagGroup:        reportFlagGroup,
-		ScanFlagGroup:          scanFlagGroup,
+		ScanFlagGroup:          flag.NewScanFlagGroup(),
 		SecretFlagGroup:        flag.NewSecretFlagGroup(),
 		VulnerabilityFlagGroup: flag.NewVulnerabilityFlagGroup(),
 	}
 
+	imageFlags.PackageFlagGroup.IncludeDevDeps = nil          // disable '--include-dev-deps'
+	imageFlags.MisconfFlagGroup.CloudformationParamVars = nil // disable '--cf-params'
+	imageFlags.MisconfFlagGroup.TerraformTFVars = nil         // disable '--tf-vars'
+
 	cmd := &cobra.Command{
 		Use:     "image [flags] IMAGE_NAME",
 		Aliases: []string{"i"},
@@ -342,6 +340,7 @@ func NewFilesystemCommand(globalFlags *flag.GlobalFlagGroup) *cobra.Command {
 		LicenseFlagGroup:       flag.NewLicenseFlagGroup(),
 		MisconfFlagGroup:       flag.NewMisconfFlagGroup(),
 		ModuleFlagGroup:        flag.NewModuleFlagGroup(),
+		PackageFlagGroup:       flag.NewPackageFlagGroup(),
 		RemoteFlagGroup:        flag.NewClientFlags(), // for client/server mode
 		RegistryFlagGroup:      flag.NewRegistryFlagGroup(),
 		RegoFlagGroup:          flag.NewRegoFlagGroup(),
@@ -400,6 +399,7 @@ func NewRootfsCommand(globalFlags *flag.GlobalFlagGroup) *cobra.Command {
 		LicenseFlagGroup:       flag.NewLicenseFlagGroup(),
 		MisconfFlagGroup:       flag.NewMisconfFlagGroup(),
 		ModuleFlagGroup:        flag.NewModuleFlagGroup(),
+		PackageFlagGroup:       flag.NewPackageFlagGroup(),
 		RemoteFlagGroup:        flag.NewClientFlags(), // for client/server mode
 		RegistryFlagGroup:      flag.NewRegistryFlagGroup(),
 		RegoFlagGroup:          flag.NewRegoFlagGroup(),
@@ -411,7 +411,7 @@ func NewRootfsCommand(globalFlags *flag.GlobalFlagGroup) *cobra.Command {
 	rootfsFlags.ReportFlagGroup.ReportFormat = nil                             // TODO: support --report summary
 	rootfsFlags.ReportFlagGroup.Compliance = nil                               // disable '--compliance'
 	rootfsFlags.ReportFlagGroup.ReportFormat = nil                             // disable '--report'
-	rootfsFlags.ScanFlagGroup.IncludeDevDeps = nil                             // disable '--include-dev-deps'
+	rootfsFlags.PackageFlagGroup.IncludeDevDeps = nil                          // disable '--include-dev-deps'
 	rootfsFlags.CacheFlagGroup.CacheBackend.Default = string(cache.TypeMemory) // Use memory cache by default
 
 	cmd := &cobra.Command{
@@ -460,6 +460,7 @@ func NewRepositoryCommand(globalFlags *flag.GlobalFlagGroup) *cobra.Command {
 		LicenseFlagGroup:       flag.NewLicenseFlagGroup(),
 		MisconfFlagGroup:       flag.NewMisconfFlagGroup(),
 		ModuleFlagGroup:        flag.NewModuleFlagGroup(),
+		PackageFlagGroup:       flag.NewPackageFlagGroup(),
 		RegistryFlagGroup:      flag.NewRegistryFlagGroup(),
 		RegoFlagGroup:          flag.NewRegoFlagGroup(),
 		RemoteFlagGroup:        flag.NewClientFlags(), // for client/server mode
@@ -516,7 +517,6 @@ func NewConvertCommand(globalFlags *flag.GlobalFlagGroup) *cobra.Command {
 		ScanFlagGroup:   &flag.ScanFlagGroup{},
 		ReportFlagGroup: flag.NewReportFlagGroup(),
 	}
-	convertFlags.ReportFlagGroup.PkgTypes = nil // disable '--pkg-types'
 
 	cmd := &cobra.Command{
 		Use:     "convert [flags] RESULT_JSON",
@@ -685,7 +685,6 @@ func NewConfigCommand(globalFlags *flag.GlobalFlagGroup) *cobra.Command {
 	configFlags.ReportFlagGroup.ListAllPkgs = nil                                                        // disable '--list-all-pkgs'
 	configFlags.ReportFlagGroup.ExitOnEOL = nil                                                          // disable '--exit-on-eol'
 	configFlags.ReportFlagGroup.ShowSuppressed = nil                                                     // disable '--show-suppressed'
-	configFlags.ReportFlagGroup.PkgTypes = nil                                                           // disable '--pkg-types'
 	configFlags.ReportFlagGroup.ReportFormat.Usage = "specify a compliance report format for the output" // @TODO: support --report summary for non compliance reports
 	configFlags.CacheFlagGroup.CacheBackend.Default = string(cache.TypeMemory)
 
@@ -960,7 +959,6 @@ func NewKubernetesCommand(globalFlags *flag.GlobalFlagGroup) *cobra.Command {
 	})
 	scanners.Default = scanners.Values
 	scanFlags.Scanners = scanners
-	scanFlags.IncludeDevDeps = nil // disable '--include-dev-deps'
 
 	// required only SourceFlag
 	imageFlags := &flag.ImageFlagGroup{ImageSources: flag.SourceFlag.Clone()}
@@ -997,13 +995,16 @@ func NewKubernetesCommand(globalFlags *flag.GlobalFlagGroup) *cobra.Command {
 		ImageFlagGroup:         imageFlags,
 		K8sFlagGroup:           flag.NewK8sFlagGroup(), // kubernetes-specific flags
 		MisconfFlagGroup:       misconfFlagGroup,
+		PackageFlagGroup:       flag.NewPackageFlagGroup(),
 		RegoFlagGroup:          flag.NewRegoFlagGroup(),
 		ReportFlagGroup:        reportFlagGroup,
 		ScanFlagGroup:          scanFlags,
 		SecretFlagGroup:        flag.NewSecretFlagGroup(),
 		RegistryFlagGroup:      flag.NewRegistryFlagGroup(),
 		VulnerabilityFlagGroup: flag.NewVulnerabilityFlagGroup(),
 	}
+	k8sFlags.PackageFlagGroup.IncludeDevDeps = nil // disable '--include-dev-deps'
+
 	cmd := &cobra.Command{
 		Use:     "kubernetes [flags] [CONTEXT]",
 		Aliases: []string{"k8s"},
@@ -1055,6 +1056,7 @@ func NewVMCommand(globalFlags *flag.GlobalFlagGroup) *cobra.Command {
 		DBFlagGroup:            flag.NewDBFlagGroup(),
 		MisconfFlagGroup:       flag.NewMisconfFlagGroup(),
 		ModuleFlagGroup:        flag.NewModuleFlagGroup(),
+		PackageFlagGroup:       flag.NewPackageFlagGroup(),
 		RemoteFlagGroup:        flag.NewClientFlags(), // for client/server mode
 		ReportFlagGroup:        flag.NewReportFlagGroup(),
 		ScanFlagGroup:          flag.NewScanFlagGroup(),
@@ -1069,7 +1071,7 @@ func NewVMCommand(globalFlags *flag.GlobalFlagGroup) *cobra.Command {
 		},
 	}
 	vmFlags.ReportFlagGroup.ReportFormat = nil             // disable '--report'
-	vmFlags.ScanFlagGroup.IncludeDevDeps = nil             // disable '--include-dev-deps'
+	vmFlags.PackageFlagGroup.IncludeDevDeps = nil          // disable '--include-dev-deps'
 	vmFlags.MisconfFlagGroup.CloudformationParamVars = nil // disable '--cf-params'
 	vmFlags.MisconfFlagGroup.TerraformTFVars = nil         // disable '--tf-vars'
 
@@ -1128,9 +1130,8 @@ func NewSBOMCommand(globalFlags *flag.GlobalFlagGroup) *cobra.Command {
 		types.VulnerabilityScanner,
 	})
 	scanFlagGroup := flag.NewScanFlagGroup()
-	scanFlagGroup.Scanners = scanners  // allow only 'vuln' and 'license' options for '--scanners'
-	scanFlagGroup.IncludeDevDeps = nil // disable '--include-dev-deps'
-	scanFlagGroup.Parallel = nil       // disable '--parallel'
+	scanFlagGroup.Scanners = scanners // allow only 'vuln' and 'license' options for '--scanners'
+	scanFlagGroup.Parallel = nil      // disable '--parallel'
 
 	licenseFlagGroup := flag.NewLicenseFlagGroup()
 	// License full-scan and confidence-level are for file content only
@@ -1141,6 +1142,7 @@ func NewSBOMCommand(globalFlags *flag.GlobalFlagGroup) *cobra.Command {
 		GlobalFlagGroup:        globalFlags,
 		CacheFlagGroup:         flag.NewCacheFlagGroup(),
 		DBFlagGroup:            flag.NewDBFlagGroup(),
+		PackageFlagGroup:       flag.NewPackageFlagGroup(),
 		RemoteFlagGroup:        flag.NewClientFlags(), // for client/server mode
 		ReportFlagGroup:        reportFlagGroup,
 		ScanFlagGroup:          scanFlagGroup,
@@ -1150,6 +1152,7 @@ func NewSBOMCommand(globalFlags *flag.GlobalFlagGroup) *cobra.Command {
 	}
 
 	sbomFlags.CacheFlagGroup.CacheBackend.Default = string(cache.TypeMemory) // Use memory cache by default
+	sbomFlags.PackageFlagGroup.IncludeDevDeps = nil                          // disable '--include-dev-deps'
 
 	cmd := &cobra.Command{
 		Use:     "sbom [flags] SBOM_PATH",