MalwareBazaar.hpp

1. Overview

The MalwareBazaar.hpp header defines the data structures and interfaces used to integrate BastionGuard with cloud-based malware intelligence services, specifically MalwareBazaar / VirusTotal-style reputation systems.

This component enables the application to perform hash-based threat lookups against remote databases, enriching local detection results with external intelligence.

Functionally, this module provides:

  • SHA-256 hashing of scanned files
  • Remote malware reputation lookups
  • Structured result reporting
  • Centralized API key management
  • Cloud intelligence integration for ScanPage
  • Support for hybrid local/cloud detection workflows

2. Dependencies and Includes

#include <string>
  • <string> – hash values, malware names, file types, and tags

3. Data Structures

3.1 MalwareBazaar Result Structure

struct MBResult {
    bool found = false;
    std::string malwareName;
    std::string fileType;
    std::string tags;
};

Represents the result of a cloud reputation lookup. It encapsulates both detection status and metadata returned by the service.

  • found – indicates whether the hash was found in the database
  • malwareName – reported malware family or signature
  • fileType – detected file format
  • tags – classification tags and attributes

4. Global API Key Handling

4.1 API Key Loader

void loadCloudApiKeys();

Loads cloud service API keys from persistent configuration storage into global runtime variables.

4.2 Global API Key Variable

extern std::string globalMalwareBazaarApiKey;

Stores the active MalwareBazaar / VirusTotal API key in memory. This variable is shared across cloud lookup operations.

The key is typically loaded during application startup and refreshed when configuration changes.

5. Class Declaration and Scope

class MalwareBazaar

The class is implemented as a static utility container. All methods are static, and no instances are created.

This design simplifies access from scanning, monitoring, and cloud integration subsystems.

6. Public Interface

6.1 API Key Configuration

static void setApiKey(const std::string& key);

Registers the API key to be used for subsequent cloud queries. This overrides any previously loaded key.

  • key – authentication token issued by the cloud provider

6.2 Hash Lookup

static MBResult lookupHash(const std::string& sha256);

Queries the cloud intelligence service using a SHA-256 hash and returns structured reputation data.

  • sha256 – hexadecimal SHA-256 digest of the file
  • Return value – populated MBResult structure

If the hash is not found or the service is unreachable, found is set to false.

6.3 File Hashing Helper

static std::string sha256_file(const std::string& filepath);

Computes the SHA-256 digest of a local file. This method is primarily used by ScanPage before invoking cloud lookups.

  • filepath – absolute or relative path to the file
  • Return value – hexadecimal SHA-256 string

7. UI Components

This module does not define any graphical UI components. It operates as a backend service used by scanning and reporting interfaces.

8. Internal State and Data Model

The primary runtime state consists of:

  • Active API key (stored in globalMalwareBazaarApiKey)
  • Temporary lookup results
  • Internal HTTP/JSON parsing structures (implementation-defined)

No persistent state is stored directly in this class.

9. Internal Logic

9.1 Lookup Workflow

A typical cloud lookup follows these steps:

  • Compute SHA-256 hash using sha256_file()
  • Validate API key availability
  • Build authenticated HTTP request
  • Send request to MalwareBazaar / VirusTotal endpoint
  • Parse JSON response
  • Populate MBResult
  • Return structured result to caller

9.2 API Key Management

API keys are loaded at startup via loadCloudApiKeys(), cached in memory, and optionally updated through user settings.

Keys are never stored in plaintext within this module.

10. Integration with Scanning Engine

MalwareBazaar is primarily used by:

  • ScanPage – for cloud-assisted detection
  • Realtime monitoring subsystems
  • Infected file handling workflows
  • Alert generation logic

Cloud lookups complement local antivirus signatures and heuristic detection.

11. Settings Storage

API keys and cloud preferences are stored externally, typically under:

~/.config/BastionGuard/cloud.json
~/.config/BastionGuard/scan.conf

Only encrypted or keyring-backed references should be persisted.

12. Runtime and Security Considerations

  • Credential protection: API keys must be stored securely and never logged or exposed in UI output.
  • Network security: all requests must use HTTPS with certificate validation.
  • Privacy compliance: users should be informed before uploading file hashes to third-party services.
  • Rate limiting: cloud APIs enforce quotas; lookups should be cached and throttled.
  • Fail-safe behavior: local protection must remain active if cloud services are unavailable.
  • Data minimization: only hashes, never full files, should be transmitted.
  • Auditability: cloud lookups should be traceable for troubleshooting and compliance.
Published on:
Last updated on: