Quarantine.hpp

1. Overview

The Quarantine.hpp header defines the Quarantine utility class, a static service component responsible for managing isolated file storage within BastionGuard. The class implements controlled workflows for moving suspicious files into a protected quarantine directory, restoring them when authorized, and permanently removing them when required.

Functionally, Quarantine provides:

  • Safe relocation of potentially malicious files into quarantine
  • Automatic generation and use of metadata files (.meta)
  • Restoration of quarantined files to their original locations
  • Secure deletion of quarantined items and related metadata
  • Centralized access to the active quarantine directory path

2. Dependencies and Includes

#include <string>
  • <string> – file paths and metadata references

3. Class Declaration and Scope

class Quarantine

The class is defined as a static utility container. All exposed operations are declared static, and no instance of Quarantine is intended to be created.

4. Public Interface

4.1 Move to Quarantine

static bool move(const std::string& file);

Relocates a file into the configured quarantine directory and generates a corresponding .meta file containing the original file path and related metadata.

  • file – absolute or relative path to the file being quarantined
  • Return value – true on success, false on failure

4.2 Restore from Quarantine

static bool restore(const std::string& quarantinedFile);

Restores a previously quarantined file to its original location using the information stored in the associated .meta file.

  • quarantinedFile – path to the quarantined file inside the quarantine directory
  • Return value – true if restoration succeeds, false otherwise

4.3 Permanent Removal

static bool remove(const std::string& quarantinedFile);

Permanently deletes a quarantined file and its associated .meta metadata file. This operation is irreversible and should only be performed after explicit user confirmation.

  • quarantinedFile – path to the quarantined file to be deleted
  • Return value – true on successful deletion, false on error

4.4 Quarantine Directory Lookup

static std::string getQuarantinePath();

Returns the filesystem path of the currently configured quarantine directory. This path is used as the root container for all isolated files and metadata.

5. UI Components

This component does not define any user interface elements. It is designed to be invoked by higher-level UI pages (for example, quarantine management views) and backend services.

6. Internal State and Data Model

The header does not expose internal state. The implementation is expected to manage:

  • The location and structure of the quarantine directory
  • Metadata file format and parsing
  • File naming and collision avoidance policies
  • Permission and ownership handling

7. User Actions (Callbacks)

This class does not define UI callbacks. It operates as a backend utility invoked by controllers and UI components.

8. Internal Logic

8.1 Metadata Management

For each quarantined file, a companion .meta file is created. This file typically stores:

  • The original filesystem path
  • Timestamps of quarantine and restoration events
  • Optional hash or integrity information

The metadata file is used as the authoritative source when restoring files.

8.2 File Relocation and Integrity

The move() operation should preserve file integrity by using atomic rename/move operations where possible. If cross-filesystem moves are required, copy-and-verify semantics should be employed.

9. Auto-Update (Scheduled Refresh)

This component does not implement scheduled tasks or timers.

10. Settings Storage

The quarantine path returned by getQuarantinePath() may be derived from application configuration files, environment variables, or system defaults. The exact storage mechanism is implementation-defined.

11. Helper Functions and Filesystem Layout

The quarantine directory is expected to follow a consistent internal layout, for example:

~/.local/share/BastionGuard/quarantine/
  ├── file_001.bin
  ├── file_001.bin.meta
  ├── file_002.bin
  └── file_002.bin.meta

This layout ensures a one-to-one mapping between quarantined files and their metadata.

12. Runtime and Security Considerations

  • Access control: quarantine directories must be protected by strict filesystem permissions to prevent unauthorized access or tampering.
  • Integrity validation: restored files should be validated (hash/signature) before being reintroduced into the system.
  • Atomic operations: use temporary files and rename semantics to reduce the risk of corruption during move/restore operations.
  • Auditability: quarantine, restore, and delete operations should be logged for security auditing and incident response.
  • User confirmation: irreversible deletion via remove() should always be gated behind explicit user consent in the UI.
Published on:
Last updated on: