trivy-k8s-wrapper

packaged by Chainguard

Chainguard Container for trivy-k8s-wrapper

Runs Trivy vulnerability scans against Kubernetes workloads for GitLab Operational Container Scanning.

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/trivy-k8s-wrapper:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

The trivy-k8s-wrapper image is comparable to the upstream trivy-k8s-wrapper image, which GitLab also mirrors to registry.gitlab.com/security-products/trivy-k8s-wrapper, and is designed to be a drop-in replacement for it. It keeps the layout the GitLab agent expects: the wrapper binary at /app/trivyK8Swrapper, the trivy binary at /home/gitlab/trivy, /home/gitlab as the working directory, and /app/trivyK8Swrapper scan as the default command.

Tags map onto upstream's unsuffixed tags: the full version (0.11.5) and the floating major version (0) resolve the same way in both upstream registries. This image also publishes a minor-version tag (0.11), which upstream does not, and it omits the architecture-suffixed tags (-amd64, -arm64) that upstream publishes alongside its multi-architecture manifests. Upstream publishes latest only in its project registry, not in the mirror. Upstream's -amd64-fips tags correspond to the separate trivy-k8s-wrapper-fips image here.

There are two differences from the upstream image:

• The trivy scanner comes from Chainguard's trivy package, which tracks the latest Trivy release, rather than from the release binary the upstream build downloads. Trivy reports its own version to GitLab, so scan reports record the version this image ships.
• The image runs as UID 1001 in the gitlab group, matching the UBI-based FIPS variant of the upstream image. It also has no shell or package manager.

The wrapper writes its intermediate report to result.json in /home/gitlab, and Trivy caches its vulnerability database under the same directory. Both are owned by UID 1001. If you override the pod's runAsUser, mount a writable volume at /home/gitlab or set TRIVY_CACHE_DIR and the working directory to a path that user can write.

Prerequisites

This image only does useful work inside a Kubernetes cluster. It needs a service account that can list the workloads it scans and create configmaps in the GitLab agent's namespace. In normal use you do not deploy this image yourself: you enable operational container scanning in your GitLab agent configuration, and the agent creates one scan Job per namespace on the cadence you set.

Getting Started

Like the upstream image, this one has no entrypoint: the whole command lives in the container's Cmd, so a docker run that passes flags has to name the binary. Confirm the wrapper responds:

docker run --rm --entrypoint /app/trivyK8Swrapper \
  cgr.dev/ORGANIZATION/trivy-k8s-wrapper:latest --help

The wrapper takes all of its parameters from the environment, so a scan is a Job with no command override. The following manifest scans the production namespace and writes the report into the gitlab-agent namespace, which is what the agent does on your behalf:

cat > ocs-scan.yaml <<EOF
apiVersion: batch/v1
kind: Job
metadata:
  name: ocs-scan
  namespace: gitlab-agent
spec:
  backoffLimit: 0
  template:
    spec:
      restartPolicy: Never
      serviceAccountName: gitlab-agent
      containers:
        - name: trivy-k8s-wrapper
          image: cgr.dev/ORGANIZATION/trivy-k8s-wrapper:latest
          env:
            - name: GITLAB_AGENT_NS
              value: gitlab-agent
            - name: GITLAB_AGENT_ID
              value: "1234"
            - name: NAMESPACE
              value: production
            - name: WORKLOADS
              value: pod,deployment,statefulset,daemonset,cronjob,job
EOF
kubectl apply -f ocs-scan.yaml

When the Job completes, the report is waiting in a chain of configmaps labeled agent.gitlab.com/scan=ocs:

kubectl get configmaps -n gitlab-agent -l agent.gitlab.com/scan=ocs

The GitLab agent reads that chain, forwards the vulnerabilities to GitLab, and deletes the configmaps. If you run the Job yourself, delete them once you are done.

Configuration

Every flag the wrapper accepts has an environment variable, which you can see with docker run --rm --entrypoint /app/trivyK8Swrapper cgr.dev/ORGANIZATION/trivy-k8s-wrapper:latest scan --help. The four shown above are required; the rest have defaults.

To run the same scan outside a Job — for example against a cluster from your workstation — pass those variables with -e and give the container a kubeconfig to reach the API server. The image has no entrypoint, so its default scan command runs on its own:

docker run --rm \
  -e GITLAB_AGENT_NS=gitlab-agent \
  -e GITLAB_AGENT_ID=1234 \
  -e NAMESPACE=production \
  -e WORKLOADS=pod,deployment,statefulset,daemonset,cronjob,job \
  -e KUBECONFIG=/home/gitlab/.kube/config \
  -v "${HOME}/.kube/config:/home/gitlab/.kube/config:ro" \
  cgr.dev/ORGANIZATION/trivy-k8s-wrapper:latest

The wrapper writes the report into the configmap chain in the GITLAB_AGENT_NS namespace, exactly as the in-cluster Job does. The mounted kubeconfig must authenticate with a token or client certificate rather than an exec credential plugin such as gke-gcloud-auth-plugin or aws eks get-token, which the minimal image does not ship, and the API server it names has to be reachable from the container.

Two settings are worth revisiting for large clusters. OCS_SEVERITY_THRESHOLD sets the lowest severity to report, and raising it from the UNKNOWN default keeps the report small enough to stay within the configmap chain. TIMEOUT bounds the Trivy scan, and the 15 minute default is short for a namespace with many distinct images:

env:
  - name: OCS_SEVERITY_THRESHOLD
    value: HIGH
  - name: TIMEOUT
    value: 30m

By default the wrapper pulls the GitLab Advisory Database build of the Trivy database from registry.gitlab.com. Set TRIVY_DB_REPOSITORY and TRIVY_JAVA_DB_REPOSITORY to use an internal registry instead, which is also how you run scans in a cluster without direct access to GitLab.

Documentation and Resources

• Upstream trivy-k8s-wrapper repository
• GitLab operational container scanning documentation
• Trivy documentation
• Chainguard Container for trivy

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.