Skip to main content

DAST Environment Setup Wizard

Overview

The Checkmarx DAST Environment Setup Wizard streamlines the configuration of scans, authentication setup, and launching scans for both public and private applications. It also helps you generate YAML configuration files and manage setup flows for new or existing environments.

You can quickly configure authentication using simple form fields - no manual YAML editing is required. Choose from multiple login methods, such as TOTP (2FA), browser-based, or recorder-driven authentication, or upload an existing configuration. Built-in pre-scan verification allows you to test authentication before initiating a full scan.

Navigating the Wizard

  1. Start the wizard by clicking + New Environment.

  2. Configure the following settings to set up your Environment:

    • Environment Name: Enter the name of the web application you want to scan and track.

    • Environment URL: Provide the base URL of the web application.

    • Type:

      • Web or API: Select whether the environment is Web- or API-based.

    • Reachability:

      • Private: Select this if the target application is internal and not externally accessible.

      • Public: Select this if the target application is accessible online.

    • Authentication: Toggle whether the environment requires authentication.

    Click Next to proceed.

    Important

    Follow step 3 and proceed with step 5 for Web-type environments. Skip to step 4 to complete the wizard for API-type environments.

  3. If you selected a Web-type environment, follow these steps:

    1. Copy the provided Docker command.

    2. Paste and run the command in your console.

    3. Once executed, a connection will be established, and you will see the status update in the terminal and the UI. Click Next to proceed.

    Once the CLI connection is successful, a confirmation message will appear.

    • If the CLI is connected, continue.

    • If the CLI is not connected, re-run the setup command.

  4. If you selected an API-type environment, follow these steps:

    1. Upload API File: Supported formats: Postman, OpenAPI, or HAR.

    2. Verify API Key or Token: Ensure the uploaded file includes valid credentials. Use the preview option to confirm.

      Important

      In rare cases, including the bearer token in the API specification does not grant access to the API docs, causing scans to fail. To resolve this, manually specify your bearer tokens to ensure your scans succeed by clicking + Add custom headers and filling out the form. Ensure your headers and target URL are correct. For more information on headers, see Scan Configurations.

    3. On the final step, select Copy Command, Run Scan, or Upload a Config File. Click Finish when done.

  5. Before a scan can run, this step verifies access to protected applications and APIs, helping you catch and resolve authentication issues early. Select your preferred authentication method by clicking on the appropriate option:

    • Form-Based: Enter your login credentials directly in the form.

    • Recorder-Based: Follow the prompts to record a live login session.

      Note

      All credentials are handled securely and used solely for scanning purposes.

    • Upload Config file: Import an existing authentication configuration file, if available.

  6. (optional) When enabling 2FA: Some applications require an additional layer of authentication using TOTP (Time-Based One-Time Passwords). TOTP generates a unique passcode based on the current time, which is valid for only a short period. This code is used during each authentication attempt to verify access to secured areas of your web application.

    Checkmarx DAST supports form-based authentication using TOTP by allowing you to provide a shared secret key.

    When you enable 2FA in your application, it typically shows a QR code for scanning with an authenticator app (e.g., Google Authenticator, Authy, Microsoft Authenticator). Most apps also offer a manual setup option, which displays the secret key - a Base32-encoded string, such as:

    JBSWY3DPEHPK3PXP

    Paste this TOTP secret key into the Secret Key field in CxDAST.

    Tip

    The secret key is often shown alongside the QR code with a label like:

    "Can’t scan the code? Enter this key manually:"

  7. After completing the authentication setup, you can verify it to ensure everything is configured correctly before launching a full scan.

    • Once all required fields are filled, the Authenticate button will become active.

    • Click Authenticate to verify your authentication setup.

      Important

      Do not close the wizard tab during authentication - the process may take a few moments.

    • If authentication succeeds, you will be redirected to the next screen, where you can start the scan directly from the UI or copy the scan command for CLI execution.

    • If authentication fails, an error screen will appear with the following troubleshooting suggestions:

      • Verify that the username and password are correct.

      • Use your stable, non-expiring credentials for authentication.

      • Using 2FA by TOTP? Fill out the 2FA form (optional) to help validate your setup.

      • If using the Recorder-based authentication method, always complete the full login flow in the browser recorder — do not stop immediately after entering credentials. Also, avoid using incognito mode or extensions that block cookies/session data while recording.

  8. After successful authentication, either copy and paste the final Docker command into the CLI or click Finish. Start the scan from the UI by hovering over the end of the environment row and clicking Scan.

    CxDAST automatically saves your configuration file, so you can reuse it for future scans without reconfiguring everything.

    1. Start Scan from the UI-Trigger the scan immediately with a single click- Optional for public apps

    2. Copy the CLI Command

      Ideal for integrating into your CI/CD pipeline.

      • Optional for public apps

      • Required for private apps, where local execution may be necessary due to network restrictions.

