Zapr

A comprehensive CLI tool for OWASP ZAP (Zed Attack Proxy) security scanning.

Table of Contents

• Installation
• Offline ZAP Installation
• Configuration
• Global Options
• Commands
  • ZAP Commands (zap)
    • Scan Commands
    • Session Management
    • Context & User Management
    • Search & Discovery
    • Advanced Proxy Management
    • Configuration
    • Maintenance
  • Docker Scan Commands
  • Config Commands
  • Daemon Commands
  • Report Commands
  • Azure DevOps Integration
  • Utils Commands
• Workspace & Logging
• GitHub Actions

Installation

# Clone the repository
git clone https://github.com/your-org/zapr.git
cd zapr

# Install dependencies (requires pnpm)
corepack enable
corepack prepare [email protected] --activate
pnpm install

# Build the project
pnpm build

# Link for CLI usage
pnpm link

Offline ZAP Installation

For air-gapped or offline environments, you can use the zap-downloader project to download ZAP core and all addons, then package them for offline use.

Quick Start

1. Download ZAP and all addons offline:

   # Using Node.js version
   cd apps/zap-downloader-node
   pnpm offline:pack
      
   # Or using Python version
   cd apps/zap-downloader
   python -m zap_downloader offline pack

2. Transfer the .tar file to your offline environment

3. Unpack and use:

   # Node.js
   pnpm offline:unpack -i zap-offline.tar -o my-workspace
   zapr daemon start -t my-workspace/workspace/default.toml
      
   # Python
   python -m zap_downloader offline unpack -i zap-offline.tar -o my-workspace
   zapr daemon start -t my-workspace/workspace/default.toml

See the zap-downloader repository for full documentation.

Configuration

Zapster can be configured via environment variables or command-line options:

# Environment variables (.env file)
ZAP_HOST=localhost
ZAP_PORT=8080
ZAP_API_KEY=your-api-key

# Workspace configuration (output directory for logs and reports)
ZAPR_WORKSPACE=./zap-results

Global Options

| Option | Alias | Default | Description | |--------|-------|---------|-------------| | --host | -H | localhost | ZAP API host | | --port | -p | 8080 | ZAP API port | | --api-key | -k | (none) | ZAP API key | | --workspace | -w | ZAPR_WORKSPACE | Output directory for reports and logs | | --name | -n | (varies) | Output filename |

Commands

ZAP Commands (zap)

The zap command provides access to core ZAP scanning and management functionality.

zapr zap <subcommand> [options]

Available subcommands:

• base-scan - Spider Scan
• active-scan - Active Scan
• ajax-scan - AJAX Spider Scan
• api-scan - Full API Scan
• passive-scan - Passive Scan Management
• session - Manage Sessions
• context - Manage Contexts
• users - Manage Users
• search - Search URLs/Messages
• forced-browse - Forced Browsing
• http-sessions - Manage HTTP Sessions
• break - Manage Break Points
• proxy - Proxy Chain Management
• configure-rules - Configure Scanning Rules
• get-report - Generate Reports
• get-alerts - Get Alerts
• get-version - Get ZAP Version
• automate - Run ZAP Automation (daemon or docker)
• gc - Run Garbage Collection

zap base-scan - Spider Scan

Discover URLs on a target site using the traditional spider.

zapr zap base-scan --url https://example.com [options]

Options:
  --url, -u              Target URL (required)
  --max-depth            Maximum crawl depth (0 = unlimited)
  --max-children         Limit children scanned (0 = unlimited)
  --recurse              Enable recursion (default: true)
  --poll-interval        Status check interval in ms (default: 2000)
  --timeout              Maximum wait time in ms (default: 300000)
  --workspace, -w        Output directory (default: ZAPR_WORKSPACE env)

Examples:
  zapr zap base-scan -u https://example.com
  zapr zap base-scan -u https://example.com --max-depth 3 --timeout 600000
  zapr zap base-scan -u https://example.com --workspace ./results

zap active-scan - Active Scan

Run vulnerability testing against a target.

zapr zap active-scan --url https://example.com [options]

Options:
  --url, -u              Target URL (required)
  --context, -c          Context name for authenticated scanning
  --user-id              User ID for authenticated scanning
  --policy               Scan policy name
  --poll-interval        Status check interval in ms (default: 5000)
  --timeout              Maximum wait time in ms (default: 600000)
  --workspace, -w        Output directory (default: ZAPR_WORKSPACE env)

Examples:
  zapr zap active-scan -u https://example.com
  zapr zap active-scan -u https://example.com --context myapp --user-id 1

zap ajax-scan - AJAX Spider Scan

Crawl a site using a real browser (Firefox/Chrome).

zapr zap ajax-scan --url https://example.com [options]

Options:
  --url, -u              Target URL (required)
  --max-duration        Maximum duration in minutes (0 = unlimited)
  --max-crawl-depth      Maximum crawl depth
  --max-crawl-states     Maximum number of states to crawl
  --browser-id           Browser to use (firefox, chrome, chrome-headless)
  --poll-interval        Status check interval in ms (default: 5000)
  --timeout              Maximum wait time in ms (default: 600000)
  --workspace, -w        Output directory (default: ZAPR_WORKSPACE env)

Examples:
  zapr zap ajax-scan -u https://example.com
  zapr zap ajax-scan -u https://example.com --max-duration 10 --browser-id firefox

zap api-scan - Full API Scan

Run a comprehensive API scan combining spider, passive scan, and active scan in one command.

zapr zap api-scan --url https://example.com [options]

Options:
  --url, -u              Target URL (required)
  --recurse              Recurse into found URLs (default: true)
  --in-scope-only        Only scan URLs in scope (default: false)
  --context, -c          Context name
  --policy               Scan policy name
  --method               HTTP method to use
  --post-data            POST data to send
  --poll-interval        Status check interval in ms (default: 5000)
  --timeout              Maximum wait time in ms (default: 600000)
  --workspace, -w        Output directory (default: ZAPR_WORKSPACE env)
  --name, -n            Output filename for report
  --format, -f           Report format: json, html (default: json)

Examples:
  zapr zap api-scan -u https://api.example.com
  zapr zap api-scan -u https://api.example.com --context myapp
  zapr zap api-scan -u https://api.example.com --workspace ./results --name report.json

zap passive-scan - Passive Scan Management

