> 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/new-to-sto/get-started.md).

# Get Started

Use the Harness Security Testing Orchestration (STO) module to scan code in a Harness pipeline. You set up a pipeline with one scanner, run scans, analyze the results, and learn about key STO features.

### Before you begin

{% hint style="info" %}
**Required accounts and access**

This tutorial requires the following accounts and access:

* A Harness account and STO module license.
* A [Security Testing Developer or AppSec role](/security-testing-orchestration/3.0/troubleshooting-and-resources/rbac.md) assigned to your profile.
* A GitHub account and a [GitHub connector](/harness-ai/use-harness-platform/connectors/code-repositories/ref-source-repo-provider/git-hub-connector-settings-reference.md) in your project. This tutorial uses an [example codebase on GitHub](https://github.com/williamwissemann/dvpwa) that contains known vulnerabilities.
  {% endhint %}

### What you will learn from this topic <a href="#objectives" id="objectives"></a>

You will learn how to:

1. Run the pipeline and analyze the security issues found by the scanner.
2. Select a baseline for your test targets and use the baseline to identify "shift-left" issues in a downstream branch only vs. "shift-right" issues also found in the baseline branch.
3. View issue details in the Harness UI and use these details to pinpoint and resolve issues in your code.
4. Set up a scan step to fail automatically if it detects an issue with the specified severity or higher.
5. Request an exemption ("ignore rule") for a specific issue.
6. Approve the exemption. Once approved, the exemption won't fail the pipeline even if it equals or exceeds the severity threshold.

<details open>

<summary>Review: what's supported in Harness STO</summary>

Go to [What's supported in Harness STO](/security-testing-orchestration/3.0/new-to-sto/sto-whats-supported/sto-deployments.md) for information about all supported STO features, infrastructures, and third-party scanners.

</details>

### Developer workflow <a href="#developer-workflow" id="developer-workflow"></a>

You're a developer, working in various development branches and merging your code updates. You want to make sure you don't introduce any new vulnerabilities when you merge your code into the upstream branch. Using STO, you can scan your repo automatically and then use the results to pinpoint and fix your vulnerabilities before you merge.

#### Set up your codebase <a href="#set-up-your-codebase" id="set-up-your-codebase"></a>

This tutorial uses [Bandit](https://bandit.readthedocs.io/en/latest/) to scan the target repository <https://github.com/williamwissemann/dvpwa> (specified in the [Codebase](/continuous-integration/use-harness-ci/use-harness-ci/codebase-configuration/create-and-configure-a-codebase.md) for this pipeline).

1. Fork the following example repository into your GitHub account. This is a Python repo with known vulnerabilities: <https://github.com/williamwissemann/dvpwa>.
2. If you don't have a Harness connector to your GitHub account, do the following:
   1. In your Harness project, select **Project Setup** > **Connectors**.
   2. Select **New Connector**, then select **Code Repositories** > **GitHub**.
   3. Set the [GitHub connector settings](/harness-ai/use-harness-platform/connectors/code-repositories/ref-source-repo-provider/git-hub-connector-settings-reference.md) as appropriate.
      * Use **Account** for the [URL type](/harness-ai/use-harness-platform/connectors/code-repositories/ref-source-repo-provider/git-hub-connector-settings-reference.md#url-type).
      * This tutorial uses Harness Cloud, so select **Connect through Harness Platform** when prompted for the connectivity mode.

#### Set up your pipeline <a href="#set-up-your-pipeline" id="set-up-your-pipeline"></a>

Do the following:

1. Select **Security Testing Orchestration** (left menu, top) > **Pipelines** > **Create a Pipeline**. Enter a name and click **Start**.
2. In the new pipeline, select **Add stage** > **Security**.
3. Set up your stage as follows:
   1. Enter a **Stage Name**.
   2. In **Select Git Provider**, select your GitHub connector.
   3. In **Repository Name**, click the value type selector (tack button) and select **Runtime Input**. You'll specify the repo to scan when you run the pipeline.
4. Go to **Infrastructure** and select **Cloud**, **Linux**, and **AMD64** for the infrastructure, OS, and architecture.

   You can also use a Kubernetes or Docker build infrastructure, but these require additional setup. For a fast start, use Harness Cloud.

#### Add a Bandit scan step <a href="#add-a-bandit-scan-step" id="add-a-bandit-scan-step"></a>

<details open>

<summary>Key concept: scan targets and variants</summary>

Every STO scan has a specific [target name and variant](/security-testing-orchestration/new-to-sto/key-concepts/targets-and-baselines.md).

* The name specifies the repository, image, or instance to scan.
* The variant specifies the codebase branch, image tag, app version, or other variant.

</details>

{% tabs %}
{% tab title="Visual" %}

1. In the Pipeline Studio, go to **Execution** and add a **Bandit** step to your pipeline.
2. Configure the step as follows:
   1. Scan Mode = **Orchestration**

      Indicates that this is an [orchestrated scan](/security-testing-orchestration/new-to-sto/key-concepts/sto-workflows-overview.md) that runs the scan and ingests the results in one step.
   2. Target name — Click the value-type selector (tack button to the right of the input field) and select **Runtime input**. You'll specify this and other values when you run the pipeline.
   3. Variant — Select **Runtime input** as the value type.

      Every STO scan has a [target variant](/security-testing-orchestration/new-to-sto/key-concepts/targets-and-baselines.md) that specifies the branch, tag, or other variant to scan.
      {% endtab %}

{% tab title="YAML" %}
Add a `Bandit` step to your `SecurityTests` stage and configure it as follows.

* `type:` [`Bandit`](/security-testing-orchestration/3.0/use-sto/sto-scanner-configuration/bandit-scanner-reference.md)
* `name:` A name for the step.
* `identifier:` A unique step ID.
* `spec :`
  * `mode :` [`orchestration`](/security-testing-orchestration/new-to-sto/key-concepts/sto-workflows-overview.md) In orchestrated mode, the step runs the scan and ingests the results in one step.
  * `config: default`
    * `target :`
      * `name : <+input>`
      * `type : repository`
      * `variant : <+input>` You will specify the [target name and variant](/security-testing-orchestration/new-to-sto/key-concepts/targets-and-baselines.md) when you run the pipeline. When scanning a repository, you will generally use the repository name and branch for these fields.
    * `advanced :`
      * `log :`
        * `level : info`

Here's a YAML example:

```yaml
steps:
  - step:
      type: Bandit
      name: bandit_scan_orchestrated
      identifier: bandit_scan_orchestrated
      spec:
        mode: orchestration
        config: default
        target:
          name: <+input>
          type: repository
          variant: <+input>
        advanced:
          log:
            level: info
```

{% endtab %}
{% endtabs %}

#### Scan the repo and analyze the results <a href="#scan-the-repo-and-analyze-the-results" id="scan-the-repo-and-analyze-the-results"></a>

Now that you've set up the pipeline, you can run a scan and view the detected issues.

1. Select **Save**, and then select **Run**.
2. In Run Pipeline, configure the run as follows:

   1. Under Codebase:
      * Repository name : **dvpwa**
      * Branch name : **master**
   2. Under Stage:
      * Target name : **dvpwa** (= the repo name)
      * Target variant : **master** (= the branch name)

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><ul><li><a href="/spaces/3F2TpHXhur2QtQnORSM9/pages/QVKYdRUmInajTuLxyGnh">Input sets</a> make it easy to re-run a pipeline with a specific set of runtime inputs. To save your runtime settings to an input set, select <strong>Save as New Input</strong> on the bottom right.</li></ul></div>
3. Run the pipeline. When the execution finishes, select **Vulnerabilities**.

This tab shows the issues that the scanner found in the test target, categorized by severity. You can filter issues using the severity buttons, expand/collapse the issue lists, and click on an issue to view details.

In this case the scanner found found two issues, one critical and one medium, in the master branch.

#### Set the baseline <a href="#set-the-baseline" id="set-the-baseline"></a>

<details open>

<summary>Key concept: baselines</summary>

A *target baseline* identifies the "prod" variant of the target, such as the `main` branch or the `latest` tag. Defining a baseline makes it easy to distinguish between “shift-right” issues in production targets and “shift-left” issues in downstream variants.

Note the following:

* Harness strongly recommends that you [specify a baseline for every target](/security-testing-orchestration/3.0/troubleshooting-and-resources/sto-use-cases/set-up-sto-pipelines/set-up-baselines.md).
* You can specify target baselines using regular expressions as well as fixed strings. Regular expressions are useful when the "prod" variant updates with each new release.

</details>

As a developer, you want to ensure that you don't introduce any new issues when you merge into your upstream branch. To do this, you create a baseline for your test target and compare your scans against the baseline.

1. Select **Security Test Orchestration** > **Test Targets**.
2. Go to the target in the table and select \*\*branch : \*\*master\*\*.

#### Compare baseline vs. downstream issues <a href="#compare-baseline-vs-downstream-issues" id="compare-baseline-vs-downstream-issues"></a>

Suppose you're developing a new feature. You're working in a `DEMO-001` branch that's downstream from the `master` branch. As a developer, you want to fix any "shift-left" issues in your downstream branch *before* you merge into the baseline.

First, you want to see if your branch has any security issues that aren't in the `master` branch.

* Run the pipeline again with **DEMO-001** as the target variant.
* When the pipeline finishes, go to the **Vulnerabilities** tab.

DEMO-001 has 5 security issues: 2 critical, 2 medium, 1 low. Note that 3 of these issues are in the DEMO-001 branch only and 2 are common to both DEMO-001 and master.

#### Fix vulnerabilities <a href="#fix-vulnerabilities" id="fix-vulnerabilities"></a>

<details open>

<summary>Key Concept: Issues and occurrences</summary>

When Harness processes the security issues identified in a scan, it deduplicates the results. *Deduplication* is the aggregation of multiple occurrences with the same root cause into one issue.

Note the following as you troubleshoot and fix your security issues:

* Each security issue you see in the **Vulnerabilities** page is unique and requires its own resolution.
* A single issue might have multiple occurrences throughout the target. To remediate an issue, you must fix all occurrences of that issue.

</details>

The Issue Details pane has useful information for troubleshooting your security vulnerabilities.

1. Expand one of the issue lists (for the baseline or the downstream branch) and select an issue. The Issue Details pane opens.

* The severity score **9.5** is based on the [NIST Common Vulnerability Scoring System](https://nvd.nist.gov/vuln-metrics/cvss) (CVSS) version 3.0:
  * None 0.0
  * Low 0.1 - 3.9
  * Medium 4.0 - 6.9
  * High 7.0 - 8.9
  * Critical 9.0 - 10.0
* The **Occurrences List** shows all occurrences of this specific issue in the test target.

2\. Select the Reference Identifier link (for example, [CWE-78](https://cwe.mitre.org/data/definitions/78.html)).

**Issue Details** includes specific information about each vulnerability. In this case, you can view detailed information about the issue in the Common Weakness Enumeration database, a community-developed list of software and hardware weakness types.

3. Examine the **Occurrences** list for this issue. (You might need to scroll down in the pane.) Here you can find additional details about each individual occurrence of the issue. Note that, to eliminate this vulnerability from the repo, you need to fix multiple occurrences:

<details open>

<summary>Key Concept: Issue details are derived from the external scanner</summary>

Many of the details you see for each issue are derived from the external scanner. These details can differ, depending on the scan tool you're using. In this tutorial we're using Bandit, which is a free, open-source scan tool. In general, paid scanners provide more extensive details (such as remediation steps) than free ones.

Here's an example of a container image vulnerability detected by a paid version of Snyk:

</details>

#### AI-enhanced remediation <a href="#new-feature-ai-enhanced-remediation" id="new-feature-ai-enhanced-remediation"></a>

Harness AI uses state-of-the-art AI technology to streamline the process of triaging and fixing security vulnerabilities. Harness AI is based on large, well-trained language models. It learns continuously based on feedback and the latest public knowledge. Optionally, you can regenerate advice with additional context and thereby optimize your results.

For more information, go to [Fix issues using AI-enhanced remediation steps](/security-testing-orchestration/3.0/use-sto/sto-remediate-issues/ai-based-remediations.md).

#### Fail pipelines on severity <a href="#fail-pipelines-on-severity" id="fail-pipelines-on-severity"></a>

<details open>

<summary>Key concept: fail_on_severity</summary>

Every STO scan step has a `fail_on_severity` setting. If any vulnerability with the specified severity or higher is found, the pipeline fails.

It is good practice to set `fail_on_severity` in every scan step in an integrated pipeline.

</details>

1. In the Pipeline Studio, open the **Bandit** step.
2. Set **Fail on Severity** to **Critical**.
3. Select **Apply Changes**, save the updated pipeline, and run the pipeline again with the **DEMO-001** branch.

The pipeline now fails because the Bandit step is now configured to fail on any critical vulnerability. The last log message in the Bandit step log is:

```
Exited with message: fail_on_severity is set to critical and that threshold was reached.
```

### Developer/AppSec workflow: exemptions for specific issues <a href="#developerappsec-workflow-exemptions-for-specific-issues" id="developerappsec-workflow-exemptions-for-specific-issues"></a>

<details open>

<summary>Key concept: Exemptions, requests, and approvals</summary>

You can exempt known issues from `fail_on_severity` so they do not stop the pipeline when a scan detects them. The following steps outline the workflow:

1. A developer requests an exemption for a specific issue and forwards the request to a AppSec user.
2. The AppSec user approves the request or rejects it. Developer users can request exemptions, but only AppSec users can approve them.
3. If the exemption is approved, and a future scan detects the exempted issue, the pipeline execution will not fail even if the issue meets the `fail_on_severity` threshold.

</details>

In this section, you'll create an exemption as a developer and then approve it as a AppSec user. (In many real-world scenarios, two separate people will be performing the workflow.)

1. Make sure that you have the AppSec role assigned to yourself:
   1. Select the account link (left-most breadcrumb at the top). Then go to **Account Settings** (left menu) and select **Access Control**.
   2. In the **Users** table, select your user profile.
   3. Under Role Bindings, select **+Manage Role**.
   4. Make sure that you have the **Security Testing AppSec** role assigned to yourself.
2. Go back to your project: Select your STO account in the left menu, then select **Project**, and then select the project with your STO pipeline.
3. In the left navigation, select **Executions** and then select the last successful build you ran *before* the failed build.

In the following step, you'll create an exemption for each of the two critical issues found: `subprocess_popen_with_shell_equals_true` (only in the current scan) and `hashlib` (common to the baseline scan).

3. In the **Vulnerabilities** tab, do the following steps for each critical issue:
   1. Select the critical issue in the issues table (bottom left) to open **Issue Details**.
   2. Select **Request Exemption**.
   3. In **Request Exemption for Issue**, configure the exemption request as follows:
   4. Where do you want this issue to be exempted? **This pipeline**
   5. For how long? **7 Days**
   6. Reason this issue should be exempted: **Other**
   7. Further describe the reason this issue should be exempted: **Tutorial example pipeline, not for use in QA or Prod environments**
   8. Select **Create Request**.
4. Select **Exemptions** in the left menu.
5. In the Security Review page, select the "thumbs-up" buttons to approve both exemptions. These exemptions now move from **Pending** to **Approved**.
6. Go back to your pipeline and run another build with the **DEMO-001** branch. When the build finishes, go to the **Vulnerabilities** page.
7. Select **Exempted** (far right, under **Security Executions**). Note that this button, like the Critical, High, and other buttons, acts as a toggle to show and hide specific issues in the issues table. If you select and unselect **Exempted**, the exempted issues switch between visible and hidden.
8. Select **Exemptions** in the left menu. Then select **Approved** to show the exemptions you created and approved.
9. Select the Delete (**X**) buttons on the right to delete both exemptions.

### What you learned <a href="#congratulations" id="congratulations"></a>

This tutorial covers the following tasks:

1. Set up a scanner
2. Create a baseline
3. Analyze scan results
4. Use the data collected by STO to pinpoint and fix vulnerabilities *before* you merge your code updates.
5. Configure `fail_on_severity` to fail a pipeline execution if a scan detects a vulnerability with the specified severity or higher.
6. Request an exemption for a specific vulnerability and approve an exemption as an AppSec user.

### Next steps <a href="#next-steps" id="next-steps"></a>

You've now learned the core STO features and workflows. Here are the next steps you can take.

#### Add steps or stages for CI/CD workflows <a href="#add-steps-or-stages-for-cicd-workflows" id="add-steps-or-stages-for-cicd-workflows"></a>

You know how to implement pipelines when scanners detect security issues, and how to create Ignore Rules for specific issues. Once you set up your Security Test steps, baselines, and exemptions, you can add more stages and steps to implement your CI/CD workflows.

For some examples of integrated workflows, go to:

* [(STO license) Create a build-scan-push pipeline](/security-testing-orchestration/3.0/troubleshooting-and-resources/sto-use-cases/set-up-sto-pipelines/build-scan-push-workflows/build-scan-push-sto-only.md)
* [(STO/CI licenses) Create a build-scan-push pipeline](/security-testing-orchestration/3.0/troubleshooting-and-resources/sto-use-cases/set-up-sto-pipelines/build-scan-push-workflows/build-scan-push-sto-ci.md)

#### Add more scanner steps <a href="#add-more-scanner-steps" id="add-more-scanner-steps"></a>

STO supports an extensive set of external scanners for repos, images, and artifacts. Go to [What's supported](/security-testing-orchestration/3.0/new-to-sto/sto-whats-supported/sto-deployments.md).

#### Add governance policies <a href="#add-governance-policies" id="add-governance-policies"></a>

You can use the [Harness Policy Engine](/harness-ai/use-harness-platform/governance/policy-as-code/harness-governance-overview.md) to create policies based on the [Open Policy Agent (OPA)](https://www.openpolicyagent.org/) standard. For example, you can create a rule like the following to ensure that all pipelines include a Security stage.

```rego
package pipeline_required

# Deny pipelines that are missing required steps <a href="#deny-pipelines-that-are-missing-required-steps" id="deny-pipelines-that-are-missing-required-steps"></a>
deny[sprintf("CI stage '%s' is missing required step '%s'", [stage.name, existing_steps])] {
     stage = input.pipeline.stages[i].stage                                # Find all stages ...
     stage.type == "CI"                                                    # ... that are CI stages
     existing_steps := [ s | s = stage.spec.execution.steps[_].step.type ] # ... and create a list of all step types in use
     required_step := required_steps[_]                                    # For each required step ...
     not contains(existing_steps, required_step)                           # ... check if it's present in the existing steps
}

# steps that must be present in every CI stage - try to create a CI stage without a Security Test step to see the policy fail <a href="#steps-that-must-be-present-in-every-ci-stage-try-to-create-a-ci-stage-without-a-security-test-step-to-see-the-policy-fail" id="steps-that-must-be-present-in-every-ci-stage-try-to-create-a-ci-stage-without-a-security-test-step-to-see-the-policy-fail"></a>
required_steps = ["Security"]

contains(arr, elem) {
    arr[_] = elem
}
```

#### Add failure strategies to a CI/CD stage <a href="#add-failure-strategies-to-a-cicd-stage" id="add-failure-strategies-to-a-cicd-stage"></a>

You can implement [Failure Strategies](/harness-ai/use-harness-platform/pipelines/failure-handling/define-a-failure-strategy-on-stages-and-steps.md) to bypass the failure policies in previous security steps. One use case for this would be to enable manual interventions when a Security Test step generates a failure. You can set up a workflow like this:

1. A Build step is downstream from the Security Test step. It has a failure strategy that's set to run on [All Errors](/harness-ai/use-harness-platform/pipelines/failure-handling/define-a-failure-strategy-on-stages-and-steps.md#error-types).
2. The scanner detects issues and the Security Test step generates an error.
3. The Failure Strategy in the Build step initiates a 30-minute pause before proceeding.
4. The developer and security team evaluate the issues and then abort the pipeline execution or allow it to proceed.