OWASP ZAP Automation

Automating security testing with OWASP ZAP's automation framework and integration capabilities

OWASP ZAP provides powerful automation capabilities that allow you to integrate security testing into your development lifecycle. This guide covers ZAP's automation framework and integration options for continuous security testing.

Automation Overview

ZAP offers multiple approaches to automation:

  • Automation Framework: YAML-based configuration for consistent, repeatable testing
  • Command Line Interface: Run ZAP from scripts and CI/CD pipelines
  • REST API: Control ZAP remotely via HTTP requests
  • Docker Images: Run ZAP in containerized environments
  • Client Libraries: Integrate ZAP with various programming languages

These approaches can be combined to create comprehensive security testing workflows tailored to your specific needs.

ZAP Automation Framework

The Automation Framework is ZAP's newest and most powerful automation solution, introduced in ZAP 2.10.0.

Automation Framework Overview

The Automation Framework provides:

  • YAML-based configuration
  • Job-based execution model
  • Integration with CI/CD systems
  • Consistent, repeatable testing
  • Headless operation
  • Version control friendly

It's designed to be simple to use while providing the flexibility needed for complex testing scenarios.

Creating an Automation Plan

1
Create a Basic Plan

Create a YAML file with the following structure:

env:
  contexts:
    - name: "My Context"
      urls:
        - "https://example.com"

jobs:
  - type: spider
    parameters:
      context: "My Context"
      url: "https://example.com"
      maxDuration: 5

  - type: passiveScan-wait
    parameters:
      maxDuration: 10

  - type: activeScan
    parameters:
      context: "My Context"
      maxDuration: 60

  - type: report
    parameters:
      template: traditional-html
      reportDir: "/path/to/reports"
      reportFile: "zap-report"
2
Define Contexts

Contexts define the scope of testing:

env:
  contexts:
    - name: "My Context"
      urls:
        - "https://example.com"
      includePaths:
        - "https://example.com/.*"
      excludePaths:
        - "https://example.com/logout/.*"
      authentication:
        method: "form"
        parameters:
          loginUrl: "https://example.com/login"
          loginRequestData: "username=%username%&password=%password%"
          loginPageUrl: "https://example.com/login"
        verification:
          method: "response"
          loggedInRegex: "Logout"
          loggedOutRegex: "Login"
      users:
        - name: "User1"
          credentials:
            username: "testuser"
            password: "testpass"
3
Configure Jobs

Configure each job with appropriate parameters:

jobs:
  - type: spider
    parameters:
      context: "My Context"
      user: "User1"  # Optional, for authenticated scanning
      url: "https://example.com"
      maxDuration: 5
      subtreeOnly: true

  - type: activeScan
    parameters:
      context: "My Context"
      user: "User1"  # Optional, for authenticated scanning
      policy: "Default Policy"
      maxRuleDurationInMins: 5
      maxScanDurationInMins: 60
4
Add Report Generation

Configure report generation:

jobs:
  # Other jobs...

  - type: report
    parameters:
      template: "traditional-html"
      reportDir: "/path/to/reports"
      reportFile: "zap-report"
      reportTitle: "ZAP Security Report"
      reportDescription: "This report contains the results of the automated security scan."
      displayReport: false  # Set to true to open the report automatically

Available report formats include:

  • traditional-html
  • traditional-md
  • traditional-xml
  • traditional-json
  • high-level-report

Running an Automation Plan

Running via Command Line

Run an automation plan using the -autorun flag:

zap.sh -cmd -autorun /path/to/plan.yaml

Additional options:

# Run with debugging enabled
zap.sh -cmd -debug -autorun /path/to/plan.yaml

# Run with a specific config file
zap.sh -cmd -config config.prop -autorun /path/to/plan.yaml

# Run with environment variables
zap.sh -cmd -autorun /path/to/plan.yaml -env "key1=value1" -env "key2=value2"

Advanced Automation Techniques

Authentication Automation

1
Form-Based Authentication

Configure form-based authentication:

env:
  contexts:
    - name: "My Context"
      authentication:
        method: "form"
        parameters:
          loginUrl: "https://example.com/login"
          loginRequestData: "username=%username%&password=%password%"
        verification:
          method: "response"
          loggedInRegex: "Logout"
          loggedOutRegex: "Login"
      users:
        - name: "User1"
          credentials:
            username: "testuser"
            password: "testpass"
