AurScan.hpp

1. Overview

The AurScan.hpp header declares the AurScan namespace, which provides functionality for detecting and monitoring Arch Linux–based systems and scanning PKGBUILD files for security or policy-related analysis.

This module is designed to integrate with BastionGuard’s logging and event pipeline through user-supplied callbacks, enabling real-time feedback to the GUI or logging subsystems without hard dependencies on UI frameworks.

2. Dependencies and Includes

#include <string>
#include <functional>
  • <string> – used for file paths and log/event messages
  • <functional> – provides std::function for callback injection

3. Namespace Scope

namespace AurScan { ... }

All functionality is encapsulated inside the AurScan namespace to avoid symbol collisions and to clearly group Arch/AUR-specific scanning logic.

4. Platform Detection

4.1 isArchBased()

bool isArchBased();

Determines whether the current system is based on Arch Linux. This function is typically used as a guard to enable or disable AUR-specific functionality at runtime.

Possible detection strategies (implementation-defined) include:

  • Checking distribution identifiers in /etc/os-release
  • Presence of Arch-specific files or directories
  • Verification of package manager availability (e.g., pacman)

Return value: true if the system is Arch-based, false otherwise.

5. Initialization and Callbacks

5.1 initialize()

void initialize(
    std::function<void(const std::string&)> logCallback,
    std::function<void(const std::string&)> pkgbuildDetectedCallback);

Initializes the AUR scanning subsystem and registers callback functions used for logging and detection events.

  • logCallback – invoked to report informational messages, warnings, or errors to the caller
  • pkgbuildDetectedCallback – invoked when a PKGBUILD file is detected or analyzed

This design decouples the scanning logic from any specific UI or logging implementation and allows seamless integration with GTKmm, Qt, or CLI frontends.

6. Monitoring Lifecycle

6.1 startMonitoring()

void startMonitoring();

Starts background monitoring for AUR-related activity. Depending on the implementation, this may include:

  • Watching filesystem paths for new or modified PKGBUILD files
  • Monitoring build directories used by AUR helpers
  • Triggering automatic scans on detection

6.2 stopMonitoring()

void stopMonitoring();

Stops the background monitoring process and releases any associated resources. This function should be safe to call multiple times and must ensure deterministic shutdown behavior.

7. On-Demand Scanning

7.1 scanPKGBUILD()

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

Performs an explicit scan of a PKGBUILD file located at the given path.

  • path – filesystem path to the PKGBUILD file

The function is expected to:

  • Validate file existence and readability
  • Analyze the file for potentially dangerous or suspicious constructs
  • Invoke pkgbuildDetectedCallback upon detection
  • Report progress and errors via logCallback

8. Runtime and Design Considerations

  • Platform gating: callers should verify isArchBased() before enabling AUR scanning features in the UI.
  • Callback thread context: callbacks may be invoked from background threads; GUI implementations must marshal updates to the main thread.
  • Security posture: scanning should treat PKGBUILD files as untrusted input and avoid executing any embedded commands.
  • Extensibility: the callback-based design allows future extension with additional event types without API breakage.
Published on:
Last updated on: