mzap

mzap は、マルチターゲット ZAP スキャンのための Crystal CLI です。ターゲットを1つ以上のZAP APIホストに分散し、オプションの待機モードをサポートし、レポートをエクスポートできます。

機能

スキャンコマンド: spider, ajaxspider, clientspider (ZAP 2.16+), ascan, pscan
API 定義のインポート: openapi、soap、graphql、postman
ZAP 2.16+ の差分/増分スキャンのための Sites Tree export/prune
スキャンポリシーの検出 (policies)
ラウンドロビンスケジューリングによるマルチホストディスパッチ
タイムアウトサポート付きのオプションの待機/ポーリングモード
フォールバック動作付きのレポートエクスポート (html/pdf/json/md/sarif)
CI 終了コードのための --fail-on リスクゲート
spider、ajaxspider、clientspider、ascan、または all の停止コマンド
$HOME/.config/mzap/config.toml およびレガシーパスからのオプションの設定読み込み

必要条件

Crystal >= 1.19.1
実行中の ZAP API エンドポイント（または複数のエンドポイント）

インストール

Homebrew

brew install hahwul/mzap/mzap

ソースからビルド

shards install --frozen
crystal build --release src/mzap_cli.cr -o bin/mzap

ビルドせずに実行

crystal run src/mzap_cli.cr -- version

Docker イメージ

docker build -t mzap .
docker run --rm -v "$PWD:/work" mzap spider --urls /work/samples/target.txt --apis http://host.docker.internal:8090

使い方

Usage:
  mzap [command]

Subcommands:
  ajaxspider    Start Ajax Spider scans in ZAP
  ascan         Start Active Scan jobs in ZAP
  clientspider  Start Client Spider scans in ZAP (ZAP 2.16+)
  help          Show help for a command
  import        Import API definitions (openapi/soap/graphql/postman)
  policies      List active-scan policies in ZAP
  pscan         Wait for Passive Scan completion in ZAP
  sitestree     Export or prune the ZAP Sites Tree (ZAP 2.16+)
  spider        Start Spider scans in ZAP
  stop          Stop running scans
  version       Show mzap version

Flags:
  --apikey string        ZAP API key (omit when API key auth is disabled)
  --apis string          Comma-separated ZAP API host URLs
                         e.g. --apis http://localhost:8090,http://192.168.0.4:8090 (default "http://localhost:8090")
  --config string        Config file path (TOML supported; default: $HOME/.config/mzap/config.toml)
  --context string       ZAP context file to import before scanning
  --fail-on string       Fail with exit code 1 if alerts at or above risk level
  --format string        API definition format for import (openapi/soap/graphql/postman)
  --target-url string    Target/endpoint URL override for import
  --policy string        Scan policy name for active scan
  --report-format        Report format after scan completion (html/pdf/json/md/sarif)
  --report-out           Report output path (default: mzap-report-<timestamp>.<ext>)
  --concurrency          Number of parallel scan dispatches (default 1)
  --wait                 Wait for initiated scans to complete
  --wait-interval        Poll interval in seconds while waiting (default 2)
  --wait-timeout         Wait timeout in seconds (default 0: no timeout)
  -h, --help             Show help for mzap
  --urls string          Path to URL list file (e.g. --urls hosts.txt)

コマンド固有のフラグは mzap help <command> を実行してください。

使用例

# spider scan with two ZAP API hosts
mzap spider --urls samples/target.txt --apis http://localhost:8090,http://192.168.0.4:8090

# run scan, wait for completion, and generate an HTML report
mzap spider --urls samples/target.txt --apis http://localhost:8090 --wait --report-format html --report-out reports/mzap.html

# Client Spider (browser-based crawler, ZAP 2.16+; needs the Client Side Integration add-on)
mzap clientspider --urls samples/target.txt --apis http://localhost:8090 --wait

# import an OpenAPI definition, wait for passive scan, gate CI on high-risk alerts
mzap import --format openapi --urls samples/specs.txt --target-url https://api.example.com \
  --apis http://localhost:8090 --wait --report-format sarif --fail-on high

# import API specs from stdin
echo https://api.example.com/openapi.json | mzap import --format openapi --urls -

# discover available scan policies (then use one with `ascan --policy`)
mzap policies --apis http://localhost:8090

# Sites Tree baseline for differential scanning (path resolved by the ZAP daemon)
mzap sitestree export baseline.tree --apis http://localhost:8090
mzap sitestree prune baseline.tree --apis http://localhost:8090

# stop all running scan types
mzap stop all --apis http://localhost:8090

APIのインポート: mzap import は ZAP の Sites Tree をシードし、パッシブスキャンを実行させます。その後、インポートしたエンドポイントをアクティブスキャンするには、同じターゲットに対して mzap ascan を実行してください。ローカルファイルの場合、--urls（および --target-url）のパスは ZAP デーモンによって解決されるため、ZAP が Docker で実行されている場合はコンテナにマウントしてください。

設定

mzap は設定ファイルが存在する場合、自動的に読み込みます。優先順位は次のとおりです:

明示的な --config パス（存在する場合）
$HOME/.config/mzap/config.toml
$HOME/.config/mzap/config + 拡張子のバリエーション
$HOME/.mzap + 拡張子のバリエーション

CLI フラグは常に設定値を上書きします。

[mzap]
apis = ["http://localhost:8090", "http://192.168.0.4:8090"]
apikey = "your-zap-api-key"
urls = "samples/target.txt"
wait = true
wait_interval = 2
wait_timeout = 0
report_format = "html"
report_out = "reports/mzap.html"

GitHub Action

このリポジトリには Docker ベースの GitHub Action (action.yml) が含まれています。

- name: Run mzap
  uses: hahwul/mzap@<tag>
  with:
    arguments: "spider --urls samples/target.txt --apis http://localhost:8090"

開発

# tests
crystal spec

# release build
crystal build --release src/mzap_cli.cr -o bin/mzap

mzap v2.2.1

カテゴリ