Tip

To edit the config file in the wizard for an existing environment (or a recently created one), hover over its row and click + Config File.

Screenshot 2025-04-02 at 22.06.46.png

Managing Saved Configuration Files

  1. Environment Configuration Indicator

    An indicator will appear for each environment, showing that an environment with a saved configuration file is ready for scanning.

    Screenshot 2025-04-03 at 0.40.36.png

  2. Scan Options by Environment Type

    • Public Environments

      • Hover and click Scan at the end of the environment row to trigger a scan directly.

        Screenshot 2025-04-03 at 0.40.36.png

      • Alternatively, click ⋮ and select Copy Scan Command.

    • Private Environments

      • Scanning requires CLI execution. Hover over the environment row to reveal the Copy Scan CMD, which you can use in your local or CI/CD environment.

        Screenshot 2025-04-03 at 0.41.43.png

  3. Update Configuration File

    You can replace an existing configuration file by clicking ⋮ on the environment row and selecting Change Config File.

  4. Download Configuration File

    On the environment row, click ⋮, then Advanced Settings > ID & Config Files > Configuration Files, then click Download.PNG on the file you wish to download.

You can modify settings for each environment at any time through the Environment Settings panel. The following options are available:

  • Tags (Optional)

    Assign custom tags to the environment. Tags help filter environments in the UI.

    Note: Tagging is independent and intended for organizational purposes. They do not impact other components.

  • Groups (Optional)

    Assign user groups to the environment.

    Once a group is assigned, all group members will have permission to perform actions in the environment, such as initiating scans and viewing results.

DAST Tunneling

DAST tunneling makes secure testing simple. Perform DAST scans on internal, private, or firewall-protected applications directly from the cloud - no need to open inbound ports or allow list scanner IPs. All traffic is securely transmitted through an end-to-end encrypted tunnel. Use an existing tunnel or create a new one.

Important

Requirements for Connecting Your Tunnel:

  1. You need a private host that can access the application you want to scan.

  2. You need Docker installed on the private host.

  3. A CMD execution will be provided after creating an environment on Checkmarx One. This command must remain running for the tunnel to be active and able to scan using Checkmarx One cloud services.

Proxy information

  • Traffic direction: outbound only from your Connector to the internet (TCP 443)

  • Proxy protocol: SOCKS5 inside the tunnel; encrypted end‑to‑end

  • Identity & access: one‑time tokens, mutual authentication, zero‑trust transport

Configuring the Tunnel in the Wizard

  1. Create an environment by clicking + Add Environment

  2. Define its name, Base URL, scan type (Web/API), and toggle authentication.

  3. Define a tunnel to associate with the Environment

    9060253720.png

  4. You can create a new tunnel or use an existing one:

    • Creating a new tunnel (give it a descriptive name)

      9058320419.png

    • Using an existing tunnel

      9059401755.png

      Retrieve execution command to run in your private host by clicking:

      9059565576.png

  5. Verify the connection by scanning.

In this section: