Backend Core Services

1. Overview

The Backend module represents the core orchestration layer of BastionGuard. It centralizes antivirus management, ransomware detection, phishing protection, firewall integration, Samba scanning, quarantine handling, update mechanisms, and multiple configuration subsystems.

The class operates as a singleton (Backend::instance()) and acts as the bridge between GTK UI components, system services, network subsystems, and security engines.

The module integrates:

  • ClamAV / clamd / clamdscan – antivirus engine
  • systemd – service lifecycle control
  • libsmbclient – SMB remote scanning
  • libcurl – remote downloads (Safe Browsing, bank list)
  • libsoup (indirect) – update operations
  • nlohmann::json – structured configuration files
  • dnsmasq – phishing DNS enforcement
  • FirewallRuleManager / BlacklistIpExtractor – firewall integration
  • D-Bus – ransomware alert signaling

2. Core Architecture

2.1 Singleton Pattern

The backend is instantiated via:

Backend& Backend::instance()

This ensures a single orchestration layer for the entire application lifecycle.

2.2 Versioning

Compile-time macros:

  • BASTIONGUARD_VERSION
  • BASTIONGUARD_BUILD

Fallback values are provided if macros are undefined.

3. Antivirus Integration

3.1 Clamonacc (On-Access)

Supported services:

  • clamav-clamonacc.service
  • clamonacc.service

Capabilities:

  • Enable/disable real-time scanning
  • Service detection via systemctl
  • Journal log extraction
  • OnAccessIncludePath parsing

3.2 Database Metadata

Database inspection reads:

  • daily.cvd / daily.cld
  • main.cvd / main.cld

Extracted information:

  • Version number
  • Signature release date
  • Last modification timestamp

4. Anti-Ransomware Subsystem

4.1 Service Control

User-scoped service:

BastionGuard-ransomware-scanner.service

Controlled via:

systemctl --user

4.2 YARA Rules Update

Source:

https://github.com/reversinglabs/reversinglabs-yara-rules

Workflow:

  • Download to user runtime directory
  • Integrity validation (size + block detection)
  • System-wide installation via pkexec

4.3 Sanesecurity Database

Downloaded from:

https://sanesecurity.com/clamav/

Files include:

  • scamsigs.hdb
  • phish.ndb
  • ransomware.ndb

4.4 D-Bus Alert Channel

Interface:

org.BastionGuard.Ransomware.Alert

Used to emit UI alerts when infected files are detected.

5. Anti-Phishing Subsystem

5.1 Blacklist Aggregation

Sources:

  • phishing.army
  • openphish.com
  • urlhaus.abuse.ch

Processing:

  • Deduplication
  • URL normalization
  • Whitelist filtering
  • IP extraction

5.2 DNS Enforcement (dnsmasq)

Generated configuration:

/etc/dnsmasq.d/BastionGuard-blacklist.conf

Blocking rule format:

address=/domain/127.0.0.2

5.3 Google Safe Browsing

Optional integration using:

https://safebrowsing.googleapis.com

Features:

  • API key storage
  • Connectivity test via CURL
  • Configuration persistence

6. Firewall Integration

6.1 Supported Backends

  • UFW
  • firewalld

Automatic detection and persistent configuration.

6.2 IP Extraction Pipeline

Workflow:

  • BlacklistIpExtractor extracts valid IPs
  • Temporary file generation
  • Deferred privileged application

7. Samba (SMB) Scanning Engine

7.1 SMB Context Management

Uses libsmbclient with per-thread context creation:

SMBCCTX*

7.2 Credential Handling

Storage:

~/.config/BastionGuard/cred.conf

Protection:

  • XOR obfuscation
  • Base64 encoding

7.3 Scan Workflow

  • Recursive enumeration
  • Temporary copy to local directory
  • clamdscan execution
  • Alert emission for infected files

8. Quarantine Management

8.1 Default Location

~/.local/share/BastionGuard/quarantine

8.2 Operations

  • Atomic rename
  • Fallback copy if rename fails
  • Permission enforcement
  • GTK confirmation dialog

9. Whitelist and Bank List

9.1 Whitelist

Stored in:

~/.config/BastionGuard/whitelist.json

Supports:

  • Add / Remove
  • Duplicate prevention
  • JSON persistence

9.2 Bank List

Downloaded via CURL into:

~/.local/share/BastionGuard/banks.json

10. Runtime and Security Considerations

  • Privilege separation: pkexec used only for system-level writes
  • Asynchronous firewall scheduling: delayed apply prevents bursts
  • SMB isolation: temporary directory scan model
  • Whitelist precedence: bank and infra domains protected
  • Fail-safe networking: timeouts and validation enforced
  • Graceful degradation: missing components do not crash backend

11. Operational Summary

The Backend module is the central security control plane of BastionGuard. It orchestrates antivirus scanning, ransomware detection, phishing enforcement, firewall blocking, SMB scanning, quarantine operations, update distribution, and configuration persistence within a unified and extensible architecture.

The implementation emphasizes modular isolation, privilege separation, controlled asynchronous execution, and system-level integration consistency.

Published on:
Last updated on: