Run a Scan from CLI

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.

• How to troubleshoot a scan that does not start or ends early.

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.

Note

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:

• 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.

  Note

  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 the 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>

  Note

  --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

  Note

  • 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:

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

Note

Pause and Resume scan is available for CLI version 1.10.20 and above. To check the current CLI version, you can 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:

Note

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:

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:

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:

Sample command sequences

The code snippets in this section show different formats of using the scan commands on Traceable CLI. For more information on other Traceable commands, see Traceable commands and options.

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 as well:

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 Actions instead of invoking the CLI directly, see GitHub Actions.