Where must the alertFilter job sit in a ZAP automation plan, and why does its position matter?

## The mechanism that forces the ordering The `alertFilters` add-on does not inspect findings at the end of a run. It registers as a consumer of ZAP's alert-added event. Each time a scan rule writes an alert, the add-on reads the new record back, walks its global filters and then the filters of any context containing the alert's URL, and rewrites the record on the first match. The shipped help states the consequence plainly: filters apply to new alerts. So the question "where does the job go" is really "was the filter registered before the alert existed". The `alertFilter` job itself is short, and everything it does is registration: - It optionally clears the global collection, if `deleteGlobalAlerts` is set. - It converts each entry in the plan into a filter object, rejecting any whose rule id is blank or negative, whose risk name is not one of the accepted five, or whose enabled pattern will not compile. - It adds each surviving filter to the global collection, or to the collection of the context the entry names. - It logs each filter it added, with the rule id and the new risk. - It does **not** walk the alert table afterwards, and nothing else in the plan does it on the job's behalf. ## Plans run in file order A plan read from YAML builds its job list by appending each entry as it is parsed, and the runner iterates that list. There is no sorting step. This is worth stating carefully, because the job class does declare an order — the same one the configuration jobs use. That declaration governs where ZAP's desktop dialogs insert a job you add through the interface, and how the job list is sorted for display. It does **not** reorder a plan you wrote by hand or generated from a script. | | what it controls | what it does not control | |---|---|---| | the job's declared order | where the desktop's add-job dialog inserts it | the execution order of a loaded plan | | the order of entries in the YAML | the execution order of a loaded plan | anything in the desktop dialogs | The practical reading: a plan with `alertFilter` in the wrong place is a valid plan, it loads without a warning, the job runs, it logs the filters it added — and nothing raised before it is ever rewritten. ## The corroboration When ZAP's own packaged scan script generates a plan for you rather than driving the daemon directly, it emits the `alertFilter` job straight after the passive-scan configuration job and ahead of every crawl job. Being above the crawl is not a style choice — it is what makes the filters apply at all. ## Where to put it, concretely 1. After the environment block and after whichever configuration jobs set up scanning. 2. Before any crawl job, because a crawl produces traffic and passive rules raise alerts on that traffic. 3. Before any active-scan job, for the same reason. 4. Before the job that waits for passive scanning to drain, since alerts are still being raised while it waits. 5. Anywhere above the job that decides the run's outcome, which is a consequence of the four above rather than a separate rule. ## The escape hatch, and why it is not one here The add-on's control-API surface does offer actions that walk the alerts already recorded and apply the filters retrospectively, plus matching actions that only count what would match without changing anything. Those exist for the desktop and for scripted use. **No automation job calls them.** In an unattended plan there is no retrospective pass available, which is exactly why position is the whole of the control. ## How this fails in practice The symptom is a pipeline that keeps failing on a finding somebody is certain they filtered. The plan is right, the filter is right, the rule id is right — and the job is sitting below the scan jobs because it was added last, which is where an editor naturally puts a new block. Check the order of the jobs before you start debugging the matching clauses.