Skip to main content

Proxy Recorder Usage Guide

The Proxy Recorder captures HTTP traffic flowing through the Checkmarx DAST ZAP proxy and exports it as a ZST file. The recording can then be uploaded to the Checkmarx platform for use in DAST scans.

Prerequisites

  • Docker installed and access to the checkmarx/dast:latest image

  • A Checkmarx API key (CX_APIKEY)

  • The environment ID you want to associate the recording with

  • Your Checkmarx platform base URL

Perform the following to run the Proxy Recorder:

<container-name-or-id> is either the container name (e.g. proxy-recorder if you used --name proxy-recorder) or the container ID from docker ps.

  1. Start the Proxy Recorder:

    docker run -it \
  --pull=always \
  --name proxy-recorder \
  -p 8090:8090 \
  -p 8092:8092 \
  -v /tmp/pr-output:/tmp/dast-output \
  -e CX_APIKEY=<your-api-key> \
  checkmarx/dast:latest \
  proxy-recorder \
  --url=https://your-target-app.com \
  --output=/tmp/dast-output \
  --proxy-recorder-port=8092 \
  --duration=60 \
  --dump-cert=true \
  --upload=true \
  --environment-id=<your-environment-id> \
  --base-url=<your-checkmarx-base-url>

    Note: -it runs the container in the foreground with an interactive terminal so you can see live logs. Use -d instead if you prefer to run it in the background (detached). --pull=always ensures you always use the latest image.

    Flag

    Required

    Description

    --url

    Yes

    URL of the application to record traffic against

    --base-url

    Yes

    Your Checkmarx platform URL (e.g. https://us.ast.checkmarx.net)

    --environment-id

    Yes (if --upload=true)

    Environment ID to associate the recording with

    --proxy-recorder-port

    No (default: 8092)

    Port for the proxy recorder control API

    --duration

    No (default: 1440 min)

    Maximum recording duration in minutes before auto-stop

    --output-file

    No

    Label for the output file (e.g. session1 → proxy-recorder_session1.zst). Must be unique — uploading with the same label will override the previously uploaded recording.

    --upload

    No (default: true)

    Upload the HAR recording to the Checkmarx platform when done

    --dump-cert

    No (default: false)

    Export the ZAP root CA certificate (required to trust the proxy in your browser/client)

  2. Wait Until the Proxy is Ready: Before routing traffic, confirm ZAP has finished initializing.

    Option A — curl

    curl -s -o /dev/null -w "%{http_code}" http://localhost:8092/ready
# 200 = ready, 503 = still starting

    Option B — docker exec

    docker exec <container-name-or-id> /app/bin proxy-recorder ready --proxy-recorder-port=8092 --base-url=<your-checkmarx-base-url>
# Exit code 0 = ready, exit code 1 = not ready yet

  3. Trust the ZAP Certificate (if using --dump-cert): For the proxy to intercept HTTPS traffic your browser or client must trust the ZAP root CA certificate.

    Option A — curl

    curl http://localhost:8092/cert -o zap-root-ca.crt

    Option B — docker exec

    docker exec <container-name-or-id> /app/bin proxy-recorder cert --proxy-recorder-port=8092 --base-url=<your-checkmarx-base-url> > zap-root-ca.crt

    Then install zap-root-ca.crt as a trusted CA in your browser or HTTP client.

  4. Record Traffic: Route your HTTP traffic through the ZAP proxy on port 8090 from inside the container using docker exec:

    docker exec -it <container-name-or-id> curl -k -x http://localhost:8090 https://your-target-app.com/some-path

    Repeat this for every request you want to record. ZAP captures all traffic passing through it.

  5. Stop the Recording: When you have finished recording, send the stop signal.

    Option A — curl

    curl -X POST http://localhost:8092/stop

    Option B — docker exec

    docker exec <container-name-or-id> /app/bin proxy-recorder stop --proxy-recorder-port=8092 --base-url=<your-checkmarx-base-url>

    The recorder will finalize the HAR export and, if --upload=true, upload it to Checkmarx One automatically.

Example and Tips

# 1. Start
docker run -it \
  --pull=always \
  --name proxy-recorder \
  -p 8090:8090 \
  -p 8092:8092 \
  -v /tmp/pr-output:/tmp/dast-output \
  -e CX_APIKEY=<your-api-key> \
  checkmarx/dast:latest \
  proxy-recorder \
  --url=<your-target-app> \
  --output=/tmp/dast-output \
  --proxy-recorder-port=8092 \
  --duration=60 \
  --dump-cert=true \
  --upload=true \
  --environment-id=<your-environment-id> \
  --base-url=<your-checkmarx-base-url>

# 2. Wait for ready
curl -s -o /dev/null -w "%{http_code}" http://localhost:8092/ready

# 3. Get the certificate
curl http://localhost:8092/cert -o zap-root-ca.crt

# 4. Browse your app with the proxy configured...

# 5. Stop
curl -X POST http://localhost:8092/stop

  • The CX_APIKEY environment variable is required for authentication. It is the API key generated from Checkmarx.

  • The output ZST file is saved inside the container under /tmp/dast-output/dast-output-<random>/. With the volume mount shown above it will appear on the host at /tmp/pr-output/dast-output-<random>/proxy-recorder.zst. The --output=/tmp/dast-output flag is required to ensure the file lands inside the mounted directory.

  • Sending SIGTERM or SIGINT to the container (e.g. docker stop) will also trigger a clean stop.

In this section: