From 88a1c0bc73f725b4b22167eb8be16b2405f49cc5 Mon Sep 17 00:00:00 2001 From: Itay Shakury Date: Sun, 14 Jul 2024 13:11:20 +0300 Subject: [PATCH 1/9] docs: update air-gapped docs --- docs/docs/advanced/air-gap.md | 191 ++++++++---------- docs/docs/references/troubleshooting.md | 6 +- .../scanner/misconfiguration/check/builtin.md | 25 +-- docs/docs/scanner/vulnerability.md | 43 +--- 4 files changed, 112 insertions(+), 153 deletions(-) diff --git a/docs/docs/advanced/air-gap.md b/docs/docs/advanced/air-gap.md index 171b80249eac..fddb4aa493e7 100644 --- a/docs/docs/advanced/air-gap.md +++ b/docs/docs/advanced/air-gap.md @@ -1,142 +1,125 @@ # Air-Gapped Environment +Trivy needs to connect to the internet to download databases. If you are running Trivy in an air-gapped environment, or an tightly controlled network, this document will explain your options. +In an air-gapped environment it is your responsibility to update the Trivy databases on a regular basis, so that the scanner can detect newly disclosed vulnerabilities. -Trivy can be used in air-gapped environments. Note that an allowlist is [here][allowlist]. +## Network requirements +Trivy's Databases are distributed as OCI images via GitHub Container registry (GHCR): -## Air-Gapped Environment for vulnerabilities +- +- +- -### Download the vulnerability database -At first, you need to download the vulnerability database for use in air-gapped environments. +If Trivy is running behind a firewall, you'll need to add the following urls to your allowlist: -=== "Trivy" +- `ghcr.io` +- `pkg-containers.githubusercontent.com` - ``` - TRIVY_TEMP_DIR=$(mktemp -d) - trivy --cache-dir $TRIVY_TEMP_DIR image --download-db-only - tar -cf ./db.tar.gz -C $TRIVY_TEMP_DIR/db metadata.json trivy.db - rm -rf $TRIVY_TEMP_DIR - ``` +The databases are pulled by Trivy using the [OCI Distribution](https://github.com/opencontainers/distribution-spec) specification, which is based on simple HTTPS protocol. -=== "oras >= v0.13.0" - Please follow [oras installation instruction][oras]. +## Running Trivy in air-gapped environment +In an air-gapped environment, you have to tell Trivy on every scan to not attempt to download the latest database files, otherwise the scan will fail. The following flags are relevant: - Download `db.tar.gz`: +- `--skip-db-update` to skip updating the main vulnerability database. +- `--skip-java-db-update` to skip updating the Java vulnerability database. +- `--offline-scan` to scan Java applications without issuing API requests. +- `--skip-check-update` to skip updating the misconfiguration database. - ``` - $ oras pull ghcr.io/aquasecurity/trivy-db:2 - ``` - -=== "oras < v0.13.0" - Please follow [oras installation instruction][oras]. +```shell +trivy image --skip-db-update --skip-java-db-update --offline-scan --skip-check-update myimage +``` - Download `db.tar.gz`: +## Self-Hosting +You can also host the databases on your own OCI registry, in order to avoid having Trivy reaching out of your network. - ``` - $ oras pull -a ghcr.io/aquasecurity/trivy-db:2 - ``` +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` -### Download the Java index database[^1] -Java users also need to download the Java index database for use in air-gapped environments. +Then, tell Trivy to use the private images: -!!! note - You container image may contain JAR files even though you don't use Java directly. - In that case, you also need to download the Java index database. +```shell +trivy image \ + --db-repository myregistry.local/trivy-db \ + --java-db-repository myregistry.local/trivy-java-db \ + --offline-scan \ + --checks-bundle-repository myregistry.local/trivy-checks \ + myimage +``` -=== "Trivy" +### Authentication - ``` - TRIVY_TEMP_DIR=$(mktemp -d) - trivy --cache-dir $TRIVY_TEMP_DIR image --download-java-db-only - tar -cf ./javadb.tar.gz -C $TRIVY_TEMP_DIR/java-db metadata.json trivy-java.db - rm -rf $TRIVY_TEMP_DIR - ``` -=== "oras >= v0.13.0" - Please follow [oras installation instruction][oras]. +For Trivy DB, configure it in the [same way as for private images](../advanced/private-registries/index.md). - Download `javadb.tar.gz`: +For Java DB, you need to run `docker login YOUR_REGISTRY`. Currently, specifying a username and password is not supported. - ``` - $ oras pull ghcr.io/aquasecurity/trivy-java-db:1 - ``` +## Manual cache population +You can also download the databases files manually and surgically populate the Trivy cache directory with them. -=== "oras < v0.13.0" - Please follow [oras installation instruction][oras]. +### Downloading the DB files +On a machine with internet access, pull the database container archive from the registry into your local workspace: - Download `javadb.tar.gz`: +Note that these examples operate in the current working directory. - ``` - $ oras pull -a ghcr.io/aquasecurity/trivy-java-db:1 - ``` +=== "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 +``` -### Transfer the DB files into the air-gapped environment -The way of transfer depends on the environment. +You should now have a file called `db.tar.gz`. Next, extract it to reveal the db files: -=== "Vulnerability db" - ``` - $ rsync -av -e ssh /path/to/db.tar.gz [user]@[host]:dst - ``` +```shell +tar -xzf db.tar.gz +``` -=== "Java index db[^1]" - ``` - $ rsync -av -e ssh /path/to/javadb.tar.gz [user]@[host]:dst - ``` +You should now have 2 new files, `metadata.json` and `trivy.db`. These are the Trivy DB files. -### Put the DB files in Trivy's cache directory -You have to know where to put the DB files. The following command shows the default cache directory. +=== "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 --cache-dir . image --download-db-only ``` -$ ssh user@host -$ trivy -h | grep cache - --cache-dir value cache directory (default: "/home/myuser/.cache/trivy") [$TRIVY_CACHE_DIR] + +You should now have 2 new files, `metadata.json` and `trivy.db`. These are the Trivy DB files. + +### Populating the Trivy Cache +Once you obtained the Trivy DB files (`metadata.json` and `trivy.db`), copy them over to the air-gapped environment. + +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 ``` -=== "Vulnerability db" - Put the DB file in the cache directory + `/db`. - - ``` - $ mkdir -p /home/myuser/.cache/trivy/db - $ cd /home/myuser/.cache/trivy/db - $ tar xvf /path/to/db.tar.gz -C /home/myuser/.cache/trivy/db - x trivy.db - x metadata.json - $ rm /path/to/db.tar.gz - ``` - -=== "Java index db[^1]" - Put the DB file in the cache directory + `/java-db`. - - ``` - $ mkdir -p /home/myuser/.cache/trivy/java-db - $ cd /home/myuser/.cache/trivy/java-db - $ tar xvf /path/to/javadb.tar.gz -C /home/myuser/.cache/trivy/java-db - x trivy-java.db - x metadata.json - $ rm /path/to/javadb.tar.gz - ``` - - - -In an air-gapped environment it is your responsibility to update the Trivy databases on a regular basis, so that the scanner can detect recently-identified vulnerabilities. - -### Run Trivy with the specific flags. -In an air-gapped environment, you have to specify `--skip-db-update` and `--skip-java-db-update`[^1] so that Trivy doesn't attempt to download the latest database files. -In addition, if you want to scan `pom.xml` dependencies, you need to specify `--offline-scan` since Trivy tries to issue API requests for scanning Java applications by default. +For the example, we will assume the `TRIVY_CACHE_DIR` variable holds the cache location: + +```shell +TRIVY_CACHE_DIR=/home/user/.cache/trivy ``` -$ trivy image --skip-db-update --skip-java-db-update --offline-scan alpine:3.12 + +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/ ``` -## Air-Gapped Environment for misconfigurations +### Java DB -No special measures are required to detect misconfigurations in an air-gapped environment. +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` -### Run Trivy with `--skip-check-update` option -In an air-gapped environment, specify `--skip-check-update` so that Trivy doesn't attempt to download the latest misconfiguration checks. +## Misconfigurations scanning -``` -$ trivy conf --skip-policy-update /path/to/conf -``` +Note that the misconfigurations database 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. -[allowlist]: ../references/troubleshooting.md +[allowlist]: ../references/troubleshooting.md#error-downloading-vulnerability-db [oras]: https://oras.land/docs/installation -[^1]: This is only required to scan `jar` files. More information about `Java index db` [here](../coverage/language/java.md) diff --git a/docs/docs/references/troubleshooting.md b/docs/docs/references/troubleshooting.md index d271882c5ecb..2c9a74a0e89a 100644 --- a/docs/docs/references/troubleshooting.md +++ b/docs/docs/references/troubleshooting.md @@ -203,10 +203,7 @@ Trivy v0.23.0 or later requires Trivy DB v2. Please update your local database o !!! error FATAL failed to download vulnerability DB -If trivy is running behind corporate firewall, you have to add the following urls to your allowlist. - -- ghcr.io -- pkg-containers.githubusercontent.com +If Trivy is running behind corporate firewall, refer to the necessary connectivity requirements as described [here][network]. ### Denied @@ -271,4 +268,5 @@ $ trivy clean --all ``` [air-gapped]: ../advanced/air-gap.md +[network]: ../advanced/air-gap.md#network-requirements [redis-cache]: ../../vulnerability/examples/cache/#cache-backend diff --git a/docs/docs/scanner/misconfiguration/check/builtin.md b/docs/docs/scanner/misconfiguration/check/builtin.md index 8b513f47607a..3e031d1a4dcd 100644 --- a/docs/docs/scanner/misconfiguration/check/builtin.md +++ b/docs/docs/scanner/misconfiguration/check/builtin.md @@ -1,21 +1,22 @@ # Built-in Checks -## Check Sources -Built-in checks are mainly written in [Rego][rego] and Go. -Those checks are managed under [trivy-checks repository][trivy-checks]. +## Checks Sources +Trivy has an extensive library of misconfiguration checks that is maintained at . +Trivy checks are mainly written in [Rego][rego], while some checks are written in Go. See [here](../../../coverage/iac/index.md) for the list of supported config types. -For suggestions or issues regarding policy content, please open an issue under the [trivy-checks][trivy-checks] repository. +## Checks Bundle +When performing a misconfiguration scan, Trivy will automatically downloads the relevant Checks bundle. The bundle is cached locally and Trivy will reuse it for subsequent scans on the same machine. Trivy takes care of updating the cache automatically so normally can be oblivious to it. -## Check Distribution -Trivy checks are distributed as an OPA bundle on [GitHub Container Registry][ghcr] (GHCR). -When misconfiguration detection is enabled, Trivy pulls the OPA bundle from GHCR as an OCI artifact and stores it in the cache. -Those checks are then loaded into Trivy OPA engine and used for detecting misconfigurations. -If Trivy is unable to pull down newer checks, it will use the embedded set of checks as a fallback. This is also the case in air-gap environments where `--skip-policy-update` might be passed. +For CLI flags related to the database, please refer to [this page](../configuration/db.md). -## Update Interval +## Checks Distribution +Trivy checks are distributed as an [OPA bundle](opa-bundle) hosted in the following GitHub Container Registry: . Trivy checks for updates to OPA bundle on GHCR every 24 hours and pulls it if there are any updates. +### External connectivity +Trivy needs to connect to the internet to download the bundle. If you are running Trivy in an air-gapped environment, or an tightly controlled network, please refer to the [air-gapped documentation](../advanced/air-gap.md). +The Checks bundle is also embedded in the Trivy binary (at build time), and will be used as a fallback if Trivy is unable to download the bundle. 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. + [rego]: https://www.openpolicyagent.org/docs/latest/policy-language/ -[trivy-checks]: https://github.com/aquasecurity/trivy-checks -[ghcr]: https://github.com/aquasecurity/trivy-checks/pkgs/container/trivy-checks \ No newline at end of file +[opa-bundle]: https://www.openpolicyagent.org/docs/latest/management-bundles/ diff --git a/docs/docs/scanner/vulnerability.md b/docs/docs/scanner/vulnerability.md index ef233b4db4da..418a2f5fbe3c 100644 --- a/docs/docs/scanner/vulnerability.md +++ b/docs/docs/scanner/vulnerability.md @@ -158,45 +158,22 @@ Trivy can detect vulnerabilities in Kubernetes clusters and components by scanni [^1]: Some manual triage and correction has been made. -## Database -Trivy downloads [the vulnerability database](https://github.com/aquasecurity/trivy-db) every 6 hours. -Trivy uses two types of databases for vulnerability detection: - -- Vulnerability Database -- Java Index Database - -This page provides detailed information about these databases. - -### Vulnerability Database -Trivy utilizes a database containing vulnerability information. -This database is built every six hours on [GitHub](https://github.com/aquasecurity/trivy-db) and is distributed via [GitHub Container registry (GHCR)](https://ghcr.io/aquasecurity/trivy-db). -The database is cached and updated as needed. -As Trivy updates the database automatically during execution, users don't need to be concerned about it. +## 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 can be oblivious to it. For CLI flags related to the database, please refer to [this page](../configuration/db.md). -#### Private Hosting -If you host the database on your own OCI registry, you can specify a different repository with the `--db-repository` flag. -The default is `ghcr.io/aquasecurity/trivy-db`. - -```shell -$ trivy image --db-repository YOUR_REPO YOUR_IMAGE -``` - -If authentication is required, it can be configured in the same way as for private images. -Please refer to [the documentation](../advanced/private-registries/index.md) for more details. +### 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 -This database is only downloaded when scanning JAR files so that Trivy can identify the groupId, artifactId, and version of JAR files. -It is built once a day on [GitHub](https://github.com/aquasecurity/trivy-java-db) and distributed via [GitHub Container registry (GHCR)](https://ghcr.io/aquasecurity/trivy-java-db). -Like the vulnerability database, it is automatically downloaded and updated when needed, so users don't need to worry about it. - -#### Private Hosting -If you host the database on your own OCI registry, you can specify a different repository with the `--java-db-repository` flag. -The default is `ghcr.io/aquasecurity/trivy-java-db`. +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). -If authentication is required, you need to run `docker login YOUR_REGISTRY`. -Currently, specifying a username and password is not supported. +### 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 [air-gapped documentation](../advanced/air-gap.md). ## Configuration This section describes vulnerability-specific configuration. From 4695eebf7a876ff18c9a56f07e4ef4c141dc7e10 Mon Sep 17 00:00:00 2001 From: Itay Shakury Date: Mon, 15 Jul 2024 18:53:18 +0300 Subject: [PATCH 2/9] advanced network scenarios --- docs/docs/advanced/air-gap.md | 45 ++++++++++--------- .../scanner/misconfiguration/check/builtin.md | 2 +- docs/docs/scanner/vulnerability.md | 2 +- mkdocs.yml | 2 +- 4 files changed, 27 insertions(+), 24 deletions(-) diff --git a/docs/docs/advanced/air-gap.md b/docs/docs/advanced/air-gap.md index fddb4aa493e7..1c83df43ec19 100644 --- a/docs/docs/advanced/air-gap.md +++ b/docs/docs/advanced/air-gap.md @@ -1,9 +1,10 @@ -# Air-Gapped Environment -Trivy needs to connect to the internet to download databases. If you are running Trivy in an air-gapped environment, or an tightly controlled network, this document will explain your options. -In an air-gapped environment it is your responsibility to update the Trivy databases on a regular basis, so that the scanner can detect newly disclosed vulnerabilities. +# Advanced Network Scenarios + +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. ## Network requirements -Trivy's Databases are distributed as OCI images via GitHub Container registry (GHCR): + +Trivy's databases are distributed as OCI images via GitHub Container registry (GHCR): - - @@ -17,11 +18,17 @@ If Trivy is running behind a firewall, you'll need to add the following urls to The databases are pulled by Trivy using the [OCI Distribution](https://github.com/opencontainers/distribution-spec) specification, which is based on simple HTTPS protocol. ## Running Trivy in air-gapped environment -In an air-gapped environment, you have to tell Trivy on every scan to not attempt to download the latest database files, otherwise the scan will fail. The following flags are relevant: + +An air-gapped environment refers to situations where the network connectivity from the machine Trivy runs on is blocked or restricted. + +In an air-gapped environment it is your responsibility to update the Trivy databases on a regular basis. + +## Offline Mode + +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: - `--skip-db-update` to skip updating the main vulnerability database. - `--skip-java-db-update` to skip updating the Java vulnerability database. -- `--offline-scan` to scan Java applications without issuing API requests. - `--skip-check-update` to skip updating the misconfiguration database. ```shell @@ -29,35 +36,36 @@ trivy image --skip-db-update --skip-java-db-update --offline-scan --skip-check-u ``` ## Self-Hosting -You can also host the databases on your own OCI registry, in order to avoid having Trivy reaching out of your network. + +You can host the databases on your own local OCI registry, in order to prevent Trivy reaching out of your network. 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` +- `ghcr.io/aquasecurity/trivy-checks:0` -Then, tell Trivy to use the private images: +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 \ - --offline-scan \ --checks-bundle-repository myregistry.local/trivy-checks \ myimage ``` ### Authentication -For Trivy DB, configure it in the [same way as for private images](../advanced/private-registries/index.md). - -For Java DB, you need to run `docker login YOUR_REGISTRY`. Currently, specifying a username and password is not supported. +If the registry requires authentication, you can configure it in as described in the [private registry authentication document](../advanced/private-registries/index.md). ## 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 registry into your local workspace: + +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. @@ -80,13 +88,12 @@ You should now have 2 new files, `metadata.json` and `trivy.db`. These are the T 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 --cache-dir . image --download-db-only +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. +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 -Once you obtained the Trivy DB files (`metadata.json` and `trivy.db`), copy them over to the air-gapped environment. 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: @@ -119,7 +126,3 @@ For Java DB the process is the same, except for the following: ## Misconfigurations scanning Note that the misconfigurations database 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. - -[allowlist]: ../references/troubleshooting.md#error-downloading-vulnerability-db -[oras]: https://oras.land/docs/installation - diff --git a/docs/docs/scanner/misconfiguration/check/builtin.md b/docs/docs/scanner/misconfiguration/check/builtin.md index 3e031d1a4dcd..2de441a02740 100644 --- a/docs/docs/scanner/misconfiguration/check/builtin.md +++ b/docs/docs/scanner/misconfiguration/check/builtin.md @@ -15,7 +15,7 @@ Trivy checks are distributed as an [OPA bundle](opa-bundle) hosted in the follow Trivy checks for updates to OPA bundle on GHCR every 24 hours and pulls it if there are any updates. ### External connectivity -Trivy needs to connect to the internet to download the bundle. If you are running Trivy in an air-gapped environment, or an tightly controlled network, please refer to the [air-gapped documentation](../advanced/air-gap.md). +Trivy needs to connect to the internet to download the bundle. 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 Checks bundle is also embedded in the Trivy binary (at build time), and will be used as a fallback if Trivy is unable to download the bundle. 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. [rego]: https://www.openpolicyagent.org/docs/latest/policy-language/ diff --git a/docs/docs/scanner/vulnerability.md b/docs/docs/scanner/vulnerability.md index 418a2f5fbe3c..2494604333ec 100644 --- a/docs/docs/scanner/vulnerability.md +++ b/docs/docs/scanner/vulnerability.md @@ -173,7 +173,7 @@ When scanning JAR files, Trivy relies on a dedicated database for identifying th 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 [air-gapped documentation](../advanced/air-gap.md). +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). ## Configuration This section describes vulnerability-specific configuration. diff --git a/mkdocs.yml b/mkdocs.yml index 2222a30220fb..4c915276c71c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -137,7 +137,7 @@ nav: - Developer guide: docs/plugin/developer-guide.md - Advanced: - Modules: docs/advanced/modules.md - - Air-Gapped Environment: docs/advanced/air-gap.md + - Advanced Network Scenarios: docs/advanced/air-gap.md - Container Image: - Embed in Dockerfile: docs/advanced/container/embed-in-dockerfile.md - Unpacked container image filesystem: docs/advanced/container/unpacked-filesystem.md From ecb017e7a08b70caed1ae02d8f1eac9a24f20efb Mon Sep 17 00:00:00 2001 From: Itay Shakury Date: Tue, 16 Jul 2024 14:24:05 +0300 Subject: [PATCH 3/9] load config from local dir --- docs/docs/advanced/air-gap.md | 3 +++ docs/docs/compliance/contrib-compliance.md | 2 +- docs/docs/scanner/misconfiguration/check/builtin.md | 2 +- docs/docs/scanner/misconfiguration/custom/data.md | 2 +- docs/docs/scanner/misconfiguration/custom/index.md | 8 ++++---- docs/docs/scanner/misconfiguration/custom/schema.md | 2 +- docs/docs/scanner/misconfiguration/index.md | 10 +++++----- docs/docs/scanner/vulnerability.md | 2 +- docs/tutorials/misconfiguration/custom-checks.md | 2 +- 9 files changed, 18 insertions(+), 15 deletions(-) diff --git a/docs/docs/advanced/air-gap.md b/docs/docs/advanced/air-gap.md index 1c83df43ec19..63c54e67603f 100644 --- a/docs/docs/advanced/air-gap.md +++ b/docs/docs/advanced/air-gap.md @@ -119,6 +119,7 @@ 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` @@ -126,3 +127,5 @@ For Java DB the process is the same, except for the following: ## Misconfigurations scanning Note that the misconfigurations database 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 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). diff --git a/docs/docs/compliance/contrib-compliance.md b/docs/docs/compliance/contrib-compliance.md index a848b1bf4367..0b83b688b664 100644 --- a/docs/docs/compliance/contrib-compliance.md +++ b/docs/docs/compliance/contrib-compliance.md @@ -35,7 +35,7 @@ Additional information is provided below. #### 1. Referencing a check that is already part of Trivy -Trivy has a comprehensive list of checks as part of its misconfiguration scanning. These can be found in the `trivy-policies/checks` directory ([Link](https://github.com/aquasecurity/trivy-checks/tree/main/checks)). If the check is present, the `AVD_ID` and other information from the check has to be used. +Trivy has a comprehensive list of checks as part of its misconfiguration scanning. These can be found in the `trivy-checks/checks` directory ([Link](https://github.com/aquasecurity/trivy-checks/tree/main/checks)). If the check is present, the `AVD_ID` and other information from the check has to be used. Note: Take a look at the more generic compliance specs that are already available in Trivy. If you are adding new compliance spec to Kubernetes e.g. AWS EKS CIS Benchmarks, chances are high that the check you would like to add to the new spec has already been defined in the general `k8s-ci-v.000.yaml` compliance spec. The same applies for creating specific Cloud Provider Compliance Specs and the [generic compliance specs](https://github.com/aquasecurity/trivy-checks/tree/main/specs/compliance) available. diff --git a/docs/docs/scanner/misconfiguration/check/builtin.md b/docs/docs/scanner/misconfiguration/check/builtin.md index 2de441a02740..0377461808cc 100644 --- a/docs/docs/scanner/misconfiguration/check/builtin.md +++ b/docs/docs/scanner/misconfiguration/check/builtin.md @@ -6,7 +6,7 @@ Trivy checks are mainly written in [Rego][rego], while some checks are written i See [here](../../../coverage/iac/index.md) for the list of supported config types. ## Checks Bundle -When performing a misconfiguration scan, Trivy will automatically downloads the relevant Checks bundle. The bundle is cached locally and Trivy will reuse it for subsequent scans on the same machine. Trivy takes care of updating the cache automatically so normally can be oblivious to it. +When performing a misconfiguration scan, Trivy will automatically download the relevant Checks bundle. The bundle is cached locally and Trivy will reuse it for subsequent scans on the same machine. Trivy takes care of updating the 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). diff --git a/docs/docs/scanner/misconfiguration/custom/data.md b/docs/docs/scanner/misconfiguration/custom/data.md index 51af206b4c63..42e120ee180a 100644 --- a/docs/docs/scanner/misconfiguration/custom/data.md +++ b/docs/docs/scanner/misconfiguration/custom/data.md @@ -31,5 +31,5 @@ Then, you need to pass data paths through `--data` option. Trivy recursively searches the specified paths for JSON (`*.json`) and YAML (`*.yaml`) files. ```bash -$ trivy conf --policy ./policy --data data --namespaces user ./configs +$ trivy conf --config-check ./checks --data ./data --namespaces user ./configs ``` \ No newline at end of file diff --git a/docs/docs/scanner/misconfiguration/custom/index.md b/docs/docs/scanner/misconfiguration/custom/index.md index 925b72cedf09..9e7b5106c1be 100644 --- a/docs/docs/scanner/misconfiguration/custom/index.md +++ b/docs/docs/scanner/misconfiguration/custom/index.md @@ -2,10 +2,10 @@ ## Overview You can write custom checks in [Rego][rego]. -Once you finish writing custom checks, you can pass the policy files or the directory where those policies are stored with `--policy` option. +Once you finish writing custom checks, you can pass the policy files or the directory where those checks are stored with --config-check` option. ``` bash -trivy conf --policy /path/to/policy.rego --policy /path/to/custom_policies --namespaces user /path/to/config_dir +trivy conf --config-check /path/to/policy.rego --config-check /path/to/custom_checks --namespaces user /path/to/config_dir ``` As for `--namespaces` option, the detail is described as below. @@ -93,7 +93,7 @@ By default, only `builtin.*` packages will be evaluated. If you define custom packages, you have to specify the package prefix via `--namespaces` option. By default, Trivy only runs in its own namespace, unless specified by the user. Note that the custom namespace does not have to be `user` as in this example. It could be anything user-defined. ``` bash -trivy conf --policy /path/to/custom_policies --namespaces user /path/to/config_dir +trivy conf --config-check /path/to/custom_checks --namespaces user /path/to/config_dir ``` In this case, `user.*` will be evaluated. @@ -135,7 +135,7 @@ correct and do not reference incorrect properties/values. #### custom.avd_id and custom.id -The AVD_ID can be used to link the check to the Aqua Vulnerability Database (AVD) entry. For example, the `avd_id` `AVD-AWS-0176` is the ID of the check in the [AWS Vulnerability Database](https://avd.aquasec.com/). If you are [contributing your check to trivy-policies](../../../../community/contribute/checks/overview.md), you need to generate an ID using `make id` in the [trivy-checks](https://github.com/aquasecurity/trivy-checks) repository. The output of the command will provide you the next free IDs for the different providers in Trivy. +The AVD_ID can be used to link the check to the Aqua Vulnerability Database (AVD) entry. For example, the `avd_id` `AVD-AWS-0176` is the ID of the check in the [AWS Vulnerability Database](https://avd.aquasec.com/). If you are [contributing your check to trivy-checks](../../../../community/contribute/checks/overview.md), you need to generate an ID using `make id` in the [trivy-checks](https://github.com/aquasecurity/trivy-checks) repository. The output of the command will provide you the next free IDs for the different providers in Trivy. The ID is based on the AVD_ID. For instance if the `avd_id` is `AVD-AWS-0176`, the ID is `ID0176`. diff --git a/docs/docs/scanner/misconfiguration/custom/schema.md b/docs/docs/scanner/misconfiguration/custom/schema.md index 612025d38866..7b305cc10dbf 100644 --- a/docs/docs/scanner/misconfiguration/custom/schema.md +++ b/docs/docs/scanner/misconfiguration/custom/schema.md @@ -1,7 +1,7 @@ # Input Schema ## Overview -Policies can be defined with custom schemas that allow inputs to be verified against them. Adding a policy schema +Checks can be defined with custom schemas that allow inputs to be verified against them. Adding a policy schema enables Trivy to show more detailed error messages when an invalid input is encountered. In Trivy we have been able to define a schema for a [Dockerfile](https://github.com/aquasecurity/trivy/tree/main/pkg/iac/rego/schemas) diff --git a/docs/docs/scanner/misconfiguration/index.md b/docs/docs/scanner/misconfiguration/index.md index 701d469d658f..bda27dc7f384 100644 --- a/docs/docs/scanner/misconfiguration/index.md +++ b/docs/docs/scanner/misconfiguration/index.md @@ -326,13 +326,13 @@ trivy config --misconfig-scanners=terraform,dockerfile . Will only scan for misconfigurations that pertain to Terraform and Dockerfiles. -### Passing custom checks -You can pass policy files or directories including your custom checks through `--policy` option. +### Loading custom checks +You can load policy files or directories including your custom checks through `--config-check` flag. This can be repeated for specifying multiple files or directories. ```bash cd examplex/misconf/ -trivy conf --policy custom-policy/policy --policy combine/policy --policy policy.rego --namespaces user misconf/mixed +trivy conf --config-check custom-policy/policy --config-check combine/policy --config-check policy.rego --namespaces user misconf/mixed ``` For more details, see [Custom Checks](./custom/index.md). @@ -346,7 +346,7 @@ This can be repeated for specifying multiple directories. ```bash cd examples/misconf/custom-data -trivy conf --policy ./policy --data ./data --namespaces user ./configs +trivy conf --config-check ./policy --data ./data --namespaces user ./configs ``` For more details, see [Custom Data](./custom/data.md). @@ -357,7 +357,7 @@ If you want to evaluate custom checks in other packages, you have to specify pac This can be repeated for specifying multiple packages. ``` bash -trivy conf --policy ./policy --namespaces main --namespaces user ./configs +trivy conf --config-check ./policy --namespaces main --namespaces user ./configs ``` ### Private terraform registries diff --git a/docs/docs/scanner/vulnerability.md b/docs/docs/scanner/vulnerability.md index 2494604333ec..070698218f8b 100644 --- a/docs/docs/scanner/vulnerability.md +++ b/docs/docs/scanner/vulnerability.md @@ -160,7 +160,7 @@ Trivy can detect vulnerabilities in Kubernetes clusters and components by scanni ## 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 can be oblivious to it. +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). diff --git a/docs/tutorials/misconfiguration/custom-checks.md b/docs/tutorials/misconfiguration/custom-checks.md index 97ab67a7f649..0058595c0dde 100644 --- a/docs/tutorials/misconfiguration/custom-checks.md +++ b/docs/tutorials/misconfiguration/custom-checks.md @@ -93,7 +93,7 @@ Note that Rego Ensure that you have Trivy installed and run the following command: ```bash -trivy fs --scanners misconf --policy ./docker-check.rego --namespaces custom ./Dockerfile +trivy fs --scanners misconf --config-check ./docker-check.rego --namespaces custom ./Dockerfile ``` Please replace: From 40a6a986b0369fe87c5e0cea51d8336f04bf5430 Mon Sep 17 00:00:00 2001 From: Itay Shakury Date: Tue, 16 Jul 2024 14:28:21 +0300 Subject: [PATCH 4/9] typo --- docs/docs/advanced/air-gap.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/advanced/air-gap.md b/docs/docs/advanced/air-gap.md index 63c54e67603f..e09a2f0216eb 100644 --- a/docs/docs/advanced/air-gap.md +++ b/docs/docs/advanced/air-gap.md @@ -128,4 +128,4 @@ For Java DB the process is the same, except for the following: Note that the misconfigurations database 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 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). +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). From b88430ea1680dee9f732651afe8d1641a7fdf9c4 Mon Sep 17 00:00:00 2001 From: Itay Shakury Date: Tue, 16 Jul 2024 14:42:45 +0300 Subject: [PATCH 5/9] load bundle from registry --- docs/docs/scanner/misconfiguration/index.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/docs/scanner/misconfiguration/index.md b/docs/docs/scanner/misconfiguration/index.md index bda27dc7f384..e8cda93a4658 100644 --- a/docs/docs/scanner/misconfiguration/index.md +++ b/docs/docs/scanner/misconfiguration/index.md @@ -315,6 +315,9 @@ Failures: 2 (MEDIUM: 2, HIGH: 0, CRITICAL: 0) This section describes misconfiguration-specific configuration. Other common options are documented [here](../../configuration/index.md). +### External connectivity +Trivy needs to connect to the internet to download the checks bundle. 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). + ### Enabling a subset of misconfiguration scanners It's possible to only enable certain misconfiguration scanners if you prefer. You can do so by passing the `--misconfig-scanners` option. @@ -327,18 +330,18 @@ trivy config --misconfig-scanners=terraform,dockerfile . Will only scan for misconfigurations that pertain to Terraform and Dockerfiles. ### Loading custom checks -You can load policy files or directories including your custom checks through `--config-check` flag. +You can load check files or directories including your custom checks using the `--config-check` flag. This can be repeated for specifying multiple files or directories. ```bash -cd examplex/misconf/ -trivy conf --config-check custom-policy/policy --config-check combine/policy --config-check policy.rego --namespaces user misconf/mixed +trivy conf --config-check custom-policy/policy --config-check combine/policy --config-check policy.rego --namespaces user myapp ``` -For more details, see [Custom Checks](./custom/index.md). +You can load checks bundle as OCI Image from a Container Registry using the `--checks-bundle-repository` flag. -!!! tip -You also need to specify `--namespaces` option. +```bash +trivy conf --checks-bundle-repository myregistry.local/mychecks --namespaces user myapp +``` ### Passing custom data You can pass directories including your custom data through `--data` option. From 2327c5f4c56b28d8734362e6c47b1cbd91988d58 Mon Sep 17 00:00:00 2001 From: Itay Shakury Date: Wed, 7 Aug 2024 13:34:18 +0300 Subject: [PATCH 6/9] add vex repo --- docs/docs/advanced/air-gap.md | 41 ++++++++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 5 deletions(-) diff --git a/docs/docs/advanced/air-gap.md b/docs/docs/advanced/air-gap.md index e09a2f0216eb..13dc21d07eef 100644 --- a/docs/docs/advanced/air-gap.md +++ b/docs/docs/advanced/air-gap.md @@ -1,6 +1,6 @@ # Advanced Network Scenarios -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 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. ## Network requirements @@ -10,12 +10,18 @@ Trivy's databases are distributed as OCI images via GitHub Container registry (G - - -If Trivy is running behind a firewall, you'll need to add the following urls to your allowlist: +The following hosts are required in order to fetch them: - `ghcr.io` - `pkg-containers.githubusercontent.com` -The databases are pulled by Trivy using the [OCI Distribution](https://github.com/opencontainers/distribution-spec) specification, which is based on simple HTTPS protocol. +The databases are pulled by Trivy using the [OCI Distribution](https://github.com/opencontainers/distribution-spec) specification, which is a simple HTTPS-based protocol. + +[VEX Hub](https://github.com/aquasecurity/vexhub) is distributed from GitHub over HTTPS. +The following hosts are required in order to fetch it: + +- `api.github.com` +- `codeload.github.com` ## Running Trivy in air-gapped environment @@ -37,7 +43,9 @@ trivy image --skip-db-update --skip-java-db-update --offline-scan --skip-check-u ## Self-Hosting -You can host the databases on your own local OCI registry, in order to prevent Trivy reaching out of your network. +## OCI Databases + +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: @@ -57,7 +65,30 @@ trivy image \ ### Authentication -If the registry requires authentication, you can configure it in as described in the [private registry authentication document](../advanced/private-registries/index.md). +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: . +1. Download the [VEX Hub Repository Manifest](https://github.com/aquasecurity/vex-repo-spec#2-repository-manifest) file from: . +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 you [Trivy VEX configuration file](https://aquasecurity.github.io/trivy/latest/docs/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](https://aquasecurity.github.io/trivy/latest/docs/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](https://aquasecurity.github.io/trivy/latest/docs/supply-chain/vex/repo/#authentication). ## Manual cache population From da24941ae136b763ba5b30a7170002116bcdce25 Mon Sep 17 00:00:00 2001 From: Itay Shakury Date: Wed, 7 Aug 2024 15:23:26 +0300 Subject: [PATCH 7/9] address comments and small improvements --- .../scanner/misconfiguration/check/builtin.md | 2 -- .../scanner/misconfiguration/custom/data.md | 22 +++++++++---------- .../scanner/misconfiguration/custom/index.md | 2 +- 3 files changed, 11 insertions(+), 15 deletions(-) diff --git a/docs/docs/scanner/misconfiguration/check/builtin.md b/docs/docs/scanner/misconfiguration/check/builtin.md index 0377461808cc..900fb27109d5 100644 --- a/docs/docs/scanner/misconfiguration/check/builtin.md +++ b/docs/docs/scanner/misconfiguration/check/builtin.md @@ -8,8 +8,6 @@ See [here](../../../coverage/iac/index.md) for the list of supported config type ## Checks Bundle When performing a misconfiguration scan, Trivy will automatically download the relevant Checks bundle. The bundle is cached locally and Trivy will reuse it for subsequent scans on the same machine. Trivy takes care of updating the 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). - ## Checks Distribution Trivy checks are distributed as an [OPA bundle](opa-bundle) hosted in the following GitHub Container Registry: . Trivy checks for updates to OPA bundle on GHCR every 24 hours and pulls it if there are any updates. diff --git a/docs/docs/scanner/misconfiguration/custom/data.md b/docs/docs/scanner/misconfiguration/custom/data.md index 42e120ee180a..2ccd9f1a2bfd 100644 --- a/docs/docs/scanner/misconfiguration/custom/data.md +++ b/docs/docs/scanner/misconfiguration/custom/data.md @@ -1,15 +1,14 @@ # Custom Data -Custom checks may require additional data in order to determine an answer. +Custom checks may require additional data in order to make a resolution. You can pass arbitrary data files to Trivy to be used when evaluating rego checks using the `--data` flag. +Trivy recursively searches the specified data paths for JSON (`*.json`) and YAML (`*.yaml`) files. -For example, an allowed list of resources that can be created. -Instead of hardcoding this information inside your policy, Trivy allows passing paths to data files with the `--data` flag. +For example, consider an allowed list of resources that can be created. +Instead of hardcoding this information inside your policy, you can maintain the list in a separate file. -Given the following yaml file: +Example data file: -```bash -$ cd examples/misconf/custom-data -$ cat data/ports.yaml [~/src/github.com/aquasecurity/trivy/examples/misconf/custom-data] +```yaml services: ports: - "20" @@ -19,7 +18,7 @@ services: - "23/tcp" ``` -This can be imported into your policy: +Example usage in a Rego check: ```rego import data.services @@ -27,9 +26,8 @@ import data.services ports := services.ports ``` -Then, you need to pass data paths through `--data` option. -Trivy recursively searches the specified paths for JSON (`*.json`) and YAML (`*.yaml`) files. +Example loading the data file: ```bash -$ trivy conf --config-check ./checks --data ./data --namespaces user ./configs -``` \ No newline at end of file +trivy config --config-check ./checks --data ./data --namespaces user ./configs +``` diff --git a/docs/docs/scanner/misconfiguration/custom/index.md b/docs/docs/scanner/misconfiguration/custom/index.md index 9e7b5106c1be..7f471d873e8b 100644 --- a/docs/docs/scanner/misconfiguration/custom/index.md +++ b/docs/docs/scanner/misconfiguration/custom/index.md @@ -2,7 +2,7 @@ ## Overview You can write custom checks in [Rego][rego]. -Once you finish writing custom checks, you can pass the policy files or the directory where those checks are stored with --config-check` option. +Once you finish writing custom checks, you can pass the check files or the directory where those checks are stored with --config-check` option. ``` bash trivy conf --config-check /path/to/policy.rego --config-check /path/to/custom_checks --namespaces user /path/to/config_dir From 88d7af1c7ea133e99ee144428702feddb3b3cd24 Mon Sep 17 00:00:00 2001 From: Itay Shakury Date: Wed, 7 Aug 2024 22:00:34 +0300 Subject: [PATCH 8/9] address comments and small changes --- docs/docs/advanced/air-gap.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/docs/advanced/air-gap.md b/docs/docs/advanced/air-gap.md index 13dc21d07eef..cf1df06f1bfe 100644 --- a/docs/docs/advanced/air-gap.md +++ b/docs/docs/advanced/air-gap.md @@ -43,7 +43,7 @@ trivy image --skip-db-update --skip-java-db-update --offline-scan --skip-check-u ## Self-Hosting -## OCI Databases +### OCI Databases You can host the databases on your own local OCI registry. @@ -63,11 +63,11 @@ trivy image \ myimage ``` -### Authentication +#### 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 +### VEX Hub You can host a copy of VEX Hub on your own internal server. @@ -82,13 +82,13 @@ First, make a copy of VEX Hub in a location that is accessible to Trivy. Then, tell Trivy to use the local VEX Repository: -1. Locate you [Trivy VEX configuration file](https://aquasecurity.github.io/trivy/latest/docs/supply-chain/vex/repo/#configuration-file) by running `trivy vex repo init`. Make the following changes to the file: +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](https://aquasecurity.github.io/trivy/latest/docs/supply-chain/vex/repo/#custom-repositories) with the URL pointing to your local server (e.g `url: https://server.local`). +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 +#### Authentication -If your server requires authentication, you can configure it as described in the [VEX Repository Authentication document](https://aquasecurity.github.io/trivy/latest/docs/supply-chain/vex/repo/#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 @@ -157,6 +157,6 @@ For Java DB the process is the same, except for the following: ## Misconfigurations scanning -Note that the misconfigurations database 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. +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). From 5f198722dddfad13afd12f0fe5afba6ab841b2cf Mon Sep 17 00:00:00 2001 From: knqyf263 Date: Thu, 8 Aug 2024 14:59:14 +0400 Subject: [PATCH 9/9] docs: fix broken links Signed-off-by: knqyf263 --- docs/docs/scanner/misconfiguration/check/builtin.md | 2 +- docs/docs/scanner/misconfiguration/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/scanner/misconfiguration/check/builtin.md b/docs/docs/scanner/misconfiguration/check/builtin.md index 900fb27109d5..c4ca18e79006 100644 --- a/docs/docs/scanner/misconfiguration/check/builtin.md +++ b/docs/docs/scanner/misconfiguration/check/builtin.md @@ -13,7 +13,7 @@ Trivy checks are distributed as an [OPA bundle](opa-bundle) hosted in the follow Trivy checks for updates to OPA bundle on GHCR every 24 hours and pulls it if there are any updates. ### External connectivity -Trivy needs to connect to the internet to download the bundle. 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). +Trivy needs to connect to the internet to download the bundle. 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 Checks bundle is also embedded in the Trivy binary (at build time), and will be used as a fallback if Trivy is unable to download the bundle. 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. [rego]: https://www.openpolicyagent.org/docs/latest/policy-language/ diff --git a/docs/docs/scanner/misconfiguration/index.md b/docs/docs/scanner/misconfiguration/index.md index e8cda93a4658..0726e7312417 100644 --- a/docs/docs/scanner/misconfiguration/index.md +++ b/docs/docs/scanner/misconfiguration/index.md @@ -316,7 +316,7 @@ This section describes misconfiguration-specific configuration. Other common options are documented [here](../../configuration/index.md). ### External connectivity -Trivy needs to connect to the internet to download the checks bundle. 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). +Trivy needs to connect to the internet to download the checks bundle. 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). ### Enabling a subset of misconfiguration scanners It's possible to only enable certain misconfiguration scanners if you prefer.