feat(vuln): Add --detection-priority flag for accuracy tuning (#7288)

Signed-off-by: knqyf263 <knqyf263@gmail.com>
aquasecurity · Aug 2, 2024 · fd8348d · fd8348d
1 parent e95152f
commit fd8348d
Show file tree

Hide file tree

Showing 30 changed files with 675 additions and 221 deletions.
diff --git a/docs/docs/coverage/language/dart.md b/docs/docs/coverage/language/dart.md
@@ -11,9 +11,9 @@ The following scanners are supported.
 The following table provides an outline of the features Trivy offers.
 
 
-| Package manager         | File         | Transitive dependencies | Dev dependencies | [Dependency graph][dependency-graph] | Position |
-|-------------------------|--------------|:-----------------------:|:----------------:|:------------------------------------:|:--------:|
-| [Dart][dart-repository] | pubspec.lock |            ✓            |     Included     |                  ✓                   |    -     |
+| Package manager         | File         | Transitive dependencies | Dev dependencies | [Dependency graph][dependency-graph] | Position | [Detection Priority][detection-priority] |
+|-------------------------|--------------|:-----------------------:|:----------------:|:------------------------------------:|:--------:|:----------------------------------------:|
+| [Dart][dart-repository] | pubspec.lock |            ✓            |     Included     |                  ✓                   |    -     |                    ✓                     |
 
 ## Dart
 In order to detect dependencies, Trivy searches for `pubspec.lock`.
@@ -22,11 +22,13 @@ Trivy marks indirect dependencies, but `pubspec.lock` file doesn't have options
 So Trivy includes all dependencies in report.
 
 ### SDK dependencies
-Dart uses version `0.0.0` for SDK dependencies (e.g. Flutter). It is not possible to accurately determine the versions of these dependencies.
+Dart uses version `0.0.0` for SDK dependencies (e.g. Flutter).
+It is not possible to accurately determine the versions of these dependencies.
+Trivy just treats them as `0.0.0`.
 
-Therefore, we use the first version of the constraint for the SDK.
+If [--detection-priority comprehensive][detection-priority] is passed, Trivy uses the minimum version of the constraint for the SDK.
+For example, in the following case, the version of `flutter` would be `3.3.0`:
 
-For example in this case the version of `flutter` should be `3.3.0`:
 ```yaml
 flutter:
   dependency: "direct main"
@@ -40,10 +42,12 @@ sdks:
 
 ### Dependency tree
 To build `dependency tree` Trivy parses [cache directory][cache-directory]. Currently supported default directories and `PUB_CACHE` environment (absolute path only).
+
 !!! note
     Make sure the cache directory contains all the dependencies installed in your application. To download missing dependencies, use `dart pub get` command.     
 
 [dart]: https://dart.dev/
 [dart-repository]: https://pub.dev/
 [dependency-graph]: ../../configuration/reporting.md#show-origins-of-vulnerable-dependencies
 [cache-directory]: https://dart.dev/tools/pub/glossary#system-cache
+[detection-priority]: ../../scanner/vulnerability.md#detection-priority
diff --git a/docs/docs/coverage/language/golang.md b/docs/docs/coverage/language/golang.md
@@ -16,10 +16,10 @@ The following scanners are supported.
 
 The table below provides an outline of the features Trivy offers.
 
-| Artifact | Offline[^1] | Dev dependencies | [Dependency graph][dependency-graph] | Stdlib |
-|----------|:-----------:|:-----------------|:------------------------------------:|:------:|
-| Modules  |      ✅      | Include          |                ✅[^2]                 |   -    |
-| Binaries |      ✅      | Exclude          |                  -                   | ✅[^4]  |
+| Artifact | Offline[^1] | Dev dependencies | [Dependency graph][dependency-graph] | Stdlib | [Detection Priority][detection-priority] |
+|----------|:-----------:|:-----------------|:------------------------------------:|:------:|:----------------------------------------:|
+| Modules  |      ✅      | Include          |                ✅[^2]                 |   -    |                    -                     |
+| Binaries |      ✅      | Exclude          |                  -                   | ✅[^4]  |                Not needed                |
 
 !!! note
     Trivy scans only dependencies of the Go project.
@@ -95,3 +95,4 @@ empty if it cannot do so[^5]. For the second case, the version of such packages
 [^5]: See https://github.com/golang/go/issues/63432#issuecomment-1751610604
 
 [dependency-graph]: ../../configuration/reporting.md#show-origins-of-vulnerable-dependencies
+[detection-priority]: ../../scanner/vulnerability.md#detection-priority
diff --git a/docs/docs/coverage/language/java.md b/docs/docs/coverage/language/java.md
@@ -12,12 +12,12 @@ Each artifact supports the following scanners:
 
 The following table provides an outline of the features Trivy offers.
 
-| Artifact         |    Internet access    | Dev dependencies | [Dependency graph][dependency-graph] | Position |
-|------------------|:---------------------:|:----------------:|:------------------------------------:|:--------:|
-| JAR/WAR/PAR/EAR  |     Trivy Java DB     |     Include      |                  -                   |    -     |
-| pom.xml          | Maven repository [^1] |     Exclude      |                  ✓                   |  ✓[^7]   |
-| *gradle.lockfile |           -           |     Exclude      |                  ✓                   |    ✓     |
-| *.sbt.lock       |          -            |     Exclude      |                  -                   |    ✓     |
+| Artifact         |    Internet access    | Dev dependencies | [Dependency graph][dependency-graph] | Position | [Detection Priority][detection-priority] |
+|------------------|:---------------------:|:----------------:|:------------------------------------:|:--------:|:----------------------------------------:|
+| JAR/WAR/PAR/EAR  |     Trivy Java DB     |     Include      |                  -                   |    -     |                Not needed                |
+| pom.xml          | Maven repository [^1] |     Exclude      |                  ✓                   |  ✓[^7]   |                    -                     |
+| *gradle.lockfile |           -           |     Exclude      |                  ✓                   |    ✓     |                Not needed                |
+| *.sbt.lock       |           -           |     Exclude      |                  -                   |    ✓     |                Not needed                |
 
 These may be enabled or disabled depending on the target.
 See [here](./index.md) for the detail.
@@ -119,3 +119,4 @@ Make sure that you have cache[^8] directory to find licenses from `*.pom` depend
 [maven-central]: https://repo.maven.apache.org/maven2/
 [maven-pom-repos]: https://maven.apache.org/settings.html#repositories
 [sbt-dependency-lock]: https://stringbean.github.io/sbt-dependency-lock
+[detection-priority]: ../../scanner/vulnerability.md#detection-priority
diff --git a/docs/docs/coverage/language/python.md b/docs/docs/coverage/language/python.md
@@ -21,11 +21,11 @@ The following scanners are supported for Python packages.
 
 The following table provides an outline of the features Trivy offers.
 
-| Package manager | File             | Transitive dependencies | Dev dependencies | [Dependency graph][dependency-graph] | Position |
-|-----------------|------------------|:-----------------------:|:----------------:|:------------------------------------:|:--------:|
-| pip             | requirements.txt |            -            |     Include      |                  -                   |    ✓     |
-| Pipenv          | Pipfile.lock     |            ✓            |     Include      |                  -                   |    ✓     |
-| Poetry          | poetry.lock      |            ✓            |     Exclude      |                  ✓                   |    -     |
+| Package manager | File             | Transitive dependencies | Dev dependencies | [Dependency graph][dependency-graph] | Position | [Detection Priority][detection-priority] |
+|-----------------|------------------|:-----------------------:|:----------------:|:------------------------------------:|:--------:|:----------------------------------------:|
+| pip             | requirements.txt |            -            |     Include      |                  -                   |    ✓     |                    -                     |
+| Pipenv          | Pipfile.lock     |            ✓            |     Include      |                  -                   |    ✓     |                Not needed                |
+| Poetry          | poetry.lock      |            ✓            |     Exclude      |                  ✓                   |    -     |                Not needed                |
 
 
 | Packaging | Dependency graph |
@@ -130,3 +130,4 @@ Trivy looks for `.dist-info/META-DATA` to identify Python packages.
 [^1]: Trivy checks `python`, `python3`, `python2` and `python.exe` file names.
 
 [dependency-graph]: ../../configuration/reporting.md#show-origins-of-vulnerable-dependencies
+[detection-priority]: ../../scanner/vulnerability.md#detection-priority
diff --git a/docs/docs/coverage/os/conda.md b/docs/docs/coverage/os/conda.md
@@ -8,6 +8,9 @@ Trivy supports the following scanners for Conda packages.
 | Vulnerability |     -     |
 |    License    |     ✓     |
 
+| Package manager | File            | Transitive dependencies | Dev dependencies | [Dependency graph][dependency-graph] | Position | [Detection Priority][detection-priority] |
+|-----------------|-----------------|:-----------------------:|:----------------:|:------------------------------------:|:--------:|:----------------------------------------:|
+| Conda           | environment.yml |            -            |     Include      |                  -                   |    ✓     |                    -                     |
 
 
 ## `<package>.json`
@@ -41,3 +44,5 @@ To correctly define licenses, make sure your `environment.yml`[^1] contains `pre
 [environment.yml]: https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#sharing-an-environment
 [env-version-range]: https://docs.conda.io/projects/conda-build/en/latest/resources/package-spec.html#examples-of-package-specs
 [prefix]: https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#specifying-a-location-for-an-environment
+[dependency-graph]: ../../configuration/reporting.md#show-origins-of-vulnerable-dependencies
+[detection-priority]: ../../scanner/vulnerability.md#detection-priority
diff --git a/docs/docs/references/configuration/cli/trivy_filesystem.md b/docs/docs/references/configuration/cli/trivy_filesystem.md
@@ -30,6 +30,10 @@ trivy filesystem [flags] PATH
       --custom-headers strings            custom headers in client mode
       --db-repository string              OCI repository to retrieve trivy-db from (default "ghcr.io/aquasecurity/trivy-db:2")
       --dependency-tree                   [EXPERIMENTAL] show dependency origin tree of vulnerable packages
+      --detection-priority string         specify the detection priority:
+                                            - "precise": Prioritizes precise by minimizing false positives.
+                                            - "comprehensive": Aims to detect more security findings at the cost of potential false positives.
+                                           (precise,comprehensive) (default "precise")
       --download-db-only                  download/update vulnerability database but don't run a scan
       --download-java-db-only             download/update Java index database but don't run a scan
       --enable-modules strings            [EXPERIMENTAL] module names to enable

diff --git a/docs/docs/references/configuration/cli/trivy_image.md b/docs/docs/references/configuration/cli/trivy_image.md
@@ -44,6 +44,10 @@ trivy image [flags] IMAGE_NAME
       --custom-headers strings            custom headers in client mode
       --db-repository string              OCI repository to retrieve trivy-db from (default "ghcr.io/aquasecurity/trivy-db:2")
       --dependency-tree                   [EXPERIMENTAL] show dependency origin tree of vulnerable packages
+      --detection-priority string         specify the detection priority:
+                                            - "precise": Prioritizes precise by minimizing false positives.
+                                            - "comprehensive": Aims to detect more security findings at the cost of potential false positives.
+                                           (precise,comprehensive) (default "precise")
       --docker-host string                unix domain socket path to use for docker scanning
       --download-db-only                  download/update vulnerability database but don't run a scan
       --download-java-db-only             download/update Java index database but don't run a scan

diff --git a/docs/docs/references/configuration/cli/trivy_kubernetes.md b/docs/docs/references/configuration/cli/trivy_kubernetes.md
@@ -39,6 +39,10 @@ trivy kubernetes [flags] [CONTEXT]
       --config-data strings               specify paths from which data for the Rego checks will be recursively loaded
       --db-repository string              OCI repository to retrieve trivy-db from (default "ghcr.io/aquasecurity/trivy-db:2")
       --dependency-tree                   [EXPERIMENTAL] show dependency origin tree of vulnerable packages
+      --detection-priority string         specify the detection priority:
+                                            - "precise": Prioritizes precise by minimizing false positives.
+                                            - "comprehensive": Aims to detect more security findings at the cost of potential false positives.
+                                           (precise,comprehensive) (default "precise")
       --disable-node-collector            When the flag is activated, the node-collector job will not be executed, thus skipping misconfiguration findings on the node.
       --download-db-only                  download/update vulnerability database but don't run a scan
       --download-java-db-only             download/update Java index database but don't run a scan

diff --git a/docs/docs/references/configuration/cli/trivy_repository.md b/docs/docs/references/configuration/cli/trivy_repository.md
@@ -30,6 +30,10 @@ trivy repository [flags] (REPO_PATH | REPO_URL)
       --custom-headers strings            custom headers in client mode
       --db-repository string              OCI repository to retrieve trivy-db from (default "ghcr.io/aquasecurity/trivy-db:2")
       --dependency-tree                   [EXPERIMENTAL] show dependency origin tree of vulnerable packages
+      --detection-priority string         specify the detection priority:
+                                            - "precise": Prioritizes precise by minimizing false positives.
+                                            - "comprehensive": Aims to detect more security findings at the cost of potential false positives.
+                                           (precise,comprehensive) (default "precise")
       --download-db-only                  download/update vulnerability database but don't run a scan
       --download-java-db-only             download/update Java index database but don't run a scan
       --enable-modules strings            [EXPERIMENTAL] module names to enable

diff --git a/docs/docs/references/configuration/cli/trivy_rootfs.md b/docs/docs/references/configuration/cli/trivy_rootfs.md
@@ -32,6 +32,10 @@ trivy rootfs [flags] ROOTDIR
       --custom-headers strings            custom headers in client mode
       --db-repository string              OCI repository to retrieve trivy-db from (default "ghcr.io/aquasecurity/trivy-db:2")
       --dependency-tree                   [EXPERIMENTAL] show dependency origin tree of vulnerable packages
+      --detection-priority string         specify the detection priority:
+                                            - "precise": Prioritizes precise by minimizing false positives.
+                                            - "comprehensive": Aims to detect more security findings at the cost of potential false positives.
+                                           (precise,comprehensive) (default "precise")
       --download-db-only                  download/update vulnerability database but don't run a scan
       --download-java-db-only             download/update Java index database but don't run a scan
       --enable-modules strings            [EXPERIMENTAL] module names to enable

diff --git a/docs/docs/references/configuration/cli/trivy_sbom.md b/docs/docs/references/configuration/cli/trivy_sbom.md
@@ -25,6 +25,10 @@ trivy sbom [flags] SBOM_PATH
       --compliance string           compliance report to generate
       --custom-headers strings      custom headers in client mode
       --db-repository string        OCI repository to retrieve trivy-db from (default "ghcr.io/aquasecurity/trivy-db:2")
+      --detection-priority string   specify the detection priority:
+                                      - "precise": Prioritizes precise by minimizing false positives.
+                                      - "comprehensive": Aims to detect more security findings at the cost of potential false positives.
+                                     (precise,comprehensive) (default "precise")
       --download-db-only            download/update vulnerability database but don't run a scan
       --download-java-db-only       download/update Java index database but don't run a scan
       --exit-code int               specify exit code when any security issues are found

diff --git a/docs/docs/references/configuration/cli/trivy_vm.md b/docs/docs/references/configuration/cli/trivy_vm.md
@@ -28,6 +28,10 @@ trivy vm [flags] VM_IMAGE
       --custom-headers strings            custom headers in client mode
       --db-repository string              OCI repository to retrieve trivy-db from (default "ghcr.io/aquasecurity/trivy-db:2")
       --dependency-tree                   [EXPERIMENTAL] show dependency origin tree of vulnerable packages
+      --detection-priority string         specify the detection priority:
+                                            - "precise": Prioritizes precise by minimizing false positives.
+                                            - "comprehensive": Aims to detect more security findings at the cost of potential false positives.
+                                           (precise,comprehensive) (default "precise")
       --download-db-only                  download/update vulnerability database but don't run a scan
       --download-java-db-only             download/update Java index database but don't run a scan
       --enable-modules strings            [EXPERIMENTAL] module names to enable