RootGuardEvent.hpp

1. Overview

The RootGuardEvent.hpp header defines the GTK integration event model and the classification helpers used to transform RootGuard JSONL records into UI-visible telemetry, observations, and actionable incidents.

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

  • RootGuard JSONL event log – source representation for Event
  • rootguard_shared.h – reason flags and event semantics used by the implementation
  • RootGuardPage – consumes classification, formatting, fingerprints, and service-path checks

2. Severity Model

  • Telemetry – informational records that stay in the event history
  • Observation – security-relevant global metadata activity that should be visible but is not directly actionable
  • Incident – protected-object, service-containment, or high-signal burst activity eligible for incident handling

3. Event Structure

Event preserves timing, event/verdict strings, process identifiers, EUID transition, rule and reason fields, LSM flags, auxiliary data, filesystem identities, actor/parent identities, actor start time, old/new mode and ownership, process names, executable paths, affected filename, path-resolution provenance, and the original JSON line.

The default path_resolution value is basename-only, making uncertain path provenance explicit.

4. Parsing and Presentation API

  • parse_event_json() – parse a JSONL record into an optional Event
  • format_event() – create the compact textual line shown in the Events page
  • event_fingerprint() – derive a stable-in-process identifier from the raw JSON record

5. Classification API

  • classify_event() – map an event to telemetry, observation, or incident
  • is_security_observation() – true for observations and incidents
  • is_actionable_incident() – true only for incident severity
  • is_system_service_path() – recognize systemd, OpenRC/SysV, and dinit service-definition trees

6. Runtime and Security Considerations

  • Path provenance is first-class: the UI can disable destructive actions when only a basename is known.
  • Raw record preservation: raw_json is retained for fingerprinting and traceability.
  • Classification is separate from transport: the same parsed event can be rendered differently without changing the underlying log format.
Published on:
Last updated on: