ArchiveInspector.hpp

1. Overview

The ArchiveInspector.hpp header defines the ArchiveInspector class, a utility component responsible for performing secure archive inspection through a dedicated external worker process. Its purpose is to analyze archive files (such as ZIP containers) within a sandboxed environment and return structured results describing the inspection outcome.

Functionally, ArchiveInspector provides:

  • Delegated archive analysis through a sandbox worker executable
  • Configurable execution timeout for the inspection process
  • Structured inspection results returned through ArchiveInspectionResult
  • Utility methods for identifying archive-like file paths

The class is designed to isolate potentially unsafe archive processing from the main application runtime by relying on a separate worker component.

2. Dependencies and Includes

#include "ArchiveResult.hpp"
#include <string>
  • ArchiveResult.hpp – defines the ArchiveInspectionResult data structure returned by the inspection process
  • <string> – standard C++ string support for file paths and configuration values

3. Class Declaration and Scope

class ArchiveInspector

The ArchiveInspector class is a lightweight inspection controller that manages communication with an external archive-analysis worker.

The design isolates archive parsing and extraction logic from the main application process to reduce the attack surface associated with malicious or malformed archive files.

4. Public Interface

4.1 Constructor

explicit ArchiveInspector(std::string worker_path, int sandbox_timeout_seconds = 10);

Initializes the archive inspection component with the path to the worker executable responsible for performing the sandboxed inspection.

  • worker_path – filesystem path to the archive inspection worker
  • sandbox_timeout_seconds – maximum allowed execution time for the worker process before termination

The timeout parameter prevents indefinitely running inspections caused by malformed archives or unexpected worker behavior.

4.2 Archive Inspection

ArchiveInspectionResult inspect(const std::string& input_path) const;

Performs inspection of the archive located at the specified file path.

The method delegates the analysis to the configured worker process and returns a structured ArchiveInspectionResult describing the outcome of the inspection.

The returned result may include information such as:

  • archive validity
  • detected file entries
  • security indicators
  • analysis status or error conditions

The method is declared const, indicating that the inspection operation does not modify the internal configuration state of the ArchiveInspector instance.

4.3 Archive Path Detection

static bool looks_like_zip_path(const std::string& path);

Utility helper used to determine whether a given filesystem path appears to reference a ZIP archive.

The method typically performs extension-based heuristics (for example checking .zip suffixes) and is intended for preliminary filtering before initiating a full archive inspection.

Since the function is static, it can be used independently of an instantiated ArchiveInspector object.

5. Internal State

std::string worker_path_;
int timeout_seconds_ = 10;
  • worker_path_ – filesystem path to the external archive inspection worker responsible for executing sandboxed analysis
  • timeout_seconds_ – maximum allowed runtime of the worker process before it is forcibly terminated

These fields define the runtime configuration used when invoking the archive analysis worker.

6. Worker Execution Model

ArchiveInspector follows a process-isolation model in which archive inspection is delegated to an external executable rather than executed directly inside the main process.

This architecture offers several advantages:

  • reduced exposure to archive parsing vulnerabilities
  • controlled execution environment through sandboxing
  • enforced execution time limits
  • clear separation between application UI and analysis engine

The worker process is expected to receive the archive path, perform analysis, and produce a result compatible with the ArchiveInspectionResult structure.

7. Runtime and Security Considerations

  • Sandbox isolation: archive inspection should occur inside a restricted execution environment to mitigate risks from malicious archive payloads.
  • Execution timeout: the configured timeout prevents denial-of-service scenarios caused by archives designed to stall extraction or analysis.
  • Path validation: input archive paths should be validated before being passed to the worker to avoid unintended filesystem access.
  • Worker trust boundary: the worker executable should be verified and protected against tampering, as it executes archive parsing logic outside the main application.
  • Graceful failure handling: unexpected worker termination or timeout conditions should return structured error information through ArchiveInspectionResult.
Published on:
Last updated on: