Configure pipeline to use STO images from private registry

Store your scanner images in a private registry. Useful for air-gapped environments.

Harness maintains its own set of scan images for STO-supported scanners. By default, a Harness pipeline pulls scan images from the Harness DockerHub.

This topic describes how to override the default image pull behavior and use your own private registry instead of pulling directly from the public Harness DockerHub. You can download the scan images you need, perform your own security checks on the images, upload them to a private registry, and then set up your STO steps to download images from your private registry.

To do this, you need to:

1. (Optional) Create scanner images with your own SSL certificates.

2. Create a connector for your private registry.

3. Configure the pipeline to download images from your registry.

Create STO scanner images with your own SSL certificates (optional)

Harness STO supports three workflows for running scans with custom certificates.

In this workflow, you set up your STO scan images and pipelines to run scans as non-root and establish trust for your own proxies using custom certificates. This workflow supports any STO-compatible scanner that can run natively without root access. This workflow also supports build environments that use a self-signed proxy server between the Harness Delegate and Harness Manager.

Running container image scans as a non-root user is not currently supported.

1. Save a copy of the following Dockerfile into a folder along with the certificates you want to copy to the image.

2. Update the FROM, COPY, and USER commands as described in the Dockerfile comments.

3. Build the new image and then publish it to your private registry.

4. Update the scan step in your pipeline as follows:

   1. Update the Image setting to point to the new image in your registry.

   2. If you specified a USER in your Dockerfile, set the Run as User (runAsUser) setting to the user you specified in your Dockerfile.

Dockerfile template for adding certificates to an STO scanner image

# STEP 1 <a href="#step-1" id="step-1"></a>
# Specify the STO scanner image where you want to add your certificates <a href="#specify-the-sto-scanner-image-where-you-want-to-add-your-certificates" id="specify-the-sto-scanner-image-where-you-want-to-add-your-certificates"></a>
# For a list of all images in the Harness Container Registry, run the following: <a href="#for-a-list-of-all-images-in-the-harness-container-registry-run-the-following" id="for-a-list-of-all-images-in-the-harness-container-registry-run-the-following"></a>
# curl -X  GET https://app.harness.io/registry/_catalog <a href="#curl-x-get-httpsappharnessioregistrycatalog" id="curl-x-get-httpsappharnessioregistrycatalog"></a>
FROM harness/twistlock-job-runner:latest as scanner

# FYI Root access is required to load and trust certificates <a href="#fyi-root-access-is-required-to-load-and-trust-certificates" id="fyi-root-access-is-required-to-load-and-trust-certificates"></a>
USER root

# STEP 2 <a href="#step-2" id="step-2"></a>
# Copy your certificates to the engine <a href="#copy-your-certificates-to-the-engine" id="copy-your-certificates-to-the-engine"></a>
# You can copy multiple ca from completely different paths into SHARE_CA_PATH <a href="#you-can-copy-multiple-ca-from-completely-different-paths-into-sharecapath" id="you-can-copy-multiple-ca-from-completely-different-paths-into-sharecapath"></a>
COPY ./CERTIFICATE_1.pem ../another-folder/CERTIFICATE_2.pem /shared/customer_artifacts/certificates/


# FYI establishes trust for certificates in Python and the OS <a href="#fyi-establishes-trust-for-certificates-in-python-and-the-os" id="fyi-establishes-trust-for-certificates-in-python-and-the-os"></a>
RUN sto_plugin --trust-certs
# Optional: To trust certificates for Java for tools such as <a href="#optional-to-trust-certificates-for-java-for-tools-such-as" id="optional-to-trust-certificates-for-java-for-tools-such-as"></a>
# - Black Duck Hub <a href="#black-duck-hub" id="black-duck-hub"></a>
# - Checkmarx <a href="#checkmarx" id="checkmarx"></a>
# - Sonarqube <a href="#sonarqube" id="sonarqube"></a>
# - Veracode <a href="#veracode" id="veracode"></a>
# - NexusIQ <a href="#nexusiq" id="nexusiq"></a>
# RUN sh /bin/setup.sh <a href="#run-sh-binsetupsh" id="run-sh-binsetupsh"></a>

# STEP 3 (optional) <a href="#step-3-optional" id="step-3-optional"></a>
# Create a user and assume limited permission user <a href="#create-a-user-and-assume-limited-permission-user" id="create-a-user-and-assume-limited-permission-user"></a>
# If you set this, you need to add runAsUser setting in the scan step <a href="#if-you-set-this-you-need-to-add-runasuser-setting-in-the-scan-step" id="if-you-set-this-you-need-to-add-runasuser-setting-in-the-scan-step"></a>
# i.e., runAsUser: "1000" <a href="#ie-runasuser-1000" id="ie-runasuser-1000"></a>
USER 1000

Create a connector to your private registry

You need a Docker connector that points to your private container registry. For more information, go to Docker Connector Settings Reference.

Configure your pipeline to use images from your registry

1. Download the scan images you need from the Harness DockerHub, test and validate the images, and store them in your private registry.

   Do not change the image names in your private registry. The image names must match the names specified by Harness; this includes the harness/ prefix.

2. By default, STO will automatically use the latest image from the public Harness registry, you might want to specify the images to use in your pipelines. This ensures that your pipelines use specific image versions. You must update this specification when you want to adopt a new version of an image.

3. Set up your pipeline to use the images from your private registry. This can be done at both the stage level and the step level for scanner steps(Blackduck, Semgrep etc.,) and Custom Scan steps. Below are the detailed steps and configurations required for each scenario.

   • Override security test images for scanner steps:

     • Stage level override

     • Step level override

   • Override security test images for Custom Scan steps

Override security test images for scanner steps

Stage level override

If you want to use your private images for all steps within a stage, follow these steps:

1. Navigate to the Infrastructure section in your stage.

2. Go to the Advanced section.

3. Configure your private registry under the Override Image Connector section.

Do not modify the names of the images in your private registry. STO will automatically look for the exact name(harness/<SCANNER_NAME>-job-runner) based on the step added to the pipeline.

Step level override

If you want to override the image for a specific step within a stage, follow these steps:

1. Navigate to the specific STO step in the pipeline.

2. Go to the Additional Configuration section in the step configuration.

3. Set your private registry and tag under Override Security Test Image section. By default, the step will look for the latest tag if no tag is provided.

Do not modify the names of the images in your private registry. STO will automatically look for the exact name(harness/<SCANNER_NAME>-job-runner) based on the step added to the pipeline.

Override security test images for Custom Scan steps

The Custom Scan step uses the sto-plugin image to launch the appropriate scanner image(internally called as runner) based on the step configuration. You have the option to either override both the sto-plugin image and the scanner image, or simply override the scanner image while keeping the sto-plugin image unchanged.

To override the scanner image in a Custom Scan step, add the following settings in the Additional Configuration section of the Custom Scan step:

• runner_registry_domain: The URL of the registry where the images are stored. The supported format is <_domain_>/<_directory_> (such as, public.ecr.aws/r7c1u4s0/harness). Do not include the scheme (such as http:// or https://).

• runner_registry_image_prefix: set this to harness (Do not change this setting)

• runner_registry_username: The username of your registry

• runner_registry_token: The token to access your registry

• runner_tag: The image tag

If you want to override the sto-plugin image for the Custom Scan steps, you can configure your private registry either at the stage level or step level, based on your requirements. Refer to the stage level or step level sections above for instructions, as they are the same.

If you specified a USER in the Dockerfile for your scan image, configure the scan step to run as the user:

1. Open the scanner step and expand Additional Configuration.

2. Set the Run as User (runAsUser) setting to the user you specified in your Dockerfile.