Version boundary: master is ahead of v1.0.35

This analysis pins product master to fbc6d91a025b561970f6e526a5c77bb07754f30a, including the 21 November 2026 filesystem tracing change. The latest stable release at review time is still v1.0.35 (23 October). In v1.0.35, mkdir, unlink and rename used separate per-syscall entry tracepoints and an unreadable user path caused an early return. The newer master source replaces those path hooks with one raw_syscalls:sys_enter dispatcher and retains an explicit unreadable-path marker. Do not attribute that unreleased behavior to an installed v1.0.35 binary.

The change follows a source-described CI/kernel case in which the path-specific hooks were not firing while file-descriptor-based hooks were aggregating. The repository also contains temporary diagnostic probes. This page inspects code and fixture assertions; it is not a new reproducible runtime measurement or a claim that every supported kernel now captures every mutation.

Which syscall observation produces which summary?

TypeEntry evidenceArgument usedMissing conclusion
FILE_DELETEunlink / unlinkat entryUser-supplied target pathnameNot proof the unlink succeeded or that the file disappeared
FILE_RENAMErename / renameat / renameat2 entryNew/destination pathname onlyDoes not preserve the old pathname or prove a completed rename
DIR_CREATEmkdir / mkdirat entryUser-supplied directory pathnameNot proof the directory was created
FILE_TRUNCATEftruncate entryFile descriptor, not a resolved target pathNot a confirmed truncation or a count of bytes removed
WRITEwrite-family tracingFile descriptor and captured byte accountingNot necessarily a persistent on-disk change; fd resolution is best effort

The raw path dispatcher branches by architecture-specific syscall ID (x86-64 and arm64 tables) and reads the relevant argument pointer. For renameat and renameat2, that is argument 3, the destination name; for plain x86 rename, it is argument 1. The source name is not stored in this path summary. Calls outside the selected IDs are not covered by that dispatcher.

These are sys_enter hooks, not success-checked return hooks. A failed permission check, an absent source file or a target that already exists can still produce an attempt record. Conversely, a missing summary is not proof that no filesystem activity occurred: probe attachment, filter configuration, read failures, map capacity and flush behavior all matter.

Why count=3 does not mean three files changed

The path aggregate key contains pid, event type, process-start identity and a short detail string constructed by extract_dir_prefix. With an ordinary absolute pathname containing a non-root parent slash, this is the parent directory, not a unique filename. Relative single-component names and root-level paths have different corner cases because the helper only truncates when its last slash index is greater than zero. The directory-like value is also size bounded.

The value contains a count, first/last observed timestamps, process command, and extra. Each later event with the same key increments count and overwrites extrawith the latest readable full path (or a read-failure marker). For example, attempted renames to /work/a.txt and/work/b.txt can share one FILE_RENAMEaggregate for the same process. Its count may be two whileextra shows only /work/b.txt. This is a source-derived illustration, not a captured sample.

The JSON printer emits timestamp from the last observed timestamp, plus type, detail,count, optional extra, and process identity. It does not serialize every attempt separately. The normal flush walks and deletes map keys in bounded batches; a later flush starts a new aggregate interval. Count is scoped to that key and flush, not to an entire session.

Field or signalWhat it supportsWhat it does not support
Observed syscall entryThe tracer saw a process enter a supported syscall while filesystem tracing and its process filter were active.A successful return value, filesystem state afterwards, or a durable mutation.
SUMMARY countThe aggregate count for one map key and flush interval.One distinct file per count, an ordered audit trail, or complete event delivery.
SUMMARY detailThe grouping string derived from the user pathname; usually a directory prefix when a slash occurs after the initial character.An authoritative canonical/absolute path, or the pathname of every grouped event.
SUMMARY extraThe most recently stored pathname for that key, or an explicit unreadable-path marker.A list of every path represented by count, or proof that this path was actually changed.
SUMMARY timestampThe aggregate last-observed timestamp, printed from last_ts.A first-event time, per-attempt latency, or syscall completion time.

An unreadable user pathname is a separate failure mode

The master implementation calls bpf_probe_read_user_stragainst the syscall argument pointer. If that read fails, it no longer discards the entire path operation merely because the path is unavailable. Instead the key uses an empty pathname-derived detail and extra contains a bounded <user path unreadable: ... marker with the helper error number. That preserves evidence of a matched syscall type and process, but the failed read gives no reliable target path.

There is another implementation-level distinction: stack-to-stack strings are copied with a bounded direct copy rather than bpf_probe_read_kernel_str, which expects a kernel address. The prior code could fail to populate the extra pathname even when the original user read succeeded. Both behaviors matter for interpretation of old and new builds.

How to inspect the exact evidence contract

The source and fixture can be inspected without attaching probes. The root-only runtime test on Linux invokes ./process -m 0 --trace-fs, performs mkdir, write, rename and unlink operations, and checks that the expected summary types appear. That assertion is not a check of syscall success attribution, per-path completeness or generalization to other kernels.

git clone https://github.com/eunomia-bpf/agentsight.git
cd agentsight
git checkout fbc6d91a025b561970f6e526a5c77bb07754f30a
rg -n "trace_raw_path|agg_path_event|extract_dir_prefix" bpf/process_ext/bpf_fs.h
rg -n "print_summary_json|flush_agg_map" bpf/process_ext/map_flush.h
rg -n "test_trace_fs_summary_events" bpf/tests/test_process_runtime.py

If you repeat capture on a disposable local workload, first confirm attachment, filter scope, target architecture and summary loss/overflow signals, then compare the resulting events with independent filesystem state and command exit results. Treat all paths and captured session data as potentially sensitive. The separate capture loss analysis explains why a tracer output can be incomplete.

Which source should you trust for a file change?

For observed file opens, read theFILE_OPEN evidence boundary: an open is not a write. For replayed agent intentions, readrepository replay provenance: native Tool logs are not independent kernel file mutations. This page is about a third layer, Linux syscall-entry summaries. None alone reconstructs a complete, independently verified final filesystem diff.

To establish that a destructive operation really took effect, combine the attempted syscall evidence with a trustworthy return status and a before/after filesystem observation for the particular path. A process exit code alone does not identify which syscall failed. The canonical documentation owns installation and supported command configuration.

Pinned first-party sources

Limitations: this is an implementation review of an unreleased master revision, with an upstream fixture rather than independent runtime reproduction. It does not establish perfect attachment or loss-free delivery on Linux kernels, exact per-operation result codes, or capture of file changes made outside the observed process/filter scope. The separate stable version remains v1.0.35.