multirule

Documentation

Overview

Package multirule provides a userspace-only rule tracker for pmark process callbacks.

A Tracker maintains an in-memory mapping from pmark.ProcessKey to the set of registered rule IDs matched by that process, plus a best-effort PID-to-latest ProcessKey index for convenience lookups. Registering a rule checks all currently tracked processes and propagates the new rule ID to already tracked descendants of every direct match. Observing a process checks all current rules and inherits any rule IDs associated with the latest known parent process.

To attach it to a pmark Daemon, pass Tracker.CheckCallback as a Callbacks.Check or install it later with Daemon.SetChecker. The callback returns ok=false, so pmark marks are not created by the tracker. If ProcessEvent callbacks are available, attach Tracker.ProcessEventCallback as well so exit events can remove process lifetimes from the userspace map.

PID-only lookups use the latest ProcessKey observed for that PID. PIDs can be reused, so these helpers are intentionally less precise than ProcessKey-based lookups.

Index

• type Rule
• type Tracker
  • func New() *Tracker
  • func (t *Tracker) ApplyProcess(info pmark.ProcessInfo)
  • func (t *Tracker) ApplyProcessEvent(event pmark.ProcessEvent)
  • func (t *Tracker) CheckCallback() pmark.CheckFunc
  • func (t *Tracker) Matches(key pmark.ProcessKey, ruleID uint64) bool
  • func (t *Tracker) MatchesPID(pid uint32, ruleID uint64) bool
  • func (t *Tracker) ProcessEventCallback() func(pmark.ProcessEvent)
  • func (t *Tracker) RegisterRule(rule Rule) uint64
  • func (t *Tracker) RuleIDs(key pmark.ProcessKey) []uint64
  • func (t *Tracker) RuleIDsByPID(pid uint32) []uint64
  • func (t *Tracker) Snapshot() map[pmark.ProcessKey][]uint64
  • func (t *Tracker) UnregisterRule(ruleID uint64) bool

Types

type Rule

type Rule func(pmark.ProcessInfo) bool

Rule decides whether a process directly matches a tracker rule.

Rules are called synchronously from Tracker methods and daemon callbacks. They should be quick and must not call back into the same Tracker.

type Tracker

type Tracker struct {
	// contains filtered or unexported fields
}

Tracker keeps a userspace process-to-rule-ID mirror.

A Tracker does not load, pin, read, or write eBPF objects. Attach it to a pmark Daemon by installing CheckCallback as the daemon Check callback. If the daemon also emits ProcessEvent callbacks, attach ProcessEventCallback to let the tracker remove exited process lifetimes.

func New

func New() *Tracker

New returns an empty Tracker.

func (*Tracker) ApplyProcess

func (t *Tracker) ApplyProcess(info pmark.ProcessInfo)

ApplyProcess checks info against registered rules, inherits rule IDs from its latest known parent process when present, and updates the tracker state.

func (*Tracker) ApplyProcessEvent

func (t *Tracker) ApplyProcessEvent(event pmark.ProcessEvent)

ApplyProcessEvent applies process-event side effects that are not visible through CheckCallback, currently exit cleanup.

func (*Tracker) CheckCallback

func (t *Tracker) CheckCallback() pmark.CheckFunc

CheckCallback returns a pmark CheckFunc that observes process information and always returns ok=false so the tracker does not create pmark/eBPF marks.

func (*Tracker) Matches

func (t *Tracker) Matches(key pmark.ProcessKey, ruleID uint64) bool

Matches reports whether key is associated with ruleID.

func (*Tracker) MatchesPID

func (t *Tracker) MatchesPID(pid uint32, ruleID uint64) bool

MatchesPID reports whether the latest ProcessKey observed for pid is associated with ruleID.

PIDs can be reused. When multiple ProcessKeys have been observed for the same pid, the latest observed ProcessKey wins. If that ProcessKey is later removed by an exit ProcessEvent, the PID lookup is removed too.

func (*Tracker) ProcessEventCallback

func (t *Tracker) ProcessEventCallback() func(pmark.ProcessEvent)

ProcessEventCallback returns a daemon ProcessEvent hook for ApplyProcessEvent.

func (*Tracker) RegisterRule

func (t *Tracker) RegisterRule(rule Rule) uint64

RegisterRule registers rule and returns its unique ID.

Existing tracked processes are immediately checked against the new rule. When an existing process directly matches, the new rule ID is also propagated to already tracked descendants of that process. Later observed children inherit from their latest known parent as usual.

func (*Tracker) RuleIDs

func (t *Tracker) RuleIDs(key pmark.ProcessKey) []uint64

RuleIDs returns a stable snapshot of rule IDs associated with key.

func (*Tracker) RuleIDsByPID

func (t *Tracker) RuleIDsByPID(pid uint32) []uint64

RuleIDsByPID returns a stable snapshot of rule IDs associated with the latest ProcessKey observed for pid.

PIDs can be reused. When multiple ProcessKeys have been observed for the same pid, the latest observed ProcessKey wins. If that ProcessKey is later removed by an exit ProcessEvent, the PID lookup is removed too.

func (*Tracker) Snapshot

func (t *Tracker) Snapshot() map[pmark.ProcessKey][]uint64

Snapshot returns a deep copy of the current process-to-rule-ID mapping.

func (*Tracker) UnregisterRule

func (t *Tracker) UnregisterRule(ruleID uint64) bool

UnregisterRule removes ruleID from the rule set and from every process entry.

It reports whether a registered rule was removed.