mzap

mzap는 다중 타겟 ZAP 스캐닝을 위한 Crystal CLI입니다. 하나 이상의 ZAP API 호스트에 타겟을 분배하며, 선택적 대기 모드를 지원하고 보고서를 내보낼 수 있습니다.

기능

스캔 명령어: spider, ajaxspider, clientspider (ZAP 2.16+), ascan, pscan
openapi, soap, graphql, postman에 대한 API 정의 가져오기
ZAP 2.16+ 차등/증분 스캔을 위한 사이트 트리 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>를 실행하세요.

예제

# 두 개의 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

# stdin에서 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

카테고리