Set up image scanning
An image scanner lists the known vulnerabilities in each app’s container image on the app’s Security tab, so that people can see which packages to update before someone exploits them. Orchard works with two scanners: Harbor’s built-in scanner, or a Trivy server that Orchard deploys for you. This page helps you choose one, set it up, and understand what a scan does on your cluster.
The tab also has configuration checks, such as secrets stored as plain variables, moving image tags, and domains without TLS. Those checks always run, with or without a scanner.
Choose a scanner
Section titled “Choose a scanner”| Harbor | Orchard scanner | |
|---|---|---|
| What it is | Harbor’s own scanner (Trivy, run by Harbor) | A Trivy server that Orchard deploys, plus one short-lived scan job for each request |
| Needs | Harbor as your registry, with API credentials | trivy.enabled: true in the chart |
| Images built by Orchard | Yes | Yes |
| Images from Docker Hub, GHCR, or another registry | No | Yes, including private images with registry credentials |
| Installer hosts (zot registry) | No | Yes |
| When a scan runs | When Harbor scans on push, or when someone selects Scan now or Scan again | When someone selects Scan now or Scan again |
If your registry is Harbor and it already scans on push, use Harbor. Otherwise, use the Orchard scanner.
The default scanner
Section titled “The default scanner”Until a superadmin chooses a scanner, Orchard uses the first match:
- The Orchard scanner, if
TRIVY_SERVER_URLandORCHARD_INTERNAL_URLare set and Kubernetes is reachable. - Harbor, if the registry is Harbor. Orchard checks
/api/v2.0/systeminfoon the Harbor API. It caches the answer for 10 minutes, or one minute after a network error. - Off.
The one-command installer sets trivy.enabled: true, except on a new install with less than 3.5 GB of memory, where it leaves the scanner off. orchardctl update sets trivy.enabled: true only when the values file has no trivy.enabled setting yet.
To choose a scanner, go to Instance admin > Configuration > Image scanning. The stored choice replaces the default, including a choice of Off. A scanner with missing requirements is unavailable, and the page shows the reason.
Set up the Orchard scanner
Section titled “Set up the Orchard scanner”Installer hosts already have the Orchard scanner.
-
Turn on the chart block. On an installer host, run the following command:
sudo orchardctl config set trivy.enabled true --applyOn a Helm install, add the following to your values file and run
helm upgrade:trivy:enabled: trueThis creates the
orchard-scansnamespace with the Trivy server, and sets the variables that the server needs. -
Wait for the
trivypod inorchard-scansto become ready. The first start downloads the vulnerability database. -
If a superadmin already chose another scanner, go to Instance admin > Configuration > Image scanning and select Orchard scanner.
Scan jobs pull images from DOCKER_REGISTRY_PUSH with HARBOR_USERNAME and HARBOR_PASSWORD. They use plain HTTP when the host is in REGISTRY_HTTP_HOSTS.
If your registry or the Orchard namespace has its own NetworkPolicy, allow traffic from orchard-scans.
To turn off the scanner on an installer host, run the following command. orchardctl update does not turn it back on.
sudo orchardctl config set trivy.enabled false --applySet up Harbor
Section titled “Set up Harbor”- Give the server Harbor API access. Set
HARBOR_USERNAMEandHARBOR_PASSWORD, and setDOCKER_REGISTRY_PULLto Harbor. A robot account with read access to the project is enough. Add the scan permission if people should start scans from Orchard. - If the API is at a different address from the registry, set
HARBOR_API_URL. - (Optional) Turn on Automatically scan images on push in the Harbor project.
- Go to Instance admin > Configuration > Image scanning.
- Select Harbor.
Pin the scanner
Section titled “Pin the scanner”To fix the choice for the instance, set IMAGE_SCANNER on the server to off, harbor, or trivy. This value overrides the stored choice and the default. The Image scanning section shows it as an environment override.
sudo orchardctl env set IMAGE_SCANNER off --applyHow a scan works
Section titled “How a scan works”With the Orchard scanner, a scan runs as follows:
- Orchard records the scan and creates a Job in
orchard-scans, with a Secret that holds the registry credentials and a one-time token. - The Job waits up to about a minute for the Trivy server to answer. On clusters that take a few seconds to apply NetworkPolicy to a new pod, such as k3s, the first connection is refused.
- The Job runs Trivy in client mode. It pulls the image layers and asks the Trivy server which packages have known vulnerabilities.
- The Job posts the report to the API server. The server keeps the worst 500 findings and the totals.
- Kubernetes deletes the Job and its Secret 10 minutes after it finishes.
The tab shows The last scan failed with the reason when a scan fails, times out, or loses its Job. If the Job never reaches the Trivy server, the reason is Couldn’t reach the Trivy server. Check that the trivy pod in orchard-scans is ready. The default timeout is 15 minutes.
At most trivy.maxConcurrentScans scans run at once. The value is 3 in the chart and 2 from the installer, or 1 on a machine with less than 8 GB of memory. Orchard refuses more requests until a scan finishes.
A result belongs to the image, so two apps that run the same image share it. Results do not refresh on their own. To check an image that has not been rebuilt, select Scan again.
Permissions
Section titled “Permissions”Anyone who can view an app can see its scan result. Members who can edit the app can start a scan. When scanning is off, the tab shows Image scanning is off and still runs the configuration checks.
Security of scan jobs
Section titled “Security of scan jobs”- Scan jobs run with no service account token, as a non-root user, with a read-only root filesystem, under Pod Security
restricted. - Scan jobs take no inbound traffic and cannot reach cloud metadata at
169.254.0.0/16. - Trivy reads image layers but does not run them.
- Only scan jobs can reach the Trivy server. They authenticate with a shared token in the
trivy-server-tokenSecret. - The result endpoint is
POST /apiv1/internal/image-scans/:id/result. It accepts one report for each scan, authenticated by that scan’s one-time token.
Related resources
Section titled “Related resources”- Environment variables - Read the reference for
IMAGE_SCANNER,TRIVY_SERVER_URL, and the Harbor variables. - Host commands - Change chart values and environment variables on an installer host.
- Run on a small server - Turn off optional parts such as the scanner to save memory.