AntiRansomEngine.hpp

1. Overview

The AntiRansomEngine.hpp header defines the AntiRansomEngine class, an anti-ransomware detection engine based on YARA. The component is designed to operate asynchronously in the background and to emit runtime events (detections, logs, diagnostic messages) toward the GUI layer via sigc::signal.

The engine follows a common pattern used across BastionGuard security subsystems:

  • Dedicated worker thread for continuous or scheduled scanning
  • Atomic lifecycle flag to ensure safe stop semantics
  • YARA rule management using the native libyara API
  • GUI event propagation through a typed signal interface

2. Dependencies and Includes

#include <string>
#include <thread>
#include <atomic>
#include <sigc++/sigc++.h>
#include <yara.h>
  • <string> – used for path handling and event messages
  • <thread> – provides the worker thread executing the main loop
  • <atomic> – ensures thread-safe run-state control
  • sigc++ – signal mechanism used to notify the GUI layer
  • yara.h – YARA C API for compiling/loading rules and scanning targets

3. Class Responsibilities

AntiRansomEngine encapsulates the anti-ransomware scanning workflow, including:

  • Thread lifecycle management via start() and stop()
  • Loading and maintaining compiled YARA rules in memory
  • Scanning files (or scan targets) for YARA rule matches
  • Event emission toward the GUI for detections and operational logs

4. Public Interface

4.1 Constructor and Destructor

AntiRansomEngine();
~AntiRansomEngine();
  • The constructor initializes engine state and prepares internal resources (e.g., setting running_ to a safe initial value and initializing yara_rules_).
  • The destructor must ensure a clean shutdown and resource release: stopping/joining the worker thread and freeing any YARA resources associated with yara_rules_.

4.2 start()

void start();

Starts the engine by enabling the run flag and launching the internal worker thread. The worker thread entrypoint is run().

Expected behavior:

  • Set running_ to true
  • Load and/or validate YARA rules via load_yara_rules() (directly or within run())
  • Create worker_ to execute the monitoring/scanning loop
  • Optionally emit startup status events through sig_event_

4.3 stop()

void stop();

Requests termination of the worker thread and stops scanning operations safely.

Expected behavior:

  • Set running_ to false
  • Ensure run() exits deterministically
  • Join worker_ if joinable
  • Optionally emit shutdown status events

4.4 signal_event()

sigc::signal<void(const std::string&)>& signal_event();

Exposes the engine’s event signal to external subscribers (typically the GUI/controller layer). The signal carries a human-readable message describing detections, logs, and status updates.

  • Payload: std::string (event message)
  • Typical consumers: status labels, log views, notification systems

5. Private Implementation Details

5.1 run()

void run();

Worker thread function implementing the main scanning loop. The loop is expected to continue executing while running_ remains true.

Typical responsibilities:

  • Initialize YARA runtime and ensure rules are loaded
  • Perform periodic scans over configured paths/targets
  • Emit detections and operational logs through sig_event_

5.2 scan_file()

void scan_file(const std::string& path);

Scans a single file at path using the compiled YARA rules stored in yara_rules_. On match, the method is expected to emit a detection event through sig_event_.

Common implementation considerations:

  • Verify file existence/access before scanning
  • Handle YARA scan return codes robustly (errors vs matches)
  • Normalize event output (rule name, file path, severity) for consistent UI display

5.3 load_yara_rules()

void load_yara_rules();

Loads and compiles YARA rules into yara_rules_. The source of rules (directory, bundled resources, or configuration) is implementation-defined.

Expected outcomes:

  • yara_rules_ is set to a valid compiled rules object
  • Any compilation errors are captured and surfaced via sig_event_
  • Previously loaded rules are released safely before replacing (to avoid leaks)

6. Internal State

std::atomic<bool> running_;
std::thread worker_;
YR_RULES* yara_rules_;
sigc::signal<void(const std::string&)> sig_event_;
  • running_ – atomic flag controlling thread execution
  • worker_ – background thread responsible for scanning
  • yara_rules_ – pointer to compiled YARA rules in memory
  • sig_event_ – signal used to publish events to the GUI

7. Runtime, Concurrency, and Security Considerations

  • Thread safety: if events are emitted from the worker thread, GTK UI updates must be marshaled onto the main thread (e.g., via Glib::signal_idle() or a dispatcher), in compliance with GTK threading rules.
  • Deterministic shutdown: run() should avoid unbounded blocking and must check running_ regularly to ensure stop() can complete promptly.
  • YARA resource lifecycle: compiled rules must be freed correctly using the proper YARA API to prevent memory leaks and dangling pointers.
  • Scan surface control: file scanning should enforce path validation and avoid following unsafe symlinks if the scan targets are user-influenced.
  • Operational transparency: detection and error messages should be structured consistently (rule name, file path, timestamp) to support troubleshooting and auditability.

8. Integration Notes

  • Signal subscription: consumers should connect to signal_event() once per instance and route messages to logging/UI components.
  • Rule reload policy: if rules can change at runtime, implement a safe reload strategy (stop scanning, reload rules, resume) or use synchronization to avoid scanning with partially updated rules.
Published on:
Last updated on: