Three identity spaces
When correlation is established, canonical identity equals observer-visible identity. Raw IDs remain available for diagnosis. SYSCALL does not silently substitute one for another.
Process-instance identity
The canonical ID is:boot_idcomes from/proc/sys/kernel/random/boot_idand is captured once per session.pidis the canonical observer-visible PID.start_time_ticksis field 22 of/proc/<pid>/stat.
/proc disappears before start time can be read, the fallback is:
PID reuse
A PID can be reused after a process exits. The scope tracker caches the start time for each tracked instance. If a new observation has the same PID but a differentstart_time_ticks, it is treated as a different process and is not admitted on the old identity’s trust.
Process relationships also use process-instance IDs, not PIDs alone. If parent linkage cannot be established unambiguously, SYSCALL reports unresolved ancestry rather than guessing.
Target-tree admission
Target-tree scope admits the launched target and its descendants. The kernel still observes the whole host; admission happens in userspace. The tracker applies these rules:- The spawned target is registered as the root.
- A fork is admitted when its parent is already tracked.
- If a fork was lost or arrived out of order,
/proc/<ppid>ancestry is walked up to 64 levels looking for a tracked ancestor. - Thread-creation events are rejected by checking whether
/proc/<child>/statushasTgid == Pid. The same distinction applies to thread exits. - A PID with a different cached start time is treated as reused and is not admitted without new lineage.
- Activity events are attributed only when the observed process resolves to a tracked instance. A numeric PID match is insufficient.
Namespace correlation
On WSL2, rootless hosts, and container hosts, the BPF programs and the collector may not see the same PID numbers. The event header carriesns_tgid, the observer/collector PID-namespace TGID when known.
- When
ns_tgidis available, it correlates the event to the collector’s view. - When it is unavailable, SYSCALL may use a verified
/procfallback only when same-namespace, process-leader evidence matches the tracked canonical parent. - Raw BPF IDs remain in the record even after correlation.
Fork buffering
The BPF fork handler currently emits childns_tgid=0; the wire layout is unchanged. A raw child TGID may differ from the observer-visible PID across namespaces, so SYSCALL does not invent a canonical child identity.
- If child
ns_tgidis available, it is used. - Otherwise, a verified procfs fallback may be attempted under the same-namespace, process-leader conditions described above.
- If identity remains unresolved, the fork is registered as provisional: lineage is admitted for scope purposes, but the identity is not claimed as resolved.
- A later child exec or exit with child-context
ns_tgidupgrades the identity, learns the alias, and flushes the buffered fork before the current event. The flushed fork uses the same canonical process-instance ID and its original timestamps. - If correlation never arrives, buffered forks are flushed at session end with explicit provisional identity.
System scope
--scope system admits every observed event. It does not change the fact that tracepoints are system-wide, and it does not add kernel filtering.
System scope is appropriate for host-level investigation. It can produce substantially more data, including unrelated process activity. The session row records the chosen scope so later readers do not have to infer it.
Bounds
When the tracked-process table is full, new processes are filtered and counted. Overflow fork entries are emitted as explicitly unresolved rather than silently dropped. A fork bomb cannot grow userspace memory without bound.
Reading unresolved evidence
An unresolved flag is an attribution limitation, not proof that an event is corrupt.- Unresolved identity means the canonical process instance could not be fully established.
- Unresolved ancestry means the parent relationship cannot be claimed from recorded evidence.
- Provisional fork means lineage was admitted but the child identity awaited correlation.