RootGuardEngine.hpp

1. Overview

The RootGuardEngine.hpp header declares the userspace RootGuard engine responsible for loading and attaching the generated eBPF skeleton, applying policy into BPF maps, polling events, enriching event context, and running userspace integrity verification for protected objects.

The file integrates the following components, APIs, or runtime concepts:

  • libbpf generated skeleton – rootguard_bpf
  • ring_buffer – kernel-to-userspace event transport
  • Policy – runtime configuration
  • IEventSink – final event output/response pipeline
  • FileIdentity – protected/trusted inode identity resolution

2. PolicyApplyReport

The report counts loaded trusted applications, privilege-trusted executables, denied executables, and protected identities, and carries non-fatal warnings for optional paths that could not be resolved.

3. Engine Lifecycle

  • start() – load BPF, apply policy, attach programs, and create the ring buffer
  • reloadPolicy() – replace the active policy without recreating the engine object
  • enterAuditMode() – force fail-safe audit configuration
  • pollOnce() – poll the event ring buffer
  • runIntegrityCheckIfDue() – compare protected snapshots with current filesystem metadata

4. Authorization Tokens

authorizeProcess() writes a temporary authorization token for a process/TGID and target EUID into the BPF authorization map. The implementation constrains token lifetime.

5. ProtectedSnapshot

Each userspace snapshot retains canonical path, device/inode key, rule ID, baseline mode/UID/GID, and drift state. This allows periodic detection of missing, replaced, permission-changed, or owner-changed protected objects.

6. Policy and Event Internals

Private methods populate kernel configuration/maps, clear maps safely, enrich paths and actor executables from baseline or /proc, classify trusted-application global events, suppress ignored/noisy records, and handle the C ring-buffer callback.

7. Ownership Model

The libbpf skeleton and ring buffer use std::unique_ptr with custom deleters. Copy and move operations are disabled to preserve one clear owner of attached BPF resources.

8. Runtime and Security Considerations

  • Fail-safe audit entry: policy replacement can explicitly drop enforcement before map mutation.
  • Identity-based protection: protected snapshots are keyed by filesystem identity and baseline metadata.
  • C callback boundary: the implementation prevents exceptions from escaping the libbpf callback.
Published on:
Last updated on: