Run a Scan from CLI

Run a scan from the Traceable CLI, queue it to a remote runner, and gate a CI/CD pipeline on the result.

A scan is configured on the Traceable platform and can then be executed from either the platform or the CLI. Running it from the CLI enables a CI/CD pipeline to start the scan, publish its results, and gate the build on its outcome as separate steps, each returning an exit code the pipeline can act on.

This topic covers what each command does and when to use it. For more information on the flags each command accepts, see Traceable commands and options.

What you will learn from this topic

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

• The commands that make up the scan lifecycle, and the order in which a pipeline runs them.

• How to dispatch a scan to a runner deployed inside your own network.

• Which exit codes the CLI returns, and which commands return them.

---

Before you begin

Make a note of the following before you run a scan from the CLI:

• Install the Traceable CLI. For more information, see CLI Pre-checks and Installation.

• Make sure you create a scan on the Traceable platform, and note its name or ID. For more information, see Creating a Scan.

• Make sure you fetch the platform access token that the CLI uses to authenticate. For more information, see Public APIs.

• Make sure you install and start at least one runner. For more information, see Installing a Runner.

Queuing a scan to remote runners requires Traceable CLI version 2.8.0 or later. For more information, see CLI Pre-checks and Installation.

---

Scan commands

The scan lifecycle is split across four commands, so that a pipeline can start a scan, publish its results, and gate on its outcome as separate steps. The following table describes each command:

Command	Description
traceable ast scan initAndRun	Initializes and executes a scan on the machine that invokes the CLI.
traceable ast scan queue	Dispatches a scan to remote Traceable runners.
traceable ast scan report	Generates and publishes a report for a scan run.
traceable ast scan getEvaluationResult	Returns the evaluation result for a scan run.

Start the scan

Choose the command based on where the target APIs are reachable from, as described in the following table:

Command	Use it when
initAndRun	The scan has been created, and you need to initialize and run the scan.
queue	The runner is reachable only from inside your own network. For more information, see Runners and CLI.

The scan must be configured on the Traceable platform before executing. It can then be run from either the platform or the CLI. For more information, see Creating a Scan.

Both commands identify the scan either by name or by ID, as shown below:

traceable ast scan initAndRun --scan-name <scan-name>
traceable ast scan initAndRun --scan-id <scan-id>

--scan-name and --scan-id are mutually exclusive, and you must provide at least one of them.

To change the target URL, API specification, or authentication hooks for this run only, add the relevant override flags in any order. For more information, see Scan Overrides.

Generate the report

Traceable produces a report whether the run completed or was aborted:

traceable ast scan report --output-format md

• The default report format is markdown (md).

• You can store the report using --output-file <path> at your desired location. For more commands, see Traceable commands and options.

Evaluate the result

This is the step a pipeline uses to pass or fail the build:

traceable ast scan getEvaluationResult

Pause or resume scan: Traceable enables you to pause and resume scans via the CLI. Follow the steps in the tabs below to pause or resume the scan according to your requirements:

Pause Scan

When you pause a scan, Traceable stops test generation for the scan. You can always resume the scan according to your requirements.

To pause a scan, complete the following steps in your CLI:

1. Press Ctrl+C or Command+C to get a list of scan termination options.

2. Type P and click Enter or Return.

Traceable pauses the scan indefinitely until you resume it.

Resume Scan

Traceable can resume a scan if it is in either of the following states:

• Paused: The scan run is paused.

• Aborted: The scan run is aborted.

To resume a scan, you must run the following command:

The <scan-id> field in the below command is optional. If you skip this field, Traceable automatically selects the ID from the last scan.

traceable ast scan resume --scan-id <scan-id>

Caveats

• Resuming a scan does not generate new test scans or plugins; it only re-runs the plugins that were partially executed or not executed in the previous run.

• As Traceable may re-run some tests from plugins that were partially executed, you may see an increase in the test count.

Pause and resume scan is available for CLI version 1.10.20 and above. To check the current CLI version, use the traceable version command.

---

Queue scan to a remote runner

The queue command dispatches a scan to Traceable runners deployed in your own network instead of executing it locally. The following command shows the structure of a queued scan, including runner selection, wait flags, and override flags:

traceable ast scan queue --scan-name <scan-name> \
  [--runner-ids <ids>] [--runner-names <names>] [--runner-labels <labels>] \
  [--wait] [--wait-timeout <minutes>] [override flags]

All scan overrides, including target URL, specifications, and hooks, are supported with the queue command. For more information, see Scan Overrides.

Runner selection

Runner selection flags control which runners are eligible to pick up the scan. The following table describes the available flags:

Flag	Type	Description
--runner-ids <ids>	Comma-separated list	Targets runners by ID.
--runner-names <names>	Comma-separated list	Targets runners by name.
--runner-labels <labels>	Comma-separated list	Targets runners that carry at least one of the labels.

If you do not specify any of these flags, Traceable assigns any available runner. For more information on how labels route scans to runners, see Installing a Runner.

Wait behavior

By default, the queue command returns as soon as the scan is dispatched, which means no result exists for a later step to act on. The wait flags keep the command running until the scan finishes. The following table describes the available flags:

Flag	Default	Description
--wait	false	Blocks until the scan reaches a terminal state.
--wait-timeout <minutes>	—	The maximum time to wait. This flag requires --wait.

---

Exit codes

Exit codes let a CI/CD pipeline act on the outcome of a scan run without parsing its output. The following table describes each code that the CLI returns:

Code	Description
0	The scan completed successfully, or the evaluation result is PASS.
1	The evaluation result is FAIL. A policy is violated.
3	The scan stopped early. It was aborted or paused, or it reached the maximum test limit.
6	The evaluation is not available. No policy is configured, or the scan is incomplete.
99	An unknown error occurred.

Not every command returns these codes by default. Most require you to opt in with --exit-code, so that a scan run does not fail a pipeline unless you intend it to. The following table describes when each command returns an exit code:

Command	Returns an exit code
initAndRun	When you specify --exit-code.
queue	When you specify both --wait and --exit-code.
report	When you specify --exit-code.
getEvaluationResult	Always, based on the evaluation result.

---

Sample command sequences

The following code snippet runs the scan, writes the report, and returns an exit code in one step:

traceable ast scan initAndRun \
  --scan-name my-scan \
  --output-format sarif --output-file results.sarif \
  --exit-code

Alternatively, you can separate the steps:

traceable ast scan initAndRun --scan-name my-scan
traceable ast scan report --output-format md
traceable ast scan getEvaluationResult

You can invoke the CLI from any CI system. To use the Traceable AST GitHub Action instead of invoking the CLI directly, go to GitHub actions.