A containerised ZAP mints a new root CA each run; which flag stops that, and what must the file hold?

## Why the authority changes ZAP does not ship a certificate authority; it makes one. The `network` add-on keeps the root in a key store held by its server-certificate options, which is to say in ZAP's home directory. On startup it looks for that key store, and: - if one is there, it uses it (and warns if the certificate has expired); - if there is none, it **generates a new root** — a fresh key pair and a self-signed certificate — and stores it. That is unremarkable on a workstation, where the home directory persists and the root is created once. It is the whole problem in a container, where the home directory is usually thrown away with the container. Each run starts with no key store, each run generates a new authority, and anything that was told to trust the previous one now sees a certificate from an authority it has never heard of. The symptom is a trust failure that appears intermittent but is actually perfectly regular: it happens on every run after the first. ## The fix, and the requirement its help text does not mention `-certload <path>` imports a root instead of generating one. It reads the file, extracts the certificate, extracts the private key, builds a key store from the two and installs it. The requirement hides in that sentence. The import needs **both** sections: | PEM section | needed by `-certload` | produced by `-certpubdump` | produced by `-certfulldump` | |---|---|---|---| | `-----BEGIN CERTIFICATE-----` | yes | yes | yes | | `-----BEGIN PRIVATE KEY-----` | yes | no | yes | Feed it a public dump and it fails with a message saying no private key section was found in the file, naming the tokens it expected. The option's shipped one-line help says only *"Loads the Root CA certificate from the specified file name"* — perfectly true, and quiet about the half that makes the difference. This is a small instance of a pattern worth expecting generally: **the artifact a reader copies from is often narrower than the code that consumes it**, and the gap only shows up at runtime. The requirement also explains the wording of the other two flags. `-certpubdump` calls itself suitable for importing into browsers; `-certfulldump` calls itself suitable for importing into ZAP. They are not two levels of detail — they are two destinations, and only one of them is a round trip. ## The pattern the project uses itself One of the project's own container entry scripts does exactly the load-or-create dance: if the private file already exists in the mounted working directory, it adds `-certload` pointing at it; otherwise it adds both dump flags, writing the public file for whatever must trust the proxy and the full file for the next run to load. That is the shape to copy: 1. Mount a directory that survives the container. 2. If the stored root is there, start ZAP with `-certload`. 3. If it is not, let ZAP generate one and export both halves — the public certificate for the clients that must trust it, the full export so the next run can load it. 4. Distribute only the public export. ## What this buys, and what it does not What it buys is **stability of identity**: the authority is the same from run to run, so whatever you configured to trust it stays configured. In a pipeline that means a device, an image, or a test client can be prepared once instead of on every execution, and a trust error becomes a real signal again instead of background noise. What it does not buy is anything about the *strength* of the arrangement. A stored root is a stored private key, and the file that makes the round trip possible is precisely the file that can sign for the authority. Keeping it around is a deliberate trade — you are choosing a durable identity, and a durable identity is a durable secret. Decide where that file lives, who can read it, and what happens to it when the pipeline is decommissioned, before you write the first `-certload`. ## Things that will bite you anyway - **A readable path is not a writable one.** The export flags check that the destination is writable and report an error rather than failing silently; the load flag checks the source is readable. Both report through the command line, so a headless run shows the reason. - **The key is stored unencrypted in the exported file.** There is no passphrase to supply on load and none to set on export. - **Loading does not change what clients already trust.** Restoring the root fixes the mismatch going forward; anything that was told to trust an earlier generated root still holds that stale entry. - **An expired stored root is loaded, not replaced, in a headless run.** The add-on logs a warning about the expiry; only an interactive session offers to generate a fresh one. A long-lived stored root will eventually need deliberate replacement.