feat: introduce \ooxml module for inspecting OOXML documents - #803

feat: introduce ooxml module for inspecting OOXML documents

This PR adds an ooxml module that parses the ZIP central directory of Office
Open XML documents (DOCX, XLSX, PPTX) and other ZIP archives, and exposes the
metadata of every entry. It's a port of an OOXML module I wrote for YARA 4.x
(RustyNoob-619/YARA — Modules/OOXML).

Like olecf, vba and msi, it is experimental and not in the default
modules; it's enabled with the ooxml-module feature.

Why

Weaponised Office documents remain one of the most common initial-access
vectors. Besides content, the ZIP metadata of a document carries a fingerprint
of the tool that built it: MS-DOS timestamps, host OS and ZIP version in
"version made by", flags, CRC-32s, entry ordering. These are useful for
clustering documents produced by the same builder, and for spotting
inconsistencies (e.g. on-disk vs. total entry counts, odd compression
methods, archive comments).

What it exposes

• is_ooxml (bool): true if one of the entries is [Content_Types].xml, false
  for other ZIP archives, undefined if the file isn't a ZIP archive.
• number_of_on_disk_entries, number_of_total_entries, central_dir_size,
  central_dir_offset, zip_comment_len, zip_comment_str.
• entries[]: name_string, name_length, compressed_size,
  uncompressed_size, crc32_checksum, compression_method_value,
  compression_method_name, mod_time_raw, mod_date_raw, flags,
  version_needed, version_made_by, os_name, spec_version.

Relationship with the zip module

The existing zip module exposes each entry's path, compression method and
sizes. ooxml focuses on the central directory metadata that zip doesn't
expose (CRC-32, timestamps, flags, ZIP versions, host OS, entry counts, central
directory location, archive comment) and on recognising OOXML documents. If
you'd prefer these fields to be added to zip instead of living in a separate
module, I'm happy to rework the PR that way.

Behaviour

• Only files starting with a local file header (PK\x03\x04) are parsed, as
  in the original module.
• The end of central directory record is searched backwards from the end of
  the file and accepted only if its comment ends exactly at the end of the
  file; comments up to the maximum 65,535 bytes are supported.
• Parsing stops at the first malformed central directory header; entries
  parsed until then are kept, so number_of_total_entries may exceed the
  number of entries.
• Entry names are exposed as raw bytes (they aren't guaranteed to be UTF-8).
• Nothing is decompressed, and all reads are bounds-checked.

Files

Following the layout of the zip module commit (e050078):

• lib/src/modules/protos/ooxml.proto (with field comments for
  field_docs.rs)
• lib/src/modules/ooxml/mod.rs
• lib/src/modules/ooxml/tests/mod.rs and tests/testdata/<sha256>.in.zip /
  <sha256>.out, prepared as described in the Module Developer's Guide
  (objcopy -I binary -O ihex, then zip); all inputs are synthetic and
  benign, and each is described next to its hash in tests/mod.rs
• lib/Cargo.toml: ooxml-module feature, listed as experimental in
  default-modules
• Generated: modules.rs, protos/generated/{mod.rs,ooxml.rs}, and the
  ooxml entries in field_docs.rs (only those; I didn't regenerate the
  whole file); one line in add_modules.rs, as done for msi.
• Second commit: site/content/docs/modules/ooxml.md. Happy to drop it while
  the module is experimental.
• Third commit: yr dump support (yr dump --module ooxml), mirroring the
  commit that added zip to dump (3bbe876): mods.proto,
  lib/src/modules/mod.rs (re-exports and invoke_all),
  cli/src/commands/dump.rs, and the regenerated protos/generated/mods.rs.
  Without the ooxml-module feature, dump --module ooxml prints nothing,
  as with the other optional modules.

Testing

• cargo test -p yara-x --features ooxml-module --lib: 340 passed (6 new rule
  tests plus the golden-file test over the new testdata).
• cargo test -p yara-x --lib (default features): 334 passed; default builds
  are unaffected.
• cargo test -p yara-x-cli --bin yr --features yara-x/ooxml-module
  (with CARGO_BIN_EXE_yr set): 56 passed.
• cargo fmt --all --check and
  cargo clippy -p yara-x -p yara-x-cli --features yara-x/ooxml-module --tests --no-deps -- --deny clippy::all:
  clean.
• Parity with the original YARA 4.x module (with two bug fixes applied to it):
  identical module output on 50 files (real DOCX/XLSX/PPTX, plain and crafted
  ZIPs, truncated archives, ZIP64, non-ZIP files — 923,608 values) and
  identical rule results on 28 rules; the only difference is that this
  version also handles a maximum-length (65,535-byte) archive comment, which
  the original missed.