Skip to content

Added --simulate-json option to write the simulated change set as JSON - #40

Open
djbclark wants to merge 10 commits into
masterfrom
simulate-json-files
Open

djbclark wants to merge 10 commits into
masterfrom
simulate-json-files

Conversation

@djbclark

@djbclark djbclark commented Sep 30, 2026 •

Copy link
Copy Markdown
Owner

Fork-internal PR for CI; not an upstream submission. PR 1 of the plan on #3: --simulate-json for files and renames. Packages follow in PR 2 (#41).

Checked on macOS: unit tests 14/14, and simulate_json.cf passes in the 29_simulate_mode acceptance directory (the three pre-existing prose tests fail there for environmental reasons: non-root uid and no diff in bindir). On Ubuntu 24.04 as root the whole directory passes, 5/5, with 75/75 unit tests. Reviewed by Claude and by a Fable workflow with adversarial verification, then a final review, with every finding fixed or tracked in #28–#38 and #43; the 2026-10-08 rework applied the last review's findings (aborted, previous_type, config plumbing, extra tests).


ELI5 — auditable without C

You know shell and a little Python. Four facts carry the whole argument, and a fifth note covers non-ASCII file names. Each fact can be checked on its own. If any one is wrong, the argument collapses, so that's where to attack it.

What the code is for. cf-agent --simulate runs the policy against a scratch copy of the files it touches (the "changes chroot"), not the real system. It keeps a log of what it did and, at the end, prints a report for humans. This PR adds --simulate-json=FILE, which writes the files and renames of that change set as one JSON document for programs to read. Packages follow in a separate PR.

Fact 1 — the JSON reads only what the text report reads. Simulate mode already leaves logs in its scratch area, including the paths it changed and the renames it did (old/new pairs). The JSON is built from those logs plus the scratch copies:

JSON field comes from
path the changed-paths log, each path once
change deleted if the scratch copy is gone and the real path exists (a file both created and deleted in the run is left out). Otherwise created or modified, depending on whether the real path exists.
type, permissions, uid, gid, size, sha256, target the scratch copy, looked at the way stat/readlink would, without following links
previous_type only when the real path is a different kind of file than the scratch copy, e.g. a directory replaced by a regular file; the text report prints both types too
renames the rename log
failsafe_fallback whether cf-agent set its existing failsafe_fallback class, i.e. ran failsafe.cf instead of your policy
aborted whether the run stopped early because an abortclasses class was defined, the same test that makes cf-agent exit 6

So the JSON can't know anything the text report doesn't. It also inherits the report's blind spots (see the end). The document is the same in all three --simulate modes.

Fact 2 — FILE only ever changes through rename(). In Python terms, the writer does this:

tmp = f"{FILE}.{secrets.token_hex(8)}.cfnew"          # same directory as FILE
fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
os.write(fd, doc); os.close(fd)                        # on any error: os.unlink(tmp); fail
os.rename(tmp, FILE)                                   # on any error: os.unlink(tmp); fail

Three properties follow. Each comes from the standard meaning of these system calls, not from anything CFEngine-specific.

  • 3a. O_EXCL makes the create fail if anything already has that name, including a symlink. So the temp file is always a new file that cf-agent made, never something planted.
  • 3b. FILE isn't touched until the rename(). A failed or killed write leaves FILE exactly as it was, at worst with a stray *.cfnew file next to it.
  • 3c. rename() replaces the name FILE in one step. Readers see either the old file or the complete new one, never half of one. If FILE was a symlink, the link itself is replaced and its target is never opened.

The 16 hex characters come from OpenSSL's RAND_bytes(), CFEngine's source of unpredictable bytes. That matters: with a predictable name, another user could create that file in advance and make the run fail. Even then, O_EXCL means a collision only makes the run fail; it never overwrites.

Fact 3 — any failure to write the whole document makes cf-agent exit non-zero, with one deliberate exception. The document is built in memory first. If the logs can't be read, nothing is written. Failing to create, write, close or rename the temp file also counts as a failure, and each is reported with its own message. In every one of those cases cf-agent exits 1, unless it was already going to exit with some other non-zero code, which it keeps.

The deliberate exception is a file whose SHA-256 can't be computed. It is written without a sha256 key, an error is logged, and the exit code doesn't change. Leaving the key out is safer than writing zeros. The hashing function has no way to report failure; it just leaves its output all zeros. Written out, "sha256": "0000…0000" looks exactly like a real digest, so a program comparing digests would get a wrong answer with full confidence. A missing key can't be mistaken for anything else. (The code treats an all-zero digest as failure. The chance of a real file hashing to all zeros is 2⁻²⁵⁶.)

The document is written just before cf-agent's shutdown routine, because that routine shuts down the OpenSSL library that computes SHA-256.

Fact 4 — a symlink's permission bits carry no information. What you can do through a symlink depends on the target's permissions, not the link's. Linux reports every symlink as 0777. macOS reports whatever the umask gave it. Including them would make the same change look different on two platforms while meaning nothing on either. So symlinks get target instead of permissions.

Fact 5 (note) — non-ASCII names come out escaped byte by byte because of libntech, not this change. A file name is bytes, but a JSON string is characters:

>>> 'é'.encode()
b'\xc3\xa9'                          # one character, two bytes
>>> json.loads('"caf\\u00c3\\u00a9"')
'café'