Enable, disable, or check passive scanning status.

zapr zap passive-scan [options]

Options:
  --enable, -e           Enable passive scanning
  --disable, -d          Disable passive scanning
  --status, -s           Show passive scan status

Examples:
  zapr zap passive-scan --status
  zapr zap passive-scan --enable

Docker Scan Commands (docker)

Zapster provides Docker-based scan commands that run ZAP in a Docker container using the official ZAP images. These commands are ideal for CI/CD pipelines and require Docker to be installed.

zapr docker <subcommand> [options]

Available subcommands:

• baseline-scan - ZAP Baseline Scan
• full-scan - ZAP Full Scan
• api-scan - ZAP API Scan
• automate - Run ZAP Automation
• pull - Pull Docker Image
• get-docker-log - Get Docker Container Logs
• start-daemon - Start ZAP Daemon
• stop-daemon - Stop ZAP Daemon
• autorun - Start Docker Daemon and Run Automation

TOML Configuration for Docker Commands

All Docker commands support TOML configuration files via the -t, --toml option. This allows you to store all your scan parameters in a configuration file instead of passing them as command-line arguments.

# Using TOML config
zapr docker baseline-scan -t config/zap-baseline.toml
zapr docker full-scan -t config/zap-fullscan.toml
zapr docker api-scan -t config/zap-apiscan.toml
zapr docker automate -f plan.yaml -t config/zap-automate.toml
zapr docker start-daemon -t config/zap-daemon.toml
zapr docker autorun --plan plan.yaml -t config/zap-daemon.toml

CLI arguments take precedence over TOML values, so you can use a config file with overrides.

TOML Configuration Sections

The TOML files support the following sections:

[DOCKER]
IMAGE = "ghcr.io/zaproxy/zaproxy:stable"   # Docker image
PORT = 8080                                  # Proxy port
HOST = "0.0.0.0"                             # Host to bind to
API_PORT = 8080                             # API port (daemon only)
NETWORK = "host"                            # Docker network mode
MAX_RESPONSE_SIZE = 104857600               # Max response size in bytes
DB_CACHE_SIZE = 1000000                    # Database cache size
DB_RECOVERY_LOG = false                    # Enable database recovery log
TIMEOUT_MINS = 30                          # Timeout in minutes
NAME = "zap-container"                      # Container name

[JAVA_OPTIONS]
flags = [
  "-Xms4g",
  "-Xmx4g",
  "-XX:+UseZGC",
  "-Xss512k",
  "-XX:+UseContainerSupport",
  "-XX:MaxRAMPercentage=80"
]

[CONFIG]
flags = [
  "api.key=my-secret-key",
  "api.addrs.addr.name=.*",
  "api.addrs.addr.regex=true"
]

# Scan-specific options (for baseline/full/api-scan)
[SCAN]
TARGET = "https://example.com"              # Target URL
SPIDER_MINS = 1                             # Spider duration
REPORT_HTML = "report.html"                 # Output report
MIN_LEVEL = "WARN"                          # Minimum alert level
AJAX_SPIDER = false                         # Use AJAX spider
FAIL_ON_WARN = false                        # Exit with failure on warning

# Volume mappings: host_path = container_path
[VOLUMES]
"./local-config" = "/zap/cfg"
"./api-specs" = "/zap/specs"
"./data" = "/zap/wrk"

Example TOML Files

Example configuration files are provided in the config/ directory:

| Command | Example File | |---------|-------------| | docker start-daemon | config/zap-daemon.toml.example | | docker baseline-scan | config/zap-baseline.toml.example | | docker full-scan | config/zap-fullscan.toml.example | | docker api-scan | config/zap-apiscan.toml.example | | docker automate | config/zap-automate.toml.example |

Copy an example file and modify it to suit your needs:

# Copy example config
cp config/zap-baseline.toml.example config/my-baseline.toml

# Edit the configuration
vim config/my-baseline.toml

# Run with your config
zapr docker baseline-scan -t config/my-baseline.toml

# Override specific options from CLI
zapr docker baseline-scan -t config/my-baseline.toml --target https://other.com

Dynamic TOML for CI/CD Pipelines

You can generate TOML files dynamically with environment variables using the included script:

# Generate TOML from template with environment variables
ZAP_IMAGE=my-custom-image ZAP_PORT=9090 zapr config generate-toml \
  -i config/zap-docker.toml.template \
  -o config/generated.toml

# Then use the generated config
zapr docker start-daemon -t config/generated.toml

Template Syntax:

• ${VAR} - Replace with environment variable value
• ${VAR:-default} - Use default value if VAR is not set

Example GitHub Actions Workflow:

jobs:
  zap-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Generate TOML config
        run: |
          ZAP_IMAGE=${{ vars.ZAP_IMAGE || 'ghcr.io/zaproxy/zaproxy:stable' }} \
          ZAP_PORT=${{ vars.ZAP_PORT || '8080' }} \
          ZAP_API_KEY=${{ secrets.ZAP_API_KEY }} \
          ZAP_NETWORK=${{ vars.ZAP_NETWORK || 'host' }} \
          zapr config generate-toml \
            config/zap-docker.toml.template \
            config/zap.toml
          
      - name: Start ZAP Daemon
        run: pnpm run docker:start-daemon -t config/zap.toml
        
      - name: Run Baseline Scan
        run: pnpm run docker:baseline-scan -t https://example.com -t config/zap.toml

Example Azure DevOps Pipeline:

steps:
  - script: |
      ZAP_IMAGE=$(ZAP_IMAGE) \
      ZAP_PORT=$(ZAP_PORT) \
      ZAP_API_KEY=$(ZAP_API_KEY) \
      zapr config generate-toml \
        -i config/zap-docker.toml.template \
        -o config/zap.toml
    env:
      ZAP_IMAGE: $(zapImage)
      ZAP_PORT: $(zapPort)
      ZAP_API_KEY: $(zapApiKey)
      
  - script: pnpm run docker:start-daemon -t config/zap.toml

For more details on the config generate-toml command and environment variables, see Config Commands.

docker baseline-scan - ZAP Baseline Scan

Run a passive baseline scan that spiders the target for a limited time and checks for common security issues without performing active attacks.

zapr docker baseline-scan --target <url> [options]

Options:
  --target, -t            Target URL with protocol (required)
  --toml, -t             Path to TOML configuration file
  --config-file, -c       Config file to set rules to INFO/IGNORE/FAIL
  --config-url, -u        URL of config file
  --gen-file, -g          Generate default config file
  --spider-mins, -m       Spider duration in minutes (default: 1)
  --report-html, -r       Output HTML report filename
  --report-json, -J       Output JSON report filename
  --report-xml, -x         Output XML report filename
  --include-alpha, -a      Include alpha passive scan rules
  --ajax-spider, -j        Use AJAX spider in addition to traditional spider
  --min-level, -l          Minimum alert level: PASS, IGNORE, INFO, WARN, FAIL
  --timeout-mins, -T       Max time in minutes for scan
  --workspace, -w          Output directory
  --image, -i              ZAP Docker image (default: ghcr.io/zaproxy/zaproxy:stable)
  --network, -n            Docker network mode (default: host)
  --java-options           Java options (default: -Xms4g -Xmx4g -XX:+UseZGC -Xss512k -XX:+UseContainerSupport -XX:MaxRAMPercentage=80)
  --api-key, -k            ZAP API key
  --fail-on-warn, -W       Return failure exit code on warning

Examples:
  zapr docker baseline-scan -t https://example.com
  zapr docker baseline-scan -t https://example.com --report-html report.html --workspace ./results
  zapr docker baseline-scan -t https://example.com --config-url https://example.com/zap.conf

Exit Codes:

• 0: Success (no issues)
• 1: At least one FAIL
• 2: At least one WARN (no FAILs)
• 3: Other failure

docker full-scan - ZAP Full Scan

Run a comprehensive scan that includes spidering, AJAX spider, and active scanning with vulnerability testing.

zapr docker full-scan --target <url> [options]

Options:
  --target, -t            Target URL with protocol (required)
  --config-file, -c       Config file to set rules to INFO/IGNORE/FAIL
  --config-url, -u        URL of config file
  --gen-file, -g          Generate default config file
  --spider-mins, -m       Spider duration in minutes (0 = unlimited)
  --report-html, -r       Output HTML report filename
  --report-json, -J       Output JSON report filename
  --report-xml, -x         Output XML report filename
  --include-alpha, -a      Include alpha scan rules
  --ajax-spider, -j        Use AJAX spider
  --min-level, -l          Minimum alert level
  --timeout-mins, -T       Max time in minutes for scan
  --workspace, -w          Output directory
  --image, -i              ZAP Docker image
  --network, -n            Docker network mode (default: host)
  --java-options           Java options (default: -Xms4g -Xmx4g -XX:+UseZGC -Xss512k -XX:+UseContainerSupport -XX:MaxRAMPercentage=80)
  --api-key, -k            ZAP API key
  --fail-on-warn, -W       Return failure exit code on warning

Examples:
  zapr docker full-scan -t https://example.com
  zapr docker full-scan -t https://example.com --ajax-spider --spider-mins 5

docker api-scan - ZAP API Scan

Scan APIs defined by OpenAPI, SOAP, or GraphQL specifications.

zapr docker api-scan --target <url> --format <format> [options]

Options:
  --target, -t            Target API definition URL or file (required)
  --format, -f           API format: openapi, soap, graphql (required)
  --config-file, -c       Config file to set rules to INFO/IGNORE/FAIL
  --config-url, -u        URL of config file
  --report-html, -r       Output HTML report filename
  --report-json, -J       Output JSON report filename
  --report-xml, -x         Output XML report filename
  --include-alpha, -a      Include alpha scan rules
  --safe-mode, -S         Skip active scan (baseline only)
  --schema                GraphQL schema location (URL or file)
  --host-override, -O     Override hostname in remote OpenAPI spec
  --min-level, -l          Minimum alert level
  --timeout-mins, -T       Max time in minutes for scan
  --workspace, -w          Output directory
  --image, -i              ZAP Docker image
  --network, -n            Docker network mode (default: host)
  --java-options           Java options (default: -Xms4g -Xmx4g -XX:+UseZGC -Xss512k -XX:+UseContainerSupport -XX:MaxRAMPercentage=80)
  --api-key, -k            ZAP API key
  --fail-on-warn, -W       Return failure exit code on warning

Examples:
  zapr docker api-scan -t https://api.example.com/openapi.json -f openapi
  zapr docker api-scan -t https://example.com/graphql -f graphql
  zapr docker api-scan -t https://example.com/api.wsdl -f soap --safe-mode

docker automate - Run ZAP Automation

Run ZAP automation using a YAML plan file via Docker.

zapr docker automate --file <plan.yaml> [options]

Options:
  --file, -f              Path to the ZAP automation plan YAML file (required)
  --workspace, -w         Workspace directory (default: current directory)
  --image, -i             ZAP Docker image (default: ghcr.io/zaproxy/zaproxy:stable)
  --network, -n           Docker network mode (default: host)
  --debug, -d             Show debug messages
  --name, -N              Container name
  --timeout-mins, -t      Minutes to wait for automation to complete (default: 30)
  --max-response-size, -M Max response body size in bytes (default: 100MB)
  --java-options          Java options (default: -Xms4g -Xmx4g -XX:+UseZGC -Xss512k -XX:+UseContainerSupport -XX:MaxRAMPercentage=80)
  --api-key, -k           ZAP API key

Examples:
  zapr docker automate --file plan.yaml
  zapr docker automate -f plan.yaml --workspace ./results

docker pull - Pull Docker Image

Pull a Docker image (useful for pre-caching before running scans).

zapr docker pull --image <image> [options]

Options:
  --image, -i            Docker image to pull (required)
  --tag, -t              Image tag (default: latest)

Examples:
  zapr docker pull --image ghcr.io/zaproxy/zaproxy:stable

docker get-docker-log - Get Docker Container Logs

Fetch logs from a Docker container using the Docker API.

zapr docker get-docker-log [options]

Options:
  --container, -c        Docker container name or ID
  --image, -i            Docker image name to find container by
  --workspace, -w        Output directory (default: ZAPR_WORKSPACE env)
  --name, -n             Output filename (default: agent.log)
  --tail, -t             Number of lines to fetch (default: 10000)

Examples:
  zapr docker get-docker-log --container my-container --workspace ./results
  zapr docker get-docker-log --image mockholm/zap-daemon --workspace ./results

