Creating a Scan

A scan in Traceable defines what to test, how to test it, and which configurations to use. By creating a scan, you can efficiently manage and organize your security testing workflows, ensuring consistent coverage and easier maintenance across various environments and APIs.

To help you create efficient, optimized scans, Traceable provides recommendations for creation that you can use according to your specific requirements. For more information, see Scan Creation Recommendations. Once you create a scan, Traceable also lets you pause and resume it from the CLI. For more information, see Pause and Resume Scan.

What you will learn from this topic

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

• How to set up a scan.

• How to configure advanced settings such as authentication, traffic filters, and scan evaluation criteria for a scan.

• How to start an ad hoc scan, and how to pause or resume a scan from the CLI.

Before you begin

Make a note of the following before creating a scan:

• Make sure that you have a clear understanding of the available traffic types. For more information, see Traffic Types.

• Make sure that you have at least one policy configured, as Traceable requires a policy to run a scan. For more information, see Policies.

• Make sure that a Runner is installed and is active for scan execution. For the steps to install one, see Runners.

Create a scan

You can create a scan by navigating to Testing → Scans, and clicking Create Scan in the page’s top right corner. Creating a scan requires just a few simple steps:

1. Provide scan details: Specify the scan name, select an environment, frequency, and enable incremental scans.

2. Select the source and attacks: Select how Traceable should generate or capture traffic, the APIs you wish to test, and define the attacks Traceable should simulate on the above APIs.

3. Configure advanced settings: Set up authentication, runners, timeouts, and integrations.

Complete the following steps to create a scan:

Step 1: Provide general scan details

Creating a scan starts with you defining where (environment) and when (frequency) Traceable should execute the scan. Provide the following details:

Click Next once you have specified the above details.

Step 2: Select the source and attacks

After defining where and when you want to scan, you must define which (traffic type), what (assets), and how (attack) Traceable should test.

1. Select the Traffic Type from the following:

   • XAST Live: Traceable executes the scan on live incoming traffic.

   • XAST Replay: Traceable executes the scan on stored APIs. This is available in environments with Replay enabled. For enabling Replay, see Environment Config.

   • DAST: Traceable executes the scan based on the specifications you upload. Traceable supports the following documentation types:

     • OpenAPI Spec

     • WSDL Spec

     • Postman Collection

     • GraphQL Schema

     • Repositories

   Note

   DAST does not require you to instrument an app, however you must choose an environment for the DAST scan to create the default service and list the APIs under it. By default, the service name is traceable-oas-processor.

Based on the traffic you select, Traceable displays the following configurations:

2. Select or create policy: You can either select a predefined policy or create a custom policy. Based on the policy, Traceable executes attacks against the selected endpoints to detect issues. For more information on available predefined policies, see Available policies.

   Traceable provides you with the following options related to a policy:

• Select existing policy: Select a policy from the drop-down list. Traceable shows the attacks configured as part of the policy. In the attack list, you can also perform the following actions according to your requirements:

  • Create a new policy using the same attack selection: Click the Copy icon to create a policy that inherits the attack selections from the selected policy. In the pop-up window, specify the policy details and customize the attack types according to your requirements. This helps when you wish to tweak attack selections by adding or removing specific attacks without altering the original policy. For more information, see Policies.

  • Edit the selected policy: Click the Edit icon to customize the attack types or policy names according to your requirements.

    Note

    This option is not available for Traceable defined policies. For more information on the available predefined policies, see Available policies.

• Create new policy: Click Create New to create a new policy according to your requirements. For more information, see Policies.

  Once you create the policy, Traceable automatically selects it to attack the endpoints.

Note

Traceable also provides AI Scan Policies that you can use to detect AI-related issues, such as LLM System Prompt Leakage and AI SQL Injection. For more information, see AI Security Testing.

Click Next once you have specified the above details.

Step 3: Configure advanced settings

In this step, you can configure the advanced settings, such as authentication and scan evaluation criteria:

Note

• Traceable performs an AND operation between the endpoint selection criteria in Step 2 above and the Filter Traffic, URL Regex, and Scan Evaluation Criteria configurations (if configured) mentioned below. As a result, endpoints selected in the above step are scanned only if they also match the configurations mentioned above.

