ArchiveInspector

1. Overview

The ArchiveInspector module provides a thin orchestration layer for archive inspection inside BastionGuard. Its role is to identify supported archive paths and delegate the actual analysis to a sandboxed worker through the archive sandbox subsystem.

The class is intentionally minimal: it stores the path of the worker executable, keeps the configured sandbox timeout, exposes a helper to recognize ZIP-like paths, and forwards inspection requests to the sandbox execution routine.

The module integrates with:

  • ArchiveSandbox – executes the actual archive analysis in an isolated environment through analyze_archive_in_sandbox(...)
  • ArchiveInspectionResult – structured result returned to callers after sandbox inspection
  • Standard C++ string handling – worker path storage, path normalization, and extension checks
  • Standard algorithms – lowercasing and suffix comparison for archive-type heuristics

2. Class Responsibilities

ArchiveInspector acts as a coordination object with two primary responsibilities:

  • Maintain the runtime parameters needed to invoke the sandboxed archive worker
  • Expose a simple archive inspection API that forwards requests to the sandbox layer

The actual unpacking, traversal, threat analysis, or nested inspection logic is not implemented inside this class. That behavior is delegated completely to the sandbox-side worker.

3. Construction and Stored State

The constructor accepts two runtime parameters:

  • worker_path – path to the archive inspection worker executable or helper
  • sandbox_timeout_seconds – execution timeout applied to the sandboxed inspection process

These values are stored internally as:

  • worker_path_
  • timeout_seconds_

The constructor uses move semantics for the worker path:

ArchiveInspector::ArchiveInspector(std::string worker_path, int sandbox_timeout_seconds)
    : worker_path_(std::move(worker_path)),
      timeout_seconds_(sandbox_timeout_seconds) {}

This avoids an unnecessary string copy when the caller passes a movable path value.

4. Archive-Type Heuristic

4.1 ZIP Path Detection

The helper method looks_like_zip_path(const std::string& path) performs a simple filename-based heuristic to determine whether an input path appears to reference a ZIP archive.

The logic:

  • Rejects paths shorter than 4 characters
  • Creates a lowercase copy of the full input string
  • Checks whether the final 4 characters are exactly .zip

This makes the check case-insensitive, so names such as sample.zip, SAMPLE.ZIP, or Test.Zip are all treated as ZIP-like paths.

4.2 Scope of the Heuristic

This helper is purely suffix-based. It does not:

  • Read file headers or magic bytes
  • Validate that the file actually exists
  • Verify archive integrity
  • Support other archive extensions in the current implementation

As a result, it should be interpreted as a lightweight UI or routing heuristic rather than a definitive archive format detector.

5. Sandboxed Inspection Flow

5.1 Public Inspection Method

The method inspect(const std::string& input_path) const is the class’s main execution entry point. It forwards the request to the archive sandbox layer and returns an ArchiveInspectionResult.

The implementation is a direct delegation:

return analyze_archive_in_sandbox(worker_path_, input_path, timeout_seconds_);

This means the inspector itself does not parse, unpack, or analyze the archive locally. Instead, it relies on the sandbox subsystem to perform the inspection under isolation and timeout constraints.

5.2 Parameters Passed to the Sandbox

Each inspection request passes three parameters to the sandbox layer:

  • worker_path_ – the helper binary or worker responsible for archive analysis
  • input_path – the archive file to inspect
  • timeout_seconds_ – the maximum allowed runtime for the sandboxed analysis

This design cleanly separates high-level orchestration from low-level sandbox execution.

6. Design Characteristics

  • Thin abstraction: the class is intentionally lightweight and does not duplicate sandbox logic
  • Single-purpose behavior: its main purpose is to route archive inspection requests into the sandbox layer
  • Case-insensitive ZIP detection: ZIP path recognition is normalized through lowercase transformation
  • Execution isolation: actual archive inspection is delegated to an isolated sandbox worker rather than performed inline
  • Timeout-aware inspection: every analysis request carries an explicit execution timeout

7. Runtime and Security Considerations

  • Sandbox-first execution: archive analysis is not performed directly in the current process, reducing exposure to malformed or hostile archive payloads
  • Worker-path dependency: correct behavior depends on the validity and availability of the configured worker executable
  • Timeout enforcement: the sandbox timeout provides a safeguard against hangs, decompression bombs, or excessively slow archive traversal
  • Heuristic extension check: ZIP recognition is filename-based only and should not be treated as a trusted format validation mechanism
  • Delegated trust boundary: the trust and safety properties of inspection depend primarily on the implementation of analyze_archive_in_sandbox(...) and the worker it launches
Published on:
Last updated on: