Migrate ZAP integration to the Client Spider via the official ZAP Docker image

Background

ZAP has moved on from the AJAX Spider, and our integration is two generations behind.

ZAP 2.16.0 introduced the Client Spider, part of the Client Side Integration add-on and driven by the ZAP Browser Extension. Unlike the AJAX Spider it builds a Client Map with direct DOM access, so it reaches links and controls the AJAX Spider cannot see.

As of 2026-07-06 ZAP officially recommends it for crawling modern web applications. On the Crawlground and Google Crawl Maze benchmarks it scores higher on both, finds more unique endpoints with fewer redundant page revisits, and its workload scales linearly where the AJAX Spider "degrades rapidly as the target grows". The AJAX Spider is not being removed, but is no longer recommended.

This matters directly for our targets: the app in this engagement was a Hotwire/Turbo Rails SPA, exactly the DOM-driven case the Client Spider was built for.

Why we can't just add a flag

Our integration calls zap-cli quick-scan --spider --ajax-spider. zap-cli is discontinued (0.12.2, ~5 years old) and predates 2.16 entirely — it has no concept of the Client Spider. The wrapper is the blocker, not the flag.

Invocation also moved: Automation Framework job spiderClient (replaces spiderAjax), API under /clientSpider/, and in the packaged scans -j --client-spider.

Proposal

Replace the Kali-hosted zap-cli path with the official ZAP image, which also fits agent-smith's Docker-per-tool architecture better than installing ZAP into Kali:

docker run -t ghcr.io/zaproxy/zaproxy:stable \
  zap-full-scan.py -t <url> -j --client-spider -m <minutes> -J out.json

• -j — use the modern spider in addition to the traditional one
• --client-spider — select the Client Spider instead of the AJAX Spider
• -J — JSON report, parseable into the coverage matrix

Why the official image specifically: the Client Spider requires a real browser with the ZAP Browser Extension injected. The image ships that; an apt/pip install into Kali will not give it to us cleanly. Removing zaproxy + zapcli from tools/kali/Dockerfile:151,158 also slims the Kali build.

Follow-ons

• Auth. The Client Spider supports all of ZAP's authentication options, but our cookie-based SSO flows need a context/auth config passed in — the current bare quick-scan has no auth wiring at all, which is a second reason the existing path was never going to produce much on an authenticated target.
• Endpoint registration. Feed the JSON report into the coverage matrix with a provenance of zap-client-spider, and only register paths ZAP confirms exist.
• Docs. Update CLAUDE.md and the /pentester skill spider mode table once the mode semantics change.

Sources

• https://www.zaproxy.org/blog/2025-01-31-client-spider/
• https://www.zaproxy.org/blog/2026-07-06-client-spider-now-recommended/
• https://www.zaproxy.org/docs/desktop/addons/client-side-integration/spider/
• https://www.zaproxy.org/docs/docker/full-scan/
• https://github.com/Grunny/zap-cli

Start with the current zap-cli quick-scan integration and tools/kali/Dockerfile lines 151 and 158. Compare its report handling with the official ZAP Docker full-scan invocation and identify how the JSON output enters the coverage matrix. Done means the Client Spider runs through the official image, its confirmed endpoints are registered with zap-client-spider provenance, and CLAUDE.md plus the /pentester skill spider mode table are updated.