Troubleshooting Authenticated Scans

This guide explains how to debug issues when authenticated scans do not work as expected.

Before analyzing logs or reports, ensure the correct scan settings are enabled and review the generated artifacts.

Enable Debug Artifacts

When creating a scan, make sure the following options are enabled:

Save vulnerabilities with information/log level

Enabling this option ensures that authentication-related messages and informational findings are recorded in the report. For example, in the Vulnerabilities tab, you may see entries like:

Authentication Request Identified
Session Management Response Identified

Save all scan artifacts for later reference

This option stores important scan artifacts such as:

authentication reports
automation plans
scanner logs
generated scripts

These files are essential for troubleshooting authentication issues.

Key Files for Debugging

For authenticated scans, focus on the following files.

File	Purpose
auth-metrics.json	Authentication summary with status and metrics
auth-report.json	Detailed authentication report
automation.yaml	Generated ZAP automation plan
scan(UUID).log (.log)	Scanner execution logs. Eg: `13969a7a-0769-43e5-8d57-b48e25b33edc__job-0.log`
add-headers.js	Script showing injected headers

1. Authentication Metrics (`auth-metrics.json`)

The auth-metrics.json file provides a summary of authentication behavior during the scan.

It is derived from auth-report.json but contains only the most important indicators.

Example:

{
  "automation.spider.urls.added": 40,
  "spiderAjax.urls.added": 30,
  "stats.ascan.started": 1,
  "stats.ascan.time": 60642,
  "stats.ascan.urls": 241,
  "stats.auth.detect.auth.json": 440,
  "stats.auth.detect.session.Authorization": 6,
  "stats.auth.failure": 220,
  "stats.auth.session.set.header": 1848,
  "stats.auth.sessiontoken.Authorization": 6,
  "stats.auth.sessiontokens.max": 6,
  "stats.code.200": 707,
  "stats.code.500": 4,
  "stats.code.503": 2,
  "stats.network.send.success": 1069,
  "site": "https://example.com",
  "auth_summary": [
    {
      "description": "Authentication failed",
      "passed": false,
      "key": "auth.summary.auth"
    },
    {
      "description": "Session Handling identified",
      "passed": true,
      "key": "auth.summary.session"
    },
    {
      "description": "Verification URL not identified",
      "passed": false,
      "key": "auth.summary.verif"
    }
  ],
  "status": "VERIFICATION_FAILED"
}

Important Field: `status`

The status field provides a quick summary of authentication results.

Possible values include:

Status	Meaning
AUTH_SUCCESS	Authentication worked successfully
VERIFICATION_FAILED	Login worked but verification endpoint failed
WRONG_CREDENTIALS	Provided credentials were invalid
UNKNOWN	Authentication status could not be determined

Important Note

The status value is heuristic-based, meaning it relies on observed behavior such as:

number of login attempts
number of 401/403 responses
verification endpoint results

Because of this, the status may sometimes be inaccurate.

Examples:

Wrong credentials may be reported as VERIFICATION_FAILED
Verification issues may appear as UNKNOWN

However, if authentication works correctly, the status will reliably report AUTH_SUCCESS.

2. Authentication Report (`auth-report.json`)

The auth-report.json file contains a detailed breakdown of authentication behavior, including:

detected tokens
session handling information
authentication attempts
verification checks

Because this file can contain a large amount of data, most debugging scenarios can start with auth-metrics.json instead.

3. Automation Plan (`automation.yaml`)

The automation.yaml file contains the generated ZAP automation plan used to run the scan.

This file is useful for debugging:

authentication configuration
header injection
verification endpoints
scan jobs

Review this file to confirm that the scan was executed with the correct configuration.

4. Scanner Log File (`.log`)

The scanner .log file provides detailed information about scan execution.

This is especially useful when using:

cookie injection
bearer token authentication
custom headers

The log shows whether the injected authentication headers were successfully used.

Example: Successful Authentication Injection

Job script started
Job: injectCookieScript Start action: add
Job script finished, time taken: 00:00:00
Job requestor started
Job verifyAuthHeaderInjection requesting URL https://api.example.com/user/profile
Job requestor finished, time taken: 00:00:01
Job spider started

At the end of the log file:

Job html-report generated report /zap/reports/ZAP-Report-example.com.html
Job report finished, time taken: 00:00:00
Automation plan succeeded!
Duration: 117 seconds

This indicates that authentication worked successfully.

Example: Verification URL Failure

Job script started
Job: injectCookieScript Start action: add
Job script finished, time taken: 00:00:00
Job requestor started
Job verifyAuthHeaderInjection requesting URL https://api.example.com/user/profile
Difference in response code values for message GET https://api.example.com/user/profile Expected : 200 Received : 403
Job requestor finished, time taken: 00:00:01
Job spider started

End of the log:

Automation plan warnings:
Difference in response code values for message GET https://api.example.com/user/profile Expected : 200 Received : 403

This indicates that the verification URL failed.

Debugging Verification URL Failures

If the verification endpoint fails, always test it manually using curl.

Example:

curl -v \
  -H "Type: admin" \
  -H "Version: 1.21.5" \
  -H "Authorization: <TOKEN>" \
  https://api.example.com/user/profile

Ensure that the request includes:

bearer token or cookie
required business headers
correct endpoint

If the response is not HTTP 200, authentication will fail during verification.

TIP: The pollUrl must always be a GET request and should return HTTP 200 when authentication is successful. Any other response indicates a failure in injected authentication or missing headers.

Identifying Required Business Headers

Some applications require additional headers for authenticated requests.

Examples include:

tenant identifiers
client identifiers
role headers
version headers

To identify them:

Open Browser Developer Tools
Navigate to Network tab
Inspect an authenticated request
Identify any custom headers

These headers must be replicated in the scan configuration.

Debugging Injected Headers (`add-headers.js`)

The add-headers.js script shows exactly which headers are injected into requests.

Example script:

// ZAP HTTP Sender Script
// Type: httpsender
// Engine: Graal.js

function sendingRequest(msg, initiator, helper) {
    msg.getRequestHeader().setHeader("Type", "admin");
    msg.getRequestHeader().setHeader("Version", "1.21.5");
    msg.getRequestHeader().setHeader("Authorization", "<TOKEN>");
}

function responseReceived(msg, initiator, helper) {
}

Review this script to confirm:

which headers are injected
whether authentication headers are present
whether business headers are included

When `add-headers.js` Is Generated

The script is automatically generated when:

cookie or bearer token injection is used
custom login headers are provided
browser-based authentication requires additional headers

Therefore, analyzing add-headers.js helps verify exactly what headers were applied during the scan.

Recommended Debugging Workflow

When authentication fails, follow this process:

Check auth-metrics.json for the status summary.
Review auth-report.json if deeper analysis is needed.
Inspect the .log file to confirm header injection behavior.
Validate the verification URL using curl.
Identify missing business headers using browser developer tools.
Review add-headers.js to confirm which headers were injected.

Following this process will help identify most authentication configuration issues quickly.

Enable Debug Artifacts

Key Files for Debugging

1. Authentication Metrics (auth-metrics.json)

Important Field: status​

Important Note​

2. Authentication Report (auth-report.json)

3. Automation Plan (automation.yaml)

4. Scanner Log File (.log)

Example: Successful Authentication Injection​

Example: Verification URL Failure​