rootguard Directory Reference

Directories
	bpf
	demo
	docs
	include
	src
	tests

Files
	RootGuardClient.cpp
	RootGuardClient.hpp
	RootGuardEvent.cpp
	RootGuardEvent.hpp
	RootGuardPage.cpp
	RootGuardPage.hpp

Detailed Description

BastionGuard RootGuard

RootGuard is BastionGuard's eBPF LSM privilege-escalation and filesystem metadata monitor. It filters global metadata activity down to privilege-relevant transitions and performs complete baseline monitoring on explicitly protected system identities, where changes can be denied before they are committed.

Protection model

RootGuard deliberately separates four concepts:

• Global surveillance records privilege-relevant transitions with an eBPF per-execution-domain sample budget, and separately counts destructive permission/ownership storms in-kernel. The domain includes cgroup plus actor and parent executable identity, avoiding cross-talk inside a broad user slice. Routine activity therefore does not become a ring-buffer or popup storm.
• Protected paths provide enforcement, integrity baselines, Restore and Quarantine.
• Trusted applications classify routine global metadata produced by desktop applications or an exact trusted orchestrator and its descendant helpers. They receive no privilege-transition trust and never bypass protected-path enforcement. Do not trust generic tools such as rsync, tar or chmod; trust the specific backup/application orchestrator instead.
• Privilege-trusted and denied executables participate only in privilege-transition decisions.

The default policy keeps user home directories audit-only even when immediate blocking is enabled. BastionGuard Anti-Ransomware remains responsible for user-data enforcement. Immediate blocking applies to protected system paths, including service definitions; blocked service-definition changes can trigger native service containment.

GTK page

RootGuardPage uses compact tabs:

1. Overview
2. Incidents
3. Events
4. Application rules

The Overview tab contains an information popover explaining the system/home scope. The Application rules tab contains nested editors for trusted applications, privilege-trusted executables and blocked/denied executables. A convenience button adds only installed known desktop/browser executables for review. Saving is explicit, policy validation is atomic, administrator authentication is used, and RootGuard is restarted only after a successful save.

Protected-path audit notifications are acknowledgement-only. Individual global metadata records are observations and never open a popup. A high-volume destructive permission pattern is aggregated by eBPF into one metadata-burst incident; the GTK client caps burst interruptions to one every 15 minutes while keeping the complete sampled history available for investigation.

Path transparency

For chmod/chown, the BPF LSM path hook captures the mount-aware target path before inode_setattr; Linux 6.12 and newer use the optional bpf_path_d_path kfunc. Protected baselines, open process descriptors and the process working directory remain additional resolution sources.

The executable identity is captured at exec time and copied into later events, so short-lived actors remain identifiable after /proc/<pid> disappears. Notifications show PID, TGID, PPID, parent process, actor and parent executable, EUID, target path/directory and device/inode identities. If an operation reaches only an inode hook and no exact mount-aware path is available, RootGuard reports that limitation and never invents a directory.

Policy additions

[engine]
block_user_home = false
monitor_global_privilege_metadata = true
detect_global_metadata_bursts = true
global_metadata_sample_limit = 3
metadata_burst_threshold = 32
metadata_burst_window_ms = 5000
metadata_burst_cooldown_ms = 300000
 
[trusted-applications]
path = /usr/bin/gnome-shell
path = /usr/bin/plasmashell
path = /usr/bin/firefox

[trusted-applications] is intentionally separate from [trusted-executables].

Native CMake integration

The module belongs at src/rootguard and is included directly:

add_subdirectory(
    "${CMAKE_SOURCE_DIR}/src/rootguard"
    "${CMAKE_BINARY_DIR}/bastionguard-rootguard-build"
)
 
target_link_libraries(BastionGuard PRIVATE BastionGuard::RootGuardUI)

The build supports systemd, OpenRC, dinit and SysV init. Set ROOTGUARD_INIT_SYSTEM explicitly when producing a distribution package.

The installed rootguard.conf is preserved across later cmake --install runs. The packaged reference policy is installed as rootguard.conf.default.