python-oletools Documentation

python-oletools is a suite of Python tools designed for analyzing Microsoft OLE2 files (Structured Storage, Compound File Binary Format), RTF files, and OpenXML (OOXML) files. It is primarily used for malware analysis, forensics, and debugging.

Key capabilities include:

• Detecting, extracting, and analyzing VBA macros.
• Extracting OLE objects.
• Analyzing Excel 4 macros (XLM) and DDE links.
• Parsing MS Office 97-2003, MS Office 2007+, MSI, Outlook messages, XPS, and MSIX files.

The olevba tool contains modified source code from the officeparser project. This specific component is published under the MIT License:

• Permission is granted to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the software.
• The original copyright notice and this permission notice must be included in all copies or substantial portions of the software.

olevba is a tool used to parse OLE and OpenXML files (like MS Office documents) to detect VBA macros, extract their source code, and identify security-related patterns. It can detect auto-executable macros, suspicious keywords, anti-sandboxing techniques, and potential Indicators of Compromise (IOCs) like IP addresses and URLs. It also deobfuscates common methods such as Hex, Base64, StrReverse, Dridex, and VBA expressions.

Supported Formats:

• Word 97-2003 (.doc, .dot), Word 2007+ (.docm, .dotm)
• Excel 97-2003 (.xls), Excel 2007+ (.xlsm, .xlsb)
• PowerPoint 97-2003 (.ppt), PowerPoint 2007+ (.pptm, .ppsm)
• Word/PowerPoint 2007+ XML (Flat OPC)
• Word 2003 XML (.xml)
• Word/Excel Single File Web Page / MHTML (.mht)
• Publisher (.pub)
• SYLK/SLK files (.slk)
• Text files containing VBA/VBScript
• Password-protected Zip archives containing any of the above

The python-oletools package is distributed under a BSD-style license. You are permitted to redistribute and use the software in source and binary forms, with or without modification, provided that:

1. Redistributions of source code must retain the copyright notice, the list of conditions, and the disclaimer.
2. Redistributions in binary form must reproduce the copyright notice, the list of conditions, and the disclaimer in the documentation and/or other materials provided with the distribution.

Note: The thirdparty folder contains files published under their own respective licenses and is excluded from this specific license.

olebrowse requires Tkinter to run its GUI. While it is typically included with Python on Windows and macOS, Linux users may need to install it manually.

For Ubuntu/Debian systems, use the following commands depending on your Python version:

The following tools are specialized for detecting and analyzing malicious content within documents:

• oleid: Analyzes OLE files to detect specific characteristics often found in malicious files.
• olevba: Extracts and analyzes VBA Macro source code from both OLE and OpenXML MS Office documents.
• mraptor: Specifically designed to detect malicious VBA Macros.
• msodde: Detects and extracts DDE/DDEAUTO links from MS Office documents, RTF, and CSV files.
• pyxswf: Detects, extracts, and analyzes embedded Flash objects (SWF) in MS Office documents and RTF files.
• oleobj: Extracts embedded objects from OLE files.
• rtfobj: Extracts embedded objects from RTF files.

If pip is unavailable, you can use the setup.py script directly.

Note: This method will not automatically create command-line scripts for the tools.

1. Download and extract the oletools archive.
2. Open a shell and navigate to the extracted oletools directory.

Linux, Mac OSX, Unix

sudo -H python setup.py install

Windows

python setup.py install

mraptor is a tool for detecting malicious VBA Macros using generic heuristics. It identifies suspicious behavior based on three categories:

• A: Auto-execution trigger
• W: Write to the file system or memory
• X: Execute a file or payload outside the VBA context

A macro is flagged as SUSPICIOUS if it contains an auto-execution trigger (A) AND either a write operation (W) or an execution operation (X).

CLI Syntax

mraptor [options] <filename> [filename2 ...]

Exit Codes

• 0: No Macro
• 1: Not MS Office
• 2: Macro OK
• 10: ERROR
• 20: SUSPICIOUS

mraptor file.doc

olebrowse is a GUI tool for browsing OLE files (such as MS Word, Excel, or PowerPoint documents). It allows you to view the internal structure, inspect individual data streams via a hexadecimal viewer, or extract streams to files for analysis.

To launch the tool, you can either pass a specific file path as an argument or run it without arguments to open a file browser dialog.

olebrowse [file]

To use the latest improvements from the development branch, install directly from the GitHub master archive via pip.

Warning: This method installs oletools without optional dependencies (like XLMMacroDeobfuscator); you must install those separately if needed.

Linux, Mac OSX, Unix

sudo -H pip install -U https://github.com/decalage2/oletools/archive/master.zip

Windows

pip install -U https://github.com/decalage2/oletools/archive/master.zip

Or for the current user only:

pip3 install -U --user https://github.com/decalage2/oletools/archive/master.zip