docker start-daemon - Start ZAP Daemon

Start a ZAP daemon container that runs in the background and exposes the ZAP API.

zapr docker start-daemon [options]

Options:
  --image, -i              ZAP Docker image (default: ghcr.io/zaproxy/zaproxy:stable)
  --port, -P              ZAP proxy port (default: 8080)
  --host, -H              ZAP host to bind to (default: 0.0.0.0)
  --api-port, -A          ZAP API port (default: 8080)
  --api-key, -k           API key for ZAP (auto-generated if not provided)
  --debug, -d             Enable debug mode
  --network, -n           Docker network mode or name
  --name, -N              Container name (default: zap-daemon)
  --timeout-mins, -t      Minutes to wait for ZAP to start (default: 1)
  --max-response-size, -M Max response body size in bytes (default: 100MB)
  --java-options             Java options (default: -Xms4g -Xmx4g -XX:+UseZGC -Xss512k -XX:+UseContainerSupport -XX:MaxRAMPercentage=80)

Examples:
  zapr docker start-daemon
  zapr docker start-daemon --port 8090 --api-key my-secret-key
  zapr docker start-daemon --java-options "-Xms2g -Xmx2g" --name my-zap

Default Java Options: | Option | Description | |--------|-------------| | -Xms4g | Initial heap size (4GB) | | -Xmx4g | Maximum heap size (4GB) | | -XX:+UseZGC | Z Garbage Collector (low latency) | | -Xss512k | Thread stack size | | -XX:+UseContainerSupport | Docker container awareness | | -XX:MaxRAMPercentage=80 | Use 80% of container memory |

The start-daemon command outputs DevOps variables for Azure DevOps, GitHub Actions, and TeamCity.

docker stop-daemon - Stop ZAP Daemon

Stop a running ZAP daemon container.

zapr docker stop-daemon [options]

Options:
  --name, -N              Container name (default: zap-daemon)
  --force, -f             Force stop the container

Examples:
  zapr docker stop-daemon
  zapr docker stop-daemon --name my-zap --force

docker autorun - Start Docker Daemon and Run Automation

Start ZAP as a daemon in Docker, wait for it to be ready, then run a ZAP Automation plan. This combines docker start-daemon + ZAP API automation into a single command.

zapr docker autorun [options]

Options:

| Option | Alias | Default | Description | |--------|-------|---------|-------------| | --plan | -p | (none) | Path to ZAP automation plan YAML file | | --toml | -t | (none) | Path to zap-docker.toml configuration file | | --image | -i | ghcr.io/zaproxy/zaproxy:stable | ZAP Docker image to use | | --port | -P | 8080 | ZAP proxy port | | --host | -H | 0.0.0.0 | ZAP host to bind to | | --api-key | | (auto-generated) | API key for ZAP | | --debug | -d | false | Enable debug mode | | --network | -n | (none) | Docker network mode or name | | --name | -N | zap-daemon | Container name | | --timeout-mins | | 5 | Minutes to wait for ZAP to start | | --max-response-size | -M | 104857600 | Max response body size in bytes | | --java-options | | (defaults) | Java options | | --db-cache-size | | 1000000 | Database cache size | | --db-recovery-log | | false | Enable database recovery log |

Examples:

# Start daemon and run a plan
zapr docker autorun --plan zap-automation.yaml

# Using TOML config
zapr docker autorun -t config/zap-docker.toml --plan plan.yaml

# With custom port and image
zapr docker autorun --plan plan.yaml -P 9090 -i ghcr.io/zaproxy/zaproxy:weekly

Config Commands (config)

Configuration utilities for generating and managing TOML configuration files.

zapr config <subcommand> [options]

Available subcommands:

• generate-toml - Generate TOML from template with environment variables

config generate-toml - Generate TOML from Template

Generate a TOML configuration file from a template by substituting environment variables. This is useful for CI/CD pipelines where you want to inject dynamic values.

zapr config generate-toml [options]

Options:
  -i, --input    Input TOML template file (required)
  -o, --output   Output TOML file (default: input filename with .generated.toml suffix)
  -x, --prefix   Environment variable prefix
  -v, --verbose  Show verbose output

Examples:
  # Basic usage with environment variables
  ZAP_IMAGE=my-custom-image ZAP_PORT=9090 zapr config generate-toml \
    -i config/zap-docker.toml.template \
    -o config/zap.toml

  # Generate with default values
  zapr config generate-toml -i config/zap-baseline.toml.template

  # Use with prefix for namespaced variables
  MYAPP_ZAP_IMAGE=custom-image zapr config generate-toml \
    -i config/zap-docker.toml.template \
    -x MYAPP_

Template Syntax:

• ${VAR} - Replace with environment variable value
• ${VAR:-default} - Use default value if VAR is not set

GitHub Actions Example

name: ZAP Security Scan

on:
  push:
    branches: [main]

jobs:
  zap-scan:
    runs-on: ubuntu-latest
    env:
      ZAP_IMAGE: ghcr.io/zaproxy/zaproxy:stable
      ZAP_PORT: 8080
      ZAP_API_KEY: ${{ secrets.ZAP_API_KEY }}
      ZAP_NETWORK: host

    steps:
      - uses: actions/checkout@v4

      - name: Generate TOML config
        run: |
          zapr config generate-toml \
            -i config/zap-docker.toml.template \
            -o config/zap.toml

      - name: Start ZAP Daemon
        run: zapr docker start-daemon -t config/zap.toml

      - name: Run Baseline Scan
        run: |
          zapr docker baseline-scan \
            -t https://example.com \
            -t config/zap.toml \
            --report-html report.html

      - name: Stop ZAP Daemon
        if: always()
        run: zapr docker stop-daemon

Azure DevOps Pipeline Example

trigger:
  - main

stages:
  - stage: ZAP_Scan
    variables:
      zapImage: 'ghcr.io/zaproxy/zaproxy:stable'
      zapPort: '8080'
      zapNetwork: 'host'
    jobs:
      - job: Security_Scan
        pool:
          vmImage: 'ubuntu-latest'
        steps:
          - script: |
              zapr config generate-toml \
                -i config/zap-docker.toml.template \
                -o config/zap.toml
            env:
              ZAP_IMAGE: $(zapImage)
              ZAP_PORT: $(zapPort)
              ZAP_NETWORK: $(zapNetwork)
              ZAP_API_KEY: $(zapApiKey)

          - script: zapr docker start-daemon -t config/zap.toml
            env:
              ZAP_API_KEY: $(zapApiKey)

          - script: |
              zapr docker baseline-scan \
                -t https://example.com \
                -t config/zap.toml \
                --report-html $(Build.ArtifactStagingDirectory)/report.html
            continueOnError: true

          - script: zapr docker stop-daemon
            condition: always()