• If none of the selected endpoints match these conditions, Traceable does not scan any endpoints.

• Authentication: Enable this toggle to select one or more predefined authentication hooks Traceable should use during testing. This ensures that Traceable can access secured endpoints during the scan. You can also create a new authentication hook according to your requirements. For more information, see Authentication.

• Select Specific Runners or Labels: Enable this toggle to select the runners Traceable should use for scan evaluation. You can select specific runners or a runner label from which Traceable should select a runner for scanning. If you do not enable this toggle, Traceable automatically selects a runner for you. For more information, see Runners.

• Filter Traffic: Allow granular filtering of traffic to include endpoints that match specific conditions. The following table describes the available fields:

  Attribute	Purpose
  Location	Specify where Traceable should look for the attribute, for example, the Request Header.
  Attribute Key	Define how Traceable should match the key and specify the name of the key to match.
  Attribute value	Define the value corresponding to the attribute key, for example, Matches Regex.

• URL Regex: Include or exclude endpoints based on regular expressions:

  • Include URL Regex: Specify a regular expression to include specific API endpoints in the scan, for example, .+ includes all URLs.

  • Exclude URL Regex: Specify a regular expression to exclude specific API endpoints in the scan, for example, .*(logout|health).* includes all health checks and logout paths.

• Scan Evaluation Criteria: Define the conditions based on which Traceable should evaluate the scan:

  Attribute	Purpose
  Matches All/Any	Define whether Traceable should execute an AND or an OR operation between the conditions.
  API Endpoints (default)/Services	The scope of assets (all or new) within which the criteria should apply.
  Vulnerability	The scope of vulnerabilities (any or new) corresponding to the above-selected assets. Based on your selection, Traceable looks for vulnerabilities in the above-selected assets.
  Severity	The severity associated with the vulnerability, based on which Traceable should evaluate the criteria.
  Operator	The operator for comparing the above-selected criteria and threshold.
  Threshold	The number of vulnerabilities Traceable should look for, as part of the scan.
  Vulnerability Age	The number of days (1-60) for which the vulnerability should be open, for the criteria to be successfully evaluated.

  You can click + Condition to add one or more conditions according to your requirements.

• Scan Execution Configs: Allow granular filtering of traffic to include endpoints matching specific conditions:

  Attribute	Purpose
  Idle Timeout	Define how long Traceable should wait if no activity occurs.
  Scan Timeout	The maximum duration for Traceable to complete the scan.
  Delay Between Requests	Milliseconds that Traceable should wait between sending individual requests.
  Test Execution Threads	The number of concurrent threads that Traceable should use for executing the scan.

• Integration: Integrate Snyk with the scan according to your requirements:

  • Snyk Organization: The Snyk organization in which you wish to include the scan results.

  • Snyk Project: The Snyk project associated with the organization. For information on setting up the integration, see Snyk Integration.

Click Create once you have configured the above settings. For information on how Traceable handles scans after creation, see FAQs.

Start an ad hoc scan

While Traceable executes the scan according to the schedule you set when creating the scan, you can start an ad hoc scan immediately. To do so, complete the following steps:

1. Navigate to the Scans dashboard.

2. Search for and click the scan you wish to run.

3. In the top right corner of the Scan Details page, click the Start Scan () icon.

4. In the Start New Scan slide-out panel, select how you wish to run the scan. You can choose to run the scan using:
   

   

   • Command from Terminal: You can run the scans using your system terminal. To do this, complete the following steps:

     1. Click Generate New Token or use an existing platform token.

     2. Click Generate Command.

     3. Execute the displayed commands in either Docker or Linux Install.

   • Trigger scan from Platform: You can run the scan on the Traceable platform. For this, complete the following steps:

     1. Specify the Scan Name.

     2. Select how Traceable should run the scan:

        • Allow Traceable to automatically select a runner.

        • Select a runner according to your requirements.

        • Select a runner label according to your requirements.

     For more information on runners, see Runners.

This scan is executed on an ad hoc basis and is listed in the Scan Runs tab. For more information, see Scan Details.

Run a scan from the CLI

Traceable enables you to run a scan from the CLI. You can also pause and resume scans via CLI. For more information, see Run a Scan from CLI.

Note

You can configure a scan only on the Traceable platform.