2
Script-Based Authentication

For complex authentication flows:

env:
  contexts:
    - name: "My Context"
      authentication:
        method: "script"
        parameters:
          script: "Authentication Script.js"
          scriptEngine: "Oracle Nashorn"
          loginUrl: "https://example.com/login"
          # Additional script parameters
        verification:
          method: "response"
          loggedInRegex: "Logout"
          loggedOutRegex: "Login"
      users:
        - name: "User1"
          credentials:
            username: "testuser"
            password: "testpass"
            # Additional credentials required by the script
3
Using Authentication in Jobs

Specify the user for authenticated scanning:

jobs:
  - type: spider
    parameters:
      context: "My Context"
      user: "User1"
      url: "https://example.com"

  - type: activeScan
    parameters:
      context: "My Context"
      user: "User1"
      policy: "Default Policy"

API Security Testing

1
API Definition Import

Import API definitions:

jobs:
  - type: import
    parameters:
      type: "openapi"
      file: "/path/to/openapi.json"
      target: "https://example.com/api"

Supported formats:

  • OpenAPI/Swagger
  • SOAP/WSDL
  • GraphQL
2
API Scanning

Configure API-specific scanning:

jobs:
  - type: graphql
    parameters:
      endpoint: "https://example.com/graphql"
      schemaFile: "/path/to/schema.graphql"
      maxQueryDepth: 5
      maxAdditionalQueryDepth: 5

  - type: activeScan
    parameters:
      context: "My Context"
      policy: "API-Only"
3
Custom API Requests

Make specific API requests:

jobs:
  - type: requestor
    parameters:
      requests:
        - url: "https://example.com/api/users"
          method: "GET"
          headers:
            - "Content-Type: application/json"
            - "Authorization: Bearer {%token%}"
        - url: "https://example.com/api/data"
          method: "POST"
          headers:
            - "Content-Type: application/json"
          data: '{"key": "value"}'

CI/CD Integration

Jenkins Integration

Using the OWASP ZAP Jenkins plugin:

pipeline {
    agent any
    
    stages {
        stage('ZAP Security Scan') {
            steps {
                script {
                    // Run ZAP with automation plan
                    sh 'docker run -v ${WORKSPACE}:/zap/wrk/:rw -t owasp/zap2docker-stable zap-automation -autorun /zap/wrk/zap-plan.yaml'
                    
                    // Archive the reports
                    archiveArtifacts artifacts: 'reports/*.html', fingerprint: true
                    
                    // Publish the report
                    publishHTML([
                        allowMissing: false,
                        alwaysLinkToLastBuild: true,
                        keepAll: true,
                        reportDir: 'reports',
                        reportFiles: 'zap-report.html',
                        reportName: 'ZAP Security Report'
                    ])
                }
            }
        }
    }
}

Alternatively, use the official ZAP Jenkins plugin:

pipeline {
    agent any
    
    stages {
        stage('ZAP Security Scan') {
            steps {
                script {
                    zapStartNew()
                    zapCrawler('https://example.com')
                    zapActiveScan('https://example.com')
                    zapReport()
                    zapAlertCheck(failHighRisk: 1, failMediumRisk: 5)
                }
            }
        }
    }
}

Command Line Interface

ZAP's command line interface provides various options for automation.

1
Basic Usage

Run ZAP from the command line:

# Start ZAP in daemon mode
zap.sh -daemon -host 0.0.0.0 -port 8080

# Run ZAP with no UI
zap.sh -cmd
2
Packaged Scans

ZAP includes several packaged scan scripts:

# Baseline scan (passive only)
zap-baseline.py -t https://example.com

# Full scan (active)
zap-full-scan.py -t https://example.com

# API scan
zap-api-scan.py -t https://example.com/api -f openapi

These scripts are available in the ZAP installation directory and in the Docker images.

3
Custom Command Line Scripts

Create custom scripts using the ZAP API:

#!/bin/bash

# Start ZAP in daemon mode
zap.sh -daemon -host 127.0.0.1 -port 8080 &

# Wait for ZAP to start
sleep 10

# Access the API
curl "http://localhost:8080/JSON/core/view/sites/"