Available Environment Variables for Templates

| Variable | Default | Description | |----------|---------|-------------| | ZAP_IMAGE | ghcr.io/zaproxy/zaproxy:stable | Docker image | | ZAP_PORT | 8080 | Proxy port | | ZAP_HOST | 0.0.0.0 | Host to bind to | | ZAP_API_PORT | 8080 | API port | | ZAP_NAME | zap-daemon | Container name | | ZAP_NETWORK | host | Docker network | | ZAP_MAX_RESPONSE_SIZE | 104857600 | Max response size | | ZAP_DB_CACHE_SIZE | 1000000 | Database cache size | | ZAP_TIMEOUT_MINS | 2 | Timeout in minutes | | ZAP_WORKSPACE | . | Workspace directory | | ZAP_API_KEY | (none) | API key | | ZAP_JAVA_XMS | -Xms4g | Initial heap size | | ZAP_JAVA_XMX | -Xmx4g | Max heap size |

zap forced-browse - Forced Browsing

Run dirb-style brute-force directory discovery.

zapr forcedBrowse [options]

Options:
  --scan, -s             Start scan on URL
  --stop                 Stop scan by ID
  --status               Show all forced browse scans
  --context, -c          Context name
  --poll-interval        Status check interval in ms (default: 5000)
  --timeout              Maximum wait time in ms (default: 300000)
  --workspace, -w        Output directory (default: ZAPR_WORKSPACE env)

Examples:
  zapr forcedBrowse --scan https://example.com/
  zapr forcedBrowse --status
  zapr forcedBrowse --stop scan123

Daemon Commands (daemon)

Manage ZAP daemon using pm2 for running ZAP as a background service. Supports both direct parameter mode and TOML configuration file.

zapr daemon <subcommand> [options]

Available subcommands:

• start - Start ZAP as a daemon using pm2
• autorun - Start ZAP daemon and run an automation plan once ready
• stop - Stop ZAP daemon managed by pm2
• status - Show PM2 status for the ZAP daemon
• log - Return PM2 logs for the ZAP daemon
• ping - Check if the ZAP daemon host:port is reachable
• health - Check ZAP daemon health via API
• started - Wait until ZAP daemon responds to API

daemon start - Start ZAP Daemon

Start ZAP as a daemon using pm2. Supports TOML config file or direct parameters.

zapr daemon start [options]

Options:
  -t, --toml                 Path to zap.toml configuration file
  -d, --dir                  ZAP installation directory (where zap.jar is)
  -w, --workspace            ZAP working directory
  -H, --host                 ZAP host to bind to (default: 0.0.0.0)
  -P, --port                 ZAP proxy port (default: 8080)
  -k, --api-key              ZAP API key
  -N, --name                 PM2 process name (default: zap-daemon)

Examples:
  # Using TOML config
  zapr daemon start -t /path/to/zap.toml
  
  # Using direct parameters
  zapr daemon start -d /path/to/zap -w /path/to/workspace -P 8080
  
  # With API key
  zapr daemon start -t config.toml -k my-api-key

daemon autorun - Start Daemon and Run Automation

Start ZAP as a daemon using pm2, wait for it to be ready, then run a ZAP Automation plan. This combines daemon start + daemon started + zap automate daemon into a single command. The plan path can be specified via CLI (--plan) or via the [AUTOMATION] section in a TOML config file.

zapr daemon autorun [options]

Options:

| Option | Alias | Default | Description | |--------|-------|---------|-------------| | --plan | -p | (none) | Path to ZAP automation plan YAML file | | --toml | -t | (none) | Path to zap.toml configuration file | | --dir | -d | (none) | ZAP installation directory (where zap.jar is) | | --workspace | -w | ZAPR_WORKSPACE | ZAP working directory | | --host | | 0.0.0.0 | ZAP host to bind to | | --port | -P | 8080 | ZAP proxy port | | --api-key | -k | (none) | ZAP API key | | --name | -N | zap-daemon | PM2 process name |

Examples:

# Start daemon and run a plan (CLI flag)
zapr daemon autorun --plan zap-plan.yaml

# Start daemon and run plan from TOML config
zapr daemon autorun --toml /path/to/zap.toml

# With explicit workspace
zapr daemon autorun --plan plan.yaml -w ./results -P 8080

TOML [AUTOMATION] section:

When using a TOML config file, you can specify the plan path in the [AUTOMATION] section:

[ENV]
ZAP_DOWNLOADER_WORKSPACE = "/path/to/workspace"

# ... other sections ...

[AUTOMATION]
planPath = "zap-plan.yaml"    # Path relative to the TOML file directory

The planPath is resolved relative to the directory containing the TOML file. CLI --plan flag takes precedence when both are provided.

daemon stop - Stop ZAP Daemon

Stop the ZAP daemon managed by pm2.

zapr daemon stop [options]

Options:
  -N, --name                 PM2 process name (default: zap-daemon)

Examples:
  zapr daemon stop
  zapr daemon stop -N my-zap-daemon

daemon status - Show Daemon Status

Show PM2 status for the ZAP daemon.

zapr daemon status [options]

Options:
  -N, --name                 PM2 process name (default: zap-daemon)
  --json                     Return status as JSON

Examples:
  zapr daemon status
  zapr daemon status --json

daemon ping - Check Daemon Reachability

Check if the ZAP daemon host:port is reachable.

zapr daemon ping [options]

Options:
  -H, --host                 Host to check (default: 127.0.0.1)
  -P, --port                 Port to check (default: 8080)
  -T, --timeout              Timeout in milliseconds (default: 2000)
  --json                     Return result as JSON

Examples:
  zapr daemon ping
  zapr daemon ping -H localhost -P 8080

daemon health - Check Daemon Health

Check ZAP daemon health via the ZAP API.

zapr daemon health [options]

