trivy-k8s-wrapper-fips

packaged by Chainguard

Chainguard Container for trivy-k8s-wrapper-fips

FIPS-enabled image that 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-fips: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-fips image is comparable to the FIPS build of the upstream trivy-k8s-wrapper image, which upstream publishes under tags such as latest-amd64-fips, 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.

There are three differences from the upstream image:

• The trivy scanner comes from Chainguard's trivy-fips 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 upstream image. It also has no shell or package manager.
• This image is published for both amd64 and arm64, whereas upstream builds its FIPS variant for amd64 only. Tags also follow the same scheme as the non-FIPS image rather than carrying an architecture in the tag name.

FIPS Support

The trivy-k8s-wrapper-fips Chainguard Container builds both the wrapper and the Trivy scanner against a validated redistribution of OpenSSL's FIPS provider module, and ships the FIPS-hardened OpenSSL configuration.

A FIPS configuration that cannot be validated at runtime never downgrades the image to unvalidated crypto. Depending on the Go toolchain a given binary was built with, it either falls back to the Go Cryptographic Module — itself FIPS-validated — or refuses to start. If your policy requires the OpenSSL provider specifically, set GODEBUG=cgr_fips=openssl to disable that fallback, so a configuration that fails validation aborts the process instead.

For more on FIPS support in Chainguard container images, consult the guide on FIPS-enabled Chainguard Containers on Chainguard Academy.

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-fips: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-fips
          image: cgr.dev/ORGANIZATION/trivy-k8s-wrapper-fips: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-fips: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-fips: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-fips
• FIPS-enabled Chainguard Containers

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.