npm package: @mockholm/zap-cli-tool
Description: A CLI for configuring ZAP authentication, running scans, and generating reports.
Author: mockholm
Latest version: 1.0.1

# ⚡ 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

Install package:

npm
```bash
npm i -g @mockholm/zap-cli-tool
```

pmpm
```bash
pnpm add -g @mockholm/zap-cli-tool
```

yarn:
```bash
yarn global add @mockholm/zap-cli-tool
```

Docker zap daemon:
Zap running as daemon
```bash
docker run -d \
  --network zap-net \
  --name zap-daemon \
  -e ZAP_API_KEY=mysecretkey \
  -p 8080:8080 \
  -v $ZAP_HOME:/home/zap/.ZAP \
  -v "$ZAP_HOME/work":/home/zap/wrk \
  -v "$(pwd)/config":/zap/cfd:rw \
  -v "$(pwd)/config/scripts":/zap/scripts:rw \
  mockholm/zap-daemon:latest
```

Run via Node:

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

Or add an npm script shortcut:

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

Then call:

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

---

## 🔐 `auth` — Configure Authentication

Configures a context-specific authentication scheme using ZAP.

```bash
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.

```bash
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.

```bash
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

---