Bring your own scanner using an ImageVulnerabilityScan

This topic tells you how to bring your own scanner using an ImageVulnerabilityScan. An ImageVulnerabilityScan allows you to scan with any scanner by defining your scan as a Tekton step. For more information, see the Tekton documentation.

Customize an ImageVulnerabilityScan

To customize an ImageVulnerabilityScan to use your scanner:

1. Create a file named image-vulnerability-scan.yaml.

   apiVersion: app-scanning.apps.tanzu.vmware.com/v1alpha1
   kind: ImageVulnerabilityScan
   metadata:
     name: generic-image-scan
     namespace: DEV-NAMESPACE
     annotations:
       app-scanning.apps.tanzu.vmware.com/scanner-name: SCANNER-NAME
   spec:
     image: TARGET-IMAGE
     scanResults:
       location: registry/project/scan-results
     serviceAccountNames:
       scanner: scanner
       publisher: publisher
     steps:
     - name: scan
       image: SCANNER-IMAGE
       command: ["SCANNER-CLI-COMMAND"]
       args:
       ...
   

   Where:

   • DEV-NAMESPACE is the developer namespace where scanning occurs.
   • spec.image is the image that you are scanning. You must specify the digest. For more information, see Retrieving an image digest.
   • scanResults.location is the registry URL where results are uploaded. For example, my.registry/scan-results.
   • serviceAccountNames includes:
     • scanner, which is the service account that runs the scan. It must have read access to image.
     • publisher, which is the service account that uploads results. It must have write access to scanResults.location.
   • SCANNER-IMAGE is your vulnerability scanner image, such as the image containing the scanner of your choice.
   • SCANNER-CLI-COMMAND is the scanner’s CLI command.
   • SCANNER-NAME is the scanner image name that is reported in Tanzu Developer Portal.

   Important

   Do not define write-certs or cred-helper as step names. These names are already used during scanning.

2. Configure the scan step. You must input your scanner-specific image, command, and args. For example:

   - name: scan
     image: anchore/grype:latest
     command: ["grype"]
     args:
     - registry:$(params.image)
     - -o
     - cyclonedx
     - --file
     - $(params.scan-results-path)/scan.cdx
   

   To pass spec.image and scanResults.location to args, you can use $(params.image) and $(params.scan-results-path).

   Because volumes on a Tekton pipeline are shared among steps, files created by one step are consumable by the other steps. The scan controller applies the following security context to pipelinerun.spec.podTemplate:

   runAsUser: 65534
   fsGroup: 65534
   runAsGroup: 65534
   

   Note

   If you populate any of the following fields in the securityContext, you must populate all the other fields or you might see a runtime error in the ImageVulnerabilityScan controller:

   allowPrivilegeEscalation
   runAsNonRoot
   seccompProfile
   capabilities
   

   The SCANNER-IMAGE runs and manipulates files with user and group IDs of 65534.

Configuration options

This section lists optional and required ImageVulnerabilityScan specifications fields.

Required fields:

• image is the registry URL and digest of the target image. For example, nginx@sha256:aa0afebbb3cfa473099a62c4b32e9b3fb73ed23f2a75a65ce1d4b4f55a5c2ef2.

• scanResults.location is the registry URL where results are uploaded. For example, my.registry/scan-results.

Optional fields:

• activeKeychains is an array of enabled credential helpers to authenticate against registries using workload identity mechanisms.

  activeKeychains:
  - name: acr  # Azure Container Registry
  - name: ecr  # Elastic Container Registry
  - name: gcr  # Google Container Registry
  - name: ghcr # Github Container Registry
  

• serviceAccountNames includes:

  • scanner, which is the service account that runs the scan. It must have read access to image.
  • publisher, which is the service account that uploads results. It must have write access to scanResults.location.

• workspace includes:

  • size, which is the size of the PersistentVolumeClaim the scan uses to download the image and vulnerability database.
  • bindings, which is an additional array of secrets, ConfigMaps, or EmptyDir volumes to mount to the running scan. The name is used as the mount path.

  bindings:
  - name: additionalconfig
    configMap:
      name: my-configmap
  - name: additionalsecret
    secret:
      secretName: my-secret
  - name: scratch
    emptyDir: {}
  

For more information about workspace bindings, see the Tekton documentation. Only Secrets, ConfigMaps, and EmptyDirs are supported.

Default environment

The following describes the default environment for Tekton workspaces:

• /home/app-scanning is a memory-backed EmptyDir mount that contains service account credentials loaded by Tekton.
• /cred-helper is a memory-backed EmptyDir mount containing:
  • config.json, which combines static credentials with workload identity credentials when activeKeychains is enabled.
  • trusted-cas.crt exists when SCST - Scan 2.0 is deployed with caCertData
• /workspace is a PersistentVolumeClaim to hold scan artifacts and results. The working directory for all steps is in /workspace/scan-results by default.

Environment variables

If undefined by your step definition, the environment uses the following default variables:

• HOME=/home/app-scanning
• DOCKER_CONFIG=/cred-helper
• XDG_CACHE_HOME=/workspace/.cache
• TMPDIR=/workspace/tmp
• SSL_CERT_DIR=/etc/ssl/certs:/cred-helper

Tekton pipeline parameters:

These parameters are populated after creating the GrypeImageVulnerabilityScan. For information about parameters, see the Tekton documentation.

Parameters	Default	Type	Description
image	""	string	The scanned image
scan-results-path	/workspace/scan-results	string	Location to save scanner output
trusted-ca-certs	""	string	PEM data from the installation’s caCertData

Note

The publisher service account uploads any files, such as scanner output, in the scan-results-path directory to the registry of your choice. For information about configuring the registry URL where the publisher service account uploads scan results, see Configure your custom ImageVulnerabilityScan samples.

Retrieving an image digest

SCST - Scan 2.0 custom resources require the digest form of the URL. For example, nginx@sha256:aa0afebbb3cfa473099a62c4b32e9b3fb73ed23f2a75a65ce1d4b4f55a5c2ef2.

Use the Docker documentation to pull and inspect an image digest

For example, by running:

docker pull nginx:latest
docker inspect --format='{{index .RepoDigests 0}}' nginx:latest

Alternatively, you can install krane to retrieve the digest without pulling the image by running:

krane digest nginx:latest