libntech's JsonWrite() escapes each byte outside printable ASCII on its own, as \u00XX. In JSON, though, à means "the character U+00C3" (Ã), not "the byte 0xC3". So café is written as café, and a standard parser such as Python's reads back café. The existing storejson() policy function produces the same escape, which shows the cause isn't this change. CFEngine's own readjson() reverses the escape and gets the right bytes back. The document is pure ASCII, so it's always valid JSON; only non-CFEngine readers misread non-ASCII names. A separate fix to libntech's encoder is being prepared.

What is not guaranteed.

  • Surviving a power loss. There is no fsync, so the all-or-nothing replacement in Fact 2 protects against other programs and a killed cf-agent, not against a power loss.
  • Old output being cleared. A FILE left from an earlier run survives a failed run, so trust FILE only if the exit code is 0.
  • Proof, from the exit code, that your policy ran. Exit 0 means the document is complete, not that your policy ran. In a non-interactive run, a policy that fails validation makes cf-agent fall back to failsafe.cf and still exit 0, as it always has; from a terminal it skips failsafe.cf instead. So check "failsafe_fallback": false in the document, not the exit code. It comes from the same class cf-agent already sets for this case. Likewise an aborted run (abortclasses) does exit 6, but the document is still written and says "aborted": true, so a reader that only has the file can tell a complete change set from a cut-short one.
  • Accuracy beyond the text report's. The JSON inherits the report's inaccuracies. For example, a relative symlink rel -> modify-me is reported, in both the text and the JSON, as target /modify-me, while a real run creates modify-me.
  • Correct owners without root. When not run as root, uid/gid show the user who ran it, because cf-agent can't chown its scratch copies.
  • Everything in manifest-full. That mode's listing of unchanged files is not in the JSON.

How you'd catch me lying, without reading C.

  • a. The 14 unit tests (tests/unit/simulate_mode_test) include a created-then-deleted file (not reported), a directory that became a regular file (previous_type), both flags set and unset, and these three cases:

    • FILE is a symlink: the victim is untouched and FILE becomes a regular file.
    • The output directory is missing: the write fails.
    • The changed-paths log is cut short: the write fails.

    The acceptance test 29_simulate_mode/simulate_json.cf runs a real cf-agent and compares the whole document with an expected file. It also checks that the option is refused without --simulate and with a relative path, and that an output path in a missing directory gives exit 1.

  • b. Point FILE into a read-only directory that already holds an old FILE. You get exit 1, the old contents are intact, and no .cfnew file is left.

  • c. Make FILE a symlink to a victim file. You get exit 0, the victim is unchanged, and FILE is now a regular 0600 file.

  • d. Without root, have a policy create a file and then set it to mode 000, so cf-agent can't read its own scratch copy. The entry has no sha256, the log says "Failed to compute the SHA-256 digest", and the exit code is 0.

  • e. Run printf created | shasum -a 256. It matches the sha256 of create-me in the acceptance test's expected output.

  • f. Create a file named café and read the JSON with Python's json. You get café. storejson() on the same string gives the same é.

  • g. Break your policy's syntax and run non-interactively (< /dev/null). The log shows the failsafe bundles running, and the document says "failsafe_fallback": true. With a working policy it says false.

Checks b through g were run against an installed build. If Fact 2 were wrong, b or c would show a changed victim or a clobbered FILE. If Fact 3 were wrong, d would show zeros or a wrong exit code.

🤖 Generated with Claude Code

Signed-off-by: Victor Moene <victor.moene@northern.tech>

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved. Cursor Bugbot was not present after the first check poll, so that signal was skipped; no approval policy required human review. No reviewers were assigned.

Open in Web View Automation 

Sent by Cursor Approval Agent: Pull Request Router and Approver

larsewi and others added 9 commits October 2, 2026 11:08
GetProcessStat() asserted on unexpected open() errors, e.g. when the
process exited in the meantime. Release builds would loop forever
instead. Now logs the error and returns false.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Ticket: CFE-4285
Changelog: Title
Signed-off-by: Lars Erik Wik <lars.erik.wik@northern.tech>
CFE-4285: Fixed cf-agent assertion failure when reading /proc/<pid>/stat
…ions.c

Linked TODOs to new tickets to fix old bugs/TODOs that were already in cf-agent
before moving the code.

Signed-off-by: Victor Moene <victor.moene@northern.tech>
Better concurrency for cf-reactor static state
- No need for map anymore, since watcher keeps track of the promise
- No need to keep key as variable anymore, since we do not use a map
- No need to run bundle inside watcher.c
- No risk of running a bundle from a wrong key between policy reads

Signed-off-by: Victor Moene <victor.moene@northern.tech>
Promises are skipped to prevent running them several times. However, on event, we want to run them every single time:
- we clear the promise lock cache
- we set the default if_elapsed time for bundles run from an events promise to be 0, so it doesn't skip the promises.

Fixed also connection cache and custom promise prologue and epilogue. Clear function cache before "then" bundle run

Signed-off-by: Victor Moene <victor.moene@northern.tech>
Signed-off-by: Victor Moene <victor.moene@northern.tech>
- Moved mod_methods.c's MethodsParseTreeCheck implementation to PromiseCheckBundleCallArity
in policy.c, and made it more generic
- Now, MethodsParseTreeCheck and EventsParseTreeCheck both call this new function when calling bundles

Signed-off-by: Victor Moene <victor.moene@northern.tech>
With --simulate-json=FILE, cf-agent also writes the files and renames of
a --simulate run to FILE as one JSON document, together with whether the
run fell back to the failsafe policy or was aborted. Under manifest-full
the JSON lists only the changed files, not the kept ones.

Ticket: none
Changelog: Title
Signed-off-by: Daniel JB Clark <djbclark@gmail.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants