OWASP ZAP Reporting

Generating and customizing security reports with OWASP ZAP

Effective reporting is a crucial part of any security assessment. OWASP ZAP provides various reporting options to document findings, share results with stakeholders, and integrate with other security tools. This guide covers all aspects of generating, customizing, and working with ZAP reports.

Report Types Overview

ZAP supports multiple report formats, each suited for different purposes:

HTML Reports

HTML reports are human-readable and provide interactive features:

  • Advantages:

    • Visually appealing and easy to navigate
    • Interactive elements (expandable sections, filtering)
    • Can be viewed in any web browser
    • Includes CSS for styling

  • Best for:

    • Sharing with technical and non-technical stakeholders
    • Detailed review of findings
    • Including in security assessment documentation

  • Example usage:

    Reports > Generate HTML Report...

Generating Basic Reports

1
Access Report Generation
  1. In ZAP, go to Report > Generate Report...
  2. Alternatively, use the keyboard shortcut Ctrl+R
2
Select Report Format
  1. Choose the desired report format:
    • HTML (default)
    • XML
    • JSON
    • Markdown
    • PDF (requires add-on)
  2. Each format has its own template options
3
Configure Report Options
  1. Title: Enter a title for the report
  2. Template: Select a template for the chosen format
  3. Report Directory: Choose where to save the report
  4. File Name: Specify the report file name
  5. Description: Add an optional description
  6. Contexts: Select which contexts to include
4
Filter Report Content
  1. Include only URLs in scope: When checked, only includes in-scope items
  2. Include only URLs in context: When checked, only includes items in the selected contexts
  3. Risk levels to include: Select which risk levels to include (High, Medium, Low, Informational)
  4. Confidence levels to include: Select which confidence levels to include (High, Medium, Low)
5
Generate the Report
  1. Click Generate Report
  2. ZAP will create the report in the specified location
  3. A confirmation dialog will appear when complete
  4. Option to open the report directly from the dialog

Customizing Report Content

Filtering Alerts

1
Use the Alert Filters Add-on
  1. Install the Alert Filters add-on if not already installed
  2. Go to Tools > Options > Alert Filters
  3. Click Add to create a new filter
  4. Configure filter criteria:
    • Rule ID: Specific rule to filter
    • URL: URL pattern to match
    • Parameter: Parameter name to match
    • Attack: Attack pattern to match
    • Evidence: Evidence pattern to match
    • New Risk Level: Risk level to assign (can be used to hide alerts by setting to False Positive)
  5. Apply filters before generating reports
2
Use Context Alert Filters
  1. Right-click on a context in the Sites tree
  2. Select Edit Context
  3. Go to the Alert Filters panel
  4. Add filters specific to this context
  5. These filters will apply when generating reports for this context
3
Filter During Report Generation

In the report generation dialog:

  1. Select specific risk levels to include
  2. Select specific confidence levels to include
  3. Choose to include only in-scope URLs
  4. Select specific contexts to include

Report Templates

Traditional Templates

ZAP includes several built-in templates:

  • Traditional HTML Report: Standard HTML report with ZAP branding
  • Traditional XML Report: Standard XML structure for alerts
  • Traditional JSON Report: Standard JSON structure for alerts
  • Traditional Markdown Report: Simple markdown format

These templates include:

  • Summary of alerts by risk level
  • Detailed information about each alert
  • Evidence and solutions
  • References to additional resources

Advanced Reporting Features

Report Automation

1
Using the ZAP API

ZAP provides a REST API for report generation:

# Generate an HTML report via the API
curl "http://localhost:8080/JSON/reports/action/generate/?apikey=YOUR-API-KEY&title=My%20Report&template=traditional&theme=&description=&contexts=&sites=&sections=&includedConfidences=&includedRisks=&reportFileName=zap-report.html&reportFileNamePattern=&reportDir=/path/to/reports/&display=false"

Key parameters:

  • title: Report title
  • template: Report template to use
  • reportFileName: Output file name
  • reportDir: Directory to save the report
  • contexts: Contexts to include (comma-separated)
  • includedRisks: Risk levels to include (comma-separated)
2
Using the Automation Framework

ZAP's Automation Framework allows report generation in scripts:

# Example automation framework configuration
env:
  contexts:
    - name: "Test Context"
      urls:
        - "https://example.com"

jobs:
  - type: spider
    parameters:
      context: "Test Context"
      url: "https://example.com"
  - type: activeScan
    parameters:
      context: "Test Context"
  - type: report
    parameters:
      template: "traditional-html"
      reportDir: "/path/to/reports/"
      reportFile: "zap-report.html"
      reportTitle: "ZAP Security Report"
      reportDescription: "This report contains the results of the scan."
      displayReport: false

Run with:

zap.sh -cmd -autorun /path/to/config.yaml
3
Scheduled Reporting

For regular reporting:

  1. Create a script to run ZAP and generate reports
  2. Schedule the script using cron (Linux/macOS) or Task Scheduler (Windows)
  3. Configure the script to:
    • Start ZAP in daemon mode
    • Run required scans
    • Generate reports
    • Distribute reports (e.g., email, upload to server)

Example bash script:

#!/bin/bash

# Start ZAP in daemon mode
zap.sh -daemon -host 0.0.0.0 -port 8080 -config api.key=12345 &
ZAP_PID=$!

# Wait for ZAP to start
sleep 30

# Run automation framework
curl "http://localhost:8080/JSON/automation/action/runPlan/?apikey=12345&planFilePath=/path/to/config.yaml"

# Wait for completion
sleep 60

# Stop ZAP
kill $ZAP_PID

Integration with Other Tools

Jenkins Integration

Integrate ZAP reports with Jenkins CI/CD:

  1. Install Required Plugins:

    • OWASP ZAP Plugin
    • HTML Publisher Plugin

  2. Configure Jenkins Pipeline:

pipeline {
    agent any
    
    stages {
        stage('ZAP Scan') {
            steps {
                sh 'docker run -v $(pwd):/zap/wrk/:rw -t owasp/zap2docker-stable zap-baseline.py -t https://example.com -r zap-report.html'
            }
            post {
                always {
                    publishHTML([
                        allowMissing: false,
                        alwaysLinkToLastBuild: true,
                        keepAll: true,
                        reportDir: '.',
                        reportFiles: 'zap-report.html',
                        reportName: 'ZAP Security Report'
                    ])
                }
            }
        }
    }
}
  1. Configure Thresholds:
    • Set build to fail based on high-risk findings
    • Use the ZAP plugin's threshold settings

Report Customization Examples

HTML Report Customization

