Skip to main content

Trivy

License Apache-2.0GitHub release (latest SemVer)OWASP Lab ProjectArtifact HUBGitHub Repo starsMastodon Follower

What is Trivy?​

Trivy (tri pronounced like trigger, vy pronounced like envy) is a simple and comprehensive vulnerability scanner for containers and other artifacts. A software vulnerability is a glitch, flaw, or weakness present in the software or in an Operating System. Trivy detects vulnerabilities of OS packages (Alpine, RHEL, CentOS, etc.) and application dependencies (Bundler, Composer, npm, yarn, etc.). Trivy is easy to use. Just install the binary, and you're ready to scan. All you need to do for scanning is to specify a target such as an image name of the container.

To learn more about the Trivy scanner itself visit Trivy's GitHub Repository.

Deployment​

The trivy chart can be deployed via helm:

# Install HelmChart (use -n to configure another namespace)
helm upgrade --install trivy secureCodeBox/trivy

Scanner Configuration​

The following security scan configuration example are based on the Trivy Documentation, please take a look at the original documentation for more configuration examples.

Trivy Container Image Scan​

Currently we support the follwing 4 scanTypes, corresponding to the trivy scanning modes:

  • scanType: "trivy-image"
    • parameters: [YOUR_IMAGE_NAME]
  • scanType: "trivy-filesystem"
    • parameters: [YOUR_PATH_TO_FILES]
  • scanType: "trivy-repo"
    • parameters: [YOUR_GITHUB_REPO]
  • scanType: "trivy-k8s"
    • parameters: [KUBERNETES_RESOURCE]

A complete example of each scanType are listed below in our example docs section.

Simply specify an image name (and a tag) when you use the scanType trivy-image. But there are also some additional configuration options e.g:

  • Filter the vulnerabilities by severities --severity HIGH,CRITICAL ruby:2.4.0
  • Filter the vulnerabilities by type (os or library) --vuln-type os ruby:2.4.0
  • Skip update of vulnerability DB: --skip-update python:3.4-alpine3.9
  • Ignore unfixed vulnerabilities:--ignore-unfixed ruby:2.4.0 By default, Trivy also detects unpatched/unfixed vulnerabilities. This means you can't fix these vulnerabilities even if you update all packages. If you would like to ignore them, use the --ignore-unfixed option.

A complete scan definition for the secureCodeBox repository may look something like this:

apiVersion: "execution.securecodebox.io/v1"
kind: Scan
metadata:
  name: "trivy-scb"
spec:
  scanType: "trivy-image"
  parameters:
    - bkimminich/juice-shop:v10.2.0

Scanning Many Targets​

By default, the docker container of trivy will download the vulnerability database when starting the process. As this download is performed directly from GitHub, you will run into API rate limiting issues after roughly 50 requests. Trivy supports a client-server mode where one process downloads a copy of the vulnerability database and provides it to the others.

This mode is implemented and active by default. A separate Deployment for the trivy server will be created during the installation and the trivy scanTypes are automatically configured to run in client mode and connect to the server.

caution

Client/server mode is not used for trivy-k8s scans, because trivy does not support it for this type of scan. If you start many trivy-k8s scans you might run into rate limits. One way to avoid that is to preemptively download the trivy database once and then provide it similar to how the nuclei template cache is handled.

In case only a single scan or very few are run, and you want to avoid the small performance overhead, client/server mode can be disabled by setting --set="trivyDatabaseCache.enabled=false" during helm install.

Requirements​

Kubernetes: >=v1.11.0-0

Values​

