mirror of
https://github.com/aquasecurity/trivy.git
synced 2025-12-12 15:50:15 -08:00
docs: improve databases documentation (#7732)
Signed-off-by: knqyf263 <knqyf263@gmail.com> Co-authored-by: simar7 <1254783+simar7@users.noreply.github.com> Co-authored-by: knqyf263 <knqyf263@gmail.com> Co-authored-by: wkoot <3715211+wkoot@users.noreply.github.com>
This commit is contained in:
Itay Shakury
@@ -1,162 +1,77 @@
|
||||
# Advanced Network Scenarios
|
||||
# Connectivity and Network considerations
|
||||
|
||||
Trivy needs to connect to the internet occasionally in order to download relevant content. This document explains the network connectivity requirements of Trivy and setting up Trivy in particular scenarios.
|
||||
Trivy requires internet connectivity in order to function normally. If your organizations blocks or restricts network traffic, that could prevent Trivy from working correctly.
|
||||
This document explains Trivy's network connectivity requirements, and how to configure Trivy to work in restricted networks environments, including completely air-gapped environments.
|
||||
|
||||
## Network requirements
|
||||
The following table lists all external resources that are required by Trivy:
|
||||
|
||||
Trivy's databases are distributed as OCI images via GitHub Container registry (GHCR):
|
||||
External Resource | Feature | Details
|
||||
--- | --- | ---
|
||||
Vulnerability Database | Vulnerability scanning | [Trivy DB](../scanner/vulnerability.md)
|
||||
Java Vulnerability Database | Java vulnerability scanning | [Trivy Java DB](../coverage/language/java.md)
|
||||
Checks Bundle | Misconfigurations scanning | [Trivy Checks](../scanner/misconfiguration/check/builtin.md)
|
||||
VEX Hub | VEX Hub | [VEX Hub](../supply-chain/vex/repo/#vex-hub)
|
||||
Maven Central / Remote Repositories | Java vulnerability scanning | [Java Scanner/Remote Repositories](../coverage/language/java.md#remote-repositories)
|
||||
|
||||
- <https://ghcr.io/aquasecurity/trivy-db>
|
||||
- <https://ghcr.io/aquasecurity/trivy-java-db>
|
||||
- <https://ghcr.io/aquasecurity/trivy-checks>
|
||||
!!! note
|
||||
Trivy is an open source project that relies on public free infrastructure. In case of extreme load, you may encounter rate limiting when Trivy attempts to connect to external resources.
|
||||
|
||||
The following hosts are required in order to fetch them:
|
||||
The rest of this document details each resource's connectivity requirements and network related considerations.
|
||||
|
||||
- `ghcr.io`
|
||||
- `pkg-containers.githubusercontent.com`
|
||||
## OCI Databases
|
||||
|
||||
The databases are pulled by Trivy using the [OCI Distribution](https://github.com/opencontainers/distribution-spec) specification, which is a simple HTTPS-based protocol.
|
||||
Trivy's Vulnerability, Java, and Checks Bundle are packaged as OCI images and stored in public container registries.
|
||||
|
||||
[VEX Hub](https://github.com/aquasecurity/vexhub) is distributed from GitHub over HTTPS.
|
||||
The following hosts are required in order to fetch it:
|
||||
### Connectivity requirements
|
||||
|
||||
The specific registries and locations are detailed in the [databases document](../configuration/db.md).
|
||||
|
||||
Communication with OCI Registries follows the [OCI Distribution](https://github.com/opencontainers/distribution-spec) spec.
|
||||
|
||||
The following hosts are known to be used by the default container registries:
|
||||
|
||||
Registry | Hosts | Additional info
|
||||
--- | --- | ---
|
||||
Google Artifact Registry | <ul><li>`mirror.gcr.io`</li><li>`googlecode.l.googleusercontent.com`</li></ul> | [Google's IP addresses](https://support.google.com/a/answer/10026322?hl=en)
|
||||
GitHub Container Registry | <ul><li>`ghcr.io`</li><li>`pkg-containers.githubusercontent.com`</li></ul> | [GitHub's IP addresses](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-githubs-ip-addresses)
|
||||
|
||||
### Self-hosting
|
||||
|
||||
You can host Trivy's databases in your own container registry. Please refer to [Self-hosting document](./self-hosting.md#oci-databases) for a detailed guide.
|
||||
|
||||
## Embedded Checks
|
||||
|
||||
Checks Bundle is embedded in the Trivy binary (at build time), and will be used as a fallback if the external database is not available. This means that you can still scan for misconfigurations in an air-gapped environment using the database from the time of the Trivy release you are using.
|
||||
|
||||
## VEX Hub
|
||||
|
||||
### Connectivity Requirements
|
||||
|
||||
VEX Hub is hosted as at <https://github.com/aquasecurity/vexhub>.
|
||||
|
||||
Trivy is fetching VEX Hub GitHub Repository directly using simple HTTPS requests.
|
||||
|
||||
The following hosts are known to be used by GitHub's services:
|
||||
|
||||
- `api.github.com`
|
||||
- `codeload.github.com`
|
||||
|
||||
## Running Trivy in air-gapped environment
|
||||
For more information about GitHub connectivity (including specific IP addresses), please refer to [GitHub's connectivity troubleshooting guide](https://docs.github.com/en/get-started/using-github/troubleshooting-connectivity-problems).
|
||||
|
||||
An air-gapped environment refers to situations where the network connectivity from the machine Trivy runs on is blocked or restricted.
|
||||
### Self-hosting
|
||||
|
||||
In an air-gapped environment it is your responsibility to update the Trivy databases on a regular basis.
|
||||
You can host a copy of VEX Hub on your own internal server. Please refer to the [self-hosting document](./self-hosting.md#vex-hub) for a detailed guide.
|
||||
|
||||
## Offline Mode
|
||||
## Maven Central / Remote Repositories
|
||||
|
||||
By default, Trivy will attempt to download latest databases. If it fails, the scan might fail. To avoid this behavior, you can tell Trivy to not attempt to download database files:
|
||||
Trivy might call out to Maven central or other remote repositories to fetch in order to correctly identify Java packages during a vulnerability scan.
|
||||
|
||||
- `--skip-db-update` to skip updating the main vulnerability database.
|
||||
- `--skip-java-db-update` to skip updating the Java vulnerability database.
|
||||
- `--skip-check-update` to skip updating the misconfiguration database.
|
||||
### Connectivity requirements
|
||||
|
||||
```shell
|
||||
trivy image --skip-db-update --skip-java-db-update --offline-scan --skip-check-update myimage
|
||||
```
|
||||
Trivy might attempt to connect (over HTTPS) to the following URLs:
|
||||
|
||||
## Self-Hosting
|
||||
- `https://repo.maven.apache.org/maven2`
|
||||
|
||||
### OCI Databases
|
||||
### Offline mode
|
||||
|
||||
You can host the databases on your own local OCI registry.
|
||||
|
||||
First, make a copy of the databases in a container registry that is accessible to Trivy. The databases are in:
|
||||
|
||||
- `ghcr.io/aquasecurity/trivy-db:2`
|
||||
- `ghcr.io/aquasecurity/trivy-java-db:1`
|
||||
- `ghcr.io/aquasecurity/trivy-checks:0`
|
||||
|
||||
Then, tell Trivy to use the local registry:
|
||||
|
||||
```shell
|
||||
trivy image \
|
||||
--db-repository myregistry.local/trivy-db \
|
||||
--java-db-repository myregistry.local/trivy-java-db \
|
||||
--checks-bundle-repository myregistry.local/trivy-checks \
|
||||
myimage
|
||||
```
|
||||
|
||||
#### Authentication
|
||||
|
||||
If the registry requires authentication, you can configure it as described in the [private registry authentication document](../advanced/private-registries/index.md).
|
||||
|
||||
### VEX Hub
|
||||
|
||||
You can host a copy of VEX Hub on your own internal server.
|
||||
|
||||
First, make a copy of VEX Hub in a location that is accessible to Trivy.
|
||||
|
||||
1. Download the [VEX Hub](https://github.com/aquasecurity/vexhub) archive from: <https://github.com/aquasecurity/vexhub/archive/refs/heads/main.zip>.
|
||||
1. Download the [VEX Hub Repository Manifest](https://github.com/aquasecurity/vex-repo-spec#2-repository-manifest) file from: <https://github.com/aquasecurity/vexhub/blob/main/vex-repository.json>.
|
||||
1. Create or identify an internal HTTP server that can serve the VEX Hub repository in your environment (e.g `https://server.local`).
|
||||
1. Make the downloaded archive file available for serving from your server (e.g `https://server.local/main.zip`).
|
||||
1. Modify the downloaded manifest file's [Location URL](https://github.com/aquasecurity/vex-repo-spec?tab=readme-ov-file#locations-subfields) field to the URL of the archive file on your server (e.g `url: https://server.local/main.zip`).
|
||||
1. Make the manifest file available for serving from your server under the `/.well-known` path (e.g `https://server.local/.well-known/vex-repository.json`).
|
||||
|
||||
Then, tell Trivy to use the local VEX Repository:
|
||||
|
||||
1. Locate your [Trivy VEX configuration file](../supply-chain/vex/repo/#configuration-file) by running `trivy vex repo init`. Make the following changes to the file.
|
||||
1. Disable the default VEX Hub repo (`enabled: false`)
|
||||
1. Add your internal VEX Hub repository as a [custom repository](../supply-chain/vex/repo/#custom-repositories) with the URL pointing to your local server (e.g `url: https://server.local`).
|
||||
|
||||
#### Authentication
|
||||
|
||||
If your server requires authentication, you can configure it as described in the [VEX Repository Authentication document](../supply-chain/vex/repo/#authentication).
|
||||
|
||||
## Manual cache population
|
||||
|
||||
You can also download the databases files manually and surgically populate the Trivy cache directory with them.
|
||||
|
||||
### Downloading the DB files
|
||||
|
||||
On a machine with internet access, pull the database container archive from the public registry into your local workspace:
|
||||
|
||||
Note that these examples operate in the current working directory.
|
||||
|
||||
=== "Using ORAS"
|
||||
This example uses [ORAS](https://oras.land), but you can use any other container registry manipulation tool.
|
||||
|
||||
```shell
|
||||
oras pull ghcr.io/aquasecurity/trivy-db:2
|
||||
```
|
||||
|
||||
You should now have a file called `db.tar.gz`. Next, extract it to reveal the db files:
|
||||
|
||||
```shell
|
||||
tar -xzf db.tar.gz
|
||||
```
|
||||
|
||||
You should now have 2 new files, `metadata.json` and `trivy.db`. These are the Trivy DB files.
|
||||
|
||||
=== "Using Trivy"
|
||||
This example uses Trivy to pull the database container archive. The `--cache-dir` flag makes Trivy download the database files into our current working directory. The `--download-db-only` flag tells Trivy to only download the database files, not to scan any images.
|
||||
|
||||
```shell
|
||||
trivy image --cache-dir . --download-db-only
|
||||
```
|
||||
|
||||
You should now have 2 new files, `metadata.json` and `trivy.db`. These are the Trivy DB files, copy them over to the air-gapped environment.
|
||||
|
||||
### Populating the Trivy Cache
|
||||
|
||||
In order to populate the cache, you need to identify the location of the cache directory. If it is under the default location, you can run the following command to find it:
|
||||
|
||||
```shell
|
||||
trivy -h | grep cache
|
||||
```
|
||||
|
||||
For the example, we will assume the `TRIVY_CACHE_DIR` variable holds the cache location:
|
||||
|
||||
```shell
|
||||
TRIVY_CACHE_DIR=/home/user/.cache/trivy
|
||||
```
|
||||
|
||||
Put the Trivy DB files in the Trivy cache directory under a `db` subdirectory:
|
||||
|
||||
```shell
|
||||
# ensure cache db directory exists
|
||||
mkdir -p ${TRIVY_CACHE_DIR}/db
|
||||
# copy the db files
|
||||
cp /path/to/trivy.db /path/to/metadata.json ${TRIVY_CACHE_DIR}/db/
|
||||
```
|
||||
|
||||
### Java DB
|
||||
|
||||
For Java DB the process is the same, except for the following:
|
||||
|
||||
1. Image location is `ghcr.io/aquasecurity/trivy-java-db:1`
|
||||
2. Archive file name is `javadb.tar.gz`
|
||||
3. DB file name is `trivy-java.db`
|
||||
|
||||
## Misconfigurations scanning
|
||||
|
||||
Note that the misconfigurations checks bundle is also embedded in the Trivy binary (at build time), and will be used as a fallback if the external database is not available. This means that you can still scan for misconfigurations in an air-gapped environment using the Checks from the time of the Trivy release you are using.
|
||||
|
||||
The misconfiguration scanner can be configured to load checks from a local directory, using the `--config-check` flag. In an air-gapped scenario you can copy the checks library from [Trivy checks repository](https://github.com/aquasecurity/trivy-checks) into a local directory, and load it with this flag. See more in the [Misconfiguration scanner documentation](../scanner/misconfiguration/index.md).
|
||||
There's no way to leverage Maven Central in a network-restricted environment, but you can prevent Trivy from trying to connect to it by using the `--offline-scan` flag.
|
||||
|
||||
132
docs/docs/advanced/self-hosting.md
Normal file
132
docs/docs/advanced/self-hosting.md
Normal file
@@ -0,0 +1,132 @@
|
||||
# Self-Hosting Trivy's Databases
|
||||
|
||||
This document explains how to host Trivy's [external dependencies](./air-gap.md) in your own infrastructure to prevent external network access. If you haven't already, please familiarize yourself with the [Databases document](../configuration/db.md) that explains about the different databases used by Trivy and the different configuration options that control them. This guide assumes you are already familiar with the concepts explained there.
|
||||
|
||||
## OCI databases
|
||||
|
||||
The following [Trivy Databases](../configuration/db.md) are packaged as OCI images:
|
||||
|
||||
- `trivy-db`
|
||||
- `trivy-java-db`
|
||||
- `trivy-checks`
|
||||
|
||||
To host these databases in your own infrastructure:
|
||||
|
||||
### Make a local copy
|
||||
|
||||
Use any container registry manipulation tool (e.g , [crane](https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane.md, [ORAS](https://oras.land), [regclient](https://github.com/regclient/regclient/tree/main)) to copy the images to your destination registry.
|
||||
|
||||
!!! note
|
||||
You will need to keep the databases updated in order to maintain relevant scanning results over time.
|
||||
|
||||
### Configure Trivy
|
||||
|
||||
Use the appropriate [database location flags](../configuration/db.md#database-locations) to change the db-repository location:
|
||||
|
||||
- `--db-repository`
|
||||
- `--java-db-repository`
|
||||
- `--checks-bundle-repository`
|
||||
|
||||
### Authentication
|
||||
|
||||
If the registry requires authentication, you can configure it as described in the [private registry authentication document](../advanced/private-registries/index.md).
|
||||
|
||||
### OCI Media Types
|
||||
|
||||
When serving, proxying, or manipulating Trivy's databases, note that the media type of the OCI layer is not a standard container image type:
|
||||
|
||||
DB | Media Type | Reference
|
||||
--- | --- | ---
|
||||
`trivy-db` | `application/vnd.aquasec.trivy.db.layer.v1.tar+gzip` | <https://github.com/aquasecurity/trivy-db/pkgs/container/trivy-db>
|
||||
`trivy-java-db` | `application/vnd.aquasec.trivy.javadb.layer.v1.tar+gzip` | https://github.com/aquasecurity/trivy-java-db/pkgs/container/trivy-java-db
|
||||
`trivy-checks` | `application/vnd.oci.image.manifest.v1+json` | https://github.com/aquasecurity/trivy-checks/pkgs/container/trivy-checks
|
||||
|
||||
## Manual cache population
|
||||
|
||||
Trivy uses a local cache directory to store the database files, as described in the [cache](../configuration/cache.md) document.
|
||||
You can download the databases files and surgically populate the Trivy cache directory with them.
|
||||
|
||||
### Downloading the DB files
|
||||
|
||||
On a machine with internet access, pull the database container archive from the public registry into your local workspace:
|
||||
|
||||
Note that these examples operate in the current working directory.
|
||||
|
||||
=== "Using ORAS"
|
||||
This example uses [ORAS](https://oras.land), but you can use any other container registry manipulation tool.
|
||||
|
||||
```shell
|
||||
oras pull ghcr.io/aquasecurity/trivy-db:2
|
||||
```
|
||||
|
||||
You should now have a file called `db.tar.gz`. Next, extract it to reveal the db files:
|
||||
|
||||
```shell
|
||||
tar -xzf db.tar.gz
|
||||
```
|
||||
|
||||
|
||||
=== "Using Trivy"
|
||||
This example uses Trivy to pull the database container archive. The `--cache-dir` flag makes Trivy download the database files into our current working directory. The `--download-db-only` flag tells Trivy to only download the database files, not to scan any images.
|
||||
|
||||
```shell
|
||||
trivy image --cache-dir . --download-db-only
|
||||
```
|
||||
|
||||
You should now have 2 new files, `metadata.json` and `trivy.db`. These are the Trivy DB files, copy them over to the air-gapped environment.
|
||||
|
||||
### Populating the Trivy Cache
|
||||
|
||||
In order to populate the cache, you need to identify the location of the cache directory. If it is under the default location, you can run the following command to find it:
|
||||
|
||||
```shell
|
||||
trivy -h | grep cache
|
||||
```
|
||||
|
||||
For the example, we will assume the `TRIVY_CACHE_DIR` variable holds the cache location:
|
||||
|
||||
```shell
|
||||
TRIVY_CACHE_DIR=/home/user/.cache/trivy
|
||||
```
|
||||
|
||||
Put the Trivy DB files in the Trivy cache directory under a `db` subdirectory:
|
||||
|
||||
```shell
|
||||
# ensure cache db directory exists
|
||||
mkdir -p ${TRIVY_CACHE_DIR}/db
|
||||
# copy the db files
|
||||
cp /path/to/trivy.db /path/to/metadata.json ${TRIVY_CACHE_DIR}/db/
|
||||
```
|
||||
|
||||
### Java DB adaptations
|
||||
|
||||
For Java DB the process is the same, except for the following:
|
||||
|
||||
1. Image location is `ghcr.io/aquasecurity/trivy-java-db:1`
|
||||
2. Archive file name is `javadb.tar.gz`
|
||||
3. DB file name is `trivy-java.db`
|
||||
|
||||
## VEX Hub
|
||||
|
||||
### Make a local copy
|
||||
|
||||
To make a copy of VEX Hub in a location that is accessible to Trivy.
|
||||
|
||||
1. Download the [VEX Hub](https://github.com/aquasecurity/vexhub) archive from: <https://github.com/aquasecurity/vexhub/archive/refs/heads/main.zip>.
|
||||
1. Download the [VEX Hub Repository Manifest](https://github.com/aquasecurity/vex-repo-spec#2-repository-manifest) file from: <https://github.com/aquasecurity/vexhub/blob/main/vex-repository.json>.
|
||||
1. Create or identify an internal HTTP server that can serve the VEX Hub repository in your environment (e.g `https://server.local`).
|
||||
1. Make the downloaded archive file available for serving from your server (e.g `https://server.local/main.zip`).
|
||||
1. Modify the downloaded manifest file's [Location URL](https://github.com/aquasecurity/vex-repo-spec?tab=readme-ov-file#locations-subfields) field to the URL of the archive file on your server (e.g `url: https://server.local/main.zip`).
|
||||
1. Make the manifest file available for serving from your server under the `/.well-known` path (e.g `https://server.local/.well-known/vex-repository.json`).
|
||||
|
||||
### Configure Trivy
|
||||
|
||||
To configure Trivy to use the local VEX Repository:
|
||||
|
||||
1. Locate your [Trivy VEX configuration file](../supply-chain/vex/repo/#configuration-file) by running `trivy vex repo init`. Make the following changes to the file.
|
||||
1. Disable the default VEX Hub repo (`enabled: false`)
|
||||
1. Add your internal VEX Hub repository as a [custom repository](../supply-chain/vex/repo/#custom-repositories) with the URL pointing to your local server (e.g `url: https://server.local`).
|
||||
|
||||
### Authentication
|
||||
|
||||
If your server requires authentication, you can configure it as described in the [VEX Repository Authentication document](../supply-chain/vex/repo/#authentication).
|
||||
@@ -1,142 +1,129 @@
|
||||
# DB
|
||||
# Trivy Databases
|
||||
|
||||
| Scanner | Supported |
|
||||
|:----------------:|:---------:|
|
||||
| Vulnerability | ✓ |
|
||||
| Misconfiguration | |
|
||||
| Secret | |
|
||||
| License | |
|
||||
When you install Trivy, the installed artifact contains the scanner engine but is lacking relevant security information needed to make security detections and recommendations.
|
||||
These so called "databases" are automatically fetched and maintained by Trivy as needed, so normally you shouldn't notice or worry about them.
|
||||
This document elaborates on the database management mechanism and its configuration options.
|
||||
|
||||
The vulnerability database and the Java index database are needed only for vulnerability scanning.
|
||||
See [here](../scanner/vulnerability.md) for the detail.
|
||||
Trivy relies on the following databases:
|
||||
|
||||
## Vulnerability Database
|
||||
DB | Artifact name | Contents | Purpose
|
||||
--- | --- | --- | ---
|
||||
Vulnerabilities DB | `trivy-db` | CVE information collected from various feeds | used only for [vulnerability scanning](../scanner/vulnerability.md)
|
||||
Java DB | `trivy-java-db` | Index of Java artifacts and their hash digest | used to identify Java artifacts only in [JAR scanning](../coverage/language/java.md)
|
||||
Checks Bundle | `trivy-checks` | Logic of misconfiguration checks | used only in [misconfiguration/IaC scanning](../scanner/misconfiguration/check/builtin.md)
|
||||
|
||||
### Skip update of vulnerability DB
|
||||
If you want to skip downloading the vulnerability database, use the `--skip-db-update` option.
|
||||
!!! note
|
||||
This is not an exhaustive list of Trivy's external connectivity requirements.
|
||||
There are additional external resources which may be required by specific Trivy features.
|
||||
To learn about external connectivity requirements, see the [Advanced Network Scenarios](../advanced/air-gap.md).
|
||||
|
||||
## Locations
|
||||
|
||||
Trivy's databases are published to the following locations:
|
||||
|
||||
| Registry | Image Address | Link
|
||||
| --- | --- | ---
|
||||
| GHCR | `ghcr.io/aquasecurity/trivy-db` | <https://ghcr.io/aquasecurity/trivy-db>
|
||||
| | `ghcr.io/aquasecurity/trivy-java-db` | <https://ghcr.io/aquasecurity/trivy-java-db>
|
||||
| | `ghcr.io/aquasecurity/trivy-checks` | <https://ghcr.io/aquasecurity/trivy-checks>
|
||||
| Docker Hub | `aquasec/trivy-db` | <https://hub.docker.com/r/aquasec/trivy-db>
|
||||
| | `aquasec/trivy-java-db` | <https://hub.docker.com/r/aquasec/trivy-java-db>
|
||||
| | `aquasec/trivy-checks` | <https://hub.docker.com/r/aquasec/trivy-checks>
|
||||
| AWS ECR | `public.ecr.aws/aquasecurity/trivy-db` | <https://gallery.ecr.aws/aquasecurity/trivy-db>
|
||||
| | `public.ecr.aws/aquasecurity/trivy-java-db` | <https://gallery.ecr.aws/aquasecurity/trivy-java-db>
|
||||
| | `public.ecr.aws/aquasecurity/trivy-checks` | <https://gallery.ecr.aws/aquasecurity/trivy-checks>
|
||||
|
||||
In addition, images are also available via pull-through cache registries like [Google Container Registry Mirror](https://cloud.google.com/artifact-registry/docs/pull-cached-dockerhub-images).
|
||||
|
||||
## Default Locations
|
||||
|
||||
Trivy will attempt to pull images from the following registries in the order specified.
|
||||
|
||||
1. `mirror.gcr.io/aquasec`
|
||||
2. `ghcr.io/aquasecurity`
|
||||
|
||||
You can specify additional alternative repositories as explained in the [configuring database locations section](#database-locations).
|
||||
|
||||
## DB Management Configuration
|
||||
|
||||
### Database Locations
|
||||
|
||||
You can configure Trivy to download databases from alternative locations by using the flags:
|
||||
|
||||
- `--db-repository`
|
||||
- `--java-db-repository`
|
||||
- `--checks-bundle-repository`
|
||||
|
||||
The value should be an image address in a container registry.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
$ trivy image --skip-db-update python:3.4-alpine3.9
|
||||
trivy image --db-repository registry.gitlab.com/gitlab-org/security-products/dependencies/trivy-db alpine
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>Result</summary>
|
||||
The flags accepts multiple values, which can be used to specify multiple alternative repository locations. In case of a transient errors (e.g. status 429 or 5xx), Trivy will fall back to alternative registries in the order specified.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
2019-05-16T12:48:08.703+0900 INFO Detecting Alpine vulnerabilities...
|
||||
|
||||
python:3.4-alpine3.9 (alpine 3.9.2)
|
||||
===================================
|
||||
Total: 1 (UNKNOWN: 0, LOW: 0, MEDIUM: 1, HIGH: 0, CRITICAL: 0)
|
||||
|
||||
+---------+------------------+----------+-------------------+---------------+--------------------------------+
|
||||
| LIBRARY | VULNERABILITY ID | SEVERITY | INSTALLED VERSION | FIXED VERSION | TITLE |
|
||||
+---------+------------------+----------+-------------------+---------------+--------------------------------+
|
||||
| openssl | CVE-2019-1543 | MEDIUM | 1.1.1a-r1 | 1.1.1b-r1 | openssl: ChaCha20-Poly1305 |
|
||||
| | | | | | with long nonces |
|
||||
+---------+------------------+----------+-------------------+---------------+--------------------------------+
|
||||
trivy image --db-repository my.registry.local/trivy-db --db-repository registry.gitlab.com/gitlab-org/security-products/dependencies/trivy-db alpine
|
||||
```
|
||||
|
||||
</details>
|
||||
The Checks Bundle registry location option does not support fallback through multiple options. This is because in case of a failure pulling the Checks Bundle, Trivy will use the embedded checks as a fallback.
|
||||
|
||||
### Only download vulnerability database
|
||||
You can also ask `Trivy` to simply retrieve the vulnerability database.
|
||||
This is useful to initialize workers in Continuous Integration systems.
|
||||
|
||||
```
|
||||
$ trivy image --download-db-only
|
||||
```
|
||||
|
||||
### DB Repository
|
||||
`Trivy` could also download the vulnerability database from an external OCI registry by using `--db-repository` option.
|
||||
|
||||
```
|
||||
$ trivy image --db-repository registry.gitlab.com/gitlab-org/security-products/dependencies/trivy-db
|
||||
```
|
||||
|
||||
The media type of the OCI layer must be `application/vnd.aquasec.trivy.db.layer.v1.tar+gzip`.
|
||||
You can reference the OCI manifest of [trivy-db].
|
||||
|
||||
<details>
|
||||
<summary>Manifest</summary>
|
||||
|
||||
```shell
|
||||
{
|
||||
"schemaVersion": 2,
|
||||
"mediaType": "application/vnd.oci.image.manifest.v1+json",
|
||||
"config": {
|
||||
"mediaType": "application/vnd.aquasec.trivy.config.v1+json",
|
||||
"digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
|
||||
"size": 2
|
||||
},
|
||||
"layers": [
|
||||
{
|
||||
"mediaType": "application/vnd.aquasec.trivy.db.layer.v1.tar+gzip",
|
||||
"digest": "sha256:29ad6505b8957c7cd4c367e7c705c641a9020d2be256812c5f4cc2fc099f4f02",
|
||||
"size": 55474933,
|
||||
"annotations": {
|
||||
"org.opencontainers.image.title": "db.tar.gz"
|
||||
}
|
||||
}
|
||||
],
|
||||
"annotations": {
|
||||
"org.opencontainers.image.created": "2024-09-11T06:14:51Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
</details>
|
||||
!!! note
|
||||
Setting the repository location flags override the default values which include the official db locations. In case you want to preserve the default locations, you should include them in the list the you set as repository locations.
|
||||
|
||||
!!!note
|
||||
Trivy automatically adds the `trivy-db` schema version as a tag if the tag is not used:
|
||||
When pulling `trivy-db` or `trivy-java-db`, if image tag is not specified, Trivy defaults to the db schema number instead of the `latest` tag.
|
||||
|
||||
`trivy-db-registry:latest` => `trivy-db-registry:latest`, but `trivy-db-registry` => `trivy-db-registry:2`.
|
||||
### Skip updates
|
||||
|
||||
You can configure Trivy to not attempt to download any or all database(s), using the flags:
|
||||
|
||||
### Rate limits
|
||||
Trivy hosts its databases on public OCI registries that are subject to their respective rate limits. While we strive to make the databases available to every
|
||||
Trivy user, there are certain recommendations that one can make in order to ensure rate limits are not hit.
|
||||
- `--skip-db-update`
|
||||
- `--skip-java-db-update`
|
||||
- `--skip-check-update`
|
||||
|
||||
#### Authenticated use of Registries
|
||||
By authenticating with the registries that Trivy hosts its DBs on can significantly increase the limit for users. For Amazon ECR, the details for rate limits can be found [ecr-limits].
|
||||
|
||||
Please see more info on how to authenticate with ECR [auth-ecr].
|
||||
|
||||
#### Caching DBs
|
||||
Trivy DB and Trivy Java DB are published every 6 hours and 24 hours, respectively. If you are running Trivy scans more often than this, you can significantly benefit from caching the DBs on each run and updating them as needed.
|
||||
One example of this can be seen in Trivy Action, where with caching multiple CI invocations can be performed with a single download of the DBs. More on info Trivy Action caching can be found [trivy-action-cache].
|
||||
|
||||
## Java Index Database
|
||||
The same options are also available for the Java index DB, which is used for scanning Java applications.
|
||||
Skipping an update can be done by using the `--skip-java-db-update` option, while `--download-java-db-only` can be used to only download the Java index DB.
|
||||
|
||||
!!! Note
|
||||
In [Client/Server](../references/modes/client-server.md) mode, `Java index DB` is currently only used on the `client` side.
|
||||
|
||||
Downloading the Java index DB from an external OCI registry can be done by using the `--java-db-repository` option.
|
||||
For example:
|
||||
|
||||
```
|
||||
$ trivy image --java-db-repository registry.gitlab.com/gitlab-org/security-products/dependencies/trivy-java-db --download-java-db-only
|
||||
trivy image --skip-db-update --skip-java-db-update --skip-check-update alpine
|
||||
```
|
||||
|
||||
The media type of the OCI layer must be `application/vnd.aquasec.trivy.javadb.layer.v1.tar+gzip`.
|
||||
You can reference the OCI manifest of [trivy-java-db].
|
||||
### Only update
|
||||
|
||||
!!!note
|
||||
Trivy automatically adds the `trivy-java-db` schema version as a tag if the tag is not used:
|
||||
You can ask `Trivy` to only update the database without performing a scan. This action will ensure Trivy is up to date, and populate Trivy's database cache for subsequent scans.
|
||||
|
||||
`java-db-registry:latest` => `java-db-registry:latest`, but `java-db-registry` => `java-db-registry:1`.
|
||||
- `--download-db-only`
|
||||
- `--download-java-db-only`
|
||||
|
||||
## Remove DBs
|
||||
"trivy clean" command removes caches and databases.
|
||||
For example:
|
||||
|
||||
```
|
||||
trivy image --download-db-only
|
||||
```
|
||||
|
||||
Note that currently there is no option to download only the Checks Bundle.
|
||||
|
||||
### Remove Databases
|
||||
|
||||
`trivy clean` command removes caches and databases.
|
||||
You can select which cache component to remove:
|
||||
|
||||
option | description
|
||||
--- | ---
|
||||
`-a`/`--all` | remove all caches
|
||||
`--checks-bundle` | remove checks bundle
|
||||
`--java-db` | remove Java database
|
||||
`--scan-cache` | remove scan cache (container and VM image analysis results)
|
||||
`--vuln-db` | remove vulnerability database
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
$ trivy clean --vuln-db --java-db
|
||||
2024-06-24T11:42:31+06:00 INFO Removing vulnerability database...
|
||||
2024-06-24T11:42:31+06:00 INFO Removing Java database...
|
||||
```
|
||||
|
||||
[trivy-db]: https://github.com/aquasecurity/trivy-db/pkgs/container/trivy-db
|
||||
[trivy-java-db]: https://github.com/aquasecurity/trivy-java-db/pkgs/container/trivy-java-db
|
||||
[ecr-limits]: https://docs.aws.amazon.com/AmazonECR/latest/public/public-service-quotas.html
|
||||
[auth-ecr]: https://aws.amazon.com/blogs/compute/authenticating-amazon-ecr-repositories-for-docker-cli-with-credential-helper/
|
||||
[trivy-action-cache]: https://github.com/aquasecurity/trivy-action?tab=readme-ov-file#cache
|
||||
@@ -1,23 +1,21 @@
|
||||
# Configuration
|
||||
Trivy can be configured using the following ways. Each item takes precedence over the item below it:
|
||||
Trivy's settings can be configured in any of the following methods, which will apply in the following precedence:
|
||||
|
||||
- CLI flags
|
||||
- Environment variables
|
||||
- Configuration file
|
||||
1. CLI flags (overrides all other settings)
|
||||
2. Environment variables (overrides config file settings)
|
||||
3. Configuration file
|
||||
|
||||
## CLI Flags
|
||||
You can view the list of available flags using the `--help` option.
|
||||
For more details, please refer to [the CLI reference](../references/configuration/cli/trivy.md).
|
||||
You can view the list of available flags by adding the `--help` flag to a Trivy command, or by exploring the [CLI reference](../references/configuration/cli/trivy.md).
|
||||
|
||||
## Environment Variables
|
||||
Trivy can be customized by environment variables.
|
||||
The environment variable key is the flag name converted by the following procedure.
|
||||
Any CLI option can be set as an environment variable. The environment variable name are similar to the CLI option name, with the following augmentations:
|
||||
|
||||
- Add `TRIVY_` prefix
|
||||
- Make it all uppercase
|
||||
- All uppercase letters
|
||||
- Replace `-` with `_`
|
||||
|
||||
For example,
|
||||
For example:
|
||||
|
||||
- `--debug` => `TRIVY_DEBUG`
|
||||
- `--cache-dir` => `TRIVY_CACHE_DIR`
|
||||
@@ -27,5 +25,6 @@ $ TRIVY_DEBUG=true TRIVY_SEVERITY=CRITICAL trivy image alpine:3.15
|
||||
```
|
||||
|
||||
## Configuration File
|
||||
By default, Trivy reads the `trivy.yaml` file.
|
||||
For more details, please refer to [the page](../references/configuration/config-file.md).
|
||||
Any setting can be set in a YAML file. By default, config file named `trivy.yaml` is read from the current directory where Trivy is run. To load configuration from a different file, use the `--config` flag and specify the config path to load: `trivy --config /etc/trivy/myconfig.yaml`.
|
||||
|
||||
The structure and settings of the YAML config file is documented in the [Config file](../references/configuration/config-file.md) document.
|
||||
|
||||
@@ -159,21 +159,8 @@ Trivy can detect vulnerabilities in Kubernetes clusters and components by scanni
|
||||
[^1]: Some manual triage and correction has been made.
|
||||
|
||||
## Databases
|
||||
Trivy utilizes several databases containing information relevant for vulnerability scanning.
|
||||
When performing a vulnerability scan, Trivy will automatically downloads the relevant databases. The databases are cached locally and Trivy will reuse them for subsequent scans on the same machine. Trivy takes care of updating the databases cache automatically, so normally users can be oblivious to it.
|
||||
|
||||
For CLI flags related to the database, please refer to [this page](../configuration/db.md).
|
||||
|
||||
### Vulnerability Database
|
||||
This is Trivy's main database which contains vulnerability information, as collected from the datasources mentioned above.
|
||||
It is built every six hours on [GitHub](https://github.com/aquasecurity/trivy-db).
|
||||
|
||||
### Java Index Database
|
||||
When scanning JAR files, Trivy relies on a dedicated database for identifying the groupId, artifactId, and version of the scanned JAR files. This database is only used when scanning JAR files, however your scanned artifacts might contain JAR files that you're not aware of.
|
||||
This database is built once a day on [GitHub](https://github.com/aquasecurity/trivy-java-db).
|
||||
|
||||
### External connectivity
|
||||
Trivy needs to connect to the internet to download the databases. If you are running Trivy in an air-gapped environment, or an tightly controlled network, please refer to the [Advanced Network Scenarios document](../advanced/air-gap.md).
|
||||
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).
|
||||
|
||||
## Detection Behavior
|
||||
Trivy prioritizes precision in vulnerability detection, aiming to minimize false positives while potentially accepting some false negatives.
|
||||
|
||||
@@ -121,7 +121,7 @@ nav:
|
||||
- Skipping Files: docs/configuration/skipping.md
|
||||
- Reporting: docs/configuration/reporting.md
|
||||
- Cache: docs/configuration/cache.md
|
||||
- DB: docs/configuration/db.md
|
||||
- Databases: docs/configuration/db.md
|
||||
- Others: docs/configuration/others.md
|
||||
- Supply Chain:
|
||||
- SBOM: docs/supply-chain/sbom.md
|
||||
@@ -143,7 +143,8 @@ nav:
|
||||
- Developer guide: docs/plugin/developer-guide.md
|
||||
- Advanced:
|
||||
- Modules: docs/advanced/modules.md
|
||||
- Advanced Network Scenarios: docs/advanced/air-gap.md
|
||||
- Connectivity and Network considerations: docs/advanced/air-gap.md
|
||||
- Self-Hosting Trivy's Databases: docs/advanced/self-hosting.md
|
||||
- Container Image:
|
||||
- Embed in Dockerfile: docs/advanced/container/embed-in-dockerfile.md
|
||||
- Unpacked container image filesystem: docs/advanced/container/unpacked-filesystem.md
|
||||
|
||||
Reference in New Issue
Block a user