> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/security-testing-orchestration/3.0/troubleshooting-and-resources/sto-use-cases/set-up-sto-pipelines/configure-pipeline-to-use-sto-images-from-private-registry.md).

# Configure pipeline to use STO images from private registry

Harness maintains its own set of scan images for [STO-supported scanners](/security-testing-orchestration/3.0/new-to-sto/sto-whats-supported/scanners.md). By default, a Harness pipeline pulls scan images from the [Harness DockerHub](https://hub.docker.com/u/harness).

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.](#create-sto-scanner-images-with-your-own-ssl-certificates-optional)
2. [Create a connector for your private registry.](#create-a-connector-to-your-private-registry)
3. [Configure the pipeline to download images from your registry.](#configure-the-pipeline-to-download-images-from-your-registry)

### Create STO scanner images with your own SSL certificates (optional) <a href="#create-sto-scanner-images-with-your-own-ssl-certificates-optional" id="create-sto-scanner-images-with-your-own-ssl-certificates-optional"></a>

Harness STO supports [three workflows](/security-testing-orchestration/troubleshooting-and-resources/sto-use-cases/secure-sto-pipelines/ssl-setup-in-sto.md#supported-workflows-for-adding-custom-ssl-certificates) 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.

{% hint style="info" %}
Running container image scans as a non-root user is not currently supported.
{% endhint %}

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.

<details>

<summary>Dockerfile template for adding certificates to an STO scanner image</summary>

```bash
# 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

```

</details>

### Create a connector to your private registry <a href="#create-a-connector-to-your-private-registry" id="create-a-connector-to-your-private-registry"></a>

You need a Docker connector that points to your private container registry. For more information, go to [Docker Connector Settings Reference](/harness-ai/use-harness-platform/connectors/cloud-providers/ref-cloud-providers/docker-registry-connector-settings-reference.md).

### Configure your pipeline to use images from your registry <a href="#configure-your-pipeline-to-use-images-from-your-registry" id="configure-your-pipeline-to-use-images-from-your-registry"></a>

1. Download the scan images you need from the [Harness DockerHub](https://hub.docker.com/u/harness), test and validate the images, and store them in your private registry.

   <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>Do not change the image names in your private registry. The image names must match the names specified by Harness; this includes the <code>harness/</code> prefix.</p></div>
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](/continuous-integration/use-harness-ci/use-harness-ci/set-up-build-infrastructure/harness-ci.md#specify-the-harness-ci-images-used-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](#stage-level-override)
     * [Step level override](#step-level-override)
   * [Override security test images for Custom Scan steps](#override-security-test-images-for-custom-scan-steps)

#### **Override security test images for scanner steps** <a href="#override-security-test-images-for-scanner-steps" id="override-security-test-images-for-scanner-steps"></a>

**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.

{% hint style="info" %}
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.
{% endhint %}

**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.

{% hint style="info" %}
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.
{% endhint %}

#### **Override security test images for Custom Scan steps** <a href="#override-security-test-images-for-custom-scan-steps" id="override-security-test-images-for-custom-scan-steps"></a>

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](#stage-level-override) or [step level](#step-level-override) sections above for instructions, as they are the same.

{% hint style="info" %}
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.
   {% endhint %}