ArchiveResult.hpp

1. Overview

The ArchiveResult.hpp header defines the data model used to represent the outcome of a secure archive inspection performed by the BastionGuard archive analysis subsystem.

It introduces:

  • The ArchiveRisk enumeration representing archive threat classifications
  • A helper function for converting risk levels into human-readable strings
  • The ArchiveInspectionResult structure used to store analysis results

This header acts as a shared contract between the archive inspection engine and the application components that consume its results.

2. Dependencies and Includes

#include <string>
  • <string> – standard C++ string support used for textual result fields

3. Risk Classification Model

3.1 ArchiveRisk Enumeration

enum class ArchiveRisk {
    CLEAN = 0,
    SUSPICIOUS,
    MALFORMED,
    EVASIVE
};

The ArchiveRisk enumeration defines the possible threat classifications assigned to an inspected archive.

  • CLEAN – the archive appears valid and no suspicious characteristics were detected
  • SUSPICIOUS – the archive contains elements that may indicate suspicious behavior or structure
  • MALFORMED – the archive structure is invalid or corrupted according to format expectations
  • EVASIVE – the archive appears intentionally crafted to evade analysis tools

The enumeration provides a concise classification system used by the archive inspection engine to communicate risk levels to the application.

3.2 Risk String Conversion

inline const char* archiveRiskToString(ArchiveRisk risk)

Converts a value of ArchiveRisk into a human-readable string representation.

This helper is typically used for:

  • logging and diagnostics
  • UI display of archive analysis results
  • serialization or reporting of inspection outcomes

If an unknown enumeration value is encountered, the function returns "UNKNOWN".

4. ArchiveInspectionResult Structure

struct ArchiveInspectionResult

The ArchiveInspectionResult structure stores the complete output of an archive inspection operation performed by the BastionGuard archive analysis subsystem.

It aggregates operational state flags, structural anomaly indicators, calculated risk metrics, and diagnostic metadata.

4.1 Execution Status Fields

bool success = false;
bool sandbox_timeout = false;
bool sandbox_failed = false;
  • success – indicates whether the inspection process completed successfully
  • sandbox_timeout – indicates that the worker process exceeded the allowed execution time
  • sandbox_failed – indicates that the sandbox or worker execution failed unexpectedly

These fields describe the operational outcome of the inspection environment rather than the archive itself.

4.2 Archive Identification

bool is_zip = false;

Indicates whether the inspected file was recognized as a valid ZIP archive according to the inspection logic.

This flag helps distinguish between invalid archives and files that were not archives to begin with.

4.3 Structural Integrity Indicators

bool stored_size_mismatch = false;
bool header_mismatch = false;
bool invalid_offset = false;
bool overlapping_entries = false;
bool nested_archive = false;

These flags represent structural anomalies detected during archive inspection:

  • stored_size_mismatch – mismatch between stored size values and actual data
  • header_mismatch – inconsistencies between archive headers and entry metadata
  • invalid_offset – invalid or out-of-range file offsets within the archive
  • overlapping_entries – archive entries that overlap in storage layout
  • nested_archive – presence of embedded archives within the inspected container

These indicators help identify archives crafted for obfuscation, corruption, or exploitation attempts.

4.4 Risk Evaluation

int risk_score = 0;
ArchiveRisk risk = ArchiveRisk::CLEAN;
  • risk_score – numeric score representing the severity or quantity of detected issues
  • risk – classification level derived from inspection findings

The risk score is typically calculated based on detected anomalies and may be used to determine the final ArchiveRisk classification.

4.5 Diagnostic and Reporting Fields

std::string reason_code;
std::string detail;
std::string raw_json;
  • reason_code – short machine-readable code explaining the primary detection reason
  • detail – human-readable explanation of the inspection result
  • raw_json – raw JSON output produced by the inspection worker

These fields provide additional context for debugging, logging, or generating detailed reports for the user interface.

5. Data Flow in the Archive Inspection Pipeline

The ArchiveInspectionResult structure is typically produced by an external archive inspection worker and returned to the application through the ArchiveInspector component.

The typical workflow is:

  • an archive file path is submitted for inspection
  • a sandboxed worker analyzes the archive structure
  • analysis results are serialized (commonly as JSON)
  • the data is converted into an ArchiveInspectionResult instance
  • the application interprets the risk level and displays the result

6. Runtime and Security Considerations

  • Untrusted input: archive files must be treated as potentially malicious and analyzed only through sandboxed or isolated processes.
  • Integrity validation: structural anomaly flags help detect archives designed to exploit parser inconsistencies or buffer overflows.
  • Risk scoring: the risk_score should be derived from deterministic rules to ensure consistent classification.
  • Diagnostic transparency: fields such as reason_code and detail should provide meaningful explanations for detected risks.
  • Worker output validation: JSON data returned by the worker must be validated before being parsed into the result structure.
Published on:
Last updated on: