Retain the --simulate changes chroot after a run (--simulate-keep-chroot)

[djbclark]

When CFEngine runs in --simulate mode, it doesn't touch your real files — instead it builds a scratch copy of "what the system would look like after this run" in a hidden temp folder, uses that copy to write a plain-English summary, then deletes the whole thing. Nobody ever gets to actually look at the copy itself. This adds a --simulate-keep-chroot=PATH flag that says: don't delete it, put it at PATH so I can go look.

Why that's interesting: once it's just a folder on disk, you can point any ordinary tool at it instead of parsing prose:

• diff -r it against the real system to get an exact, scriptable changeset instead of a human-readable summary.
• Feed it to a security scanner, linter, or compliance checker before the real run ever happens — a true dry-run gate in CI.
• Compare two retained runs against each other (e.g. before/after a policy edit) to see exactly how the predicted end-state shifted.
• Hand it to a human reviewer as a literal preview they can cd into and browse, no report-reading required.

---

The changes chroot created by a --simulate run is always deleted by a cleanup handler on exit, so the files as they would be after the run can never be inspected by a user or consumed by another program.

Proposal: a new --simulate-keep-chroot=PATH option. cf-agent creates the changes chroot at PATH instead of the state directory and keeps it after the run. PATH must be absolute and must not already exist; it's created with mode 0700 so permission-mirrored copies of potentially sensitive system files can't land somewhere looser or mix with a previous run. Requiring an explicit destination also means no PID-named trees pile up in the state directory unannounced, and a calling program knows where the retained tree is without parsing output. Retention is announced with a notice-level message at the end of the run. Default behavior (no option) is unchanged.

PR: #6293

[djbclark]

Now tracked in Jira as CFE-4715.

This discussion was opened because the CFE tracker wasn't reachable to us at the time. That's now resolved (the Atlassian account alone wasn't enough — I also needed permission in the project; thanks to @nickanderson).

One correction worth making here rather than leaving it standing: the proposal above says the directory "is created with mode 0700 so permission-mirrored copies of potentially sensitive system files can't land somewhere looser". Review of our own implementation showed that claim doesn't hold as written — mkdir(path, 0700) is umask-relative (under umask 0777 you get mode 0000), and it doesn't inspect the parent directory at all. CFE-4715 states the feature's guarantees accurately and lists the defects being corrected in #6293 before it should be merged.

Future feature proposals from us will go to Jira rather than new discussions.