morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[GH-ISSUE #3628] [Feature] Microsoft Office reverse engineering: OLE/OOXML, VBA source and p-code de-stomping, XLM macros, and embedded objects #1351

New issue

Open

opened 2026-10-16 21:04:35 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-16 21:04:35 +00:00

Owner

Originally created by @matbrgz on GitHub (Oct 14, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/3628

Summary

Microsoft Office documents (spanning legacy OLE Compound File Binary .doc, .xls, .ppt and modern OpenXML .docm, .xlsm, .pptm formats) represent the most ubiquitous document ecosystem worldwide. They also constitute the primary initial access vector in targeted cyber attacks, corporate espionage, and malware distribution (via malicious macros, external template injection, embedded OLE packages, and DDE execution).

While REA's issue #3153 introduces read-only Compound File Binary (CFB) inventory for Windows Installer (.msi) packages, that exact CFB parsing foundation can be extended to power comprehensive Microsoft Office Reverse Engineering.

This feature proposal introduces dedicated static analysis for Microsoft Office artifacts:

Unpacking OLE CFB legacy containers and OOXML ZIP packages;
Extracting both compressed VBA source code and decompiling raw VBA P-Code to detect and resolve VBA Stomping;
Parsing legacy Excel 4.0 (XLM) macro sheets and formula de-obfuscation;
Carving embedded OLE objects (\x01Ole10Native, PE binaries, scripts, ActiveX controls);
Auditing external template injection links and Dynamic Data Exchange (DDE) formulas.

Technical Capabilities & Architecture

                                    +-----------------------------------------+
                                    | Input: Office Document (DOC, XLS, PPT,  |
                                    |        DOCM, XLSM, PPTM)                |
                                    +--------------------+--------------------+
                                                         |
                         +-------------------------------+-------------------------------+
                         |                                                               |
                         v                                                               v
           +---------------------------+                                   +---------------------------+
           | OLE CFB Container Parser  |                                   | OOXML Package Reader      |
           | (Reusing #3153 foundation)|                                   | (OPC ZIP & XML relations) |
           +-------------+-------------+                                   +-------------+-------------+
                         |                                                               |
                         +-------------------------------+-------------------------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | vbaProject.bin & Macro Extraction     |
                                     | (MS-OVBA Compressed Source & P-Code)  |
                                     +-------------------+-------------------+
                                                         |
                         +-------------------------------+-------------------------------+
                         |                               |                               |
                         v                               v                               v
           +---------------------------+   +---------------------------+   +---------------------------+
           | VBA P-Code vs Source      |   | Excel 4.0 (XLM) Macro     |   | OLE Object Carving &      |
           | Discrepancy (VBA Stomping)|   | Formula De-obfuscation    |   | External Link Auditing    |
           +-------------+-------------+   +-------------+-------------+   +-------------+-------------+
                                                         |
                                                         v
                                     +---------------------------------------+
                                     | REA Evidence: Security Dossier,       |
                                     | Extracted Scripts & Payload Artifacts |
                                     +---------------------------------------+

1. Container Unpacking & Structure Inventory

OLE Compound File Binary (CFB): Leverage the OLE CFB parser developed for #3153 to parse Sector Allocation Tables (FAT), MiniFAT, and Directory Entries, extracting streams from .doc, .xls, .ppt, and standalone vbaProject.bin files.
OpenXML (OOXML) Packaging: Parse ZIP-based OPC archives (.docm, .xlsm, .pptm), extracting [Content_Types].xml and relationship graphs (.rels).

2. VBA Macro Extraction: Compressed Source & P-Code Decompilation

MS-OVBA Source Stream Decompression: Implement the MS-OVBA decompression algorithm to recover raw VBA macro source code from module streams.
VBA P-Code Extraction & Disassembly:
- Extract compiled P-Code (Performance Code) from module streams and _VBA_PROJECT metadata.
- Disassemble P-Code opcodes (e.g. LitStr, ConcatStr, ArgsCall, MemLd, Branch).
VBA Stomping & Purging Detection:
- Compare decompressed VBA source against disassembled P-Code. Flag documents where the source code is missing, cleared, or disguised (benign dummy code) while the underlying P-Code executes malicious instructions.
Auto-Execution Triggers: Detect standard execution hooks: AutoOpen, AutoExec, Document_Open, Workbook_Open, Auto_Close, and UserForm event handlers.

3. Excel 4.0 (XLM) Macro Sheet Parsing

XLM Formula Recovery: Parse BIFF4/BIFF8 binary records in .xls and xl/macrosheets/*.xml in .xlsm.
De-obfuscation Engine: Trace cell formula evaluation chains (=CHAR(...), =CONCATENATE(...)), detecting suspicious command execution primitives (EXEC, CALL, REGISTER, HALT, RUN).

4. Embedded OLE Objects & Payload Carving

\x01Ole10Native Stream Extraction: Extract embedded native files (executables, DLLs, VBScript, PowerShell, batch scripts) packaged inside OLE containers.
ActiveX & UserForm Controls: Extract embedded ActiveX control properties, CLSIDs, and UserForm binary definitions.

5. External Relationship & DDE Auditing

Remote Template Injection: Inspect word/_rels/settings.xml.rels and general .rels streams, flagging external relationship targets (TargetMode="External") pointing to remote template URLs (http://, https://).
Dynamic Data Exchange (DDE): Detect DDE and DDEAUTO fields used for arbitrary process execution without macro security prompts.

Acceptance Criteria

Introduce analyze_office_document in REA CLI and MCP contracts, accepting legacy binary and modern macro-enabled formats.
Safely decompress VBA source streams across synthetic Word and Excel test fixtures.
Detect VBA Stomping discrepancies between decompressed source and compiled P-code.
Extract embedded OLE payloads (Ole10Native) and report their file types and SHA-256 digests.
Audit external relationship URLs and flag remote template injection vectors in structured evidence.

#3153 [Feature] Inventory Windows Installer (.msi / OLE CFB) packages read-only
#3599 [Feature] Passive DNS extraction and cybersecurity analysis primitives
#3618 [Feature] ActiveX, COM, and OCX reverse engineering

Originally created by @matbrgz on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3628 [![Type: Feature](https://img.shields.io/badge/type-feature-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Domain: Reverse Engineering](https://img.shields.io/badge/domain-reverse_engineering-blueviolet.svg?style=flat-square)](https://github.com/morluto/rea) [![Status: Proposed](https://img.shields.io/badge/status-proposed-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Ecosystem: REA](https://img.shields.io/badge/ecosystem-morluto%2Frea-8A2BE2.svg?style=flat-square)](https://github.com/morluto/rea) ## Summary Microsoft Office documents (spanning legacy OLE Compound File Binary `.doc`, `.xls`, `.ppt` and modern OpenXML `.docm`, `.xlsm`, `.pptm` formats) represent the most ubiquitous document ecosystem worldwide. They also constitute the primary initial access vector in targeted cyber attacks, corporate espionage, and malware distribution (via malicious macros, external template injection, embedded OLE packages, and DDE execution). While REA's issue #3153 introduces read-only Compound File Binary (CFB) inventory for Windows Installer (`.msi`) packages, that exact CFB parsing foundation can be extended to power comprehensive **Microsoft Office Reverse Engineering**. This feature proposal introduces dedicated static analysis for Microsoft Office artifacts: 1. Unpacking OLE CFB legacy containers and OOXML ZIP packages; 2. Extracting both compressed VBA source code and decompiling raw VBA P-Code to detect and resolve **VBA Stomping**; 3. Parsing legacy Excel 4.0 (XLM) macro sheets and formula de-obfuscation; 4. Carving embedded OLE objects (`\x01Ole10Native`, PE binaries, scripts, ActiveX controls); 5. Auditing external template injection links and Dynamic Data Exchange (DDE) formulas. --- ## Technical Capabilities & Architecture ``` +-----------------------------------------+ | Input: Office Document (DOC, XLS, PPT, | | DOCM, XLSM, PPTM) | +--------------------+--------------------+ | +-------------------------------+-------------------------------+ | | v v +---------------------------+ +---------------------------+ | OLE CFB Container Parser | | OOXML Package Reader | | (Reusing #3153 foundation)| | (OPC ZIP & XML relations) | +-------------+-------------+ +-------------+-------------+ | | +-------------------------------+-------------------------------+ | v +---------------------------------------+ | vbaProject.bin & Macro Extraction | | (MS-OVBA Compressed Source & P-Code) | +-------------------+-------------------+ | +-------------------------------+-------------------------------+ | | | v v v +---------------------------+ +---------------------------+ +---------------------------+ | VBA P-Code vs Source | | Excel 4.0 (XLM) Macro | | OLE Object Carving & | | Discrepancy (VBA Stomping)| | Formula De-obfuscation | | External Link Auditing | +-------------+-------------+ +-------------+-------------+ +-------------+-------------+ | v +---------------------------------------+ | REA Evidence: Security Dossier, | | Extracted Scripts & Payload Artifacts | +---------------------------------------+ ``` ### 1. Container Unpacking & Structure Inventory - **OLE Compound File Binary (CFB):** Leverage the OLE CFB parser developed for #3153 to parse Sector Allocation Tables (FAT), MiniFAT, and Directory Entries, extracting streams from `.doc`, `.xls`, `.ppt`, and standalone `vbaProject.bin` files. - **OpenXML (OOXML) Packaging:** Parse ZIP-based OPC archives (`.docm`, `.xlsm`, `.pptm`), extracting `[Content_Types].xml` and relationship graphs (`.rels`). ### 2. VBA Macro Extraction: Compressed Source & P-Code Decompilation - **MS-OVBA Source Stream Decompression:** Implement the MS-OVBA decompression algorithm to recover raw VBA macro source code from module streams. - **VBA P-Code Extraction & Disassembly:** - Extract compiled P-Code (Performance Code) from module streams and `_VBA_PROJECT` metadata. - Disassemble P-Code opcodes (e.g. `LitStr`, `ConcatStr`, `ArgsCall`, `MemLd`, `Branch`). - **VBA Stomping & Purging Detection:** - Compare decompressed VBA source against disassembled P-Code. Flag documents where the source code is missing, cleared, or disguised (benign dummy code) while the underlying P-Code executes malicious instructions. - **Auto-Execution Triggers:** Detect standard execution hooks: `AutoOpen`, `AutoExec`, `Document_Open`, `Workbook_Open`, `Auto_Close`, and UserForm event handlers. ### 3. Excel 4.0 (XLM) Macro Sheet Parsing - **XLM Formula Recovery:** Parse BIFF4/BIFF8 binary records in `.xls` and `xl/macrosheets/*.xml` in `.xlsm`. - **De-obfuscation Engine:** Trace cell formula evaluation chains (`=CHAR(...)`, `=CONCATENATE(...)`), detecting suspicious command execution primitives (`EXEC`, `CALL`, `REGISTER`, `HALT`, `RUN`). ### 4. Embedded OLE Objects & Payload Carving - **`\x01Ole10Native` Stream Extraction:** Extract embedded native files (executables, DLLs, VBScript, PowerShell, batch scripts) packaged inside OLE containers. - **ActiveX & UserForm Controls:** Extract embedded ActiveX control properties, CLSIDs, and UserForm binary definitions. ### 5. External Relationship & DDE Auditing - **Remote Template Injection:** Inspect `word/_rels/settings.xml.rels` and general `.rels` streams, flagging external relationship targets (`TargetMode="External"`) pointing to remote template URLs (`http://`, `https://`). - **Dynamic Data Exchange (DDE):** Detect `DDE` and `DDEAUTO` fields used for arbitrary process execution without macro security prompts. --- ## Acceptance Criteria 1. Introduce `analyze_office_document` in REA CLI and MCP contracts, accepting legacy binary and modern macro-enabled formats. 2. Safely decompress VBA source streams across synthetic Word and Excel test fixtures. 3. Detect VBA Stomping discrepancies between decompressed source and compiled P-code. 4. Extract embedded OLE payloads (`Ole10Native`) and report their file types and SHA-256 digests. 5. Audit external relationship URLs and flag remote template injection vectors in structured evidence. --- ## Related - #3153 [Feature] Inventory Windows Installer (.msi / OLE CFB) packages read-only - #3599 [Feature] Passive DNS extraction and cybersecurity analysis primitives - #3618 [Feature] ActiveX, COM, and OCX reverse engineering

bsakaguchi referenced this issue

2026-10-17 21:01:32 +00:00

[GH-ISSUE #2383] [Tracker] Audit analysis and debugging coverage for the TIOBE top 100 languages (October 2026) #794

bsakaguchi referenced this issue

2026-10-17 21:10:38 +00:00

[PR #1351] [MERGED] fix(javascript): resolve exported callables through lexical bindings #2818

bsakaguchi commented

2026-10-31 00:30:44 +00:00

Author

Owner

@Happy-Zulu commented on GitHub (Oct 28, 2026):

Hello. @matbrgz , would you consider extending this request to cover Microsoft Access databases (.mdb, .accdb, .mde and .accde)? Access applications keep their logic in VBA modules, forms, reports and saved queries inside a single database file, and REA cannot read any of it today.

The VBA part would reuse what this issue already proposes. Access 2000 and later store the VBA project in the MSysAccessStorage system table (Access 97 uses MSysAccessObjects), and the entries in that table rebuild into a Compound File Binary container, from which the modules are extracted with the same MS-OVBA decompression described here. The addition would be a reader for the Jet and ACE database format and its system tables. jetdb (https://github.com/dominion525/jetdb).

For an Access file, a useful result would be:

the object list: tables with their columns, saved queries with their SQL, forms, reports, macros, modules, and linked tables with their sources;
the VBA source of every module, including form and report modules;
all of it read statically, because opening the database in Access runs its AutoExec macro and startup form;
for .mde and .accde files, a report that the source is absent, because Access removes it when it compiles them.

@Happy-Zulu commented on GitHub (Oct 28, 2026): Hello. @matbrgz , would you consider extending this request to cover Microsoft Access databases (.mdb, .accdb, .mde and .accde)? Access applications keep their logic in VBA modules, forms, reports and saved queries inside a single database file, and REA cannot read any of it today. The VBA part would reuse what this issue already proposes. Access 2000 and later store the VBA project in the MSysAccessStorage system table (Access 97 uses MSysAccessObjects), and the entries in that table rebuild into a Compound File Binary container, from which the modules are extracted with the same MS-OVBA decompression described here. The addition would be a reader for the Jet and ACE database format and its system tables. jetdb (https://github.com/dominion525/jetdb). For an Access file, a useful result would be: - the object list: tables with their columns, saved queries with their SQL, forms, reports, macros, modules, and linked tables with their sources; - the VBA source of every module, including form and report modules; - all of it read statically, because opening the database in Access runs its AutoExec macro and startup form; - for .mde and .accde files, a report that the source is absent, because Access removes it when it compiles them.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#1351

No description provided.

Rows
Columns