> 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/use-sto/sto-scanner-configuration/traceable-step-configuration.md).

# Harness API DAST step configuration (previously Traceable)

The **API DAST** step previously called as **Traceable** enables API testing by connecting with your [**Traceable**](https://docs.traceable.ai/docs/ast-scans) account. Depending on your requirements, you can choose from the following three STO scan modes for API DAST step, follow the appropriate documentation for each mode.

{% hint style="info" %}
This step previously referred to as **Traceable** has been renamed to **API DAST** under [Harness Security Scanners](/security-testing-orchestration/new-to-sto/sto-whats-supported/scanners.md#harness-security-scanners). You may still encounter the term **Traceable** in certain references or interfaces; both refer to the same scanner.
{% endhint %}

* [**Orchestration Mode**](#orchestration-mode-configuration): This mode allows you to initiate a Scan Run within an existing [Traceable Scan](https://docs.traceable.ai/docs/ast-scans). The scan results are then automatically saved in STO.
* [**Ingestion Mode**](#ingestion-mode-configuration): You can use Ingestion mode to read the scan results from a data file and feed them into STO. This also covers how to fetch the results from Traceable for Ingestion.
* [**Extraction Mode**](#extraction-mode-configuration): Use Extraction mode to retrieve the latest scan data of a specific [Traceable Scan](https://docs.traceable.ai/docs/ast-scans) and feed the results into STO.

{% hint style="info" %}

* 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-testing-orchestration/troubleshooting-and-resources/sto-use-cases/set-up-sto-pipelines/configure-pipeline-to-use-sto-images-from-private-registry.md).
* STO supports three different approaches for loading self-signed certificates. For more information, refer [Run STO scans with custom SSL certificates](/security-testing-orchestration/troubleshooting-and-resources/sto-use-cases/secure-sto-pipelines/ssl-setup-in-sto.md#supported-workflows-for-adding-custom-ssl-certificates).
  {% endhint %}

### Orchestration mode configuration <a href="#orchestration-mode-configuration" id="orchestration-mode-configuration"></a>

The Orchestration mode in the API DAST step allows you to initiate a scan(Scan Run in Traceable) within an existing [Traceable Scan](https://docs.traceable.ai/docs/ast-scans). In this mode, you cannot create a new Scan or define the API endpoints; it is currently limited to initiating an existing scan and having the scan results in STO. Here's how you can do it.

Search for and add the **Traceable** step to your pipeline. This step can be used in either the **Build** stage or the **Security** stage. In the step configuration, set the following fields:

1. **Scan Mode**: Set the **Scan Mode** to **Orchestration**.
2. **Target**: Under [**Target**](#target), for [**Target and Variant Detection**](#target-and-variant-detection), it's recommended to use the [**Auto**](#auto) option. Alternatively, you can manually define **Name** and **Variant** using the **Manual** option.
3. **Authentication**: Provide your Traceable [**Domain**](#domain) and pass your Traceable [**Access Token**](#access-token) as a Harness secret, for example: `<+secrets.getValue("traceable_api_token")>`.
4. **Scan Tool**: Enter your [**Scan Name**](#scan-name) and configure the [**Runner Selection**](#runner-selection) field.

These are the essential settings for performing an Orchestration scan using the API DAST step. For more features and configuration options, see the [API DAST step Settings](#api-dast-step-settings) section.

### Ingestion mode configuration <a href="#ingestion-mode-configuration" id="ingestion-mode-configuration"></a>

With the Ingestion mode in the API DAST step, you can read scan results from a data file and import them into STO. To do this, you need the scan results saved in a supported format. This section explains how to fetch and save the scan results in `JSON` format, then use Ingestion mode in the API DAST step to feed the data into STO.

If you already have the scan results in the supported format and just need to configure Ingestion mode, skip ahead to [Configure the API DAST step for Ingestion](#configure-the-api-dast-step-for-ingestion).

#### Fetch and save scan results in JSON format <a href="#fetch-and-save-scan-results-in-json-format" id="fetch-and-save-scan-results-in-json-format"></a>

Search and add a **Run** step in your pipeline and add the following command in the step.

<details>

<summary>Command to fetch scan results and save in JSON format</summary>

```
#!/bin/sh

# Variables <a href="#variables" id="variables"></a>
API_URL="https://api.traceable.ai/graphql"  
API_TOKEN="YOUR_API_TOKEN" 
SCAN_ID="scan_id_test"  
OUTPUT_FILE="/harness/vulnerabilities.json"  # File to store the result

# GraphQL Query - Using HEREDOC for better readability <a href="#graphql-query-using-heredoc-for-better-readability" id="graphql-query-using-heredoc-for-better-readability"></a>
get_vulnerabilities_query=$(cat <<EOF
{
  "query": "query GetVulnerabilities {
    vulnerabilitiesV3(
      filter: {
        logicalFilter: {
          operator: AND,
          filters: [
            {
              relationalFilter: {
                key: SCAN_ID,
                operator: EQUALS,
                value:  \"${SCAN_ID}\"
              }
            }
          ]
        }
      }
    ) {
      results {
        name: selection(key: DISPLAY_NAME) {
          value
          type
        }
        description: selection(key: DESCRIPTION) {
          value
          type
        }
        category: selection(key: VULNERABILITY_SUB_CATEGORY) {
          value
          type
        }
        cvss_score: selection(key: CVSS_SCORE) {
          value
          type
        }
        severity: selection(key: SEVERITY) {
          value
          type
        }
        mitigation: selection(key: MITIGATION) {
          value
          type
        }
        impact: selection(key: IMPACT) {
          value
          type
        }
        references: selection(key: REFERENCES) {
          value
          type
        }
        cve: selection(key: CVE) {
          value
          type
        }
        cwe: selection(key: CWE) {
          value
          type
        }
        path: selection(key: ENTITY_NAME) {
          value
          type
        }
      }
      count
      total
    }
  }"
}
EOF
)

# Execute GraphQL query and save the response <a href="#execute-graphql-query-and-save-the-response" id="execute-graphql-query-and-save-the-response"></a>
response=$(curl -s -X POST "$API_URL" \
  -H "Authorization: $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$get_vulnerabilities_query")

# Check for valid response <a href="#check-for-valid-response" id="check-for-valid-response"></a>
if [ -z "$response" ]; then
  echo "No response from API"
  exit 1
fi

# Print the raw response for debugging <a href="#print-the-raw-response-for-debugging" id="print-the-raw-response-for-debugging"></a>
echo "Raw API response:"
echo "$response"



# Sanitize the response to escape control characters (if necessary) <a href="#sanitize-the-response-to-escape-control-characters-if-necessary" id="sanitize-the-response-to-escape-control-characters-if-necessary"></a>
sanitized_response=$(echo "$response" | tr -d '\r' | tr -d '\n' | tr -d '\t')

# Format the response <a href="#format-the-response" id="format-the-response"></a>
formatted_response=$(echo "$sanitized_response" | jq '.data.vulnerabilitiesV3.results | { issues: . }')

# Check if jq executed successfully <a href="#check-if-jq-executed-successfully" id="check-if-jq-executed-successfully"></a>
if [ $? -ne 0 ]; then
  echo "Error formatting the response with jq."
  exit 1
fi

# Check if issues are empty <a href="#check-if-issues-are-empty" id="check-if-issues-are-empty"></a>
if [ "$(echo "$formatted_response" | jq '.issues | length')" -eq 0 ]; then
  echo "No vulnerabilities found for SCAN_ID: $SCAN_ID"
else
  # Save to the output file
  echo "$formatted_response" > "$OUTPUT_FILE"
  echo "Vulnerabilities stored in $OUTPUT_FILE"
  
  # Print the content of the output file
  echo "Content of $OUTPUT_FILE:"
  cat "$OUTPUT_FILE"
fi

```

</details>

* In the above command, make sure to replace the variables **API\_TOKEN** and **SCAN\_ID** with your own values. You may also use Harness Secrets for enhanced security.
* If you want to save the output file to a different path than `/harness` (used in the example command), you need to configure the shared path. Go to the **Overview** tab of the stage and, under **Shared Paths**, enter the desired path, such as `/shared/scan_results`. This will be the location where the Run step saves the scan results.

#### Configure the API DAST step for Ingestion <a href="#configure-the-api-dast-step-for-ingestion" id="configure-the-api-dast-step-for-ingestion"></a>

Search for and add the **Traceable** step to your pipeline.

1. **Scan Mode**: Set the **Scan Mode** to **Ingestion**.
2. **Target**: Under [**Target**](#target), for [**Target and Variant Detection**](#target-and-variant-detection), define the **Name** and **Variant** manually.
3. **Ingestion File**: For the field [**Ingestion File**](#ingestion-file), enter the path where the JSON scan results file is saved. In our example, if you haven’t changed the **OUTPUT\_FILE** variable in the shared command, you can use `/harness/vulnerabilities.json` or specify the path you updated it to.

These are the essential settings for performing an Ingestion scan using the API DAST step. For more features and configuration options, see the [API DAST step Settings](#api-dast-step-settings) section.

### Extraction mode configuration <a href="#extraction-mode-configuration" id="extraction-mode-configuration"></a>

The Extraction mode in API DAST step allows you to retrieve the latest scan data of a specific [Traceable Scan](https://docs.traceable.ai/docs/ast-scans) and feed the results into STO. Here's how you can do it.

Search for and add the **Traceable** step to your pipeline. This step can be used in either the **Build** stage or the **Security** stage. In the step configuration, set the following fields:

1. **Scan Mode**: Set the **Scan Mode** to **Extraction**.
2. **Target**: Under [**Target**](#target), for [**Target and Variant Detection**](#target-and-variant-detection), it's recommended to use the [**Auto**](#auto) option. Alternatively, you can manually define **Name** and **Variant** using the **Manual** option.
3. **Authentication**: Provide your Traceable [**Domain**](#domain) and pass your Traceable [**Access Token**](#access-token) as a Harness secret, for example: `<+secrets.getValue("traceable_api_token")>`.
4. **Scan Tool**: Enter your [**Scan Name**](#scan-name).

These are the essential settings for performing an Extraction scan using the API DAST step. For more features and configuration options, see the [API DAST step Settings](#api-dast-step-settings) section.

### API DAST step settings <a href="#api-dast-step-settings" id="api-dast-step-settings"></a>

The following are the details of each field in the API DAST step.

#### Scan Mode <a href="#scan-mode" id="scan-mode"></a>

The API DAST step in STO supports three scan modes: [Orchestration](#orchestration-mode-configuration), [Ingestion](#ingestion-mode-configuration), and [Extraction](#extraction-mode-configuration). Refer to the documentation specific to each mode for details and configuration instructions.

#### Scan Configuration <a href="#scan-configuration" id="scan-configuration"></a>

The predefined configuration used for the scan. The API DAST step currently supports only the default scan configuration.

#### Target <a href="#target" id="target"></a>

**Type**

The type is set to **Instance** by default, which is used to scan a running application

**Target and Variant Detection**

You can configure the details of your scan instance by setting its name and variant. These are the labels assigned to the target you’re scanning. You can choose to set them manually by selecting the **Manual** option or have them configured automatically by selecting **Auto**. When Auto is chosen, the values are set as follows:

**Auto**

When selected **Auto**, the step sets these values as:

* **Name**: Uses the value specified in the [Scan Name](#scan-name) field as the target name.
* **Variant**: Automatically sets the scan execution timestamp as the variant.

Note the following:

* **Auto** is not available when the **Scan Mode** is Ingestion.
* **Auto** is the default selection for new pipelines. **Manual** is the default for old pipelines, but you might find that neither radio button is selected in the UI.
* You should carefully consider the [baseline you want to specify](/security-testing-orchestration/troubleshooting-and-resources/sto-use-cases/set-up-sto-pipelines/set-up-baselines.md) for your instance target. Every target needs a baseline to enable the full suite of STO features. Here are a few options:
  * Specify a RegEx baseline that captures timestamps. This ensures that every new scan compares issues in the new scan vs. the previous scan. Then it updates the baseline to the current scan.

    You can use this RegEx to capture timestamps: `\d{2}/\d{2}/\d{4}\,\s\d{2}\:\d{2}\:\d{2}`
  * Specify a fixed baseline.

    1. Scan the instance using a manual variant name.
    2. Select the baseline as a fixed value.
    3. Update the step to use auto-detect for future scans.

    This ensures that future scans get compared with one fixed baseline.

#### Authentication <a href="#authentication" id="authentication"></a>

**Domain**

The fully-qualified URL to the scanner.

**Access Token**

The access token used to log in to a specific product in the scanner. This is required for some scans. In most cases, this is a password or an API key.

You should create a Harness text secret with your encrypted token and reference the secret using the format `<+secrets.getValue("container-access-id")>`. For more information, go to [Add and Reference Text Secrets](/harness-ai/use-harness-platform/secrets/add-use-text-secrets.md).

#### Scan Tool <a href="#scan-tool" id="scan-tool"></a>

**Scan Name**

Enter the Traceable Scan ID, which you can find in the URL when you open your Scan in Traceable. For example, in the URL `https://app.traceable.ai/my-scan/44aadeB-782b-8d52-8q12-43kdf33/vulnerabilities?time=1d&env=env`, the Scan ID is `44aadeB-782b-8d52-8q12-43kdf33`. You can learn more about Scans in the [Traceable documentation](https://docs.traceable.ai/docs/ast-scans).

**Runner Selection**

This field appears when the scan mode is set to **Orchestration**. You can allow Traceable to set it automatically by selecting **Auto**, or configure it manually by choosing **Manual**. If you select **Manual**, enter the Traceable [Runner ID](https://docs.traceable.ai/docs/runners#runner-view) in the **Runner ID** field. Also, make sure you have runners created and active in Traceable, as the step cannot create runners.

#### Ingestion File <a href="#ingestion-file" id="ingestion-file"></a>

The path to your scan results when running an [Ingestion scan](/security-testing-orchestration/new-to-sto/key-concepts/ingest-scan-results-into-an-sto-pipeline.md), for example `/shared/scan_results/myscan.latest.sarif`.

* The data file must be in a [supported format](/security-testing-orchestration/new-to-sto/sto-whats-supported/scanners.md#supported-ingestion-formats) for the scanner.
* The data file must be accessible to the scan step. It's good practice to save your results files to a [shared path](/continuous-integration/new-to-harness-ci/key-concepts.md#stages) in your stage. In the visual editor, go to the stage where you're running the scan. Then go to **Overview** > **Shared Paths**. You can also add the path to the YAML stage definition like this:

  ```yaml
      - stage:
        spec:
          sharedPaths:
            - /shared/scan_results
  ```

#### Log Level <a href="#log-level" id="log-level"></a>

The minimum severity of the messages you want to include in your scan logs. You can specify one of the following:

* **DEBUG**
* **INFO**
* **WARNING**
* **ERROR**

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

Every STO scan step has a **Fail on Severity** setting. If the scan finds any vulnerability with the specified [severity level](/security-testing-orchestration/new-to-sto/key-concepts/severities.md) or higher, the pipeline fails automatically. You can specify one of the following:

* **`CRITICAL`**
* **`HIGH`**
* **`MEDIUM`**
* **`LOW`**
* **`INFO`**
* **`NONE`** — Do not fail on severity

The YAML definition looks like this: `fail_on_severity : critical # | high | medium | low | info | none`

#### Settings <a href="#settings" id="settings"></a>

You can use this field to specify environment variables for your scanner.

#### Additional Configuration <a href="#additional-configuration" id="additional-configuration"></a>

The fields under **Additional Configuration** vary based on the type of infrastructure. Depending on the infrastructure type selected, some fields may or may not appear in your settings. Below are the details for each field

* Override Security Test Image
  * [Container Registry](/security-testing-orchestration/troubleshooting-and-resources/sto-use-cases/set-up-sto-pipelines/configure-pipeline-to-use-sto-images-from-private-registry.md#step-level-override)
  * [Image Tag](/security-testing-orchestration/troubleshooting-and-resources/sto-use-cases/set-up-sto-pipelines/configure-pipeline-to-use-sto-images-from-private-registry.md#step-level-override)
* [Privileged](/continuous-integration/use-harness-ci/use-harness-ci/manage-dependencies/background-step-settings.md#privileged)
* [Image Pull Policy](/continuous-integration/use-harness-ci/use-harness-ci/manage-dependencies/background-step-settings.md#image-pull-policy)
* [Run as User](/continuous-integration/use-harness-ci/use-harness-ci/manage-dependencies/background-step-settings.md#run-as-user)
* [Set Container Resources](/continuous-integration/use-harness-ci/use-harness-ci/manage-dependencies/background-step-settings.md#set-container-resources)
* [Timeout](/continuous-integration/use-harness-ci/use-harness-ci/run-step-settings.md#timeout)

#### Advanced settings <a href="#advanced-settings" id="advanced-settings"></a>

In the **Advanced** settings, you can use the following options:

* [Conditional Execution](/harness-ai/use-harness-platform/pipelines/step-skip-condition-settings.md)
* [Failure Strategy](/harness-ai/use-harness-platform/pipelines/failure-handling/define-a-failure-strategy-on-stages-and-steps.md)
* [Looping Strategy](/harness-ai/use-harness-platform/pipelines/looping-strategies/looping-strategies-matrix-repeat-and-parallelism.md)
* [Policy Enforcement](/harness-ai/use-harness-platform/governance/policy-as-code/harness-governance-overview.md)

### Proxy settings <a href="#proxy-settings" id="proxy-settings"></a>

This step supports private network connectivity if you're using Harness Cloud infrastructure. For information on connectivity options, see [Private network connectivity options](/harness-ai/use-harness-platform/references/private-network-connectivity/private-network-connectivity.md). When using proxy configurations, the `HTTPS_PROXY` and `HTTP_PROXY` variables are automatically set to route traffic through the secure tunnel. If there are specific addresses that you want to bypass the proxy, you can define those in the `NO_PROXY` variable. This can be configured in the **Settings** of your step.

If you need to configure a different proxy, you can manually set the `HTTPS_PROXY`, `HTTP_PROXY`, and `NO_PROXY` variables in the **Settings** of your step.

**Definitions of Proxy variables:**

* `HTTPS_PROXY`: Specify the proxy server for HTTPS requests, example `https://sc.internal.harness.io:30000`
* `HTTP_PROXY`: Specify the proxy server for HTTP requests, example `http://sc.internal.harness.io:30000`
* `NO_PROXY`: Specify the domains as comma-separated values that should bypass the proxy. This allows you to exclude certain traffic from being routed through the proxy.