Archive Worker

1. Overview

The Archive Worker module is a standalone inspection utility used by BastionGuard to analyze archive files (currently focused on the ZIP format) and detect structural anomalies that may indicate malware evasion techniques, archive corruption, or suspicious packaging patterns.

The tool performs a low-level structural analysis of ZIP archives without extracting the contents. It parses the ZIP container format directly and evaluates internal consistency between the central directory and local file headers.

The output is emitted as structured JSON, allowing seamless integration with BastionGuard’s scanning pipeline and decision engine.

2. Architecture

The Archive Worker is implemented as a lightweight command-line utility written in C++ and uses standard library facilities for filesystem access and binary parsing.

The module operates independently and can be invoked by higher-level BastionGuard components when an archive file is encountered during scanning.

Primary architectural goals:

  • No archive extraction required
  • Minimal runtime dependencies
  • Safe parsing of binary structures
  • Deterministic risk scoring

3. ZIP Structure Analysis

The worker validates ZIP archives by analyzing the structural components defined by the ZIP specification.

Important signatures parsed during inspection:

  • Local File Header (0x04034b50)
  • Central Directory Header (0x02014b50)
  • End of Central Directory (0x06054b50)

The worker searches for the End of Central Directory (EOCD) record by scanning the final portion of the archive file, as permitted by the ZIP specification (maximum comment length of 65535 bytes).

4. Header Validation

For each entry listed in the central directory, the worker validates the corresponding local file header.

The following fields are cross-checked:

  • Filename consistency
  • Compression method
  • Compressed size
  • Uncompressed size

If discrepancies are detected between the central directory and the local file header, the archive is flagged with a header mismatch condition.

5. Structural Anomaly Detection

The module performs several structural checks designed to detect malformed or evasive archives.

5.1 Invalid Offsets

Entries pointing outside the archive file boundaries are treated as invalid and contribute to the risk score.

5.2 Overlapping Entries

The worker sorts archive entries by data offset and detects overlapping data ranges. Overlapping entries are commonly used in evasive archive techniques.

5.3 Stored Size Mismatch

If an entry uses the STORED method (no compression) but reports different compressed and uncompressed sizes, the archive is flagged as suspicious.

6. Path Safety Checks

Archive filenames are analyzed for potentially dangerous path patterns.

The worker detects:

  • Directory traversal paths (../)
  • Absolute paths
  • Windows drive paths (C:\)

These patterns may indicate attempts to exploit extraction routines.

7. Nested Archive Detection

The module checks entry filenames for nested archive extensions.

Supported detection patterns include:

  • .zip
  • .rar
  • .7z
  • .tar
  • .gz
  • .tgz
  • .bz2
  • .xz

Nested archives may indicate attempts to hide malicious payloads within multiple archive layers.

8. Risk Scoring System

The worker assigns a numeric risk score based on the anomalies detected during parsing.

Example scoring logic:

  • Invalid offsets – high severity
  • Overlapping entries – high severity
  • Header mismatch – medium severity
  • Stored size mismatch – medium severity
  • Nested archive – low severity

The final classification is derived from the cumulative score:

  • CLEAN
  • SUSPICIOUS
  • EVASIVE
  • MALFORMED

9. JSON Output

The worker emits structured JSON containing detection flags and risk metadata.

{
"is_zip": true,
"stored_size_mismatch": false,
"header_mismatch": false,
"invalid_offset": false,
"overlapping_entries": false,
"nested_archive": true,
"risk_score": 15,
"risk": "SUSPICIOUS",
"reason_code": "ZIP_NESTED_ARCHIVE",
"detail": "nested archive detected"
}

10. Security Considerations

  • No archive extraction is performed
  • Binary parsing is bounds-checked against file size
  • Offset validation prevents out-of-bounds reads
  • All anomalies contribute to deterministic risk scoring

These measures ensure safe analysis of potentially malicious archive files while minimizing attack surface.

Published on:
Last updated on: