Skip to main content

DAST Environment Setup Wizard

Overview

The Checkmarx DAST Environment Setup Wizard simplifies configuring scans, setting up authentication, and launching public and private application scans. It also helps you generate YAML configuration files and manage setup flows for new or existing environments - all in a streamlined interface.

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 and selecting Create & Configure Environment.

    Tip

    To edit the config file in the wizard for an existing environment, hover over its row and click + Config File.

    Screenshot 2025-04-02 at 22.06.46.png
  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.

    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.

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