gitea-mirror/trivy
1
0
Fork 0
mirror of https://github.com/aquasecurity/trivy.git synced 2025-12-12 15:50:15 -08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
Signed-off-by: knqyf263 <knqyf263@gmail.com>
This commit is contained in:
Teppei Fukuda
2024-08-02 14:41:56 +04:00
committed by GitHub
parent e95152f796
commit fd8348d610
30 changed files with 675 additions and 221 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/docs/coverage/language/dart.md
View File

@@ -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,6 +42,7 @@ 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.
@@ -47,3 +50,4 @@ To build `dependency tree` Trivy parses [cache directory][cache-directory]. Curr
[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

9
docs/docs/coverage/language/golang.md
View File

@@ -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

13
docs/docs/coverage/language/java.md
View File

@@ -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

11
docs/docs/coverage/language/python.md
View File

@@ -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

5
docs/docs/coverage/os/conda.md
View File

@@ -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

4
docs/docs/references/configuration/cli/trivy_filesystem.md
View File

@@ -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

4
docs/docs/references/configuration/cli/trivy_image.md
View File

@@ -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

4
docs/docs/references/configuration/cli/trivy_kubernetes.md
View File

@@ -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

4
docs/docs/references/configuration/cli/trivy_repository.md
View File

@@ -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

4
docs/docs/references/configuration/cli/trivy_rootfs.md
View File

@@ -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

4
docs/docs/references/configuration/cli/trivy_sbom.md
View File

@@ -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

4
docs/docs/references/configuration/cli/trivy_vm.md
View File

@@ -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

73
docs/docs/scanner/vulnerability.md
View File

@@ -198,6 +198,54 @@ The default is `ghcr.io/aquasecurity/trivy-java-db`.
If authentication is required, you need to run `docker login YOUR_REGISTRY`.
Currently, specifying a username and password is not supported.
## Detection Behavior
Trivy prioritizes precision in vulnerability detection, aiming to minimize false positives while potentially accepting some false negatives.
This approach is particularly relevant in two key areas:
- Handling Software Installed via OS Packages
- Handling Packages with Unspecified Versions
### Handling Software Installed via OS Packages
For files installed by OS package managers, such as `apt`, Trivy exclusively uses advisories from the OS vendor.
This means that even if a JAR file is present in a container image, if it was installed via an OS package manager (e.g., `apt`), Trivy will not analyze the JAR file itself and use upstream security advisories.
For example, consider the Python `requests` package in Red Hat Universal Base Image 8:
```bash
[root@987ee49dc93d /]# head -n 3 /usr/lib/python3.6/site-packages/requests-2.20.0-py3.6.egg-info/PKG-INFO
Metadata-Version: 2.1
Name: requests
Version: 2.20.0
```
Version 2.20.0 is installed, and this package is installed by `dnf`.
```bash
[root@987ee49dc93d /]# rpm -ql python3-requests | grep PKG-INFO
/usr/lib/python3.6/site-packages/requests-2.20.0-py3.6.egg-info/PKG-INFO
```
At first glance, this might seem vulnerable to [CVE-2023-32681], which affects versions of requests prior to v2.31.0.
However, Red Hat backported the fix to v2.20.0-3 in [RHSA-2023:4520], and the package is not vulnerable.
- Upstream (PyPI [requests]): Fixed in v2.31.0
- Red Hat (`python-requests`): Backported fix applied in v2.20.0-3 (RHSA-2023:4520)
If Trivy were to detect CVE-2023-32681 in this case, it would be a false positive.
This illustrates why using the correct security advisory is crucial to avoid false detections.
To minimize false positives, Trivy trusts the OS vendor's advisory for software installed via OS package managers and does not use upstream advisories for these packages.
However, this approach may lead to false negatives if the OS vendor's advisories are delayed or missing.
In such cases, using [--detection-priority comprehensive](#detection-priority) allows Trivy to consider upstream advisories (e.g., [GitHub Advisory Database][ghsa]), potentially increasing false positives but reducing false negatives.
### Handling Packages with Unspecified Versions
When a package version cannot be uniquely determined (e.g., `package-a: ">=3.0"`), Trivy typically skips vulnerability detection for that package to avoid false positives.
If a lock file is present with fixed versions, Trivy will use those for detection.
To detect potential vulnerabilities even with unspecified versions, use [--detection-priority comprehensive](#detection-priority).
This option makes Trivy use the minimum version in the specified range for vulnerability detection.
While this may increase false positives if the actual version used is not the minimum, it helps reduce false negatives.
## Configuration
This section describes vulnerability-specific configuration.
Other common options are documented [here](../configuration/index.md).
@@ -307,6 +355,25 @@ By default, all relationships are included in the scan.
!!! warning
As it may not provide a complete package list, `--pkg-relationships` cannot be used with `--dependency-tree`, `--vex` or SBOM generation.
### Detection Priority
Trivy provides a `--detection-priority` flag to control the balance between false positives and false negatives in vulnerability detection.
This concept is similar to the relationship between [precision and recall][precision-recall] in machine learning evaluation.
```bash
$ trivy image --detection-priority {precise|comprehensive} alpine:3.15
```
- `precise`: This mode prioritizes reducing false positives. It results in less noisy vulnerability reports but may miss some potential vulnerabilities.
- `comprehensive`: This mode aims to detect more vulnerabilities, potentially including some that might be false positives.
It provides broader coverage but may increase the noise in the results.
The default value is `precise`. Also refer to the [detection behavior](#detection-behavior) section for more information.
Regardless of the chosen mode, user review of detected vulnerabilities is crucial:
- `precise`: Review thoroughly, considering potential missed vulnerabilities.
- `comprehensive`: Carefully investigate each reported vulnerability due to increased false positive possibility.
[^1]: https://github.com/GoogleContainerTools/distroless
@@ -353,3 +420,9 @@ By default, all relationships are included in the scan.
[nvd]: https://nvd.nist.gov/vuln
[k8s-cve]: https://kubernetes.io/docs/reference/issues-security/official-cve-feed/
[CVE-2023-32681]: https://nvd.nist.gov/vuln/detail/CVE-2023-32681
[RHSA-2023:4520]: https://access.redhat.com/errata/RHSA-2023:4520
[ghsa]: https://github.com/advisories
[requests]: https://pypi.org/project/requests/
[precision-recall]: https://developers.google.com/machine-learning/crash-course/classification/precision-and-recall