ZAP Automation Framework (AF Plan) – Complete Guide

This guide explains how to create an Automation Framework (AF) Plan YAML file to run automated security scans.

An AF plan defines:

• Application scope
• Authentication configuration
• Session handling
• Scan jobs (Spider, AJAX Spider, Active Scan)
• Report generation

Once created, the YAML file can be uploaded to the platform to execute a full automated scan.

---

1. AF Plan Structure

A typical AF Plan contains:

• env → Environment configuration
• contexts → Application scope and authentication
• users → Credentials for authenticated scans
• jobs → Scan execution workflow
• reports → Generated scan reports

Example:

env:
  contexts:
    - name: "Application"
      urls:
        - "http://localhost:3000"

jobs:
  - type: spider
  - type: spiderAjax
  - type: activeScan
  - type: report

---

2. Context Configuration

A context defines the target application and scan boundaries.

Example:

env:
  contexts:
    - name: "JuiceShop"
      urls:
        - "http://localhost:3000"

      includePaths:
        - "http://localhost:3000.*"

      excludePaths:
        - "http://localhost:3000/#/login"
        - "http://localhost:3000/#/register"

Fields

Field	Description
name	Context name
urls	Base application URL
includePaths	URLs included in scan
excludePaths	URLs excluded from scan

---

3. Authentication Methods

The Automation Framework supports three authentication types.

Authentication	Use Case
JSON	API login returning JSON tokens
Form	Standard HTML form login
Browser	JavaScript-heavy login requiring browser interaction

Authentication is defined inside the authentication section.

---

4. JSON-Based Authentication

Used when login happens through an API endpoint returning JSON.

Example:

authentication:
  method: "json"
  parameters:
    loginRequestUrl: "http://localhost:3000/rest/user/login"
    loginRequestBody: >
      {
        "email":"{%username%}",
        "password":"{%password%}"
      }
  verification:
    method: "response"
    loggedInRegex: "\"authentication\":true"

Verification Methods

JSON authentication supports:

Method	Description
response	Verifies login using login API response
poll	Calls a protected endpoint repeatedly to verify login

Example poll verification:

verification:
  method: poll
  pollUrl: "http://localhost:3000/api/profile"
  loggedInRegex: "user"

---

5. Form-Based Authentication

Used when login occurs through an HTML form submission.

Example:

authentication:
  method: "form"
  parameters:
    loginPageUrl: "http://localhost/login.php"
    loginRequestUrl: "http://localhost/login.php"
    loginRequestBody: "username={%username%}&password={%password%}"

Verification Methods

Form authentication supports:

Method	Description
response	Validate login response
poll	Check a protected page repeatedly

Example:

verification:
  method: poll
  pollUrl: "http://localhost/dashboard"
  loggedInRegex: "admin"

---

6. Browser-Based Authentication

Browser authentication simulates a real user login using a headless browser.

Example:

authentication:
  method: browser
  parameters:
    browserId: firefox-headless
    loginPageUrl: "http://localhost/login"
    loginPageWait: 5

Verification Methods

Browser authentication supports:

Method	Description
autodetect	Automatically detect login success
response	Verify using response pattern
poll	Verify using protected endpoint

Example:

verification:
  method: autodetect

---

7. Session Management

Session management ensures authenticated requests remain valid.

Example:

sessionManagement:
  method: headers
  parameters:
    Authorization: "Bearer {%json:authentication.token%}"

Supported Methods

Method	Use Case
headers	JWT / API token authentication
cookies	Session cookie authentication
autodetect	Automatic session detection (recommended for browser login)

Notes:

• Browser authentication can use autodetect
• JSON and Form authentication typically use headers or cookies

---

8. User Configuration

Users define credentials used during authenticated scans.

Example:

users:
  - name: "zap-user"
    credentials:
      username: "admin@example.com"
      password: "password123"

Multiple users can be defined if needed.

---

9. Scan Jobs

Jobs define the scan execution process.

Typical workflow:

1. Spider
2. AJAX Spider
3. Active Scan
4. Passive Scan
5. Report

Example:

jobs:
  - name: spider
    type: spider

  - name: ajaxSpider
    type: spiderAjax

  - name: activeScan
    type: activeScan

---

10. Spider Job

The spider crawls the application to discover URLs.

Example:

- name: spider
  type: spider
  parameters:
    maxDepth: 5
    maxChildren: 25
    maxDuration: 2

Parameter	Meaning
maxDepth	Maximum crawl depth
maxChildren	Maximum links followed per page
maxDuration	Maximum spider runtime in minutes

---

11. AJAX Spider

The AJAX spider discovers JavaScript-generated content using a browser.

Example:

- name: ajaxSpider
  type: spiderAjax
  parameters:
    maxDuration: 5

Parameter	Meaning
maxDuration	Maximum runtime of AJAX spider

---

12. Active Scan

The active scan sends attack payloads to detect vulnerabilities.

Example:

- name: activeScan
  type: activeScan
  parameters:
    maxRuleDurationInMins: 1
    maxScanDurationInMins: 1
    maxAlertsPerRule: 1

Parameter	Meaning
maxRuleDurationInMins	Maximum time per rule
maxScanDurationInMins	Total active scan duration
maxAlertsPerRule	Maximum alerts per rule

---

13. Passive Scan

Passive scanning analyzes traffic captured during crawling.

Example:

- type: passiveScan-wait

Optional configuration:

- type: passiveScan-config

---

14. Authentication Flow Tree

Authentication
│
├── JSON Authentication
│   │
│   ├── Verification
│   │   ├── Response Verification
│   │   └── Poll Verification
│   │
│   └── Session Management
│       ├── Headers (JWT / API Token)
│       └── Cookies
│
├── Form Authentication
│   │
│   ├── Verification
│   │   ├── Response Verification
│   │   └── Poll Verification
│   │
│   └── Session Management
│       ├── Cookies
│       └── Headers
│
└── Browser Authentication
    │
    ├── Verification
    │   ├── Autodetect
    │   ├── Response Verification
    │   └── Poll Verification
    │
    └── Session Management
        ├── Autodetect
        ├── Cookies
        └── Headers

---

15. Scan Execution Flow

Authentication
      │
      ▼
Spider Crawl
      │
      ▼
AJAX Spider
      │
      ▼
Active Scan
      │
      ▼
Passive Scan
      │
      ▼
Report Generation

---

16. Uploading the AF Plan

Steps:

1. Save the configuration as af-plan.yaml
2. Upload the file in the scan interface
3. Start the scan
4. Download generated reports

---

17. Best Practices

• Always define includePaths to limit scan scope.
• Exclude logout endpoints to avoid session loss.
• Prefer response verification when possible.
• Use poll verification for complex login flows.
• For modern SPAs, browser authentication is recommended.