STO step settings

This document describes a few common settings available for scanners in STO. For a list of supported scanners, see the Supported Scanners page.

Scanning a Docker image with STO

STO supports two primary ways of scanning a container image; scanning the docker image contained within a Docker-in-Docker background step (requiring privileged mode) or scanning an OCI/Docker archive, which doesn't need the Docker-in-Docker background step (this is the recommended approach).

Scanning an OCI/Docker archive with STO

Scanning an OCI/Docker archive is easier and preferred approach, as it simplifies configuration by removing the need for a Docker-in-Docker background step and reducing security overhead (since privileged mode is not required). STO will automatically scan the OCI/Docker archive without any need for additional DinD configurations.

If you want to force the scanner step not to use any Docker-in-Docker(DinD) background step, set the following variable in the Settings section of your step configuration (optional):

• docker_mode: without-docker-in-docker

This setting is optional and only needed if you want to force the STO to use a specific approach.

The following scanners can perform container scanning without requiring a Docker-in-Docker background step.

Scanners that do not require Docker-in-Docker as a background step

Scanner	Do not need DinD
Anchore	✅
Aqua Security	✅
Aqua Trivy	✅
AWS ECR Scan	✅
Black Duck	DinD is required
Custom Scan	DinD is required
Grype	✅
Prisma Cloud	✅
Snyk	✅
Sysdig	✅
Wiz	✅

Configuring Docker-in-Docker (DinD) for your pipeline

Here’s how you can set up Docker-in-Docker as a Background step in your pipeline.

Set up a Docker-in-Docker background step

1. Go to the stage where you want to run the scan.

2. In Overview, add the shared path /var/run.

3. In Execution, do the following:

   1. Click Add Step and then choose Background.
   2. Configure the Background step as follows:
      1. Dependency Name = dind
      2. Container Registry = The Docker connector to download the DinD image. If you don't have one defined, go to Docker connector settings reference.
      info

      If your container registry uses a self-signed certificate, the background step will not be able to access the registry by default. Refer to Configure DinD Background step to trust self-signed container registries for instructions.

      3. Image = docker:dind

      4. Under Entry Point, add the following: dockerd

         In most cases, using dockerd is a faster and more secure way to set up the background step. For more information, go to the TLS section in the Docker quick reference.

         If the DinD service doesn't start with dockerd, clear the Entry Point field and then run the pipeline again. This starts the service with the default entry point.

      5. Under Optional Configuration, select the Privileged checkbox.

Visual setup

YAML setup

Add a Background step to your pipeline and set it up as follows:

- step:
   type: Background
   name: background-dind-service
   identifier: Background_1
   spec:
      connectorRef: CONTAINER_IMAGE_REGISTRY_CONNECTOR
      image: docker:dind
      shell: Sh
      entrypoint:
         - dockerd
      privileged: true

For Orchestrated and Extraction scans, you might want to increase the resource limits for your Docker-in-Docker background step. This can speed up your scan times, especially for large scans. For more information, go to Optimize STO pipelines.

If you want to force the scanner step to use Docker-in-Docker (DinD) background step, set the following variable in the Settings section of your step configuration (optional):

• docker_mode: docker-in-docker

This setting is optional and only needed if you want to force the STO to use a specific approach.

Configuring DinD Background step to trust self-signed container registries

When using Docker-in-Docker (DinD) as a background step for scanning container images, the step needs to pull images from your container registry. If your container registry uses a self-signed certificate, the background step will not be able to access it by default. To resolve this issue, you need to add the following command to configure the background step to trust the self-signed container registry.

Following the DinD configuration, apply the below settings

1. Set the Shell field to Sh
2. In the Command filed, enter the following command
   Command to configure the background step to trust your container registry.

   
       # This is the domain name where the image is going to be pulled from. For example,
       # registry_domain=example.io
       # registry_domain=localhost:5000
   
       registry_domain=example.io # replace with the domain of the registry behind the self-signed CA
   
       # Get all .pem files in the current directory
       pem_files=$(find $HARNESS_SHARED_CERTS_PATH -name "*.pem")
   
       # Iterate over each .pem file
       mkdir -p /etc/docker/certs.d/${registry_domain}
       touch /etc/docker/certs.d/${registry_domain}/ca.crt
       echo $pem_files
       for pem_file in $pem_files; do
       # Extract the key from the .pem file
       cat $pem_file >> /etc/docker/certs.d/${registry_domain}/ca.crt
       done
   
       dockerd-entrypoint.sh

Root access requirements for STO

If you want to add trusted certificates to your scan images at runtime, you need to run the scan step with root access.

You can utilize custom STO scan images and pipelines to run scans as a non-root user. For more details, refer Configure your pipeline to use STO images from private registry.

Security steps and scanner templates in STO

The Step library includes a Custom Scan step for setting up scanners: open the step and configure the scan as a set of key/value pairs under Settings.

Some scanners also have their own steps with simplified UIs that simplify the setup process.

Step Library with scanner-specific steps and Custom Scan step

Custom Scan step configuration

Scanner-specific step configuration