Skip to content
Install

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.

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.

Until a superadmin chooses a scanner, Orchard uses the first match:

  1. The Orchard scanner, if TRIVY_SERVER_URL and ORCHARD_INTERNAL_URL are set and Kubernetes is reachable.
  2. Harbor, if the registry is Harbor. Orchard checks /api/v2.0/systeminfo on the Harbor API. It caches the answer for 10 minutes, or one minute after a network error.
  3. 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.

Installer hosts already have the Orchard scanner.

  1. Turn on the chart block. On an installer host, run the following command:

    sudo orchardctl config set trivy.enabled true --apply

    On a Helm install, add the following to your values file and run helm upgrade:

    trivy:
    enabled: true

    This creates the orchard-scans namespace with the Trivy server, and sets the variables that the server needs.

  2. Wait for the trivy pod in orchard-scans to become ready. The first start downloads the vulnerability database.

  3. 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 --apply
  1. Give the server Harbor API access. Set HARBOR_USERNAME and HARBOR_PASSWORD, and set DOCKER_REGISTRY_PULL to Harbor. A robot account with read access to the project is enough. Add the scan permission if people should start scans from Orchard.
  2. If the API is at a different address from the registry, set HARBOR_API_URL.
  3. (Optional) Turn on Automatically scan images on push in the Harbor project.
  4. Go to Instance admin > Configuration > Image scanning.
  5. Select Harbor.

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

With the Orchard scanner, a scan runs as follows:

  1. Orchard records the scan and creates a Job in orchard-scans, with a Secret that holds the registry credentials and a one-time token.
  2. 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.
  3. The Job runs Trivy in client mode. It pulls the image layers and asks the Trivy server which packages have known vulnerabilities.
  4. The Job posts the report to the API server. The server keeps the worst 500 findings and the totals.
  5. 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.

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.

  • 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-token Secret.
  • 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.
  • 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.