Skip to main content

Trivy

License Apache-2.0GitHub release (latest SemVer)OWASP Incubator 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.

  • Filter the vulnerabilities by severities trivy image --severity HIGH,CRITICAL ruby:2.4.0
  • Filter the vulnerabilities by type (os or library) trivy image --vuln-type os ruby:2.4.0
  • Skip update of vulnerability DB: trivy image --skip-update python:3.4-alpine3.9
  • Ignore unfixed vulnerabilities:trivy image --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.
caution

Due to limitations in the trivy argument parser, scanning anything other than docker images (e.g., Git repositories) requires some extra parameters. Please append the following extra arguments after specifying the mode (e.g., repo) but before specifying the target for the scan:

- "--no-progress"- "--format"- "json"- "--output"- "/home/securecodebox/trivy-results.json"

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

apiVersion: "execution.securecodebox.io/v1"kind: Scanmetadata:  name: "trivy-scb"spec:  scanType: "trivy"  parameters:    - "repo"    - "--no-progress"    - "--format"    - "json"    - "--output"    - "/home/securecodebox/trivy-results.json"    - "https://github.com/secureCodeBox/secureCodeBox"

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 podkind: ServiceapiVersion: v1metadata:  name: trivy-rules  # Update the namespace here if you are using a different one  namespace: default  labels:    app: trivy-rulesspec:  selector:    app: trivy-rules  ports:  - port: 8080    protocol: TCP    targetPort: 8080  type: ClusterIP---# Now declare the actual deployment of the rule serverapiVersion: apps/v1kind: Deploymentmetadata:  name: trivy-rules  # Again, update the namespace here  namespace: default  labels:    app: trivy-rulesspec:  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: Scanmetadata:  name: "test-trivy"  # Don't forget to update the namespace if necessary  namespace: defaultspec:  scanType: "trivy"  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
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.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.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.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.

Examples#

juice-shop#

# SPDX-FileCopyrightText: 2021 iteratec GmbH## SPDX-License-Identifier: Apache-2.0
apiVersion: "execution.securecodebox.io/v1"kind: Scanmetadata:  name: "trivy-juiceshop"  labels:    organization: "OWASP"spec:  scanType: "trivy"  parameters:    - "bkimminich/juice-shop:v10.2.0"

mediawiki#

# SPDX-FileCopyrightText: 2021 iteratec GmbH## SPDX-License-Identifier: Apache-2.0
apiVersion: "execution.securecodebox.io/v1"kind: Scanmetadata:  name: "trivy-mediawiki"spec:  scanType: "trivy"  parameters:    - "mediawiki:stable"