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
check-circle-line exclamation-circle-line close-line
Scroll to top icon