BastionGuard::RootGuard Namespace Reference

Namespaces
namespace	anonymous_namespace{RootGuardClient.cpp}
namespace	anonymous_namespace{RootGuardEvent.cpp}

Classes
struct	ApplicationRules
class	Client
struct	Event
struct	ServiceStatus
struct	Snapshot

Enumerations
enum class	EventSeverity { Telemetry , Observation , Incident }

Functions
std::optional< Event >	parse_event_json (const std::string &line)
std::string	format_event (const Event &event)
std::string	event_fingerprint (const Event &event)
EventSeverity	classify_event (const Event &event) noexcept
bool	is_security_observation (const Event &event) noexcept
bool	is_actionable_incident (const Event &event) noexcept
bool	is_system_service_path (const std::string &path) noexcept

Enumeration Type Documentation

EventSeverity

enum class BastionGuard::RootGuard::EventSeverity

strong

Enumerator
Telemetry
Observation
Incident

Definition at line 14 of file RootGuardEvent.hpp.

                         {
    Telemetry,
    Observation,
    Incident,
};

Function Documentation

classify_event()

EventSeverity BastionGuard::RootGuard::classify_event ( const Event & event )

noexcept

Definition at line 217 of file RootGuardEvent.cpp.

{
    if (event.filename.empty() || event.filename == "--")
        return EventSeverity::Telemetry;
    if (event.verdict != "blocked" && event.verdict != "alert" &&
        event.verdict != "audit")
        return EventSeverity::Telemetry;
 
    if (event.event == "service-blocked")
        return EventSeverity::Incident;
 
    const bool metadataEvent =
        event.event == "permission-change" ||
        event.event == "owner-change" ||
        event.event == "xattr-change" ||
        event.event == "acl-change";
    if (metadataEvent) {
        /*
         * Explicitly protected identities retain their existing incident
         * semantics because they have a baseline and may have been blocked.
         */
        if (event.rule_id != 0)
            return EventSeverity::Incident;
 
        /*
         * Desktop policy: unprotected global privilege metadata is diagnostic
         * telemetry only. Keep it visible as an observation when explicitly
         * enabled, but never let backup/package metadata replay interrupt the
         * user with a popup. Historical broad-surveillance records remain
         * telemetry-only.
         */
        if ((event.reason_flags & RG_REASON_GLOBAL_METADATA) != 0)
            return (event.reason_flags & RG_REASON_METADATA_BURST) != 0
                ? EventSeverity::Incident
                : EventSeverity::Observation;
 
        return EventSeverity::Telemetry;
    }
 
    if (event.event == "protected-unlink" ||
        event.event == "protected-rename" ||
        event.event == "protected-hardlink" ||
        event.event == "integrity-drift")
        return event.rule_id != 0
            ? EventSeverity::Incident
            : EventSeverity::Telemetry;
 
    return EventSeverity::Telemetry;
}

References classify_event(), Incident, Observation, RG_REASON_GLOBAL_METADATA, RG_REASON_METADATA_BURST, and Telemetry.

Referenced by classify_event(), is_actionable_incident(), is_security_observation(), main(), and RootGuardPage::render_incidents().

event_fingerprint()

std::string BastionGuard::RootGuard::event_fingerprint

(

const Event &

event

)

Definition at line 209 of file RootGuardEvent.cpp.

{
    const auto hash = std::hash<std::string>{}(event.raw_json);
    std::ostringstream output;
    output << std::hex << hash;
    return output.str();
}

References event_fingerprint().

Referenced by RootGuardPage::dismiss_alert(), RootGuardPage::dismiss_event(), event_fingerprint(), main(), RootGuardPage::queue_new_alerts(), and RootGuardPage::render_incidents().

format_event()

std::string BastionGuard::RootGuard::format_event

(

const Event &

event

)

Definition at line 167 of file RootGuardEvent.cpp.

{
    std::ostringstream output;
    output << '[' << (event.received_at.empty() ? "unknown time" : event.received_at)
           << "] [" << event.verdict << "] " << event.event
           << " process=" << event.comm
           << " pid=" << event.pid
           << " tgid=" << event.tgid
           << " ppid=" << event.ppid;
 
    if (event.old_euid != event.new_euid)
        output << " euid=" << event.old_euid << "->" << event.new_euid;
    if (event.old_mode != event.new_mode)
        output << " mode=" << octal_mode(event.old_mode)
               << "->" << octal_mode(event.new_mode);
    if (event.old_uid != event.new_uid || event.old_gid != event.new_gid)
        output << " owner=" << event.old_uid << ':' << event.old_gid
               << "->" << event.new_uid << ':' << event.new_gid;
    if (event.rule_id != 0)
        output << " rule=" << event.rule_id;
    if (!event.parent_comm.empty())
        output << " parent=" << event.parent_comm;
    if (!event.parent_executable.empty())
        output << " parent-exe=" << event.parent_executable;
    if (event.parent_device != 0 || event.parent_inode != 0)
        output << " parent-identity=" << event.parent_device
               << ':' << event.parent_inode;
    if (!event.actor_executable.empty())
        output << " actor=" << event.actor_executable;
    if (event.actor_device != 0 || event.actor_inode != 0)
        output << " actor-identity=" << event.actor_device
               << ':' << event.actor_inode;
    if (!event.filename.empty())
        output << " file=" << event.filename
               << " path-resolution=" << event.path_resolution;
    if (event.device != 0 || event.inode != 0)
        output << " identity=" << event.device << ':' << event.inode;
 
    output << " reason=0x" << std::hex << event.reason_flags << std::dec;
    return output.str();
}