Options:
  -H, --host                 Host (default: 0.0.0.0)
  -P, --port                 Port (default: 8080)

Examples:
  zapr daemon health
  zapr daemon health -H localhost -P 8080

daemon started - Wait for Daemon

Wait until ZAP daemon responds to the ZAP API.

zapr daemon started [options]

Options:
  -H, --host                 Host (default: 0.0.0.0)
  -P, --port                 Port (default: 8080)
  -T, --timeout              Max wait time in seconds (default: 60)

Examples:
  zapr daemon started
  zapr daemon started --timeout 120

daemon log - View Daemon Logs

Return PM2 logs for the ZAP daemon.

zapr daemon log [options]

Options:
  -N, --name                 PM2 process name (default: zap-daemon)
  -n, --lines                Number of log lines to return (default: 200)
  --json                     Return logs as JSON
  -f, --follow               Stream logs (like tail -f)
  -e, --err                  Show error log (stderr)
  -b, --both                 Show both output and error logs
  -c, --copy                 Copy logs to a file path instead of console

Examples:
  zapr daemon log
  zapr daemon log -n 100
  zapr daemon log --err
  zapr daemon log --follow
  zapr daemon log --copy ./logs

Report Commands

getReport - Generate Reports

Generate security reports in various formats.

zapr getReport --format <format> [options]

Options:
  --format, -f           Report format: xml, json, md, html (required)
  --workspace, -w        Output directory (default: ZAPR_WORKSPACE env)
  --name, -n             Output filename
  --title                Report title
  --template             Report template name
  --description          Report description

Examples:
  zapr getReport -f html --workspace ./results --name report.html
  zapr getReport -f json --workspace ./results --name report.json --title "Weekly Scan"
  zapr getReport -f xml --workspace ./results --name report.xml

getPdf - Generate PDF Report

Generate a PDF report from ZAP scan results.

zapr getPdf [options]

Options:
  --workspace, -w        Output directory (default: ZAPR_WORKSPACE env)
  --name, -n             Output filename (default: report.pdf)
  --title, -t            Report title (default: "ZAP Security Scan Report")

Examples:
  zapr getPdf --workspace ./results
  zapr getPdf --workspace ./results --name scan-report.pdf --title "Security Audit"

getAlerts - Get Alerts

Retrieve and display security alerts.

zapr getAlerts [options]

Options:
  --base-url, -u         Filter by base URL
  --start                Start index for pagination (default: 0)
  --count                Maximum alerts to return
  --workspace, -w        Output directory (default: ZAPR_WORKSPACE env)
  --name, -n             Output filename
  --summary, -s          Show alerts summary by risk level

Examples:
  zapr getAlerts
  zapr getAlerts --summary
  zapr getAlerts -u https://example.com --workspace ./results --name alerts.json
  zapr getAlerts --count 50

createJUnitResults - JUnit XML Output

Generate JUnit-compatible test results from alerts. High and Medium risk alerts are marked as failures, while Low and Informational alerts are marked as passing tests.

zapr createJUnitResults [options]

Options:
  --workspace, -w        Output directory (default: ZAPR_WORKSPACE env)
  --name, -n             Output filename (required)
  --title, -t            Test suite title (default: "ZAP Security Scan")
  --base-url             Filter alerts by base URL

Examples:
  zapr createJUnitResults --workspace ./results --name junit-results.xml
  zapr createJUnitResults --workspace ./results --name results.xml -t "My App Scan" -u https://example.com

Test Result Logic:

• Passed: Low and Informational risk alerts
• Failed: High and Medium risk alerts

utils create-excel-report - Excel Report

Generate an Excel spreadsheet report from ZAP alerts. Reports include test result summaries with pass/fail breakdowns.

zapr utils create-excel-report [options]

Options:
  --workspace, -w        Output directory (default: ZAPR_WORKSPACE env)
  --name, -n             Output filename (default: zap-report.xlsx)
  --base-url, -u         Filter alerts by base URL
  --input, -i            Input JSON file path (alternative to fetching from ZAP)

Examples:
  zapr utils create-excel-report --workspace ./results
  zapr utils create-excel-report --workspace ./results --name security-report.xlsx
  zapr utils create-excel-report --input ./alerts.json --workspace ./results --name report.xlsx

Excel Sheets:

• Summary: Test results overview with pass/fail counts and pass rate
• All Alerts: Complete list of all alerts
• FAIL - High Risk: High severity alerts
• FAIL - Medium Risk: Medium severity alerts
• PASS - Low Risk: Low severity alerts (passing tests)
• PASS - Informational: Informational alerts (passing tests)

getDockerLog - Get Docker Container Logs

Fetch logs from a Docker container using the Docker API.

zapr getDockerLog [options]

Options:
  --container, -c        Docker container name or ID
  --image, -i            Docker image name to find container by
  --workspace, -w        Output directory (default: ZAPR_WORKSPACE env)
  --name, -n             Output filename (default: agent.log)
  --tail, -t             Number of lines to fetch (default: 500)

Examples:
  zapr getDockerLog --container my-container --workspace ./results
  zapr getDockerLog --image mockholm/zap-daemon --workspace ./results

Session Management

session - Manage Sessions

Create, save, and manage ZAP sessions.

zapr session [options]

Options:
  --new, -n              Create new session with name
  --save, -s             Save current session with name
  --overwrite            Overwrite existing session file
  --sites, -l            List all sites in session
  --urls, -u             List all URLs in session
  --access-url, -a       Access URL and capture responses

Examples:
  zapr session --new my-scan
  zapr session --save backup --overwrite
  zapr session --sites
  zapr session --urls
  zapr session --access-url https://example.com

zap gc - Run Garbage Collection

Trigger ZAP's garbage collection to free up memory.

zapr zap gc

Examples:
  zapr zap gc

Context & User Management

context - Manage Contexts

Create and manage ZAP contexts for organizing scans.

zapr context [options]

Options:
  --list, -l             List all contexts
  --new, -n              Create new context with name
  --context, -c          Context name (for other operations)
  --include              Include regex in context
  --exclude              Exclude regex from context
  --export               Export context to file
  --import               Import context from file

Examples:
  zapr context --list
  zapr context --new myapp
  zapr context --new api --include "https://api\.example\.com.*"
  zapr context --context myapp --exclude ".*logout.*"

users - Manage Users

Manage users for authenticated scanning.

zapr users [options]

Options:
  --list, -l             List users (requires --context)
  --new, -n              Create new user (requires --context)
  --remove               Remove user by ID (requires --context)
  --enable               Enable user by ID (requires --context)
  --disable              Disable user by ID (requires --context)
  --context, -c          Context name
  --credentials           Set authentication credentials
  --user-id              User ID

Examples:
  zapr users --list --context myapp
  zapr users --new testuser --context myapp
  zapr users --enable 1 --context myapp

Search & Discovery

search - Search URLs/Messages

Search captured URLs and HTTP messages by regex.

zapr search --regex <pattern> [options]

Options:
  --regex, -r            Regular expression pattern (required)
  --urls, -u             Search URLs matching pattern
  --messages, -m         Search HTTP messages matching pattern

Examples:
  zapr search -r ".*\.json$" --urls
  zapr search -r "api/v[0-9]+" --messages

getVersion - Get ZAP Version

Check the connected ZAP version.

zapr getVersion

zap automate - Run ZAP Automation

Run ZAP automation using a YAML plan file. Supports both daemon and docker backends.

zapr zap automate <subcommand> [options]

Available subcommands:

• daemon - Run automation against a local ZAP daemon
• docker - Run automation against a ZAP daemon running in Docker

zap automate daemon - Run Against Local Daemon

Run automation against a local ZAP daemon.

zapr zap automate daemon --file <plan.yaml> [options]

Options:
  -f, --file                 Path to the ZAP automation plan YAML file (required)
  -w, --workspace            Workspace directory for outputs

Examples:
  zapr zap automate daemon --file plan.yaml
  zapr zap automate daemon -f plan.yaml -w ./results

zap automate docker - Run Against Docker Daemon

Run automation against a ZAP daemon running in Docker.

zapr zap automate docker --file <plan.yaml> --container <name> [options]

Options:
  -f, --file                 Path to the ZAP automation plan YAML file (required)
  -c, --container            Docker container name or ID (required)
  -i, --image                Docker image name to find container by
  -w, --workspace            Workspace directory for outputs

Examples:
  zapr zap automate docker --file plan.yaml --container zap-daemon
  zapr zap automate docker -f plan.yaml -c my-zap -w ./results

The automation command provides progress tracking for each job in the plan (spider, activeScan, ajaxSpider, report, etc.) and automatically copies generated reports to the workspace reports directory.

getLogs - Get Log Configuration

Display ZAP log configuration.

zapr getLogs

Advanced Proxy Management

httpSessions - Manage HTTP Sessions

Manage HTTP sessions for authenticated scanning.

zapr httpSessions --site <hostname> [options]

Options:
  --site, -s              Site hostname (required)
  --list, -l              List sessions for site
  --create, -c            Create a new empty session
  --activate, -a          Set active session by name

Examples:
  zapr httpSessions --site example.com --list
  zapr httpSessions --site example.com --create mysession

break - Manage Break Points

Control break points for request/response interception.

zapr break [options]

Options:
  --add                   Add a new break point
  --type                  Break type: request, response
  --scope                 Break scope: all, mock, suite, tag
  --state                 Break state: all, on, off
  --match                 URL regex pattern to match
  --list, -l              List all break points
  --continue, -c          Continue the intercepted request/response

Examples:
  zapr break --list
  zapr break --add --type request --match ".*login.*"
  zapr break --continue

proxy - Proxy Chain Management

Manage proxy chain exclusions.

zapr proxy [options]

Options:
  --list, -l              List excluded domains
  --add                   Add domain to exclusion list
  --regex                 Treat value as regex
  --disable               Add as disabled

Examples:
  zapr proxy --list
  zapr proxy --add "localhost"
  zapr proxy --add ".*\.internal\.com" --regex

Azure DevOps Integration

createWorkItem - Create Azure DevOps Work Items

Create bugs or tasks in Azure DevOps from ZAP alerts.

zapr createWorkItem [options]

Options:
  --organization, --org  Azure DevOps organization (required)
  --project, --proj       Project name (required)
  --pat                   Personal Access Token (required)
  --type                  Work item type: Bug, Task, User Story
  --title                 Work item title (required)
  --description           Work item description
  --severity              Bug severity (1-4)
  --priority              Work item priority (1-4)
  --area-path             Area path
  --iteration-path        Iteration path
  --base-url              Filter alerts by base URL
  --alert-id              Create work item from specific alert ID
  --threshold             Minimum risk level: High, Medium, Low

Examples:
  zapr azdo create-work-item --org myorg --proj myproject --pat $PAT \
    --title "Security Issue" --threshold High

azdo create-test-result - Create Azure DevOps Test Results

Create test runs in Azure DevOps from scan results.

zapr azdo create-test-result [options]

Options:
  --organization, --org  Azure DevOps organization (required)
  --project, --proj       Project name (required)
  --pat                   Personal Access Token (required)
  --test-run-name, -n      Test run name (required)
  --base-url              Filter alerts by base URL
  --build-id              Azure DevOps build ID
  --release-id            Azure DevOps release ID

Examples:
  zapr azdo create-test-result --org myorg --proj myproject --pat $PAT \
    --test-run-name "ZAP Security Scan"

Utils Commands (utils)

The utils command provides utility commands for generating reports and exports.

zapr utils <subcommand> [options]

Available subcommands:

• create-junit-results - Generate JUnit XML results
• get-pdf - Generate PDF report
• get-logs - Get ZAP log messages

utils create-junit-results - JUnit XML Output

Generate JUnit-compatible test results from alerts. High and Medium risk alerts are marked as failures, while Low and Informational alerts are marked as passing tests.

zapr utils create-junit-results [options]

Options:
  --workspace, -w        Output directory (default: ZAPR_WORKSPACE env)
  --name, -n             Output filename (required)
  --title, -t            Test suite title (default: "ZAP Security Scan")
  --base-url             Filter alerts by base URL

Examples:
  zapr utils create-junit-results --workspace ./results --name junit-results.xml
  zapr utils create-junit-results --workspace ./results --name results.xml -t "My App Scan" -u https://example.com

Test Result Logic:

• Passed: Low and Informational risk alerts
• Failed: High and Medium risk alerts

utils get-pdf - Generate PDF Report

Generate a PDF report from ZAP scan results.

zapr utils get-pdf [options]

Options:
  --workspace, -w        Output directory (default: ZAPR_WORKSPACE env)
  --name, -n             Output filename (default: report.pdf)
  --title, -t            Report title (default: "ZAP Security Scan Report")

Examples:
  zapr utils get-pdf --workspace ./results
  zapr utils get-pdf --workspace ./results --name scan-report.pdf --title "Security Audit"

utils get-logs - Get ZAP Log Messages

Retrieve ZAP log configuration and information.

zapr utils get-logs [options]

Examples: zapr utils get-logs

---

### Configuration

#### `zap configure-rules` - Configure Scanning Rules

Manage ZAP scanning rules and policies.

```bash
zapr zap configure-rules [options]

Options:
  --list, -l             List all rule configurations
  --reset                Reset specific rule (requires --scanner-id)
  --reset-all            Reset all rules to defaults
  --scanner-id           Scanner ID
  --threshold            Alert threshold: OFF, DEFAULT, LO, MEDIUM, HIGH
  --strength             Attack strength: DEFAULT, INSANE, LOW, MEDIUM, HIGH
  --policy-name          Scan policy name

Examples:
  zapr zap configure-rules --list
  zapr zap configure-rules --scanner-id 40012 --threshold HIGH
  zapr zap configure-rules --reset-all

Workspace & Logging

Zapster uses a workspace directory for organizing all output files including logs and reports.

Environment Variable

ZAPR_WORKSPACE=./zap-results

Log File

All commands write logs to <workspace>/zapr.log in the format:

2026-03-21 20:46:33 [INFO] Starting spider scan on: https://example.com
2026-03-21 20:46:35 [INFO] Scan progress: 45%
2026-03-21 20:46:40 [INFO] ✓ Spider scan completed successfully!

Progress Display

Progress bars are shown in terminal. In CI environments (GitHub Actions, etc.), progress is displayed as log messages instead.

GitHub Actions

Zapster includes GitHub Actions workflows for automated security scanning.

Daemon Workflow (Recommended)

The zap-scan-daemon.yml workflow starts ZAP as a daemon container and runs scans against your target.

name: ZAP Security Scan (Daemon)

on:
  workflow_dispatch:
    inputs:
      target_url:
        description: 'Target URL to scan'
        required: true
        default: 'http://localhost:3000'
      zap_port:
        description: 'ZAP Port'
        required: false
        default: '8080'
      api_key:
        description: 'ZAP API Key'
        required: false
        default: 'zapr-api-key'

jobs:
  zap-scan:
    runs-on: ubuntu-latest
    env:
      ZAP_HOST: 0.0.0.0
      ZAP_PORT: ${{ inputs.zap_port || '8080' }}
      ZAP_API_KEY: ${{ inputs.api_key || 'zapr-api-key' }}
      TARGET_URL: ${{ inputs.target_url || 'http://localhost:3000' }}
      ZAPR_WORKSPACE: zap-results

    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: actions/setup-node@v4
        with:
          node-version: '22'

      - name: Enable Corepack
        run: corepack enable

      - name: Install dependencies
        run: pnpm install

      - name: Build project
        run: pnpm run build

      - name: Install Playwright browsers
        run: pnpm exec playwright install --with-deps chromium

      - name: Create workspace
        run: mkdir -p $ZAPR_WORKSPACE

      - name: Start ZAP Daemon
        run: |
          pnpm run docker:start-daemon \
            --port $ZAP_PORT \
            --api-key $ZAP_API_KEY

      - name: Run scans
        run: |
          pnpm run zap:passive-scan --enable
          pnpm run zap:base-scan --url ${{ env.TARGET_URL }}
          pnpm run zap:active-scan --url ${{ env.TARGET_URL }}

      - name: Generate Reports
        run: |
          pnpm run zap:get-report --format json --workspace zap-results
          pnpm run utils:get-pdf --workspace zap-results

      - name: Stop ZAP Daemon
        if: always()
        run: pnpm run docker:stop-daemon

      - name: Upload Reports
        uses: actions/upload-artifact@v4
        with:
          name: zap-reports
          path: zap-results/

Services Workflow (Legacy)

The original zap-scan.yml workflow uses Docker services:

name: ZAP Security Scan

on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]

jobs:
  zap-scan:
    runs-on: ubuntu-latest
    env:
      ZAP_HOST: localhost
      ZAP_PORT: 8080
      ZAP_API_KEY: zapr-api-key
      ZAPR_WORKSPACE: zap-results
    services:
      zap:
        image: mockholm/zap-daemon
        ports:
          - 8080:8080

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install --with-deps chromium

      - name: Build project
        run: npm run build

      - name: Create workspace directory
        run: mkdir -p $ZAPR_WORKSPACE

      - name: Run Spider Scan
        run: npm run zap:base-scan -- --url ${{ env.TARGET_URL }}

      - name: Run Active Scan
        run: npm run zap:active-scan -- --url ${{ env.TARGET_URL }}

      - name: Generate Reports
        run: |
          npm run zap:get-report -- --format json --workspace zap-results --name report.json
          npm run zap:get-report -- --format html --workspace zap-results --name report.html
          npm run utils:get-pdf -- --workspace zap-results --name report.pdf
          npm run utils:create-excel-report -- --workspace zap-results --name zap-report.xlsx
          npm run utils:create-junit-results -- --workspace zap-results --name junit-results.xml

      - name: Get Docker Logs
        run: npm run docker:get-docker-log -- --image mockholm/zap-daemon --workspace zap-results

      - name: Upload Reports
        uses: actions/upload-artifact@v4
        with:
          name: zap-reports
          path: zap-results/

Generated Reports

The workflow generates the following reports:

| Report | File | Description | |--------|------|-------------| | JSON Report | report.json | Full scan results in JSON format | | HTML Report | report.html | Human-readable HTML report | | PDF Report | report.pdf | Printable PDF version | | Excel Report | zap-report.xlsx | Spreadsheet with Summary, All Alerts, FAIL-High, FAIL-Medium, PASS-Low, PASS-Informational sheets | | XML Report | report.xml | XML format report | | JUnit Results | junit-results.xml | JUnit-compatible test results | | Docker Logs | agent.log | ZAP container logs | | OpenAPI Spec | zap-openapi.yaml | ZAP API specification |

License

MIT