Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update air-gapped docs #7160

Merged
merged 10 commits into from
Aug 9, 2024
Merged

docs: update air-gapped docs #7160

Changes from 1 commit
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
88a1c0b
docs: update air-gapped docs
itaysk Jul 14, 2024
4695eeb
advanced network scenarios
itaysk Jul 15, 2024
ecb017e
load config from local dir
itaysk Jul 16, 2024
40a6a98
typo
itaysk Jul 16, 2024
b88430e
load bundle from registry
itaysk Jul 16, 2024
2327c5f
add vex repo
itaysk Aug 7, 2024
da24941
address comments and small improvements
itaysk Aug 7, 2024
88d7af1
address comments and small changes
itaysk Aug 7, 2024
0cffae0
Merge branch 'main' into airgap
knqyf263 Aug 8, 2024
5f19872
docs: fix broken links
knqyf263 Aug 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
add vex repo
  • Loading branch information
@itaysk
itaysk committed Aug 7, 2024
commit 2327c5f4c56b28d8734362e6c47b1cbd91988d58
41 changes: 36 additions & 5 deletions docs/docs/advanced/air-gap.md
View file
Open in desktop
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have an idea about re-structuring this page, but we can do that in another PR.

Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -10,12 +10,18 @@ Trivy's databases are distributed as OCI images via GitHub Container registry (G
- <https://ghcr.io/aquasecurity/trivy-java-db>
- <https://ghcr.io/aquasecurity/trivy-checks>

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

Expand All @@ -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
itaysk marked this conversation as resolved.
Show resolved Hide resolved

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:

Expand All @@ -57,7 +65,30 @@ trivy image \

### Authentication
itaysk marked this conversation as resolved.
Show resolved Hide resolved

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: <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 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`).
itaysk marked this conversation as resolved.
Show resolved Hide resolved

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

Expand Down