# Vulnerability Scanning
Trivy detects known vulnerabilities in software components that it finds in the scan target.
The following are supported:
- [OS packages](#os-packages)
- [Language-specific packages](#language-specific-packages)
- [Non-packaged software](#non-packaged-software)
- [Kubernetes components](#kubernetes)
## OS Packages
Trivy is capable of automatically detecting installed OS packages when scanning container images, VM images and running hosts.
!!! note
Trivy doesn't support third-party/self-compiled packages/binaries, but official packages provided by vendors such as Red Hat and Debian.
### Supported OS
See [here](../coverage/os/index.md#supported-os) for the supported OSes.
### Data Sources
| OS | Source |
|---------------------------|--------------------------------------------------------------|
| Arch Linux | [Vulnerable Issues][arch] |
| Alpine Linux | [secdb][alpine] |
| Wolfi Linux | [secdb][wolfi] |
| Chainguard | [secdb][chainguard] |
| MinimOS | [secdb][minimos] |
| Amazon Linux | [Amazon Linux Security Center][amazon] |
| Echo | [Echo][echo] |
| Debian | [Security Bug Tracker][debian-tracker] / [OVAL][debian-oval] |
| Ubuntu | [Ubuntu CVE Tracker][ubuntu] |
| RHEL/CentOS | [OVAL][rhel-oval] / [Security Data][rhel-api] |
| AlmaLinux | [AlmaLinux Product Errata][alma] |
| Rocky Linux | [Rocky Linux UpdateInfo][rocky] |
| Oracle Linux | [OVAL][oracle] |
| Azure Linux (CBL-Mariner) | [OVAL][azure] |
| OpenSUSE/SLES | [CVRF][suse] |
| Photon OS | [Photon Security Advisory][photon] |
| Root.io | [Root.io Patch Feed][rootio] |
| Seal Security | [Seal Security vulnerability feed][seal] |
#### Data Source Selection
Trivy **only** consumes security advisories from the sources listed in the above table.
As for packages installed from OS package managers (`dpkg`, `yum`, `apk`, etc.), Trivy uses the advisory database from the appropriate **OS vendor**.
For example: for a python package installed from `yum` (Amazon linux), Trivy will only get advisories from [ALAS][amazon].
But for a python package installed from another source (e.g. `pip`), Trivy will get advisories from the `GitLab` and `GitHub` databases.
This advisory selection is essential to avoid getting false positives because OS vendors usually backport upstream fixes, and the fixed version can be different from the upstream fixed version.
#### Severity Selection
The severity is taken from the selected data source since the severity from vendors is more accurate.
Using CVE-2023-0464 as an example, while it is [rated as "HIGH" in NVD][nvd-CVE-2023-0464], Red Hat has marked its 'Impact' as ["Low"][redhat-CVE-2023-0464].
As a result, Trivy will display it as "Low".
The severity depends on the compile option, the default configuration, etc.
NVD doesn't know how the vendor distributes the software.
Red Hat evaluates the severity more accurately.
That's why Trivy prefers vendor scores over NVD.
If the data source does not provide a severity, the severity is determined based on the CVSS score as follows:
| Base Score Range | Severity |
| ---------------- | -------- |
| 0.1-3.9 | Low |
| 4.0-6.9 | Medium |
| 7.0-8.9 | High |
| 9.0-10.0 | Critical |
If the CVSS score is also not provided, it falls back to [NVD][nvd].
NVD and some vendors may delay severity analysis, while other vendors, such as Red Hat, are able to quickly evaluate and announce the severity of vulnerabilities.
To avoid marking too many vulnerabilities as "UNKNOWN" severity, Trivy uses severity ratings from other vendors when the NVD information is not yet available.
The order of preference for vendor severity data can be found [here](https://github.com/aquasecurity/trivy-db/blob/79d0fbd1e246f3c77eef4b9826fe4bf65940b221/pkg/vulnsrc/vulnerability/vulnerability.go#L17-L19).
You can reference `SeveritySource` in the [JSON reporting format](../configuration/reporting.md#json) to see from where the severity is taken for a given vulnerability.
```shell
"SeveritySource": "debian",
```
In addition, you can see all the vendor severity ratings.
```json
"VendorSeverity": {
"amazon": 2,
"cbl-mariner": 4,
"ghsa": 4,
"nvd": 4,
"photon": 4,
"redhat": 2,
"ubuntu": 2
}
```
Here is the severity mapping in Trivy:
| Number | Severity |
|:------:|----------|
| 0 | Unknown |
| 1 | Low |
| 2 | Medium |
| 3 | High |
| 4 | Critical |
If no vendor has a severity, the `UNKNOWN` severity will be used.
### Unfixed Vulnerabilities
The unfixed/unfixable vulnerabilities mean that the patch has not yet been provided on their distribution.
To hide unfixed/unfixable vulnerabilities, you can use the `--ignore-unfixed` flag.
## Language-specific Packages
### Supported Languages
See [here](../coverage/language/index.md#supported-languages) for the supported languages.
### Data Sources { #langpkg-data-sources }
| Language | Source | Commercial Use | Delay[^1] |
|----------|-----------------------------------------------------|:--------------:|:---------:|
| PHP | [PHP Security Advisories Database][php] | ✅ | - |
| | [GitHub Advisory Database (Composer)][php-ghsa] | ✅ | - |
| Python | [GitHub Advisory Database (pip)][python-ghsa] | ✅ | - |
| Ruby | [Ruby Advisory Database][ruby] | ✅ | - |
| | [GitHub Advisory Database (RubyGems)][ruby-ghsa] | ✅ | - |
| Node.js | [Ecosystem Security Working Group][nodejs] | ✅ | - |
| | [GitHub Advisory Database (npm)][nodejs-ghsa] | ✅ | - |
| Java | [GitHub Advisory Database (Maven)][java-ghsa] | ✅ | - |
| Go | [GitHub Advisory Database (Go)][go-ghsa] | ✅ | - |
| | [Go Vulnerability Database][go-vulndb] | ✅ | - |
| Rust | [Open Source Vulnerabilities (crates.io)][rust-osv] | ✅ | - |
| .NET | [GitHub Advisory Database (NuGet)][dotnet-ghsa] | ✅ | - |
| C/C++ | [GitLab Advisories Community][gitlab] | ✅ | 1 month |
| Dart | [GitHub Advisory Database (Pub)][pub-ghsa] | ✅ | - |
| Elixir | [GitHub Advisory Database (Erlang)][erlang-ghsa] | ✅ | - |
| Swift | [GitHub Advisory Database (Swift)][swift-ghsa] | ✅ | - |
[^1]: Intentional delay between vulnerability disclosure and registration in the DB
## Non-packaged software
If you have software that is not managed by a package manager, Trivy can still detect vulnerabilities in it in some cases:
- [Using SBOM from Sigstore Rekor](../supply-chain/attestation/rekor.md#non-packaged-binaries)
- [Go Binaries with embedded module information](../coverage/language/golang.md#go-binary)
- [Rust Binaries with embedded information](../coverage/language/rust.md#binaries)
- [SBOM embedded in container images](../supply-chain/sbom.md#sbom-detection-inside-targets)
## 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-software-installed-via-os-packages)
- [Handling Packages with Unspecified Versions](#handling-packages-with-unspecified-versions)
Trivy can also detect only specific packages:
- [Subset of Package Types](#enabling-a-subset-of-package-types)
- [Specific package Relationship](#filtering-by-package-relationships)
### 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.
## Package Detection
Vulnerability detection is based on package detection.
This section describes the specifics of package detection, which also affect SBOM generation.
### Detection Priority
Trivy provides a `--detection-priority` flag to control the balance between false positives and false negatives in package/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.
### 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.
Available values:
- os
- Scan OS packages managed by the OS package manager (e.g. `dpkg`, `yum`, `apk`).
- library
- Scan language-specific packages (e.g. packages installed by `pip`, `npm`, or `gem`).
```bash
$ trivy image --pkg-types os ruby:2.4.0
```
Result
```bash
2019-05-22T19:36:50.530+0200 [34mINFO[0m Updating vulnerability database...
2019-05-22T19:36:51.681+0200 [34mINFO[0m Detecting Alpine vulnerabilities...
2019-05-22T19:36:51.685+0200 [34mINFO[0m Updating npm Security DB...
2019-05-22T19:36:52.389+0200 [34mINFO[0m Detecting npm vulnerabilities...
2019-05-22T19:36:52.390+0200 [34mINFO[0m Updating pipenv Security DB...
2019-05-22T19:36:53.406+0200 [34mINFO[0m Detecting pipenv vulnerabilities...
ruby:2.4.0 (debian 8.7)
=======================
Total: 7 (UNKNOWN: 0, LOW: 1, MEDIUM: 1, HIGH: 3, CRITICAL: 2)
+---------+------------------+----------+-------------------+---------------+----------------------------------+
| LIBRARY | VULNERABILITY ID | SEVERITY | INSTALLED VERSION | FIXED VERSION | TITLE |
+---------+------------------+----------+-------------------+---------------+----------------------------------+
| curl | CVE-2018-14618 | CRITICAL | 7.61.0-r0 | 7.61.1-r0 | curl: NTLM password overflow |
| | | | | | via integer overflow |
+ +------------------+----------+ +---------------+----------------------------------+
| | CVE-2018-16839 | HIGH | | 7.61.1-r1 | curl: Integer overflow leading |
| | | | | | to heap-based buffer overflow in |
| | | | | | Curl_sasl_create_plain_message() |
+---------+------------------+----------+-------------------+---------------+----------------------------------+
| git | CVE-2018-17456 | HIGH | 2.15.2-r0 | 2.15.3-r0 | git: arbitrary code execution |
| | | | | | via .gitmodules |
+ +------------------+ + + +----------------------------------+
| | CVE-2018-19486 | | | | git: Improper handling of |
| | | | | | PATH allows for commands to be |
| | | | | | executed from... |
+---------+------------------+----------+-------------------+---------------+----------------------------------+
| libssh2 | CVE-2019-3855 | CRITICAL | 1.8.0-r2 | 1.8.1-r0 | libssh2: Integer overflow in |
| | | | | | transport read resulting in |
| | | | | | out of bounds write... |
+---------+------------------+----------+-------------------+---------------+----------------------------------+
| sqlite | CVE-2018-20346 | MEDIUM | 3.21.0-r1 | 3.25.3-r0 | CVE-2018-20505 CVE-2018-20506 |
| | | | | | sqlite: Multiple flaws in |
| | | | | | sqlite which can be triggered |
| | | | | | via... |
+---------+------------------+----------+-------------------+---------------+----------------------------------+
| tar | CVE-2018-20482 | LOW | 1.29-r1 | 1.31-r0 | tar: Infinite read loop in |
| | | | | | sparse_dump_region function in |
| | | | | | sparse.c |
+---------+------------------+----------+-------------------+---------------+----------------------------------+
```
!!! info
This flag filters the packages themselves, so it also affects the list of detected packages in JSON reports 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. `workspace`: Workspaces of the root package (Currently only `pom.xml`, `yarn.lock` and `cargo.lock` files are supported)
3. `direct`: Direct dependencies of the root/workspace package
4. `indirect`: Transitive dependencies
5. `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 /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 of detected packages in JSON reports 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.
## Kubernetes
Trivy can detect vulnerabilities in Kubernetes clusters and components by scanning a Kubernetes Cluster, or a KBOM (Kubernetes bill of Material). To learn more, see the [documentation for Kubernetes scanning](../target/kubernetes.md).
### Data Sources
| Vendor | Source |
|------------|---------------------------------------------|
| Kubernetes | [Kubernetes Official CVE feed][k8s-cve][^1] |
[^1]: Some manual triage and correction has been made.
## Databases
The information from the above sources is collected and stored in databases that Trivy uses for vulnerability scanning. Trivy automatically fetches, maintains, and caches the relevant databases when performing a vulnerability scan
For more information about Trivy's Databases mechanism and configurations, refer to the [Databases document](../configuration/db.md).
## Configuration
This section describes vulnerability-specific configuration.
Other common options are documented [here](../configuration/index.md).
### Overriding OS version
By default, Trivy automatically detects the OS during container image scanning and performs vulnerability detection based on that OS.
However, in some cases, you may want to scan an image with a different OS version than the one detected.
Also, you may want to specify the OS version when OS is not detected.
For these cases, Trivy supports a `--distro` flag using the `/` format (e.g. `alpine/3.20`) to set the desired OS version.
### Severity selection
By default, Trivy automatically detects severity (as described [here](#severity-selection)).
But there are cases when you may want to use your own source priority. Trivy supports the `--vuln-severity-source` flag for this.
Fill in a list of required sources, and Trivy will check the sources in that order until it finds an existing severity.
If no source has the severity - Trivy will use the `UNKNOWN` severity.
!!! note
To use the default logic in combination with your sources - use the `auto` value.
Example logic for the following vendor severity levels when scanning an Alpine image:
```json
"VendorSeverity": {
"ghsa": 3,
"nvd": 4,
}
```
- `--vuln-severity-source auto,nvd` - severity is `CRITICAL`, got from `auto`.
- `--vuln-severity-source alpine,auto` - severity is `CRITICAL`, got from `auto`.
- `--vuln-severity-source alpine,ghsa` - severity is `HIGH`, got from `ghsa`.
- `--vuln-severity-source alpine,alma` - severity is `UNKNOWN`.
[^1]: https://github.com/GoogleContainerTools/distroless
[nvd-CVE-2023-0464]: https://nvd.nist.gov/vuln/detail/CVE-2023-0464
[redhat-CVE-2023-0464]: https://access.redhat.com/security/cve/cve-2023-0464
[arch]: https://security.archlinux.org/
[alpine]: https://secdb.alpinelinux.org/
[wolfi]: https://packages.wolfi.dev/os/security.json
[chainguard]: https://packages.cgr.dev/chainguard/security.json
[minimos]: https://packages.mini.dev/advisories/secdb/security.json
[amazon]: https://alas.aws.amazon.com/
[echo]: https://advisory.echohq.com/data.json
[debian-tracker]: https://security-tracker.debian.org/tracker/
[debian-oval]: https://www.debian.org/security/oval/
[ubuntu]: https://ubuntu.com/security/cve
[rhel-oval]: https://www.redhat.com/security/data/oval/v2/
[rhel-api]: https://www.redhat.com/security/data/metrics/
[alma]: https://errata.almalinux.org/
[rocky]: https://download.rockylinux.org/pub/rocky/
[oracle]: https://linux.oracle.com/security/oval/
[suse]: http://ftp.suse.com/pub/projects/security/cvrf/
[photon]: https://packages.vmware.com/photon/photon_cve_metadata/
[azure]: https://github.com/microsoft/AzureLinuxVulnerabilityData/
[rootio]: https://api.root.io/external/patch_feed
[seal]: http://vulnfeed.sealsecurity.io/v1/osv/renamed/vulnerabilities.zip
[php-ghsa]: https://github.com/advisories?query=ecosystem%3Acomposer
[python-ghsa]: https://github.com/advisories?query=ecosystem%3Apip
[ruby-ghsa]: https://github.com/advisories?query=ecosystem%3Arubygems
[nodejs-ghsa]: https://github.com/advisories?query=ecosystem%3Anpm
[java-ghsa]: https://github.com/advisories?query=ecosystem%3Amaven
[dotnet-ghsa]: https://github.com/advisories?query=ecosystem%3Anuget
[pub-ghsa]: https://github.com/advisories?query=ecosystem%3Apub
[erlang-ghsa]: https://github.com/advisories?query=ecosystem%3Aerlang
[go-ghsa]: https://github.com/advisories?query=ecosystem%3Ago
[swift-ghsa]: https://github.com/advisories?query=ecosystem%3Aswift
[go-vulndb]: https://pkg.go.dev/vuln/
[php]: https://github.com/FriendsOfPHP/security-advisories
[ruby]: https://github.com/rubysec/ruby-advisory-db
[nodejs]: https://github.com/nodejs/security-wg
[gitlab]: https://gitlab.com/gitlab-org/advisories-community
[python-osv]: https://osv.dev/list?q=&ecosystem=PyPI
[rust-osv]: https://osv.dev/list?q=&ecosystem=crates.io
[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