Repository navigation
Description
Status: working document on a personal fork. Not an upstream submission. This
is PR 2 of two; see #1 for the investigation this came out of, and #2 for the
companion chroot-retention change. Both are intended to go upstream under a single
Jira ticket describing the pair.
Explain it like I'm 5
Imagine you're about to let someone make changes to your computer, and you ask a
careful friend to go check what those changes would actually do. Your friend comes
back and hands you a note:
I'd change three files in your settings folder, and install one new program
called caddy.
Perfect. For a human being, that note is exactly right.
Now imagine you want a robot to check the note instead of you — because the note
might be four hundred lines long, because you're tired, because you're going to
read a note like this every week for years and eventually you'll skim one. The
robot's job is to confirm that nothing got quietly added that you didn't agree to.
But the robot has to read your friend's handwriting. And your friend writes it a
little differently every time — sometimes "I'd change", sometimes "changes to",
sometimes a helpful extra sentence. One day your friend rephrases something, the
robot misreads the note, and it waves through a change nobody approved. The robot
was never given anything solid to hold onto.
This change asks CFEngine to also hand over the same information as a filled-in
form with labeled boxes — path here, kind-of-change there, package name in this
box — instead of only as a paragraph. Same facts, same friend, same trip. One is
prose written for a person; the other is a form written for a program.
Why anyone would want that: the moment a program can read the answer reliably,
you can build things on top of it. Show a person a clean summary of exactly what
would change. Refuse to proceed if anything appears that wasn't in what they
approved. Keep a signed record of what was agreed to. Have CI fail when a change
touches something it shouldn't. None of that is safe to build on text that was
written to be read by a human and can be reworded at any time.
What is wanted
A machine-readable rendering of the change set --simulate already computes:
changed files, renames, and package operations, as JSON.
Proposed surface, to be confirmed with maintainers first:
--simulate-output=json, orthogonal to the existing
--simulate=<manifest|manifest-full|diff> mode selector.
Why today's output can't be parsed instead
cf-agent/simulate_mode.c renders with printf() throughout — '%s' is a %s,
'%s' no longer exists, Package '%s-%s [%s]' would be %s — and for
--simulate=diff it shells out to diff -u (RunDiff(), simulate_mode.c:360)
and passes the result through.
Parsing that back into structure is possible and unwise: it is a stat(1)-shaped
text format with no stability contract, and any consumer doing it is one wording
change away from silently misreading a security-relevant artifact. Note that
tests/acceptance/29_simulate_mode/ already carries a
normalize_agent_output.cf.sub — the project's own tests need output
normalisation to be comparable at all, which is itself an argument for structured
output.
Why this is cheaper than it looks, as of 17eb78e
- The data already exists and is already structured. Four record files are
written during a simulate run (libpromises/changes_chroot.h:28-31). Package
operations are already a four-field CSV row with an operation code from a
defined enum (ChrootPkgOperationCode,cf-agent/simulate_mode.h:38-43). - The renderer already runs before cleanup.
cf-agent.c:392-428dispatches on
EVAL_MODEand calls the manifest/diff renderers; only afterwards, at
cf-agent.c:435, doesCallCleanupFunctions()tear down the chroot. A JSON
renderer slots in beside the existing prose ones with all the same data live. - The serializer is already linked in.
libntech/libutils/json.hprovides
JsonObjectCreate(),JsonArrayCreate(),JsonObjectAppendString(),
JsonWrite(), and libntech is already a submodule — so this is a single-repo
change, avoiding the coordinated multi-repo PR thatCONTRIBUTING.md
otherwise requires.
The prose renderers stay untouched and remain the default.
What this does not get, and must not claim
- Files and packages only. Service activation is not simulated.
commands
promises are not executed — see the still-open
CFE-3548. - No runtime confinement. Simulate mode computes a would-be change set; it is
not a capability sandbox and nothing here makes it one. --simulate=manifestis stat(1) prose.ManifestStatInfo()prints
size/mode/uid/gid/atime/mtime/ctime. Structuring that is straightforward but is
distinct work from structuring the change list.
Open questions — deliberately not answered on paper
These get decided against a running prototype, not by reasoning. An earlier note
in this project reasoned about simulate mode from source alone and got the chroot
lifetime wrong; the correction only came from running cf-agent.
- Destination. stdout, interleaved with
Log()output? A separate
--simulate-output-file=PATH? Anything on stdout must survive log interleaving
to be parseable. - Schema. What does a changed-file entry contain — path, change kind, old and
new stat, content hashes, the unified diff as a string, or a structured hunk
list? The security-relevant question downstream is whether content is committed
to by digest. - Diff representation. Keep the
diff -ushell-out and embed its text, or
restructure? Embedding is far cheaper and probably the right first cut. - Stability contract. Supported interface with a version field, or explicitly
unstable? Maintainers will care about this more than about the shape.
Definition of done
- Surface agreed with maintainers before implementation
- JSON renderer beside the existing prose renderers; prose unchanged and still
the default - Unit tests for the new C functions
- Acceptance tests in the style of
tests/acceptance/29_simulate_mode/ - Built and run for real against a policy with file and package promises
-
clang-formatclean; matches the local idiom ofsimulate_mode.c -
Changelog:andTicket:trailers in the commit message
Activity
djbclark commentedon Aug 15, 2026
Finding:
--simulate=diffdepends on adiffbinary in CFEngine's own bindirFound by running the built agent, not by reading source. On a real run, diff mode failed:
The cause is
RunDiff()atcf-agent/simulate_mode.c:363-364:It resolves
difffromGetBinDir(), not$PATH— CFEngine's own bin directory. Neither amake installtree nor the Homebrewcfenginepackage puts adiffthere, so--simulate=difffails out of the box on macOS while--simulate=manifestworks fine. (Whether the Linux packages ship one is unverified and worth checking before saying anything upstream — the finding is about the lookup path, not about any particular package being broken.)Why this matters for this ticket, in both directions:
diffimplementation emits — flags, labels, and all. That is a second stability problem layered on the first.diff -utext vs. restructure). Embedding is still the cheap first cut, but embedding means the JSON inherits the external dependency and the failure mode above. A structured representation computed in-process would not. Worth putting to maintainers explicitly rather than deciding quietly.Also relevant: a JSON mode that reports changed files without needing
diffat all would make simulate genuinely useful on platforms where this currently silently degrades.djbclark commentedon Aug 17, 2026
Now tracked upstream in Jira as CFE-4716.
Jira became usable to us on 2026-08-17 — the Atlassian account alone wasn't enough, project-level permission was the missing piece. This fork issue stays as the working record; CFE-4716 is the upstream reference, and the two should be kept in step.
Going forward we file upstream items in the CFE Jira project rather than by email or GitHub Discussion.
djbclark commentedon Aug 22, 2026
Upstream disposition: closed
Filed as CFE-4716, now Rejected / Won't Do. Upstream PR cfengine/core#6294 closed 2026-08-19T10:45:41Z. Review volume, not the merits. One of the two features in the set of 26; the other 24 were resolved Done.
Ticket-only content worth keeping — the UTF-8 interaction, tested for real
Built a throwaway
core-p2worktree with its libntech submodule repointed at a merge offix/json-double-decode+fix/mustache-minor-defectson top of0c0620d(the codec fixes now tracked as djbclark/libntech#6 and #7), then rantests/unit/simulate_mode_testplus a standalone probe isolatingRestoreUtf8InJson()/GetJsonEscapedByte()/ValidUtf8SequenceLength()against the fixedJsonEncodeStringWriter(). Two different results:Valid multi-byte UTF-8 (e.g. U+00E9): confirmed safe. The fixed encoder emits one escape per code point instead of one
\u00XXper UTF-8 byte, soRestoreUtf8InJson()never collects the 2+ consecutive escapes it looks for and passes the text through unchanged — dead code for this case, not corruption.test_special_characters_in_path's failure under the fixed library is cosmetic: it asserts the old raw-byte output shape, and the parsed value itself is correct.Invalid non-UTF-8 bytes (e.g. a lone
0xE9filename byte): a real gap, but not the one the workaround guards against. A genuine U+00E9 code point and a lone invalid byte0xE9encode to the identical escape sequence;RestoreUtf8InJson()cannot tell them apart.test_invalid_utf8_in_pathonly ever passed because the old non-conformant parser and writer were exact inverses — the same "round-trips its own corruption" shape the codec issue itself describes — and cancelled out. Once the parser side is also conformant, the escape correctly decodes to the valid code point, which is not the original byte. A non-UTF-8-valid path byte cannot be represented exactly in a JSON string at all, conformant or not. Pre-existing representational gap the old test accidentally papered over, not a new defect.This needs a real design decision — replacement character, error out, or a separate raw/base64 field for the rare non-UTF-8 path — before
test_invalid_utf8_in_pathcan be fixed for real, whenever the codec fix lands here and this branch is rebased onto it. Carried into the consolidated questions issue.djbclark commentedon Aug 22, 2026
Open decision from this item is tracked in the consolidated list: #23
djbclark commentedon Sep 30, 2026
2026-09-30: upstream said yes; the split is ready on the fork.
On cfengine#6332 (2026-09-23), larsewi wrote: "Feel free to open a PR. It would help if you split the work in logical parts." The rebased and trimmed version is fork PR #27, branch
simulate-json-v2, with two commits:09d8d9f1fShared the reduction of recorded package operations (a refactor with no output change)4c4919edeAdded--simulate-jsonoption to write the simulated change set as JSONChanges from the 08-15 version:
permissions. Symlink modes are meaningless: always 0777 on Linux, 0700 here on macOS. The Linux gate caught this.simulate-json-utf8(b9a02866e), because it works around libntech'sJsonWrite()escaping and belongs there.Results:
simulate_json.cfpasses on macOS and in an Ubuntu 24.04 arm64 container.Open questions:
Ticket:trailer? CFE-4716 is Rejected/Won't Do.djbclark commentedon Sep 30, 2026
Independent review of #27: no blockers. Fixes are folded into commit 2, which is now
4c7d20e1a. The UTF-8 commit on top of it is now313e9b7ff.Verified by the reviewer:
leaksfound 0 leaks across the error paths: corrupt, truncated or empty records, an output path that is a directory, an unreadable file.O_EXCL+rename()security design holds up.Fixed:
<FILE>.new, which was deleted before writing, so an existing file of that name was silently removed. It is now<FILE>.<6 digits>.cfnewwithO_EXCL, the same idiom asoverride_fsattrs.c, and nothing is deleted first.main()repeated whatWriteChangesJson()had already logged on every failure path.%04o, matching the rest of the file.unlink()block in the tree.cfengine formaton the acceptance test. Fork CI'sformat --checkhad failed on it, which skipped every workflow that depends on the lint job.Left as they are, with reasons:
JsonWrite()escapes each byte separately.simulate-json-utf8fixes it; whether it goes upstream is an operator decision.Tests: unit 2/2, 11/11 and 13/13 at each commit, and the acceptance test passes, on macOS and in the Ubuntu 24.04 container.
djbclark commentedon Sep 30, 2026
Decision (operator, 2026-09-30): the upstream PR carries commits 1 and 2 only, with no Jira ticket.
Non-ASCII path handling will be offered upstream as a libntech encoder fix, not as a core workaround. The fix writes valid UTF-8 as-is and keeps escaping invalid bytes. It changes only the encoder, so CFEngine still reads its own output identically and no migration is needed. It is djbclark/libntech#9 (
1a3b12fef, +77/−1 C plus a test). Results:make check: 39/39 programs pass.The fork-only core workaround stays on
simulate-json-utf8.The ELI5 for the logic is in #27's description. A pre-existing relative-symlink target bug found while writing it is filed as #28.
djbclark commentedon Sep 30, 2026
Upstream plan: three PRs (decided 2026-09-30)
On cfengine#6332, larsewi invited the PR "split in logical parts". After two independent reviews (Claude, plus a Fable workflow with adversarial verification) and a size analysis, the operator chose to send it as a sequence of small PRs. Tests may run a bit longer, since they carry the correctness case. This comment is the tracker and is edited as work lands.
PR 0: two simulate mode package reporting fixes (pre-existing bugs), fork PR #39
dba2a1032: version and architecture were written swapped; regression test fails without the fix98006a443(Pre-existing: --simulate=diff never reports a versioned removal with no prior install record #38):--simulate=diffomitted a removal with a version unless it cancelled a recorded install; regression test fails without the fixgit merge-tree)PR 1:
--simulate-jsonfor files and renames, fork PR #40 (d5cc2c4e0, +716)IsAbsoluteFileName(); the deadoptarg == NULLbranch removedReadChrootRecords()readerfailsafe_fallback(hard class only);simulate_modefield droppedRAND_bytes()temp name,O_EXCL,rename()); write, close and rename failures each reported accurately--simulate-jsonPR 2: packages in the JSON, fork PR #41 (stacked on PR 1; full CI via #42)
16a6b6567:PkgOperationRecordstores fields and both modes format at print time, with one shared print helper. Output identical over 12,314 generated logs.c1bf747ea; again identical output over 12,314 logs)packagesarray29fce4663, sorted by name then architecture; unit tests 15/15Then
Fork-only:
simulate-json-utf8rebased onto PR 1 (1b0fb89db, 13/13). Deferred items are in #28–#38 and #43. #27 is closed as superseded.