zap-clean-report

Generate clean, non-technical HTML security reports from OWASP ZAP JSON output.

Built for teams who need to share scan results with developers, managers, and stakeholders who are not security specialists. Findings are written in plain English, grouped by severity, and the output is a single HTML file you can email, attach or print.

Features

• Single HTML file: everything is inline except the web fonts, which fall back to system fonts when offline
• Editorial layout: dark header with an at-a-glance verdict, sticky section navigation, severity stat tiles
• Your own branding: logo, name, accent colour and footer text
• Plain English descriptions for common vulnerability types
• Findings grouped and filterable by risk level (High, Medium, Low, Informational)
• OWASP Top 10 category badges per finding
• CWE reference badges with clickable links
• Systemic finding detection
• Collapsible finding details with affected URL list
• Print-ready layout with all sections expanded automatically
• Auto-generated filename based on target hostname and UTC timestamp
• Zero runtime dependencies

Install

npm install -g zap-clean-report

Or run without installing:

npx zap-clean-report zap-output.json

Usage

zap-clean-report <input.json> [options]

Options

| Option | Description | |---|---| | --output, -o <file> | Output file path (overrides auto-generated name) | | --title <text> | Report title (default: Security Scan Report) | | --brand <text> | Name shown next to the logo in the header (default: zap-clean-report) | | --logo <file> | Logo image embedded in the header: .svg, .png, .jpg or .webp | | --accent <hex> | Accent colour used for highlights, e.g. "#6A3E87" (default: #20B2AA) | | --footer <text> | Footer text (default: Generated by zap-clean-report) | | --help, -h | Show help |

Examples

# Basic usage - auto-generates filename
zap-clean-report zap-output.json

# Custom output path
zap-clean-report zap-output.json --output report.html

# Custom title (appears in the report header)
zap-clean-report zap-output.json --title "My App - Sprint 22"

# Your own branding
zap-clean-report zap-output.json --brand "Acme" --logo acme.svg --accent "#6A3E87" --footer "Acme, Confidential"

Auto-generated filename format

<hostname>-<UTC timestamp>-security-report.html

Example: app.example.com-20260504164752-security-report.html

Programmatic usage

const { generateReport } = require('zap-clean-report');
const fs = require('fs');

const raw = JSON.parse(fs.readFileSync('zap-output.json', 'utf8'));
const html = generateReport(raw, {
  title: 'My App - Security Scan',
  // Optional. logo is an image URL or data URI; accent must be a hex colour.
  brand: { name: 'Acme', logo: 'data:image/svg+xml;base64,...', accent: '#6A3E87', footer: 'Acme, Confidential' },
});
fs.writeFileSync('report.html', html);

Input format

Accepts the standard JSON export from OWASP ZAP. To generate it:

1. Run your ZAP scan
2. Go to Report > Generate Report and select JSON format, or use the ZAP CLI with --format json

Sample JSON files for testing are available in the examples/ folder.

Requirements

Node.js 16 or later.

License

MIT