Skip to main content

Trivy

License Apache-2.0GitHub release (latest SemVer)OWASP Lab ProjectArtifact HUBGitHub Repo starsTwitter 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 3 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]

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 new rulesets 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 rule database and provides it to the others. Due to limitations in trivy, this mode currently only supports scanning container images. If this fits your use case, you can deploy a rule service with the following template:

# First declare a service that will serve requests to the rule pod
kind: Service
apiVersion: v1
metadata:
  name: trivy-rules
  # Update the namespace here if you are using a different one
  namespace: default
  labels:
    app: trivy-rules
spec:
  selector:
    app: trivy-rules
  ports:
  - port: 8080
    protocol: TCP
    targetPort: 8080
  type: ClusterIP
---
# Now declare the actual deployment of the rule server
apiVersion: apps/v1
kind: Deployment
metadata:
  name: trivy-rules
  # Again, update the namespace here
  namespace: default
  labels:
    app: trivy-rules
spec:
  replicas: 1
  selector:
    matchLabels:
      app: trivy-rules
  template:
    metadata:
      labels:
        app: trivy-rules
    spec:
      containers:
      - name: trivy-rules
        # Don't forget to set this to a version matching that used in secureCodeBox
        image: aquasec/trivy:0.20.2
        imagePullPolicy: Always
        args:
        - "server"
        - "--listen"
        - "0.0.0.0:8080"
        ports:
        - containerPort: 8080
          protocol: TCP

You can then start scans of images using the client mode. For example:

apiVersion: "execution.securecodebox.io/v1"
kind: Scan
metadata:
  name: "test-trivy"
  # Don't forget to update the namespace if necessary
  namespace: default
spec:
  scanType: "trivy-image"
  parameters:
    - "client"
    # Again, add the extra parameters here (required to make the parser work)
    # But don't add the --no-progress switch.
    - "--format"
    - "json"
    - "--output"
    - "/home/securecodebox/trivy-results.json"
    # Specify the rule service internal DNS name here.
    # (Substitute a different namespace if you changed it)
    - "--remote"
    - "http://trivy-rules.default.svc:8080"
    # Finally, specify the image you want to scan
    - "securecodebox/operator:3.0.0"

If you want to scan anything other than docker images, you currently cannot use the client-server mode described above. Instead, you have to manually download the ruleset and provide it to trivy. In practice, this is a difficult problem because the most natural method for providing these files in kubernetes, ConfigMaps, has a size limit of 1 MB, while the vulnerability database is over 200 MB in size (28 MB after compression). Your best bet would thus be to serve the files from your own servers and load them into the scanner using an initContainer, taking care to keep the databases on your server up to date. Consult the trivy documentation for additional details on the required steps.

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/)
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.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.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/

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"

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"