# Spider a URL
curl "http://localhost:8080/JSON/spider/action/scan/?url=https://example.com"

# Wait for spider to complete
while [ "$(curl -s http://localhost:8080/JSON/spider/view/status/ | jq -r .status)" != "100" ]; do
    sleep 5
done

# Run active scan
curl "http://localhost:8080/JSON/ascan/action/scan/?url=https://example.com"

# Wait for scan to complete
while [ "$(curl -s http://localhost:8080/JSON/ascan/view/status/ | jq -r .status)" != "100" ]; do
    sleep 5
done

# Generate report
curl "http://localhost:8080/OTHER/core/other/htmlreport/" > report.html

# Shutdown ZAP
curl "http://localhost:8080/JSON/core/action/shutdown/"

REST API

ZAP provides a comprehensive REST API for remote control.

Basic API Usage

Access the API via HTTP requests:

# View available sites
GET http://localhost:8080/JSON/core/view/sites/

# Spider a URL
GET http://localhost:8080/JSON/spider/action/scan/?url=https://example.com

# Check spider status
GET http://localhost:8080/JSON/spider/view/status/

# Start active scan
GET http://localhost:8080/JSON/ascan/action/scan/?url=https://example.com

# Get alerts
GET http://localhost:8080/JSON/alert/view/alerts/

The API is available in JSON, XML, HTML, and other formats by changing the URL prefix.

Docker Integration

ZAP provides official Docker images for containerized security testing.

1
Available Images

ZAP offers several Docker images:

  • owasp/zap2docker-stable: Latest stable release
  • owasp/zap2docker-weekly: Latest weekly release
  • owasp/zap2docker-bare: Minimal image without GUI
  • owasp/zap2docker-live: Development version
2
Basic Usage

Run ZAP in Docker:

# Run ZAP in daemon mode
docker run -p 8080:8080 -i owasp/zap2docker-stable zap.sh -daemon -host 0.0.0.0 -port 8080

# Run a baseline scan
docker run -t owasp/zap2docker-stable zap-baseline.py -t https://example.com

# Run with mounted directory for reports
docker run -v $(pwd):/zap/wrk/:rw -t owasp/zap2docker-stable \
  zap-full-scan.py -t https://example.com -r report.html
3
Custom Docker Configurations

Create a custom Dockerfile:

FROM owasp/zap2docker-stable

# Install additional tools
RUN apt-get update && apt-get install -q -y --fix-missing \
    curl \
    jq \
    && rm -rf /var/lib/apt/lists/*

# Add custom scripts
COPY scripts/ /zap/scripts/

# Add custom configuration
COPY config/ /zap/config/

# Set working directory
WORKDIR /zap/wrk

# Default command
CMD ["zap-automation", "-autorun", "/zap/wrk/plan.yaml"]

Best Practices for Automation

1
Scan Configuration
  • Start with a baseline scan before active scanning
  • Define appropriate scope to avoid scanning unintended targets
  • Use context definitions to properly scope tests
  • Configure appropriate scan policies based on the application type
  • Set reasonable timeouts to prevent scans from running too long
2
Resource Management
  • Allocate sufficient memory for ZAP (e.g., -Xmx4G)
  • Consider using multiple ZAP instances for large applications
  • Schedule scans during off-peak hours
  • Use incremental scanning for large applications
  • Monitor resource usage and adjust as needed
3
CI/CD Integration
  • Start with non-blocking security tests
  • Gradually introduce quality gates as the application matures
  • Use different scan types for different stages:
    • Quick baseline scans for pull requests
    • Full scans for nightly builds
    • Comprehensive scans for releases
  • Archive and compare reports to track security posture over time
4
Alert Management
  • Use alert filters to manage false positives
  • Set appropriate risk thresholds for CI/CD pipelines
  • Implement a process for reviewing and addressing alerts
  • Track security debt over time
  • Use context-specific alert handling

Troubleshooting Automation

Common Issues

  • ZAP fails to start: Check memory allocation and permissions
  • Scans timeout: Increase timeout values or reduce scope
  • Missing reports: Verify report directory permissions
  • API connection errors: Check network configuration and API key

Enable debug logging for more information:

# Enable debug logging
zap.sh -debug -cmd -autorun plan.yaml

Next Steps

Now that you understand ZAP's automation capabilities, explore these related topics: