Vulnerability scanning

Scan container images for known CVEs with Trivy on every server, read the findings, and block updates that would bring in critical vulnerabilities.

Kowan scans images for known vulnerabilities with Trivy and can block an update when the new image is riskier than you accept. Scans run on the server that holds the image, so they work the same on every host and need nothing installed on the Kowan server.

How a scan works

When you scan an image, Kowan starts a short-lived Trivy container on the image's host, through the same connection it uses for everything else on that host (the local Docker socket or the agent).

• Trivy reads the image straight from the host's Docker daemon, through a read-only socket. Nothing is pulled from a registry, so images built on the host can be scanned too.
• Trivy's vulnerability database is kept in a named volume, kowan-trivy-cache, on each host. The first scan on a host pulls the Trivy image and downloads the database, so it takes longer and the host needs to reach them. Later scans reuse both.
• One scan runs at a time per host. The scan container is removed when it finishes.
• Kowan runs Trivy's vulnerability scanner only. It does not look for secrets or misconfigurations.

Results are stored per image ID:

• A result younger than 24 hours is reused for the same image, also when it runs on another host.
• A failed scan never replaces an earlier good result.
• Up to 1000 findings are kept per image, most severe first. The severity counts are always exact.

Scan an image

1. Go to Images and open an image.
2. In the Vulnerabilities section, click Scan now.

Re-scan runs a new scan even when a result younger than 24 hours exists. A container's page shows the same Vulnerabilities section for the image it runs. Starting a scan needs the operator role.

Kowan scans when you ask, and when a scan gate needs a result before an update.

Read the results

Each finding has a severity: critical, high, medium, low or unknown.

• In the Images list, the Vulnerabilities column shows short chips such as C 2 and H 5, clean when nothing was found, scanning while a scan runs and scan failed when it did not complete. Sort by the column to bring the worst images to the top.
• The Vulnerabilities section of an image shows the Trivy version, when the image was scanned, the number of findings and how many have a fix. Below it, a searchable table lists each finding with its ID, Package, Installed version, Fixed in version and Severity.

A finding with a Fixed in version goes away once the image ships that package version. See Image updates to roll out a newer image.

Block risky updates

A scan gate scans the new image before an update switches to it, and blocks the update when the result is not acceptable. It applies to the Update buttons and to auto-update policies in apply mode.

Set the gate in one of three places. The first one that is set wins:

1. The kowan.scan.block label on the container.
2. Scan gate in the auto-update policy of the container or deployment.
3. Default scan gate in Automation → Auto-update (admins).

services:
  api:
    image: ghcr.io/example/api:2.4
    labels:
      kowan.scan.block: high

When the new image cannot be scanned, the gate blocks the update for every setting except Never block.

A blocked update leaves the running container untouched. It is recorded in the auto-update history and raises a warning alert in the bell and on your notification channels, unless the container has the label kowan.notify=off.

Configuration

These environment variables of the Kowan server change how scans run. See Configuration for the others.

API

{id} is an image ID (sha256:...) or a reference without a /. For a reference that contains /, pass _ as the ID and the reference as ?image=<ref>. See REST API.