Using the DAST CLI

Overview

The DAST CLI (Dynamic Application Security Testing Command Line Interface) is a powerful tool for performing security scans on web applications and APIs. It supports multiple scanning modes and offers extensive configuration options to tailor scans to your specific needs.

Note

Commands and flags are automatically maintained and updated with each CLI release. Pull the images from Docker Hub for the most current versions. Use dast --help or dast [command] --help for more details in the CLI.

Installation and Setup

Prerequisites

Go 1.22 or higher
Java Runtime Environment (for OWASP ZAP engine)
Access to CxOne platform
Valid authentication credentials

Commands Overview

The DAST CLI supports the following main commands:

scan - Run a scan based on the environment configuration
web - Perform web application scan
api - Perform API security scan
setup - Set up authentication sessions
version - Display version information

Global Flags

Required Flags

These are flags that you must use for all commands. --environment-id flag is used for all commands except for the scan command. -v flag is used in any command where you need to specify a file path, for example, for configuration files, API files, or Recorder files.

Flag	Description	Example
`--base-url`	CxOne server base URL	`<https://ast.checkmarx.net`>
`--environment-id`	Environment ID from CxOne platform	`12345678-abcd-1234-5678-123456789012`
`-v`	Mounts the directory filepath Warning Without read and write permissions to the mounted directory, DAST CLI scan will fail.	`-v ${PWD}:/dast_test`

Common Optional Flags

Flag	Default	Description
`--config`	`""`	Path to configuration file
`--output`	`""`	Path to output directory
`--timeout`	`10000`	Timeout in seconds
`--log-level`	`"info"`	Log level (debug, info, warn, error)
`--verbose`	`false`	Print logs to stdout
`--fail-on`	`""`	Lowest severity to fail execution (all, low, info, medium, high)
`--update-interval`	`30`	Update interval in seconds
`--jvm-properties`	`"-Xmx3G"`	JVM properties for heap-stack size
`--zap-port`	8090	zap proxy port to use

Authentication & Retry Flags

Flag	Default	Description
`--retry`	`3`	Number of retry attempts on connection failure
`--retry-delay`	`20`	Time between retries in seconds

Proxy Configuration

Flag	Default	Description
`--proxy-host`	`""`	Proxy host address
`--proxy-port`	`""`	Proxy port number
`--no-proxy`	`""`	Exclude URLs matching pattern from proxy

Polling Configuration

Flag	Default	Description
`--poll-timeout`	`600`	Poll timeout in seconds
`--poll-ticker`	`30`	Poll ticker interval in seconds

Commands

Important

ALL commands require the API Key and --base-url to run the DAST CLI

1. Scan Command

Runs a scan based on the pre-configured environment settings. Ensure you mount the directory that includes the web, API, recording, authentication, and custom config files you wish to scan. Remember to confirm the filepaths are consistent with the mounted directory. See here for more information on using Docker image in the CLI.

Usage

dast scan --base-url <url> --environment-id <id> [flags]

Specific Flags

Flag	Default	Description
`--url`	`""`	URL of the application to scan
`--is-cloud-scan`	`false`	Run a scan using cloud services instead of locally
`--custom-headers`	`[]`	Custom HTTP headers to include in each outgoing request, in the format: `[{"header":"header-name", "value":"header-value", "url":"url-regex"}]`
`--env-setup`	`""`	JSON configuration for environment setup before the scan is run
`--tunnel-name`	`""`	Name of the tunnel to use to access a private host (will be created if it does not exist)
`--tunnel-ready-timeout`	`120`	Timeout in seconds to wait for the tunnel to become ready
`--one-time-tunnel`	`false`	If true, it will create a one-time tunnel for the scan. The tunnel will be deleted at the end.

--env-setup JSON Structure includes the following fields:

Field	Type	Required	Description
`name`	string	Yes	Name of the environment
`url`	string	Yes	URL of the application to be scanned
`scanType`	string	Yes	Type of scan: `web` or `api`
`isPublic`	boolean	No	Whether the target is publicly accessible (default: `false`)
`groups`	string[]	No	List of group names to associate with the environment
`tags`	string[]	No	List of tags to associate with the environment
`projectIds`	string[]	No	List of project IDs to associate with the environment
`hasAuth`	boolean	No	Whether authentication is required (default: `false`)
`authMethod`	string	Conditional	Authentication method: `recording`, `browser`, or `customConfig`. Required when `hasAuth` is `true` and `scanType` is `web`
`customConfigFile`	string	Conditional	Path to custom ZAP configuration file. Required when `authMethod` is `customConfig`
`recordingFile`	string	Conditional	Path to the authentication recording file. Required when `authMethod` is `recording`
`browserForm`	object	Conditional	Browser-based authentication form data. Required when `authMethod` is `browser`
`totp`	object	No	TOTP (Time-based One-Time Password) configuration for 2FA
`apiFiles`	array	Conditional	List of API definition files. Required when `scanType` is `api`
`tunnel`	string	No	Tunnel name for accessing private hosts

