Beyond issuing requests, what does a ZAP `openapi` job write into the history, Sites tree and context?

## Four places the import leaves a mark An import is usually described as "it fills the history". It does, but that is one of four side effects, and the other three change how the rest of the run behaves. | what changes | mechanism | why it matters | |---|---|---| | the history table | `HistoryPersister` creates a `HistoryReference` per message | this is what the passive engine drains | | the Sites tree | `getSiteTree().addPath(historyRef, message)` | this is what you can select and attack | | a statistic | an `openapi.urls.added` counter is incremented | gives you something to assert on | | the named context | `Context.addIncludeInContextRegex(...)` per imported path | the import edits your scope definition | ## The history type, and why it is not the spider's The persister picks its type from the initiator the requestor was built with: - driven from the import paths, the requestor is constructed with the **manual-request** initiator, so messages are recorded as `TYPE_ZAP_USER` — the type documented for messages a user sends by hand from a resend or manual-request dialogue; - only when the add-on is driven from the spider integration is the initiator the spider's, and only then are messages recorded as `TYPE_SPIDER`. This is worth getting right because it is easy to assume anything that populates the tree is "spider traffic". It is not, and a filter written on that assumption will hide the import's messages. It also matters that `TYPE_ZAP_USER` is one of the history types the passive rule base class treats as in scope by default, so imported messages **are** passively scanned — the type differs, the treatment does not. ## The context write, which nobody expects When the job names a context, the converter walks the imported operations and, for each path that the context does not already include and does not exclude, adds an include regex: - a path with no parameters is added quoted, so it matches literally; - a path such as `/pets/{petId}` is rewritten to `/pets/[^/?]+` and added as a regex. So after the job runs, the context you declared in `env.contexts` is not the context you wrote. That is usually what you want — the imported operations are now in scope for jobs that respect scope — but it means the plan's context block is a starting point, not a fixed definition, and two imports into the same context accumulate. ## The tree shape The add-on also registers a `Variant` whose only real job is `getTreePath`. Given a message, it matches the URL against the path templates it learned from the definition, and returns a tree path where the parameter segment is marked as a data-driven node. The practical effect: `/pets/1`, `/pets/2` and `/pets/9999` collapse into a single node in the Sites tree instead of one node per identifier. That is not cosmetic. It is the difference between an active scan attacking one node once and attacking one node per identifier it happens to have seen, and between a readable tree and an unusable one. It also only works for messages whose method and path actually match an imported operation, so traffic that arrived some other way is unaffected. ## What this means when you drive it from a plan Three habits follow: 1. **Assert the import worked.** A run where the import silently produced nothing still proceeds, and the later jobs quietly scan an empty tree. The statistic the import bumps is the cheapest evidence that it did something. 2. **Do not hand-maintain include regexes for imported paths.** The job will add them; writing them yourself as well only creates drift. 3. **Expect the history to look hand-sent.** When you are reading the record afterwards, the import's messages are typed as user-sent, and that is the correct reading — a person, via a plan, asked for exactly those requests. The job also reports what it did. The add-on collects the history references it created into a results object, and the job writes the count of URLs added into the plan's progress output, so the run log carries the number even when nothing tested it. The sibling definition jobs persist the same way with their own listeners, and the `soap` importer is the bluntest of them: it writes the user-sent type unconditionally, with no initiator test at all. If you are building a filter or a report that separates crawl traffic from import traffic, key it on the job that ran, not on the history type.