1
Create a Custom Template

  1. Locate the ZAP home directory:

    • Windows: %USERPROFILE%\.ZAP
    • Linux/macOS: ~/.ZAP

  2. Create a reports directory if it doesn't exist

  3. Create a new HTML template file, e.g., custom-template.html:

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>{{title}}</title>
    <style>
        body { font-family: Arial, sans-serif; margin: 20px; }
        .risk-high { background-color: #ff5555; }
        .risk-medium { background-color: #ffaa00; }
        .risk-low { background-color: #ffff00; }
        .risk-info { background-color: #00aaff; }
        table { border-collapse: collapse; width: 100%; }
        th, td { border: 1px solid #ddd; padding: 8px; }
        th { background-color: #f2f2f2; }
    </style>
</head>
<body>
    <h1>{{title}}</h1>
    <p>{{description}}</p>
    
    <h2>Summary</h2>
    <table>
        <tr>
            <th>Risk Level</th>
            <th>Number of Alerts</th>
        </tr>
        {{#alertsSeverityBreakdown}}
        <tr>
            <td>{{severity}}</td>
            <td>{{count}}</td>
        </tr>
        {{/alertsSeverityBreakdown}}
    </table>
    
    <h2>Alerts</h2>
    {{#alerts}}
    <div class="alert risk-{{riskLowercase}}">
        <h3>{{name}} ({{risk}})</h3>
        <p><strong>Description:</strong> {{desc}}</p>
        <p><strong>Solution:</strong> {{solution}}</p>
        <p><strong>Reference:</strong> {{reference}}</p>
        
        <h4>Instances</h4>
        <ul>
        {{#instances}}
            <li>
                <p><strong>URL:</strong> {{uri}}</p>
                <p><strong>Method:</strong> {{method}}</p>
                {{#param}}<p><strong>Parameter:</strong> {{param}}</p>{{/param}}
                {{#attack}}<p><strong>Attack:</strong> {{attack}}</p>{{/attack}}
                {{#evidence}}<p><strong>Evidence:</strong> {{evidence}}</p>{{/evidence}}
            </li>
        {{/instances}}
        </ul>
    </div>
    {{/alerts}}
</body>
</html>
2
Use the Custom Template
  1. In ZAP, go to Report > Generate Report...
  2. Select HTML as the report format
  3. In the Template dropdown, select your custom template
  4. Configure other report options as needed
  5. Generate the report
3
Customize Further

You can enhance your template with:

  • Company branding and logos
  • Interactive JavaScript elements
  • Charts and graphs using libraries like Chart.js
  • Custom CSS for better styling
  • Additional sections for methodology, scope, etc.

Available template variables include:

  • {{title}} - Report title
  • {{description}} - Report description
  • {{alerts}} - All alerts
  • {{alertsSeverityBreakdown}} - Summary of alerts by severity
  • {{alertsJson}} - All alerts in JSON format (for JavaScript processing)

XML Report Transformation

1
Create an XSLT Template
  1. Create an XSLT file, e.g., custom-transform.xslt:
<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <xsl:output method="html" indent="yes"/>
    
    <xsl:template match="/">
        <html>
            <head>
                <title>Security Report</title>
                <style>
                    body { font-family: Arial, sans-serif; }
                    .high { color: red; }
                    .medium { color: orange; }
                    .low { color: yellow; }
                    .info { color: blue; }
                </style>
            </head>
            <body>
                <h1>Security Assessment Report</h1>
                
                <h2>Summary</h2>
                <table border="1">
                    <tr>
                        <th>Risk Level</th>
                        <th>Count</th>
                    </tr>
                    <tr>
                        <td class="high">High</td>
                        <td><xsl:value-of select="count(//alertitem[riskcode='3'])"/></td>
                    </tr>
                    <tr>
                        <td class="medium">Medium</td>
                        <td><xsl:value-of select="count(//alertitem[riskcode='2'])"/></td>
                    </tr>
                    <tr>
                        <td class="low">Low</td>
                        <td><xsl:value-of select="count(//alertitem[riskcode='1'])"/></td>
                    </tr>
                    <tr>
                        <td class="info">Informational</td>
                        <td><xsl:value-of select="count(//alertitem[riskcode='0'])"/></td>
                    </tr>
                </table>
                
                <h2>Findings</h2>
                <xsl:for-each select="//alertitem">
                    <xsl:sort select="riskcode" order="descending"/>
                    <div>
                        <h3>
                            <xsl:attribute name="class">
                                <xsl:choose>
                                    <xsl:when test="riskcode='3'">high</xsl:when>
                                    <xsl:when test="riskcode='2'">medium</xsl:when>
                                    <xsl:when test="riskcode='1'">low</xsl:when>
                                    <xsl:otherwise>info</xsl:otherwise>
                                </xsl:choose>
                            </xsl:attribute>
                            <xsl:value-of select="name"/> (<xsl:value-of select="risk"/>)
                        </h3>
                        <p><strong>Description:</strong> <xsl:value-of select="desc"/></p>
                        <p><strong>Solution:</strong> <xsl:value-of select="solution"/></p>
                        <p><strong>Reference:</strong> <xsl:value-of select="reference"/></p>
                        
                        <h4>Instances</h4>
                        <ul>
                            <xsl:for-each select="instances/instance">
                                <li>
                                    <p><strong>URL:</strong> <xsl:value-of select="uri"/></p>
                                    <p><strong>Method:</strong> <xsl:value-of select="method"/></p>
                                    <xsl:if test="param">
                                        <p><strong>Parameter:</strong> <xsl:value-of select="param"/></p>
                                    </xsl:if>
                                    <xsl:if test="attack">
                                        <p><strong>Attack:</strong> <xsl:value-of select="attack"/></p>
                                    </xsl:if>
                                    <xsl:if test="evidence">
                                        <p><strong>Evidence:</strong> <xsl:value-of select="evidence"/></p>
                                    </xsl:if>
                                </li>
                            </xsl:for-each>
                        </ul>
                    </div>
                </xsl:for-each>
            </body>
        </html>
    </xsl:template>
</xsl:stylesheet>
2
Apply the Transformation
  1. Generate an XML report from ZAP
  2. Use an XSLT processor to transform the report:
# Using xsltproc (Linux/macOS)
xsltproc custom-transform.xslt zap-report.xml > transformed-report.html

# Using Saxon (Java)
java -jar saxon.jar -s:zap-report.xml -xsl:custom-transform.xslt -o:transformed-report.html
  1. View or distribute the transformed report

Best Practices for Reporting

Effective Report Structure

1
Include an Executive Summary
  • Brief overview of the assessment
  • Key findings and risk levels
  • High-level recommendations
  • Visual summary (charts, graphs)

This section should be understandable by non-technical stakeholders.

2
Provide Clear Methodology
  • Scope of the assessment
  • Testing approach and tools used
  • Testing environment and conditions
  • Limitations and constraints

This helps establish the context and boundaries of the assessment.

3
Organize Findings by Risk
  • Group findings by risk level (High, Medium, Low, Informational)
  • Within each risk level, organize by vulnerability type
  • Include clear titles that describe the issue
  • Use consistent formatting for all findings
4
Include Detailed Finding Information

For each finding, include:

  • Description of the vulnerability
  • Technical impact and business risk
  • Steps to reproduce
  • Affected components/URLs
  • Evidence (screenshots, request/response data)
  • Remediation recommendations
  • References to standards or best practices
5
Add Remediation Guidance
  • Provide clear, actionable remediation steps
  • Include code examples where applicable
  • Reference industry best practices
  • Suggest verification methods
  • Prioritize fixes based on risk

Report Distribution and Security

1
Secure Report Distribution
  • Encrypt reports containing sensitive information
  • Use secure channels for report distribution
  • Limit access to reports on a need-to-know basis
  • Consider using secure document sharing platforms
  • Include confidentiality notices in reports
2
Sanitize Sensitive Data
  • Remove or mask sensitive data in reports:
    • Personally identifiable information (PII)
    • Authentication credentials
    • Session tokens
    • Internal IP addresses and hostnames
    • Detailed internal architecture information
  • Use placeholders or redaction for sensitive data
3
Version Control and Tracking
  • Include version information in reports
  • Maintain an audit trail of report distribution
  • Track remediation progress against findings
  • Update reports as vulnerabilities are fixed
  • Archive reports securely for compliance purposes

Next Steps

Now that you understand OWASP ZAP's reporting capabilities, explore these topics: