> 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/web-application-and-api-protection-waap/application-security-testing/ast-basics-and-workflow/scan-overrides.md).

# Scan Overrides

Override a scan's target URL, authentication hooks, and API specifications for a single run from the Traceable CLI.

A scan that you create on the Traceable platform holds the baseline configuration for that scan. Scan overrides enable you to change specific parts of that baseline for a single run using the Traceable CLI, without editing the scan itself or creating a new one.

## What you will learn from this topic

By the end of this topic, you will be able to understand:

* How to override the target URL, authentication hooks, and API specifications of a scan run.
* How to queue a scan to a remote runner and apply overrides.

***

## Before you begin

Make a note of the following before you use scan overrides:

* Ensure that you are using Traceable CLI version *2.8.0 or later*. For more information, see [CLI Pre-checks and Installation](/web-application-and-api-protection-waap/application-security-testing/ast-basics-and-workflow/runners-and-cli/cli-pre-checks-and-installation.md).
* Make sure you note the name or ID of the scan you wish to override. For more information, see [Retrieve scan name](#retrieve-scan-name) and [Retrieve scan ID](#retrieve-scan-id).

***

## Understand scan overrides

The scan on the Traceable platform provides the baseline configuration. Passing a CLI flag overrides its setting for that run only, and you can pass multiple flags in the same run. Any setting you do not override keeps the scan's original configuration. When a setting is defined in more than one place, Traceable resolves the configuration in the following order of precedence, from highest to lowest:

**CLI flag > Config file > Platform scan configuration > Platform defaults**

### Retrieve scan name

You can find the name of your scan by following the given steps:

1. Navigate to **Testing → Scans**.
2. Copy the scan name from the corresponding row.

### Retrieve scan ID

You can find the scan ID for your scan by following the given steps:

1. Navigate to **Testing → Scans**.
2. Select your scan.
3. Copy the scan ID from the URL.

<figure><img src="https://1414883571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdr7UJpJrdGkkSGT6AFTu%2Fuploads%2FjlAJHNHAI6zY2tUKbVXX%2Ffind%20scan%20id(1).png?alt=media&amp;token=29ce2afd-b15c-4dab-a451-3565451dfa86" alt=""><figcaption></figcaption></figure>

### Supported commands

Scan overrides apply to the following commands:

```bash
traceable ast scan initAndRun --scan-name <scan-name> [override flags]
traceable ast scan initAndRun --scan-id <scan-id> [override flags]
traceable ast scan queue --scan-name <scan-name> [override flags]
traceable ast scan queue --scan-id <scan-id> [override flags]
```

{% hint style="info" %}

* Replace `<scan-name>` or `<scan-id>` with the name or ID of your scan, respectively. For more information, see [Retrieve scan name](#retrieve-scan-name) and [Retrieve scan ID](#retrieve-scan-id).
* You must provide either `--scan-name` or `--scan-id`. The two flags are mutually exclusive.
  {% endhint %}

### Use scan overrides

The following overrides are supported:

* [Override the target URL](#override-the-target-url)
* [Override authentication hooks](#override-authentication-hooks)
* [Override API specifications](#override-api-specifications)

#### Override the target URL

Use the `--target-url <url>` flag to override the target URL of the scan. The `<url>` value must be a valid `http://` or `https://` URL.

| Input                                | Behavior                                            |
| ------------------------------------ | --------------------------------------------------- |
| Flag omitted                         | Traceable uses the platform scan configuration.     |
| `--target-url "https://example.com"` | Traceable overrides the platform scan's target URL. |

The following code snippet illustrates how to override the target URL:

```bash
traceable ast scan initAndRun --scan-name my-scan --target-url https://staging.example.com
```

#### Override authentication hooks

You can reference authentication hooks either by `--hook-names` or by `--hook-ids`. You can retrieve the hook name by navigating to **Testing → Authentications** and finding your authentication in the **Name** column.

| Flag                   | Type                   | Description               |
| ---------------------- | ---------------------- | ------------------------- |
| `--hook-names <names>` | Comma-separated string | References hooks by name. |
| `--hook-ids <uuids>`   | Comma-separated UUIDs  | References hooks by ID.   |

{% hint style="info" %}
`--hook-names` and `--hook-ids` are mutually exclusive.
{% endhint %}

The following table shows different use cases of the flag:

| Input                        | Behavior                                                                  |
| ---------------------------- | ------------------------------------------------------------------------- |
| Flag omitted                 | Traceable uses the platform scan configuration.                           |
| `--hook-names ""`            | Traceable clears all hooks. The scan run executes without authentication. |
| `--hook-names "hookA,hookB"` | Traceable overrides the platform scan's hooks with the specified hooks.   |

{% hint style="info" %}
`--hook-names` can be used interchangeably with `--hook-ids` for the above set of commands.
{% endhint %}

The following code snippets give examples of different ways you can override authentication hooks:

```bash
# Override with specific hooks by name
traceable ast scan initAndRun --scan-name my-scan --hook-names "staging-auth"

# Override with specific hooks by ID
traceable ast scan initAndRun --scan-name my-scan --hook-ids "uuid-1,uuid-2"

# Clear all hooks
traceable ast scan initAndRun --scan-name my-scan --hook-names ""
```

Traceable executes the hooks in the order that you specify. If a hook name or ID does not exist on the platform, the scan errors out.

#### Override API specifications

Specification overrides replace the platform scan's traffic configuration. You can override only one specification type per scan run. For more information on traffic types, see [Understanding Scans and Traffic Types](/web-application-and-api-protection-waap/application-security-testing/ast-basics-and-workflow/understanding-scans-and-traffic-types.md).

**Retrieve API specification file paths**

You can find the file path to your API specifications in your project's GitHub repository. The following are the accepted file path formats:

* Absolute: `/path/to/spec.yaml`
* Relative: `./specs/openapi.yaml`
* Directory: `./specs/` (files with matching extensions are recursively collected)

Local files are automatically uploaded to the platform before the scan starts, if provided.

**Retrieve API specification IDs**

You can find the API specification IDs by following the steps given below:

1. Navigate to **Discovery → Documentation**.
2. Select the API specification file for which you wish to obtain the ID.
3. Copy the API ID from the URL.

<figure><img src="https://1414883571-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdr7UJpJrdGkkSGT6AFTu%2Fuploads%2FsNICGNo1p5lOh9IE4pVf%2Ffind%20auth%20hook%20id%20new.png?alt=media&amp;token=38ea207c-6dca-4173-9be5-d0c8b26210cc" alt=""><figcaption></figcaption></figure>

Overrides are supported for the following specification types:

* OpenAPI
* GraphQL
* WSDL
* Postman

{% tabs %}
{% tab title="OpenAPI" %}
The following table describes the available flags for OpenAPI:

| Flag                           | Type                                    | Description                                                                                                             |
| ------------------------------ | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `--openapi-spec-files <paths>` | Comma-separated file or directory paths | Traceable uploads local files automatically. Directories are walked recursively for `.json`, `.yml`, and `.yaml` files. |
| `--openapi-spec-ids <uuids>`   | Comma-separated UUIDs                   | References specifications that are already on the platform.                                                             |

{% hint style="info" %}
`--openapi-spec-files` and `--openapi-spec-ids` are mutually exclusive. You cannot use both together.
{% endhint %}
{% endtab %}

{% tab title="GraphQL" %}
The following table describes the available flags for GraphQL:

| Flag                             | Type                                    | Description                                                                                                                                            |
| -------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--graphql-schema-files <paths>` | Comma-separated file or directory paths | Traceable uploads local Schema Definition Language (SDL) files automatically. Traceable walks directories recursively for `.graphql` and `.gql` files. |
| `--graphql-schema-ids <uuids>`   | Comma-separated UUIDs                   | References schemas that are already on the platform.                                                                                                   |

{% hint style="info" %}
`--graphql-schema-files` and `--graphql-schema-ids` are mutually exclusive. You cannot use both together.
{% endhint %}
{% endtab %}

{% tab title="WSDL" %}
The following table describes the available flags for WSDL:

| Flag                   | Type                                    | Description                                                                                             |
| ---------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `--wsdl-files <paths>` | Comma-separated file or directory paths | Traceable uploads local files automatically. Traceable walks directories recursively for `.wsdl` files. |
| `--wsdl-ids <uuids>`   | Comma-separated UUIDs                   | References specifications that are already on the platform.                                             |

{% hint style="info" %}
`--wsdl-files` and `--wsdl-ids` are mutually exclusive. You cannot use both together.
{% endhint %}
{% endtab %}

{% tab title="Postman" %}
Postman overrides differ from other specification types. They consist of two separate artifacts, a collection and an environment, and each accepts a single value rather than a comma-separated list. For more information on Postman collections, see [Postman collections with AST](/web-application-and-api-protection-waap/application-security-testing/advanced-usage/postman-collections-with-ast.md). The following table describes the available flags for Postman:

| Flag                              | Type             | Description                                               |
| --------------------------------- | ---------------- | --------------------------------------------------------- |
| `--postman-collection <path>`     | Single file path | The collection file. Traceable uploads it automatically.  |
| `--postman-collection-id <uuid>`  | Single UUID      | References a collection on the platform.                  |
| `--postman-environment <path>`    | Single file path | The environment file. Traceable uploads it automatically. |
| `--postman-environment-id <uuid>` | Single UUID      | References an environment on the platform.                |

{% hint style="info" %}
Exclusivity applies within each pair, not across them. The following pairs are mutually exclusive:

* `--postman-collection` and `--postman-collection-id`
* `--postman-environment` and `--postman-environment-id`

Cross-pair combinations are allowed, such as `--postman-collection-id <uuid> --postman-environment ./env.json`.
{% endhint %}
{% endtab %}
{% endtabs %}

***

## Use scan overrides in CI/CD

Overrides enable you to customize scan configuration at runtime without changing the underlying scan definition. Pass override values as CLI flags to adapt the scan to your execution environment.

Because overrides are supported directly by the Traceable CLI, they can be used with any CI system that can invoke the CLI.

The following options are available depending on your setup:

* **GitHub Actions** — The Traceable AST GitHub Action exposes override flags through its inputs. For supported actions, their inputs, and sample workflows, go to [GitHub actions](/web-application-and-api-protection-waap/integrations/ci-cd/github-actions.md).
* **Any other CI system** — Invoke the CLI directly and pass overrides as flags. For command sequences and exit code handling, see [Run a Scan from CLI](/web-application-and-api-protection-waap/application-security-testing/ast-basics-and-workflow/run-scan-from-cli.md).

{% @harness-feedback/feedback %}