oletools: OLE Analysis Tools

0.60.2 · active · verified Fri Apr 10

oletools is a Python package providing a collection of tools to analyze Microsoft Office and OLE (Object Linking and Embedding) files, also known as Structured Storage or Compound Document File Format. It's primarily used for malware analysis and incident response (DFIR). The current version is 0.60.2, with an active release cadence focused on bug fixes and new detection capabilities.

Warnings

breaking Python 3.12 compatibility issues (SyntaxError) were fixed in version 0.60.2 for `oleobj` and `rtfobj` modules. Earlier versions may fail to run or parse specific files under Python 3.12.
Fix: Upgrade to oletools v0.60.2 or newer when using Python 3.12.
gotcha The `msoffcrypto-tool` library became a required dependency in version 0.54.2. Installations without this dependency might fail when attempting to process encrypted Office files, or during installation if not explicitly handled.
Fix: Ensure `msoffcrypto-tool` is installed alongside `oletools` by running `pip install oletools[full]` or `pip install oletools msoffcrypto-tool lxml`.
deprecated Separate Python 3-specific scripts like `olevba3` and `mraptor3` were removed in version 0.54. All tools are now Python 3 compatible, and users should directly use `olevba`, `mraptor`, etc.
Fix: Remove the '3' suffix from script calls (e.g., `olevba` instead of `olevba3`). Update any import paths that might have referred to these legacy versions.
gotcha Parsing of malformed OLE files, especially those with unusual 'PROJECTCOMPATVERSION' records, was improved in 0.60.2. Older versions might encounter errors or incomplete analysis for such specially crafted files.
Fix: Upgrade to oletools v0.60.2 or newer to ensure robust parsing of a wider range of potentially malicious OLE documents.

Install

pip install oletools Install stable version

Imports

VBA_Parser
```
from oletools.olevba import VBA_Parser
```
OleID
```
from oletools.oleid import OleID
```
OleObject
```
from oletools.oleobj import OleObject
```

Quickstart

This example demonstrates how to use `olevba` to detect and analyze VBA macros in a (dummy) OLE file. In a real scenario, `dummy_file_path` would point to an actual Office document. The `VBA_Parser` provides methods for macro detection, analysis, and extraction of suspicious keywords and IOCs. Remember to close the parser with `vbaparser.close()` to release file handles.

import os
from oletools.olevba import VBA_Parser, get_filepath_or_data

# Create a dummy OLE file for demonstration
dummy_file_path = 'dummy_macro.doc'
with open(dummy_file_path, 'wb') as f:
    # A very basic, non-functional OLE header structure
    # In a real scenario, this would be a proper MS Office file
    f.write(b'\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1\x00\x00\x00\x00\x00\x00\x00\x00')
    f.write(b'\x00' * 500) # Padding to make it somewhat resemble a file

try:
    # Initialize VBA_Parser with the file path
    # olevba handles file paths and file-like objects
    vbaparser = VBA_Parser(dummy_file_path)

    if vbaparser.detect_vba_macros():
        print(f"VBA Macros detected in {dummy_file_path}:")
        # Analyze and print macro details
        results = vbaparser.analyze_macros()
        for kw, description, typ, filename, original_code, code in results:
            print(f"  [{typ}] {kw}: {description}")
            if code:
                print(f"    Code:\n{code[:200]}...")
    else:
        print(f"No VBA macros detected in {dummy_file_path}.")

    vbaparser.close()

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # Clean up the dummy file
    if os.path.exists(dummy_file_path):
        os.remove(dummy_file_path)

view raw JSON →