olefile

olefile is a pure Python module used to parse, read, and write Microsoft OLE2 files (also known as Compound File Binary Format or Structured Storage).

Key capabilities include:

• Parsing and reading legacy Microsoft Office formats (Word .doc, Excel .xls, PowerPoint .ppt, etc.), MSI files, and Outlook messages.
• Listing all streams and storages within an OLE file.
• Opening streams as files.
• Parsing and reading property streams containing file metadata.

Note: olefile is a low-level library intended for developers. For higher-level tools focused on malware analysis and forensics, consider using python-oletools, which is built upon olefile.

olefile is a pure Python module designed to parse, read, and write OLE (Object Linking and Embedding) files. It supports a wide range of legacy formats including:

• Microsoft Office 97-2003 formats (.doc, .xls, .ppt, .vsd, .mpp)
• Outlook messages
• StickyNotes
• Image Composer and FlashPix files
• Zeiss AxioVision ZVI files
• Olympus FluoView OIB files

Key functional capabilities include:

• Listing all streams and storages within an OLE file.
• Opening streams as file-like objects.
• Parsing and reading property streams (metadata).
• Operating as a portable module with no external dependencies.

Decide which library to use based on your technical requirements:

• Use olefile if you are a developer needing a low-level, pure Python library to programmatically parse, read, or write OLE structures and streams.
• Use python-oletools if you need high-level tools for analyzing OLE files or extracting data, specifically for security-focused tasks like malware analysis and digital forensics. python-oletools is built on top of olefile.

Microsoft OLE2 files (also known as Structured Storage, Compound File Binary Format, or Compound Document File Format) are structured similarly to a mini file system or a Zip archive. They consist of three main components:

• Streams: These are data objects that function like files embedded within the OLE container. Every stream has a unique name (e.g., a MS Word document's main text stream is named WordDocument).
• Storages: These act as folders that can contain either streams or other storages, allowing for a hierarchical directory structure (e.g., a MS Word document might have a Macros storage).
• Properties: These are specific values used to store metadata (such as title, author, or creation date). Property stream names typically begin with the character \x05 (ASCII code 5).

When accessing streams or storages, olefile supports two path syntaxes (both are case-insensitive):

1. List of strings: A list representing the hierarchy from root to target.
   • Example: ['Macros', 'VBA', 'ThisDocument']
2. Slash-separated string: A single string using / as a separator.
   • Example: 'Macros/VBA/ThisDocument'

Note on Encoding:

• Python 3.x: Paths are handled as Unicode strings without encoding.
• Python 2.x: Paths are handled as bytes strings using UTF-8 by default. You can use path_encoding=None to use Unicode.

If you prefer not to use pip, you can install from a source distribution:

1. Download and extract the zip archive from the repository.
2. Navigate to the extracted directory.
3. Run the setup script using Python.

On Windows, you can automate this by double-clicking install.bat in the extracted folder.

python setup.py install

Before installing, ensure your environment meets the following Python version requirements:

• Python 2.7
• Python 3.5 or higher

The simplest way to install olefile for use in Python scripts or other applications is using pip. This will download and install the package in a single step.

To update an existing installation to the latest version, use the -U flag.

pip install olefile
# To update
pip install -U olefile

By default, olefile is permissive to allow parsing of most malformed files. To enforce stricter compliance with OLE specifications, use the raise_defects parameter when initializing OleFileIO.

To inspect non-fatal issues detected during parsing, check the parsing_issues attribute of the OleFileIO instance.

import olefile

# Force exceptions for non-conforming files
ole = olefile.OleFileIO('myfile.doc', raise_defects=olefile.DEFECT_INCORRECT)

# Inspect non-fatal issues
print('Non-fatal issues raised during parsing:')
if ole.parsing_issues:
    for exctype, msg in ole.parsing_issues:
        print('- %s: %s' % (exctype.__name__, msg))
else:
    print('None')

When reporting a bug or an issue, providing the debugging output from olefile is highly recommended. You can capture the detailed execution trace by running the olefile.py script with the -d (debug) and -c (command) flags and redirecting the output to a file.

Use the following command structure to generate a debug log:

olefile.py -d -c file >debug.txt

Replace file with the path to the OLE file you are investigating.