Skip to content

refactor(ps): Decouple process snapshotter from raw events - #758

Merged
rabbitstack merged 7 commits into
masterfrom
rearch-process-snapshotter
Nov 20, 2026
Merged

rabbitstack merged 7 commits into
masterfrom
rearch-process-snapshotter

Conversation

@rabbitstack

Copy link
Copy Markdown
Owner

What is the purpose of this PR / why it is needed?

This changeset combines the refactoring to decouple the process snapshotter from raw events and a set of bug fixes encountered during the refactor. For more details, revise individual commit messages.

What type of change does this PR introduce?


Uncomment one or more /kind <> lines:

/kind feature (non-breaking change which adds functionality)

/kind bug-fix (non-breaking change which fixes an issue)

/kind refactor (non-breaking change that restructures the code, while not changing the original functionality)

/kind breaking (fix or feature that would cause existing functionality to not work as expected

/kind cleanup

/kind improvement

/kind design

/kind documentation

/kind other (change that doesn't pertain to any of the above categories)

Any specific area of the project related to this PR?


Uncomment one or more /area <> lines:

/area instrumentation

/area telemetry

/area rule-engine

/area filters

/area yara

/area event

/area captures

/area alertsenders

/area outputs

/area rules

/area filaments

/area config

/area cli

/area tests

/area ci

/area build

/area docs

/area deps

/area evasion

/area other

Special notes for the reviewer


Does this PR introduce a user-facing change?


@rulecheck

rulecheck Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

RuleCheck.io  RuleCheck test run results

Commit: 2b955cf
Total: 0 rules
Test scope: Fibratus
Test run: View the run

Selection: PR changes only (matching scope patterns). No added or modified rule files match this scope's file patterns and exclusions. Deleted files are not evaluated; the full scope was not tested.

@rabbitstack
rabbitstack force-pushed the rearch-process-snapshotter branch from dffc0ee to e2e5db9 Compare November 20, 2026 14:37
GetExitCodeProcess returns 259 (STILL_ACTIVE / STATUS_PENDING, 0x103)
while the process hasn't terminated. But 259 is also a perfectly
valid exit code. A process that calls ExitProcess(259) or
TerminateProcess(h, 259) is reported as running forever.
The process snapshotter Find method now returns the
*pstypes.PS, bool tuple to make it uniform with the
Go standard library API (for example, map existence
checks).
The SID to username resolution is done for every
new process on the system. This calls into LookupAccountSid
that routes to LSASS for the account resolution.
These calls are now cached by TTL-bounded SID to user/domain cache.
Walk is now iterative and stops on cycles. A process
that is its own parent (or a longer loop caused by
pid reuse) overflowed the stack.
UUID fallback combined boot id, pid and start time with +/|, which have
equal precedence in Go and let the nanosecond timestamp mask the other
components. The value is now a hash of the three. The Windows version
gate compared the build number against 1507 (a release name), it now
uses the real Windows 10 1507 build number (10240)

UUID/AssignUUID lazily initialized the uuid without synchronization

AddHandle, RemoveHandle, AddMmap, RemoveMmap and FindMmap did not take
the process lock while the thread/module methods did

AddModule checked for an existing module and appended under two
separate lock acquisitions, and FindModuleByVa could cache the same
live module twice when called concurrently. Both are now atomic
FindModule, FindModuleByAddr, FindModuleByVa and FindMmap returned
pointers into the backing slices, which Remove* shifts in place, so a
retained pointer could silently refer to a different entry. They now
return copies

Remove* use slices.Delete so vacated tail slots are zeroed
OS query resolution for process attributes is moved to
the process state structure. Process executable path,
parent id, creation flags, and start time are defined
as PS type receiver methods.
The snapshotter no longer consumes raw events. Mappers turn events into
the pstypes values, and the snapshotter only manages state.

API changes:
- Write/Remove are replaced by AddProcess(*pstypes.PS) and RemoveProcess(pid)
- AddThread takes pstypes.Thread (carries the pid)
- AddModule/AddMmap take (pid, pstypes.Module/Mmap)
- WriteFromCapture is dropped; the capture reader decodes and calls AddProcess

Fixes:
- OS enrichment (handles, PE, PEB, token) no longer runs under the global
  snapshotter lock; Find no longer holds RLock during OS queries
- Enrichment steps are independent. Handle lookup failure no longer skips
  PE/PEB, and a PE parse failure no longer aborts the OS process query
- Repeated system events for a known pid no longer lose token attributes
- process/thread/module/mmap counters only change when state really changes
- Close is idempotent and the GC goroutine exits on Close
- GC probes processes without holding the lock and only deletes the state it
  inspected
- Delayed dirty-state removal cannot drop the dirty entry of a process that
  reused the pid
- Self-parenting is guarded to avoid infinite ancestor walks
- Thread.Pid is now populated when decoding thread events
@rabbitstack
rabbitstack force-pushed the rearch-process-snapshotter branch from e2e5db9 to 2b955cf Compare November 20, 2026 22:31
@rabbitstack
rabbitstack merged commit 0d2cb65 into master Nov 20, 2026
13 of 14 checks passed
@rabbitstack
rabbitstack deleted the rearch-process-snapshotter branch November 20, 2026 23:00
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.

1 participant