References BastionGuard::RootGuard::Event::actor_device, BastionGuard::RootGuard::Event::actor_executable, BastionGuard::RootGuard::Event::actor_inode, BastionGuard::RootGuard::Event::device, BastionGuard::RootGuard::Event::filename, format_event(), BastionGuard::RootGuard::Event::inode, BastionGuard::RootGuard::Event::new_euid, BastionGuard::RootGuard::Event::new_gid, BastionGuard::RootGuard::Event::new_mode, BastionGuard::RootGuard::Event::new_uid, BastionGuard::RootGuard::Event::old_euid, BastionGuard::RootGuard::Event::old_gid, BastionGuard::RootGuard::Event::old_mode, BastionGuard::RootGuard::Event::old_uid, BastionGuard::RootGuard::Event::parent_comm, BastionGuard::RootGuard::Event::parent_device, BastionGuard::RootGuard::Event::parent_executable, BastionGuard::RootGuard::Event::parent_inode, BastionGuard::RootGuard::Event::received_at, and BastionGuard::RootGuard::Event::rule_id.

Referenced by format_event(), main(), and RootGuardPage::render_events().

is_actionable_incident()

bool BastionGuard::RootGuard::is_actionable_incident ( const Event & event )

noexcept

Definition at line 272 of file RootGuardEvent.cpp.

{
    return classify_event(event) == EventSeverity::Incident;
}

References classify_event(), Incident, and is_actionable_incident().

Referenced by is_actionable_incident(), main(), and RootGuardPage::queue_new_alerts().

is_security_observation()

bool BastionGuard::RootGuard::is_security_observation ( const Event & event )

noexcept

Definition at line 267 of file RootGuardEvent.cpp.

{
    return classify_event(event) != EventSeverity::Telemetry;
}

References classify_event(), is_security_observation(), and Telemetry.

Referenced by is_security_observation(), main(), and RootGuardPage::render_incidents().

is_system_service_path()

bool BastionGuard::RootGuard::is_system_service_path ( const std::string & path )

noexcept

Definition at line 277 of file RootGuardEvent.cpp.

{
    if (path.empty())
        return false;
    const bool systemd = has_prefix(path, "/etc/systemd/system") ||
                         has_prefix(path, "/usr/lib/systemd/system") ||
                         has_prefix(path, "/lib/systemd/system");
    const bool initScript = has_prefix(path, "/etc/init.d") ||
                            has_prefix(path, "/etc/conf.d");
    const bool dinit = has_prefix(path, "/etc/dinit.d") ||
                       has_prefix(path, "/usr/lib/dinit.d");
    return systemd || initScript || dinit;
}

References is_system_service_path().

Referenced by anonymous_namespace{RootGuardPage.cpp}::incident_detail(), is_system_service_path(), main(), BastionGuard::RootGuard::Client::run_request(), and RootGuardPage::show_next_alert().

parse_event_json()

std::optional< Event > BastionGuard::RootGuard::parse_event_json

(

const std::string &

line

)

Definition at line 122 of file RootGuardEvent.cpp.

{
    Event event;
    event.raw_json = line;
 
    const auto event_name = json_string(line, "event");
    const auto verdict = json_string(line, "verdict");
    if (!event_name || !verdict)
        return std::nullopt;
 
    event.received_at = json_string(line, "received_at").value_or("");
    event.event = *event_name;
    event.verdict = *verdict;
    event.pid = as_u32(json_u64(line, "pid"));
    event.tgid = as_u32(json_u64(line, "tgid"));
    event.ppid = as_u32(json_u64(line, "ppid"));
    event.old_euid = as_u32(json_u64(line, "old_euid"));
    event.new_euid = as_u32(json_u64(line, "new_euid"));
    event.rule_id = as_u32(json_u64(line, "rule_id"));
    event.reason_flags = as_u32(json_u64(line, "reason_flags"));
    event.lsm_flags = as_i32(json_i64(line, "lsm_flags"));
    event.auxiliary = as_u32(json_u64(line, "auxiliary"));
    event.device = json_u64(line, "device").value_or(0);
    event.inode = json_u64(line, "inode").value_or(0);
    event.actor_device = json_u64(line, "actor_device").value_or(0);
    event.actor_inode = json_u64(line, "actor_inode").value_or(0);
    event.parent_device = json_u64(line, "parent_device").value_or(0);
    event.parent_inode = json_u64(line, "parent_inode").value_or(0);
    event.actor_start_boottime_ns =
        json_u64(line, "actor_start_boottime_ns").value_or(0);
    event.old_mode = as_u32(json_u64(line, "old_mode"));
    event.new_mode = as_u32(json_u64(line, "new_mode"));
    event.old_uid = as_u32(json_u64(line, "old_uid"));
    event.new_uid = as_u32(json_u64(line, "new_uid"));
    event.old_gid = as_u32(json_u64(line, "old_gid"));
    event.new_gid = as_u32(json_u64(line, "new_gid"));
    event.comm = json_string(line, "comm").value_or("unknown");
    event.parent_comm = json_string(line, "parent_comm").value_or("");
    event.actor_executable = json_string(line, "actor_executable").value_or("");
    event.parent_executable = json_string(line, "parent_executable").value_or("");
    event.filename = json_string(line, "filename").value_or("");
    event.path_resolution = json_string(line, "path_resolution").value_or("basename-only");
    return event;
}

References parse_event_json(), and BastionGuard::RootGuard::Event::raw_json.

Referenced by main(), parse_event_json(), and BastionGuard::RootGuard::anonymous_namespace{RootGuardClient.cpp}::read_recent_events().