browserForm Object

Required if the out method is browser.

Field	Type	Required	Description
`loginUrl`	string	Yes	The URL of the login page
`username`	string	Yes	Username for authentication
`password`	string	Yes	Password for authentication

totp Object

Field	Type	Required	Description
`secretKey`	string	Yes	The TOTP secret key
`digits`	integer	Yes	Number of digits in the OTP (must be > 0)
`period`	integer	Yes	Time period in seconds for OTP rotation (must be > 0)

apiFiles Array Item

Field	Type	Required	Description
`type`	string	Yes	Type of API file: `openapi`, `postman`, or `har`
`file`	string	Yes	Path to the API definition file

Examples

Basic local scan:

dast scan \
  --base-url https://ast.checkmarx.net \
  --environment-id 12345678-abcd-1234-5678-123456789012 \
  --output ./scan-results \
  --verbose

Cloud scan:

dast scan \
  --base-url https://ast.checkmarx.net \
  --environment-id 12345678-abcd-1234-5678-123456789012 \
  --is-cloud-scan

Scan with custom headers:

dast scan \
  --base-url https://ast.checkmarx.net \
  --environment-id 12345678-abcd-1234-5678-123456789012 \
  --custom-header "Authorization:Bearer token123" \
  --custom-header "X-API-Key:myapikey" \
  --output ./results

Cloud scan with environment setup and tunneling:

docker run --user=root \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e CX_APIKEY=<your-api-key> \
  dast-cli:local scan \
    --base-url=https://ast.checkmarx.net \
    --is-cloud-scan=true \
    --tunnel-name=my-tunnel \
    --env-setup='{"name":"my-environment","url":"https://internal-app.local","scanType":"web","isPublic":false,"hasAuth":false}'

Cloud scan with tunneling, authentication, and TOTP:

docker run --user=root \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e CX_APIKEY=<your-api-key> \
  dast-cli:local scan \
    --base-url=https://ast.checkmarx.net \
    --is-cloud-scan=true \
    --tunnel-name=my-tunnel \
    --env-setup='{
      "name":"my-environment",
      "url":"https://internal-app.local",
      "scanType":"web",
      "isPublic":false,
      "hasAuth":true,
      "authMethod":"browser",
      "browserForm":{
        "loginUrl":"https://internal-app.local/login",
        "username":"user@example.com",
        "password":"secret123"
      }
    }'

Cloud scan with tunneling for API scan:

docker run --user=root \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /path/to/api-specs:/specs \
  -e CX_APIKEY=<your-api-key> \
  dast-cli:local scan \
    --base-url=https://ast.checkmarx.net \
    --is-cloud-scan=true \
    --tunnel-name=my-tunnel \
    --env-setup='{
      "name":"my-api-environment",
      "url":"https://internal-api.local",
      "scanType":"api",
      "isPublic":false,
      "hasAuth":false,
      "apiFiles":[{"type":"openapi","file":"/specs/openapi.yaml"}]
    }'

Note

--user=root and -v /var/run/docker.sock:/var/run/docker.sock are required for tunneling because the CLI spawns a tunnel container.
The tunnel will be created automatically if it doesn't exist.
Use --tunnel-ready-timeout to adjust the wait time for tunnel connection (default: 120 seconds).

2. Web Command

Performs web application security scanning. Specify the path to the configuration file using the --config flag. Ensure you mount the directory that includes the web and custom config files you wish to scan. Remember to confirm the filepaths are consistent with the mounted directory.

Usage

dast web --base-url <url> --environment-id <id> [flags]

Examples

Basic web scan:

dast web \
  --base-url https://ast.checkmarx.net \
  --environment-id 12345678-abcd-1234-5678-123456789012 \
  --config ./web-config.yml \
  --output ./web-results

Web scan with specific timeout and fail conditions:

dast web \
  --base-url https://ast.checkmarx.net \
  --environment-id 12345678-abcd-1234-5678-123456789012 \
  --timeout 7200 \
  --fail-on high \
  --verbose

3. API Command

Performs API security scanning using OpenAPI, Postman collections, or HAR files. Specify the file paths for each API and their configuration files, using the --config flag. Ensure you mount the directory that includes the API and custom config files you wish to scan. Remember to confirm the filepaths are consistent with the mounted directory.

Usage

dast api --base-url <url> --environment-id <id> [one of: --openapi | --postman | --har] [flags]

Specific Flags (select one - required)

Flag	Description
`--openapi`	Path to OpenAPI specification file
`--postman`	Path to Postman collection file
`--har`	Path to HAR (HTTP Archive) file

Examples

API scan with OpenAPI specification:

dast api \
  --base-url https://ast.checkmarx.net \
  --environment-id 12345678-abcd-1234-5678-123456789012 \
  --openapi ./api-spec.yml \
  --output ./api-results

API scan with Postman collection:

dast api \
  --base-url https://ast.checkmarx.net \
  --environment-id 12345678-abcd-1234-5678-123456789012 \
  --postman ./collection.json \
  --log-level debug

API scan with HAR file:

dast api \
  --base-url https://ast.checkmarx.net \
  --environment-id 12345678-abcd-1234-5678-123456789012 \
  --har ./traffic.har \
  --fail-on medium

5. setup Command

Sets up authentication sessions for scanning.

Usage

dast setup --base-url <url> --environment-id <id> [flags]

Specific Flags

Flag	Default	Description
`--url`	`""`	URL of the application
`--auth-session-uuid`	`""`	UUID of authentication session
`--setup-timeout`	`300`	Setup timeout in seconds
`--setup-poll-ticker`	`5`	Setup poll ticker in seconds
`--setup-poll-timeout`	`900`	Setup poll timeout in seconds

Examples

Basic setup:

dast setup \
  --base-url https://ast.checkmarx.net \
  --environment-id 12345678-abcd-1234-5678-123456789012 \
  --url https://example.com

Setup with custom timeouts:

dast setup \
  --base-url https://ast.checkmarx.net \
  --environment-id 12345678-abcd-1234-5678-123456789012 \
  --url https://example.com \
  --setup-timeout 600 \
  --setup-poll-timeout 1200

6. version Command

Displays the version information of the DAST CLI.

Usage

dast version

Example

dast version
# Output: DAST CLI version: 1.2.3

Environment Variables

The CLI supports the following environment variables:

Variable	Description
`CX_APIKEY`	API key for authentication
`CX_TIMEOUT`	Client timeout value
`CX_AGENT_NAME`	Custom agent name
`HTTP_PROXY`	HTTP proxy URL
`DAST_CONSTANT_OUTPUT_FOLDER`	Use constant output folder

Exit Codes

The CLI uses the following exit codes:

0 - Success
2 - Error (configuration, scan failure, etc.)

Debug Mode

Enable verbose logging for detailed troubleshooting:

dast [command] --verbose --log-level debug [other-flags]

Examples by Use Case

Web Scan

docker run \-e CX_APIKEY={API_KEY} \
-v /downloads/directory:/dast_test \
checkmarx/dast:latest web \
--config=/dast_test/fast_scan_sample.yaml \
--base-url=<base URL>\
--output=/dast_test \
--jvm-properties=-Xmx3G \
--timeout=86400 \
--verbose \
--environment-id=ce17623b-0545-4f04-a8b1-f39c689e9ccd

API Testing with Multiple Formats

Note

In the below example, .har file are interchangeable with Postman and OpenAPI files.

docker run \-e CX_APIKEY={API_KEY} \
-v ${PWD}:/dast_test \
checkmarx/dast:latest api \
--config=/dast_test/configHarTest.yaml \
--har=/dast_test/harFile.har \
--base-url={CX_ONE_URL} \
--output=/dast_test \
--jvm-properties=-Xmx3G \
--timeout=86400 \
--verbose \
--environment-id=10790c6f-a16e-4018-95e9-790aae837141

In this section:

Using the DAST CLI

Overview

Note

Installation and Setup

Prerequisites

Commands Overview

Global Flags

Required Flags

Warning

Common Optional Flags

Authentication & Retry Flags

Proxy Configuration

Polling Configuration

Commands

Important

1. Scan Command

Usage

Specific Flags

browserForm Object

totp Object

apiFiles Array Item

Examples

Cloud scan with environment setup and tunneling:

Cloud scan with tunneling, authentication, and TOTP:

Cloud scan with tunneling for API scan:

Note

2. Web Command

Usage

Examples

3. API Command

Usage

Specific Flags (select one - required)

Examples

5. setup Command

Usage

Specific Flags

Examples

6. version Command

Usage

Example

Environment Variables

Exit Codes

Debug Mode

Examples by Use Case

Web Scan

API Testing with Multiple Formats

Note

Search results