Comparable Tools

## The shape of the problem A pipeline needs three things from a security tool: it must start without a human, it must be drivable from whatever language the pipeline is written in, and it must not need anything the runner cannot give it. This project is a good fit for all three, and the reason is structural rather than accidental — the automatable surface is where the project puts its effort, and you can see that by reading what it ships. ## The headless entry point `-daemon` is one of the small set of options core itself registers, rather than one an add-on adds. It runs the program headless and keeps it up with its control API available, which is what a build step needs: start it, drive it, collect the result, stop it. Nothing about that path is a reduced version of the program — it is the same build, with the same add-ons loaded. Core also registers `-silent`, and reads a `ZAP_SILENT` environment variable for the same purpose. It stops the program making any request nobody asked for, including its own check for updates. In a container with restricted egress that is the difference between a clean run and a log full of outbound failures. ## One surface, and clients generated from it Everything the program exposes to the outside world goes through a single control API, and the client libraries are **generated** from it rather than hand-written. The generators live in the core repository — one per target language, plus one that emits documentation — and the published client packages say so in their own header: *"This file was automatically generated."* The consequence is the part worth remembering: - An add-on declares an `apiClientGen` block in its build script, naming the class that implements its API component. - That component is then emitted into the generated clients like any core component. - So the published Python client carries a module per component, **including add-on components** — `automation`, `openapi`, `reports`, `accessControl` and others each get one. - Each generated method for an optional component even carries the caveat in its own docstring: the API will only work if that add-on is installed. Nobody hand-writes a binding, and nobody has to wait for a maintainer to catch up. That is a different maintenance model from a tool whose automation surface is a separate product built on top of an interactive one. | what a pipeline needs | what the project provides | where it comes from | |---|---|---| | start with no human | `-daemon` | a core command-line option | | no surprise network calls | `-silent`, or `ZAP_SILENT` | a core command-line option | | drive it from your language | generated client libraries | generators in the core repository | | reach an add-on's features | the add-on's own API component | `apiClientGen` in the add-on's build script | ## What generation costs you Generation is not free, and a senior answer says so: 1. **You inherit renames.** A signature that changes in an add-on's API changes in the next generated client. Pin the client you tested against and read the add-on's changelog before you move. 2. **Coverage follows the API, not the UI.** Generation emits exactly what a component declares and nothing else, so an operation that was never given an API action reaches no client in any language. The access-control add-on is the instructive case: it has a component and a generated client module, and still has no action that writes the rules its scan depends on. 3. **The client is a wrapper, not a contract.** The generated method exists whether or not the add-on behind it is installed; the failure shows up at call time, which is why those docstrings carry the warning. ## Reading the fit honestly The useful comparison sentence is about **centre of gravity**. A tool whose unattended path is generated from the same surface a person drives will tend to keep the two in step; a tool whose automation is a separate integration will tend to lag behind its own interactive features. Neither is better in the abstract. But if the job in front of you is a nightly run in a pipeline that nobody watches, the first shape is the one that costs you less over a year — and that, rather than the price tag, is the argument to make. Be careful not to overstate it. Headless operation does not mean the program needs nothing: a crawl that drives a real browser needs a browser present, and the machinery you drive over the API still has to be installed. What the project gives you is that **the automated path is not a second-class path** — it is the path its own tooling is built around.