KeyTypeDefaultDescription
cascadingRules.enabledboolfalseEnables or disables the installation of the default cascading rules for this scanner
createAutoDiscoveryScanTypeboolfalseCreates a trivy-image-autodiscovery scanType with its own ServiceAccount for the SCB AutoDiscovery, enabled to scan images from both public & private registries.
imagePullSecretslist[]Define imagePullSecrets when a private registry is used (see: https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/)
kubeauditScopestring"cluster"Automatically sets up rbac roles for kubeaudit to access the resources it scans. Can be either "cluster" (ClusterRole) or "namespace" (Role)
parser.affinityobject{}Optional affinity settings that control how the parser job is scheduled (see: https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes-using-node-affinity/)
parser.envlist[]Optional environment variables mapped into each parseJob (see: https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/)
parser.image.pullPolicystring"IfNotPresent"Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images
parser.image.repositorystring"docker.io/securecodebox/parser-trivy"Parser image repository
parser.image.tagstringdefaults to the charts versionParser image tag
parser.nodeSelectorobject{}Optional nodeSelector settings that control how the scanner job is scheduled (see: https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes/)
parser.resourcesobject{ requests: { cpu: "200m", memory: "100Mi" }, limits: { cpu: "400m", memory: "200Mi" } }Optional resources lets you control resource limits and requests for the parser container. See https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
parser.scopeLimiterAliasesobject{}Optional finding aliases to be used in the scopeLimiter.
parser.tolerationslist[]Optional tolerations settings that control how the parser job is scheduled (see: https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/)
parser.ttlSecondsAfterFinishedstringnilseconds after which the Kubernetes job for the parser will be deleted. Requires the Kubernetes TTLAfterFinished controller: https://kubernetes.io/docs/concepts/workloads/controllers/ttlafterfinished/
scanner.activeDeadlineSecondsstringnilThere are situations where you want to fail a scan Job after some amount of time. To do so, set activeDeadlineSeconds to define an active deadline (in seconds) when considering a scan Job as failed. (see: https://kubernetes.io/docs/concepts/workloads/controllers/job/#job-termination-and-cleanup)
scanner.affinityobject{}Optional affinity settings that control how the scanner job is scheduled (see: https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes-using-node-affinity/)
scanner.backoffLimitint3There are situations where you want to fail a scan Job after some amount of retries due to a logical error in configuration etc. To do so, set backoffLimit to specify the number of retries before considering a scan Job as failed. (see: https://kubernetes.io/docs/concepts/workloads/controllers/job/#pod-backoff-failure-policy)
scanner.envlist[]Optional environment variables mapped into each scanJob (see: https://kubernetes.io/docs/tasks/inject-data-application/define-environment-variable-container/)
scanner.extraContainerslist[]Optional additional Containers started with each scanJob (see: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/)
scanner.extraVolumeMountslist[]Optional VolumeMounts mapped into each scanJob (see: https://kubernetes.io/docs/concepts/storage/volumes/)
scanner.extraVolumeslist[]Optional Volumes mapped into each scanJob (see: https://kubernetes.io/docs/concepts/storage/volumes/)
scanner.image.pullPolicystring"IfNotPresent"Image pull policy. One of Always, Never, IfNotPresent. Defaults to Always if :latest tag is specified, or IfNotPresent otherwise. More info: https://kubernetes.io/docs/concepts/containers/images#updating-images
scanner.image.repositorystring"docker.io/aquasec/trivy"Container Image to run the scan
scanner.image.tagstringnildefaults to the charts appVersion
scanner.nameAppendstringnilappend a string to the default scantype name.
scanner.nodeSelectorobject{}Optional nodeSelector settings that control how the scanner job is scheduled (see: https://kubernetes.io/docs/tasks/configure-pod-container/assign-pods-nodes/)
scanner.podSecurityContextobject{}Optional securityContext set on scanner pod (see: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/)
scanner.resourcesobject{}CPU/memory resource requests/limits (see: https://kubernetes.io/docs/tasks/configure-pod-container/assign-memory-resource/, https://kubernetes.io/docs/tasks/configure-pod-container/assign-cpu-resource/)
scanner.securityContextobject{"allowPrivilegeEscalation":false,"capabilities":{"drop":["all"]},"privileged":false,"readOnlyRootFilesystem":false,"runAsNonRoot":false}Optional securityContext set on scanner container (see: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/)
scanner.securityContext.allowPrivilegeEscalationboolfalseEnsure that users privileges cannot be escalated
scanner.securityContext.capabilities.drop[0]string"all"This drops all linux privileges from the container.
scanner.securityContext.privilegedboolfalseEnsures that the scanner container is not run in privileged mode
scanner.securityContext.readOnlyRootFilesystemboolfalsePrevents write access to the containers file system
scanner.securityContext.runAsNonRootboolfalseEnforces that the scanner image is run as a non root user
scanner.suspendboolfalseif set to true the scan job will be suspended after creation. You can then resume the job using kubectl resume <jobname> or using a job scheduler like kueue
scanner.tolerationslist[]Optional tolerations settings that control how the scanner job is scheduled (see: https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/)
scanner.ttlSecondsAfterFinishedstringnilseconds after which the Kubernetes job for the scanner will be deleted. Requires the Kubernetes TTLAfterFinished controller: https://kubernetes.io/docs/concepts/workloads/controllers/ttlafterfinished/
trivyDatabaseCache.enabledbooltrueEnables or disables the use of trivy server in another pod to cache the vulnerability database for all scans.
trivyDatabaseCache.replicasint1amount of replicas to configure for the Deployment

License​

License

Code of secureCodeBox is licensed under the Apache License 2.0.

CPU architectures​

The scanner is currently supported for these CPU architectures:

  • linux/amd64
  • linux/arm64
  • linux/ppc64le
  • linux/s390x

Examples​

filesystem​

This example shows how to use the trivy filesystem scan with the secureCodeBox. You can use a ìnitContainer and also volumeMounts to point to the filesystem you want to scan.

# SPDX-FileCopyrightText: the secureCodeBox authors
#
# SPDX-License-Identifier: Apache-2.0

apiVersion: "execution.securecodebox.io/v1"
kind: Scan
metadata:
  name: "trivy-filesystem"
spec:
  scanType: "trivy-filesystem"
  # Define a volume and mount it at /repo in the scan container to have a filesystem in place
  volumes:
    - name: repo
      emptyDir: {}
  volumeMounts:
    - name: repo
      mountPath: "/repo/"
  # Define an init container to run the git clone for us
  initContainers:
    - name: "git-clone"
      image: bitnami/git
      # Specify that the "repo" volume should also be mounted on the
      # initContainer
      volumeMounts:
        - name: repo
          mountPath: "/repo/"
      # Clone to /repo in the init container
      command:
        - git
        - clone
        # Add access token to the URL for authenticated HTTPS clone
        - "https://github.com/yourOrg/yourRepo"
        - /repo/
  parameters:
    - "/repo"

image-juice-shop​

This example shows how to use the trivy image scan with the secureCodeBox.

# SPDX-FileCopyrightText: the secureCodeBox authors
#
# SPDX-License-Identifier: Apache-2.0

apiVersion: "execution.securecodebox.io/v1"
kind: Scan
metadata:
  name: "trivy-juiceshop"
  labels:
    organization: "OWASP"
spec:
  scanType: "trivy-image"
  parameters:
    - "bkimminich/juice-shop:v10.2.0"

image-mediawiki​

This example shows how to use the trivy image scan with the secureCodeBox.

# SPDX-FileCopyrightText: the secureCodeBox authors
#
# SPDX-License-Identifier: Apache-2.0

apiVersion: "execution.securecodebox.io/v1"
kind: Scan
metadata:
  name: "trivy-mediawiki"
spec:
  scanType: "trivy-image"
  parameters:
    - "mediawiki:stable"

k8s​

This example shows how to use the trivy k8s scan with the secureCodeBox.

# SPDX-FileCopyrightText: the secureCodeBox authors
#
# SPDX-License-Identifier: Apache-2.0

apiVersion: "execution.securecodebox.io/v1"
kind: Scan
metadata:
  name: "trivy-k8s"
spec:  
  scanType: "trivy-k8s"
  parameters:
    - "cluster"

repo-github​

This example shows how to use the trivy repo scan with the secureCodeBox.

# SPDX-FileCopyrightText: the secureCodeBox authors
#
# SPDX-License-Identifier: Apache-2.0

apiVersion: "execution.securecodebox.io/v1"
kind: Scan
metadata:
  name: "trivy-repo-github"
spec:
  scanType: "trivy-repo"
  parameters:
    - "https://github.com/knqyf263/trivy-ci-test"