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.

You can create a scan directly from the Traceable platform. 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.

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.

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 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. To create a scan, complete the following steps:

Step 1 — Provide scan details

Creating a scan starts with you laying a foundation by providing basic details and defining where (environment) and when (frequency) Traceable should execute the scan.

In this step, you should provide the following details:

Once you have specified the above details, click Next.

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. In this step, you should 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

  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:

XAST Live / Replay

DAST

• Select API Endpoints — Select the API endpoints you wish to test as part of the scan. You can select from the following:

  • All Endpoints — Traceable tests all endpoints associated with the environment you selected in Step 1 above.

  • Specific Endpoints — Traceable tests the endpoints you select from the available list.

  • Endpoint Selection Condition — Traceable tests the endpoints based on the conditions you select.

  You can also click View Endpoints to view the endpoints that Traceable has selected based on the condition you select above.

• (Optional) Target URL — Specify the domain on which you wish to execute the scan, for example, mydomain.com.

• Document Type — Select the type of specification you wish to use for testing:

  • OpenAPI Spec/WSDL Spec/GraphQL Schema —

    • (For GraphQL Schema only) Introspection Enabled — Select this option to enable Traceable to dynamically extract the schema from the Target URL you specify below. This enables you to run security tests on the discovered schema without uploading a specification.

    • API Specification — Select one or more specs from the list of pre-uploaded ones or upload new ones according to your requirements.

      Note (for WSDL Spec only)

      • You must merge any XSD definitions into the corresponding WSDL file before uploading. Traceable does not support standalone XSD file parsing.

      • You must ensure that all references are defined within the same WSDL file. Traceable does not support external or cross-file references.

      • Traceable does not support the complexContent element in WSDL files.

    • (For OpenAPI Spec only) Configure API dependencies & sample values — Define the application’s dependency graph. When an API requires one or more prerequisite APIs to run first, the dependency ensures that those calls are executed in order during the DAST scan. For example, GET /orders/{order_id} depends on POST /service/order because an order must be created before it can be retrieved. For more information, see Understanding API Dependencies.

  • Postman Collection —

    • Collection — Select one or more collections from the list of pre-uploaded ones or upload new collections according to your requirements.

    • (Optional) Environment Doc — Select a Postman environment document from the list of pre-uploaded ones or upload a new document according to your requirements. Traceable uses this document to resolve variable references present in the collection(s) that you selected above.

• Target URL — Specify the domain on which you wish to execute the scan, for example, mydomain.com.

Once you have selected the above configurations, you must either select an existing policy or create a new one. Based on the policy, Traceable executes attacks against the selected endpoints to detect issues.

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

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

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

Once you have configured the above settings, click Next.

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:

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

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

  • Idle Timeout — Define how long Traceable should wait if no activity occurs.

  • Scan Timeout — 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 you wish to include the scan results in.

  • Snyk Project — The Snyk project associated with the organization.

  For information on setting up the integration, see Snyk Integration.

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

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

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

Pause and 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 --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.