This is the custom yaml file
automation: true # Always set to true.
# ==========================================================
# SCAN SCOPE CONFIGURATION
# ==========================================================
scope:
# Entry URLs from where spidering / crawling starts.
# For SPA applications (React, Angular, Vue), use the base domain URL.
# Avoid using SPA hash routes (e.g. /#/dashboard) as entry points —
# the traditional spider ignores everything after # since it never reaches the server.
# Browser auth will naturally start from loginPageUrl and capture traffic from there.
#
# URL ORDER MATTERS for multi-domain apps:
# ZAP uses the FIRST URL as the primary site for auth reporting.
# If your login API is on a different domain than your app, put the
# LOGIN domain first — otherwise auth report will show wrong domain
# and authentication will appear to fail even when it succeeds.
#
# Example — React app on spa.example.com, login API on backend.example.com:
# entryUrls:
# - "https://backend.example.com" ← login domain FIRST
# - "https://spa.example.com" ← app domain second
# includePaths order does NOT affect this — only hosts/urls order matte
entryUrls:
- "https://example.com"
# URL patterns that MUST be included in scan scope.
# Supports regex. Include both frontend and backend API domains if they differ.
# For SPAs, backend API domain is more important than frontend domain
# since all actual functionality lives in API endpoints, not frontend routes.
includePaths:
- "https://example.com.*"
- "https://api.example.com.*"
# URL patterns that MUST be excluded from scanning.
# Always exclude logout endpoints — ZAP scanning them will kill the session
# mid-scan and cause all subsequent authenticated requests to fail.
# Static assets are excluded automatically but can be listed explicitly.
# The urls matching png, css, jpg, svg etc. will automaticlaly be excluded
excludePaths:
- "https://example.com/logout.*"
# Static assets (png, css, jpg, svg, ico, woff2 etc.) are automatically
# excluded by ZAP and do not need to be listed explicitly.
# Add only application-specific paths you want to exclude below.
# ==========================================================
# REQUEST HEADERS CONFIGURATION
# ==========================================================
# IMPORTANT: Always check your browser devtools Network tab on any
# authenticated request to see ALL headers your app sends to the backend.
# Missing even one required header causes ZAP requests to be silently
# rejected by the server — even if the token is correctly extracted.
# Common headers to check: Authorization, Type, Version, X-Client-ID, tenant-id
# TWO TYPES OF HEADERS:
#
# 1. Dynamic headers — change every login (tokens, session IDs)
# ZAP can only extract values that look like JWT/Bearer tokens.
# Short strings and numbers CANNOT be extracted dynamically.
# Example: Authorization: Bearer {%json:results.accessToken%} ✅
# Example: tenant-id: "{%json:results.tenantId%}" ❌ won't work
#
# 2. Static headers — fixed per user/tenant (IDs, codes, names)
# Always hardcode these — ZAP will not extract them from login response.
# Example: tenant-id: "1" ✅
# Example: login-id: "iV5356" ✅
# Example: customer-name: "SBIBANK" ✅
#
# NOTE: These headers are injected on scan/spider/poll requests.
# For headers required on the LOGIN REQUEST ITSELF, use the authentication.headers — not this section.
# ==========================================================
headers:
# --------------------------------------------------------
# Authentication headers
# Use ONE of the following (Authorization OR Cookie)
# --------------------------------------------------------
# JWT / Bearer token authentication
# Token is dynamically extracted from login response after successful auth.
# Check your browser devtools → any authenticated request → Authorization header
# to confirm the exact format your app uses:
# Some apps: "Bearer eyJhbGci..." → use: Bearer {%json:token%}
# Some apps: "eyJhbGci..." only → use: {%json:token%} (no Bearer prefix)
# Replace "token" with the actual key name from your login response body.
# Examples:
# {%json:Authorization%} → login response has "Authorization": "eyJ..."
# {%json:accessToken%} → login response has "accessToken": "eyJ..."
# {%json:data.token%} → login response has "data": {"token": "eyJ..."}
Authorization: "Bearer {%json:token%}"
# Cookie-based authentication
# Used for server-rendered apps (Django, Rails, PHP) that return session cookies.
# Not needed for SPA/API apps that use Bearer tokens.
# Cookie: "SESSIONID={%cookie:SESSIONID%}"
# --------------------------------------------------------
# Application specific headers
# --------------------------------------------------------
# Many production apps require additional headers on every request.
# If these are missing ZAP's scan requests will be rejected silently
# even with a valid token — causing authenticated scans to behave like
# unauthenticated scans without any obvious error.
# Check devtools Network tab → any authenticated API request → Request Headers
# and replicate every non-standard header your app sends below.
# Static app-specific headers — hardcode values, do not use {%json:...%}
# These are fixed per user/tenant and ZAP cannot extract them dynamically.
# Check devtools Network tab on any authenticated request to find these.
login-id: "<LOGIN_ID>"
tenant-id: "<TENANT_ID>"
# Role: "admin" # add if your app sends this
# Version: "1.1.0" # add if your app sends this
# X-Client-ID: "web" # add if your app sends this
# ==========================================================
# AUTHENTICATION CONFIGURATION
# ==========================================================
authentication:
# Authentication type — choose based on how your application handles login
#
# json → Your app has a separate backend API endpoint for login (e.g. /api/auth/login)
# that returns a token (JWT, Bearer) in the response body.
# Best for: React, Angular, Vue SPAs with REST APIs, mobile backends.
#
# form → Your app submits login via a traditional HTML <form> with username/password fields.
# The server responds with a session cookie (no token in response body).
# Best for: Server-rendered apps like Django, Rails, PHP, older Java apps.
#
# browser → ZAP launches a real headless Firefox browser to perform login.
# Handles JavaScript-driven forms, redirects, SSO, OAuth, MFA flows.
# Best for: Complex login flows, SPAs with non-standard auth, anything
# that breaks with json or form methods.
# Note: browser auth passively captures more URLs than json auth because
# the real browser executes JavaScript and records all network traffic
# during the login session — giving ZAP a head start on URL discovery.
type: "json"
# Frontend login page URL
# The URL a user visits in their browser to see the login page.
#
# json → Optional. Not used during actual login request.
# form → Required. ZAP fetches this page to find the HTML form fields.
# browser → Required. ZAP opens this URL in headless Firefox to start login flow.
#
# WARNING: For SPA applications (React, Angular, Vue), the login URL typically
# contains a # fragment (e.g. /#/auth/login). Everything after # is handled by
# JavaScript in the browser and never reaches the server. This is fine for
# browser auth but has no meaning for json or form auth.
loginPageUrl: "https://example.com/login"
# Backend login API endpoint
# The actual URL that receives login credentials as an HTTP POST request.
#
# json → Required. This is your API login endpoint (e.g. /api/auth/login).
# form → Leave empty. ZAP auto-discovers form action URL from loginPageUrl.
# browser → Leave empty. Browser handles the full login flow automatically.
loginBackendUrl: "https://api.example.com/auth/login"
# Request body sent to loginBackendUrl
# Only modify the JSON KEY NAMES to match your application's login payload.
# DO NOT change {identifier} or {password} — these are internal placeholders
# automatically replaced with real credentials at scan runtime.
#
# json → Required. Must match the EXACT payload your login API expects.
# Check your browser devtools Network tab → login request → Request Payload
# to see the exact keys and any extra fields your server requires.
# Example: some apps require extra fields like "isAdmin", "clientId", "Type"
# If these are missing, login will silently fail even if credentials are correct.
# form → Leave empty. ZAP auto-fills HTML form fields.
# browser → Leave empty. Browser fills the login form like a real user.
bodyTemplate: |
{
"username": "{identifier}",
"password": "{password}"
}
# Optional. Use this when login have custom headers. Add them as key value pair.
# For headers required on the LOGIN REQUEST ITSELF (e.g. tenant-id on /api/login).
# NOTE: loginRequestHeaders is not officially documented and may be silently ignored.
# headers:
# tenant-id: 1
# ==========================================================
# POST-LOGIN VERIFICATION
# How ZAP confirms authentication actually succeeded.
# ==========================================================
#
# OPTION 1 — No pollUrl (verify against login response directly)
# -------------------------------------------------------
# Leave pollUrl empty. Set loggedInRegex to a keyword in your LOGIN
# ENDPOINT'S own response body on success.
# Best for:
# - json → Simplest and most reliable. Login API returns token + status
# in same response. Use a unique keyword from that response.
# e.g. if response has "status":"login successful!" use that.
# - form → Works if server returns a success indicator in login response.
#
# OPTION 2 — With pollUrl (verify against a protected endpoint)
# -------------------------------------------------------
# Set pollUrl to a backend API endpoint that requires authentication.
# ZAP periodically GETs this URL and checks response against loggedInRegex.
# Best for:
# - json → Use a backend API URL only (e.g. /api/user/profile)
# - form → Any authenticated page or API URL works
# - browser → Any authenticated backend API URL works
#
# CRITICAL — NEVER use SPA frontend URLs for pollUrl:
# ❌ https://example.com/#/dashboard (Angular/React hash route)
# ❌ https://example.com/app/home (SPA client-side route)
# These URLs return an empty HTML shell — JavaScript never executes
# during ZAP's plain HTTP GET, so your regex will never match.
# Always use the actual backend API endpoint instead:
# ✅ https://api.example.com/dashboard/data
# ✅ https://api.example.com/user/profile
#
# OPTION 3 — autodetect (remove pollUrl, loggedInRegex, loggedOutRegex)
# -------------------------------------------------------
# ZAP automatically identifies login/logout indicators from traffic.
# Best for:
# - browser → Recommended first attempt
# - form → Works well for standard HTML apps
# - json → Unreliable. Prefer Option 1.
# Backend API URL accessible only when authenticated.
# Leave empty to use Option 1 (check login response directly).
# Must be a backend API endpoint — never a SPA frontend route.
# Must be a GET endpoint — ZAP poll always sends a GET request
pollUrl: "https://api.example.com/user/profile"
pollFrequency: 10 # seconds — reduce for short scans, increase for long scans
# Keyword or regex matched against pollUrl response (if set)
# or directly against login response (if pollUrl is empty).
# Use a keyword that ONLY appears in successful authenticated responses.
# Tip: use a specific value like an email, role name, or unique status message
# rather than generic words like "success" that might appear in error responses too.
loggedInRegex: "success|profile|dashboard"
# TIP: if using pollUrl, test the endpoint manually first with curl
# using a real token to confirm your regex actually appears in the response.
# curl -X GET https://api.example.com/user/profile -H "Authorization: Bearer <token>" -H "Role: admin"
# This saves significant debugging time.
# Keyword or regex matched to confirm session expired or login failed.
# Set this to whatever your app returns for wrong credentials or expired sessions.
# Check your app by intentionally using wrong credentials and noting the response.
# Helps ZAP clearly distinguish logged-out state from ambiguous responses.
loggedOutRegex: "Unauthorized|Invalid"
I will keep thsi entire yaml file as code block. now give me documnetation explaining about this yaml file at highlevel in detail where it explains each block clearly.