Onboarding guide

This topic describes the steps you need to do to set up STO in your pipeline.

The entire setup workflow should take about 30 minutes.

STO Requirements

Make sure you meet the following requirements before you do the STO Setup Procedures steps described below.

External Requirements

Before you create your first Harness pipeline, you must have the following:

• Git account and Personal Access Token — If you are scanning a repo, you need an account and access token with the Git provider.
• Docker Hub account — STO uses Docker-in-Docker to run scans. The Pipeline needs to pull the docker:dind image from Docker Hub.
• A build infrastructure for executing pipelines and scanning targets.

Harness user permissions

• Developers need a Security Testing Developer role to run tests and view results.
• Security Operations staff need a Security Testing SecOps role to run tests, view results, and approve security exemptions.
• To assign these roles, you need an Account Admin role. Project Admin permissions aren't enough.

Harness account requirements

Harness recommends you create the following resources at the Account level. This enables you to use them across all projects and pipelines in the account.

• Harness delegate — Required to run builds in your Kubernetes infrastructure.
• Secret for Git access credentials — Required to set up a codebase connector.
• Git codebase connector — Required if you want to scan a codebase in your pipeline.
• Docker Hub connector — Required to download images needed to run the pipeline.

STO setup procedures

The following sections describe the workflow for setting up STO. Once you complete this workflow, you'll have the build infrastructure and connectors required to build a pipeline and run security scans. You'll also have an STO-enabled pipeline that you can clone and configure based on your security requirements.

Add Security Testing roles

Harness includes two RBAC roles specifically for STO users:

• Developer role — Permissions needed for developer workflows. These workflows are described in the first tutorial, Create a standalone STO pipeline.
• SecOps role — Permissions needed for Security Operations staff. This role includes all Developer permissions and also allows users to approve security exemptions ("ignore rules") for specific issues. These workflows are covered in the second tutorial, Create an integrated STO/CI pipeline.

note

You need Administrative privileges at the Account level (Account Admin role) to assign these roles.

Assign Security Testing Roles: Default Workflow

1. Select Account Settings (left menu) > Access Control.
2. In the Users table, select the user profile.
3. Under Role Bindings, select +Role.
4. Assign the Security Testing Developer role or the Security Testing SecOps role to the user profile.

Set up a build infrastructure for STO

You need a Harness build infrastructure to run scans in STO. First, review the supported build infrastructures in What's supported in Harness STO. Then select the infrastructure you want to use:

• Harness Cloud build infrastructure This is the simplest option. No initial setup is required.
• Local Kubernetes build infrastructure Recommended when you want to run ephemeral builds-at-scale in your own infrastructure.
• Local Docker build infrastructure Recommended for small, limited builds, such as a one-off build on your local machine.

Use Harness Cloud build infrastructure for STO

With Harness Cloud, you can run builds in isolation on Harness-hosted VMs that are preconfigured with tools, packages, and settings commonly used in CI pipelines. Harness hosts, maintains, and upgrades these machines so that you can focus on building software instead of maintaining build infrastructure. No initial setup is required.

For more information, go to Use Harness Cloud build infrastructure.

Install a Kubernetes delegate for STO

Executing builds in a Kubernetes cluster is useful when you want to run ephemeral builds-at-scale in your own infrastructure. When running builds in a Kubernetes cluster, each stage executes in a pod, and the stage's steps share the pod's resources.

Kubernetes Delegate Requirements

• Number of pods: 3 (two pods for the Harness Delegate, the remaining pod for scanning infrastructure).
• Machine type: 4vCPU.
• Memory: 16GB RAM. The scanning infrastructure and Delegate requirements are low but the remaining memory is for Kubernetes, the Docker container, and other default services.
• Networking: outbound HTTPS for the Harness connection, and to connect to Docker Hub. Allow TCP port 22 for SSH.
• Namespace: when you install the Harness Delegate, it will create the harness-delegate-ng namespace. You'll use the same namespace for the scanning infrastructure.
• A Kubernetes service account with permission to create entities in the target namespace is required. The set of permissions should include list, get, create, and delete permissions. In general, the cluster-admin role or a namespace admin permission is enough. For more information, go to User-Facing Roles from Kubernetes.

note

Google Kubernetes Engine (GKE) Autopilot is not supported at this time.

To set up the build infrastructure, you add a connector to your Kubernetes cluster and then install a Harness delegate.

Install a Kubernetes Delegate: Default Workflow

1. Select Account Settings > Account Resources > Connector, then New Connector.
2. Under Cloud Providers, choose Kubernetes cluster.
3. Enter the following settings in the wizard.
   1. In Overview, Name = STO delegate
   2. In Details, select Use the credentials of a specific Harness Delegate.
      If you already have a Delegate set up in your Harness account, you can use the Specify master URL and credentials option.
      This workflow assumes you are new to Harness.
   3. Delegate setup: Select Install new Delegate.
   4. Delegate type: select Kubernetes.
   5. Kubernetes setup:
      You might need to scroll up/down to set all options.
      • Delegate Name: sto.
      • Delegate Size: Small.
      • What installer do you want to use? Kubernetes
      • Delegate permissions: Install Delegate with cluster-wide read/write access
      • Delegate Configurations: Primary Configuration
      • Delegate Tokens: default_token
   6. Download the YAML file.
   7. In a terminal, navigate to the location of the file.
   8. In the same Terminal, log into your cluster and run the following:
      kubectl apply -f harness-delegate.yml
      Once you apply the YAML file, you'll see an output like this:

      % kubectl apply -f harness-delegate.yml
      namespace/harness-delegate-ng created
      clusterrolebinding.rbac.authorization.k8s.io/harness-delegate-ng-cluster-admin created
      secret/sto-proxy created
      statefulset.apps/sto created
      service/delegate-service created

      In the Harness Delegate setup, you'll see the Delegate register with Harness. This might take a few minutes.
      If you encounter errors, ensure your cluster can connect outbound to app.harness.io. See Allowlist Harness Domains and IPs.
4. Select Done to close the delegate wizard and return to the connector setup.
5. In Delegates Setup, select Only use Delegates with all of the following tags, select the new delegate, and then select Save and Continue.
6. In Connection Test, wait for "Verification successful" and then select Finish.

Install a local Docker delegate for STO

A local runner build infrastructure is recommended for small, limited builds, such as a one-off build on your local machine.

For more information, go to Set up a local runner build infrastructure in the CI documentation.

Create secrets for your Git and DockerHub access credentials

Harness includes a built-in Secrets Manager that enables you to store encrypted secrets, such as access keys, and use them in your Harness account. Secrets are always stored in encrypted form and are not accessible by Harness. Only the delegate, which runs in your infrastructure, can access them.

In this step, you'll create a secret for your GitHub and DockerHub access tokens. Then you'll use the secret when you set up the connector to your GitHub repo.

Create a Secret for your GitHub access token: Default Workflow

1. In your Github account, a GitHub Personal Access Token that has the following scopes:

   • repo
   • admin:repo_hook
   • user

2. Go to Account Settings > Account Resources and select Secrets.

3. Select New Secret > Text.

   

4. Specify the Secret Name and Secret Value (your GitHub access token). It's good practice to indicate the scope of the secret in the name, as shown in this example.

   

5. Repeat this procedure to create a secret for your DockerHub access token.

Create a Docker Hub connector

A Docker Hub connector is required to run a Docker-in-Docker service as described in Set up the Security Tests stage below. It is also required for any pipeline that scans or uploads a built image.

Create a Docker Hub Connector: Default Workflow

1. If you want to upload images to your Docker Hub repo, you'll need an access token. To do this:
   1. Create a token: log in to your Docker Hub account and go to https://hub.docker.com/settings/security.
   2. Create a secret for your token.
2. Go to the Account Settings > Account Resources page and select Connectors.
3. Select New Connector. Under Artifact Repositories, select Docker Registry.
4. In the connector setup wizard, specify the following:
   1. Docker Registry URL = https://index.docker.io/v2/
   2. Provider Type = DockerHub
   3. Username = Your Docker Hub username
   4. Password = The secret you created for your Docker Hub access token.
5. In Delegates Setup, select Use any available Delegate and then select Save and Continue.
6. Wait for "Verification successful" and then select Finish.

Create a Codebase Connector

You'll need a GitHub account to do the STO Tutorials.

You also need a Git repo connector for any STO pipeline that scans a codebase. You can create codebase connectors for the following SCMs:

• Azure
• Bitbucket
• Git (platform-agnostic)
• GitHub
• GitLab

To do the STO tutorials, point the connector at the following repo: https://github.com/williamwissemann/dvpwa

Create a Codebase Connector: Default Workflow

1. Go to the Account Settings > Account Resources page and select Connectors.
2. Under Code Repositories, choose GitHub.
3. Specify the following in the setup wizard:
   1. Overview:
      Name = GitHub STO tutorial.
   2. Details:
      URL Type: Repository
      Connection Type: HTTP
      GitHub Repository URL: https://github.com/williamwissemann/dvpwa
   3. Credentials:
      Username: Your GitHub username.
      Personal Access Token: Your GitHub Personal Access Token secret.
      Enable API Access: Select this checkbox and select the same secret.
   4. Connect to the provider:
      Select Connect through Harness Platform.
4. When you're done, select Save and Continue. Harness will test the connection and credentials. Select Finish.

Create a base pipeline for STO

The following procedure creates a pipeline with the STO functionality required to run scans on your repos, images, and instances. Once you set up this pipeline, you can clone it to a new pipeline and update the pipeline to set up your scans. This workflow is described in the Create a standalone STO pipeline tutorial.

Add a Security Test stage

1. In the Pipeline Studio, select Home > Projects and choose the project where you want to create the pipeline.

   

2. Select Select Modules (left menu) and then select Security Tests.

3. In Create New Pipeline:

   1. Select Pipelines > Create a Pipeline.
   2. In Create new Pipeline > Name, enter sto-pipeline-base.
   3. Select Start.
   

4. In About your Stage:

   1. Select Add Stage and then Security Tests.
   2. Stage Name = securityTestStage
   3. Connector = The connector you created in Create a Codebase Connector.
   4. Select Set Up Stage.
   

Set up the Security Tests stage

1. In the Overview tab, under Shared Paths, select Add and enter the path /var/run.

   

2. In the Infrastructure tab, select the infrastructure and specify the options based on the infrastructure type.

   

Add a Bandit scanner step

1. In the Execution tab, select Add Step and then Bandit.

2. Configure the step as follows:

   1. Scan Mode = Orchestration

   2. Target Name = **dvpwa**

   3. Target Variant — Select the tack button on the right, select Expression as the value type, and enter the expression <+codebase.branch>.

      With this setting, you will specify the variant — in this case, the branch name — when you execute the pipeline.

      

3. Apply your changes, return to the Stage, and Save the pipeline.

   

Run the pipeline (optional)

1. Select Run.
2. Select Git Branch, enter master for the branch name, and then select Run Pipeline.
3. When the pipeline finishes, select the Security Tests tab to see the dashboard.

Congratulations!

You now have the build infrastructure, connectors, and pipeline required to build a pipeline and run security scans. You can simply clone the pipeline you just created and configure new pipelines based on your security requirements.