⚡ ZAP CLI Tool — Usage Guide

A command-line utility built in TypeScript to control OWASP ZAP for authentication, scanning, and report generation. Powered by yargs and fully customizable with CLI flags.

📦 Installation & Setup

Run via Node:

ts-node bin/index.ts <command> [options]

Or add an npm script shortcut:

"scripts": {
  "zap": "ts-node bin/index.ts"
}

Then call:

npm run zap -- scan --target https://your.site --contextName MyCtx --apiKey 12345

🔐 auth — Configure Authentication

Configures a context-specific authentication scheme using ZAP.

zap-tool auth --mode basic --target <URL> --context <CTX> --apiKey <KEY> [options]

Available Flags

| Flag | Type | Required | Description | |------------------|----------|----------|--------------------------------------------------------------------------------| | --mode | string | ✅ | Auth type: basic, session, jwt, header, cert | | --target | string | ✅ | Target URL for authentication | | --context | string | ✅ | Name of the ZAP context | | --apiKey | string | ✅ | ZAP API key for authorized interaction | | --zapHost | string | ❌ | Host of ZAP proxy (default: localhost) | | --zapPort | number | ❌ | Port of ZAP proxy (default: 8080) | | --username | string | ❌ | Username for BASIC or SESSION auth | | --password | string | ❌ | Password for BASIC or SESSION auth | | --jwt | string | ❌ | JWT token for Bearer auth via scripting | | --headerName | string | ❌ | Header name for header-based authentication | | --headerValue | string | ❌ | Header value to inject | | --certPath | string | ❌ | Path to client certificate file | | --certPassword | string | ❌ | Password for client certificate | | --verbose | boolean | ❌ | Enables logging for verbose output |

🕸️ scan — Run Spider + Active Scan

Starts a spider (AJAX optional) followed by active scan using context and user identity.

zap-tool scan --target <URL> --contextName <CTX> --apiKey <KEY> [options]

Available Flags

| Flag | Type | Required | Description | |------------------|----------|----------|-----------------------------------------------------------------------| | --target | string | ✅ | Target URL to scan | | --contextName | string | ✅ | ZAP context name | | --apiKey | string | ✅ | ZAP API key | | --zapHost | string | ❌ | Host of ZAP proxy (default: localhost) | | --zapPort | number | ❌ | Port of ZAP proxy (default: 8080) | | --userName | string | ❌ | ZAP internal user name to scan as | | --useUser | boolean | ❌ | Whether to scan as a specific user (default: false) | | --ajax | boolean | ❌ | Use AJAX spider (default: false) | | --minRisk | string | ❌ | Minimum risk to include in alerts: Low, Medium, High, Informational | | --confidence | string | ❌ | Minimum confidence level: Low, Medium, High, Confirmed | | --outputJson | string | ❌ | Save scan results to file as JSON | | --verbose | boolean | ❌ | Print verbose scan details |

📄 report — Generate Vulnerability Report

Generates a report in specified format using the ZAP context.

zap-tool report --contextName <CTX> --output ./report.html --apiKey <KEY> [options]

Available Flags

| Flag | Type | Required | Description | |------------------|----------|----------|-----------------------------------------------------------------------| | --contextName | string | ✅ | Name of ZAP context to report on | | --output | string | ✅ | Path to save output report | | --apiKey | string | ✅ | ZAP API key | | --zapHost | string | ❌ | Host of ZAP proxy (default: localhost) | | --zapPort | number | ❌ | Port of ZAP proxy (default: 8080) | | --format | string | ❌ | Report format. Options: html, pdf, jest, markdown, composite_json | | --threshold | string | ❌ | Filter alerts below this risk: Low, Medium, High | | --open | boolean | ❌ | Auto-open generated report in system viewer (HTML or PDF only) |

🧠 Notes

• All commands require --apiKey to communicate with ZAP proxy
• Contexts must be defined in ZAP prior to scanning or reporting
• You can inject host and port flags to target remote ZAP instances
• Verbose logging helps with debugging integration into CI/CD pipelines