docs: reorg db and airgapped docs

docs/docs/advanced/air-gap.md

@@ -1,94 +1,48 @@
-# Advanced Network Scenarios
+# Air-Gapped Environments and Self-Hosting
 
-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.
+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 fetched and maintained by Trivy automatically as needed.
 
-## Network requirements
+If your organizations blocks or restricts network traffic (from the machine Trivy runs on), Trivy might not be able to download the databases from public repositories.
 
-Trivy's databases are distributed as OCI images via GitHub Container registry (GHCR):
+This document explains how handle such advanced connectivity scenarios.
 
-- <https://ghcr.io/aquasecurity/trivy-db>
-- <https://ghcr.io/aquasecurity/trivy-java-db>
-- <https://ghcr.io/aquasecurity/trivy-checks>
-
-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 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
-
-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.
-- `--skip-check-update` to skip updating the misconfiguration database.
-
-```shell
-trivy image --skip-db-update --skip-java-db-update --offline-scan --skip-check-update myimage
-```
+!!! note
+    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.
 
 ## Self-Hosting
 
-### OCI Databases
+You can host Trivy's databases in a container registry that is accessible to Trivy.
 
-You can host the databases on your own local OCI registry. 
+First, make a copy of the databases into your container registry. The different databases, their use cases, and their locations are detailed in the [Trivy Databases](../configuration/db.md) document.
 
-First, make a copy of the databases in a container registry that is accessible to Trivy. The databases are in:
+ !!! note
+    You will need to keep the databases updated in order to maintain relevant scanning results.
 
-- `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 using the relevant flags.
 
-Then, tell Trivy to use the local registry:
+For example, we if we scan a Java application, we copy the `trivy-db` and `trivy-java-db` databases to our local registry, and tell Trivy to use them. In this case we also need to turn off Trivy's [Java scanner external service](../coverage/language/java.md) with the `--offline-scan` flag:
 
 ```shell
 trivy image \
     --db-repository myregistry.local/trivy-db \
     --java-db-repository myregistry.local/trivy-java-db \
-    --checks-bundle-repository myregistry.local/trivy-checks \
+    --offline-scan \
     myimage
 ```
 
-#### Authentication
+### Registry 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:
+### Pull through cache
 
-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`).
+You can install a pull-through cache service inside your environment that automatically serves consecutive pulls from cache instead of reaching the origin.  
+Here are some examples for pull-through cache solutions:
 
-#### Authentication
-
-If your server requires authentication, you can configure it as described in the [VEX Repository Authentication document](../supply-chain/vex/repo/#authentication).
+- [Docker Registry](https://docs.docker.com/docker-hub/mirror/)
+- [Harbor](https://goharbor.io/docs/2.1.0/administration/configure-proxy-cache/)
+- [Zot](https://zotregistry.dev/v2.1.0/articles/mirroring)
+- [AWS ECR](https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache.html) 
 
 ## Manual cache population
 
@@ -157,6 +111,27 @@ For Java DB the process is the same, except for the following:
 
 ## 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.
+Misconfigurations checks are 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.
+
+## 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:
 
-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).
+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`).
+
+### VEX Hub Authentication
+
+If your server requires authentication, you can configure it as described in the [VEX Repository Authentication document](../supply-chain/vex/repo/#authentication).