mzap

mzap 是一个用于多目标 ZAP 扫描的 Crystal CLI 工具。它将目标分发到一个或多个 ZAP API 主机，支持可选的等待模式，并可以导出报告。

功能

扫描命令：spider、ajaxspider、clientspider（ZAP 2.16+）、ascan、pscan
支持 openapi、soap、graphql 和 postman 的 API 定义导入
ZAP 2.16+ 的 Sites Tree export/prune，用于差异/增量扫描
扫描策略发现（policies）
多主机轮询调度分发
可选的等待/轮询模式，支持超时
报告导出（html/pdf/json/md/sarif），带有后备行为
--fail-on 风险门控，用于 CI 退出码
停止命令：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    在 ZAP 中启动 Ajax Spider 扫描
  ascan         在 ZAP 中启动主动扫描任务
  clientspider  在 ZAP 中启动客户端爬虫扫描（ZAP 2.16+）
  help          显示命令的帮助信息
  import        导入 API 定义（openapi/soap/graphql/postman）
  policies      列出 ZAP 中的主动扫描策略
  pscan         等待 ZAP 中的被动扫描完成
  sitestree     导出或修剪 ZAP 站点树（ZAP 2.16+）
  spider        在 ZAP 中启动爬虫扫描
  stop          停止正在运行的扫描
  version       显示 mzap 版本

Flags:
  --apikey string        ZAP API 密钥（禁用 API 密钥认证时可省略）
  --apis string          逗号分隔的 ZAP API 主机 URL
                         例如 --apis http://localhost:8090,http://192.168.0.4:8090（默认 "http://localhost:8090"）
  --config string        配置文件路径（支持 TOML；默认：$HOME/.config/mzap/config.toml）
  --context string       ZAP 上下文文件，扫描前导入
  --fail-on string       如果警报达到或超过指定风险级别则以退出码 1 失败
  --format string        导入的 API 定义格式（openapi/soap/graphql/postman）
  --target-url string    导入的目标/端点 URL 覆盖
  --policy string        主动扫描的扫描策略名称
  --report-format        扫描完成后的报告格式（html/pdf/json/md/sarif）
  --report-out           报告输出路径（默认：mzap-report-<timestamp>.<ext>）
  --concurrency          并发扫描分发的数量（默认 1）
  --wait                 等待启动的扫描完成
  --wait-interval        等待时的轮询间隔（秒，默认 2）
  --wait-timeout         等待超时时间（秒，默认 0：无超时）
  -h, --help             显示 mzap 的帮助信息
  --urls string          URL 列表文件路径（例如 --urls hosts.txt）

运行 mzap help <command> 查看特定命令的标志。

示例

# 使用两个 ZAP API 主机进行 spider 扫描
mzap spider --urls samples/target.txt --apis http://localhost:8090,http://192.168.0.4:8090

# 运行扫描，等待完成，并生成 HTML 报告
mzap spider --urls samples/target.txt --apis http://localhost:8090 --wait --report-format html --report-out reports/mzap.html

# Client Spider（基于浏览器的爬虫，ZAP 2.16+；需要 Client Side Integration 插件）
mzap clientspider --urls samples/target.txt --apis http://localhost:8090 --wait

# 导入 OpenAPI 定义，等待被动扫描，以高严重性警报为 CI 门控
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

# 从标准输入导入 API 规范
echo https://api.example.com/openapi.json | mzap import --format openapi --urls -

# 发现可用的扫描策略（然后使用 `ascan --policy` 使用其中一个）
mzap policies --apis http://localhost:8090

# 站点树基线，用于差异扫描（路径由 ZAP 守护进程解析）
mzap sitestree export baseline.tree --apis http://localhost:8090
mzap sitestree prune baseline.tree --apis http://localhost:8090

# 停止所有正在运行的扫描类型
mzap stop all --apis http://localhost:8090

导入 API： mzap import 会填充 ZAP 的站点树并让被动扫描运行；要在之后主动扫描导入的端点，请对同一目标运行 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"

开发

# 测试
crystal spec

# 发布构建
crystal build --release src/mzap_cli.cr -o bin/mzap

mzap v2.2.1

分类