Oledump.py: A Powerful Tool for Analyzing OLE Documents
Introduction to Oledump.py
oledump.py is a powerful Python tool developed by Didier Stevens for analyzing OLE (Object Linking and Embedding) files, which are commonly used in Microsoft Office documents and can contain embedded macros. This tool is crucial for digital forensics, malware analysis, and cybersecurity investigations, as malicious actors often use macros in Office documents for initial infection vectors.
Understanding OLE Documents
OLE (Object Linking and Embedding) is a technology introduced by Microsoft that allows embedding and linking to documents and other objects. Many Microsoft Office files (such as .doc, .xls, and .ppt) use OLE structures.
Attackers often embed malicious macros in these files to execute code upon opening.
Installation
You can use one of the following 2 methods to download and install the oledump.py tool.
# Clone the repository
git clone https://github.com/DidierStevens/DidierStevensSuite.git
cd DidierStevensSuite
# Run oledump.py
python oledump.py -hOr
wget http://didierstevens.com/files/software/oledump_V0_0_9.zip
unzip oledump.zip
python oledump.py -hBasic Usage
The core functionality of oledump.py is to analyze OLE files and extract potential macro streams. A typical command to analyze an OLE document is:
python oledump.py suspicious.docLets's analyse the output formats. Output looks similer like :
| # | Indicator | Size | Name |
|---|---|---|---|
| 1 | 1024 | ' | |
| 2 | 2048 | 'OleStream' | |
| 3 | M | 1048576 | 'Macros' |
| 4 | m | 32768 | 'VBA/ThisDocument' |
| 5 | 65536 | 'VBA/_VBA_PROJECT' | |
| 6 | 65536 | 'VBA/Module1' |
# : Stream number
ind : indicators
- M - VBA Macro with Code
- m - VBA Macro with attributes only
- E - corrupt VBA code
- ! - unusual VBA code
- O - embedded object
- . - Storage
- R - Root entry
Size : Size of stream
Name : Name of stream
| Option | Description | Example/Syntax |
|---|---|---|
| -m / -h | Manual/help page | python oledump.py -h |
| --version | Show version | python oledump.py --version |
| -s [number] | Select item for dumping | python oledump.py -s 3 file.doc |
| -d | Dump data | python oledump.py -s 3 -d file.doc |
| -x | Hexdump output | python oledump.py -s 3 -x file.doc |
| -a | ASCII dump | python oledump.py -s 3 -a file.doc |
| -A | ASCII dump with RLE | python oledump.py -s 3 -A file.doc |
| -S | Dump strings | python oledump.py -s 3 -S file.doc |
| -T | Head & tail dump | python oledump.py -s 3 -T file.doc |
| -v | Decompress VBA | python oledump.py -s 3 -v file.doc |
| -r | Read raw file | python oledump.py -s 3 -r file.doc |
| -t | String translation | python oledump.py -s 3 -t file.doc |
| -e | Extract OLE embedded file | python oledump.py -s 3 -e file.doc |
| -i | Additional item info | python oledump.py -s 3 -i file.doc |
| -p PLUGINS | Load plugin | python oledump.py -p plugin.py file.doc |
| -q | Quiet mode | python oledump.py -q file.doc |
| -y [file] | Load YARA file | python oledump.py -y rules.yar file.doc |
| -D [name] | Load decoder | python oledump.py -D decoder.py file.doc |
| -M | Print metadata | python oledump.py -M file.doc |
| -c | Add calculated data | python oledump.py -c file.doc |
| -V | Verbose mode | python oledump.py -V file.doc |
| -C [n] | Cut data output | python oledump.py -C 10 file.doc |
| --storages | Include storages in report | python oledump.py --storages file.doc |
| -j | JSON output | python oledump.py -j file.doc |
| --password | ZIP password (default: infected) | python oledump.py --password infected file.doc |
Frequently Asked Questions
What is oledump.py?➕
oledump.py is a powerful Python tool developed by Didier Stevens for analyzing OLE (Object Linking and Embedding) files, commonly used in Microsoft Office documents that may contain embedded macros. It is essential for digital forensics, malware analysis, and cybersecurity investigations.
What are OLE documents?➕
OLE (Object Linking and Embedding) is a Microsoft technology allowing embedding and linking to documents and objects. Many Office files (.doc, .xls, .ppt) use OLE structures, which can contain malicious macros.
How do I install oledump.py?➕
You can install oledump.py by cloning the repository using 'git clone https://github.com/DidierStevens/DidierStevensSuite.git' and running 'python oledump.py -h', or by downloading the zip file with 'wget http://didierstevens.com/files/software/oledump_V0_0_9.zip', unzipping it, and running 'python oledump.py -h'.
How do I analyze an OLE document using oledump.py?➕
To analyze an OLE document, use the command 'python oledump.py suspicious.doc'. This will display various streams within the document, including potential macro streams.
What do the indicators in the output mean?➕
Indicators in the output represent different types of content: M - VBA Macro with Code, m - VBA Macro with attributes only, E - corrupt VBA code, ! - unusual VBA code, O - embedded object, . - Storage, R - Root entry.
What are some common commands for oledump.py?➕
Common commands include: - '-h' for help - '--version' to show version - '-s [number]' to select an item - '-d' to dump data - '-x' for hexdump - '-v' to decompress VBA - '-j' for JSON output - '-p [plugin]' to load plugins
How can I extract all VBA code from a document?➕
To extract all VBA code, use the command 'oledump.py -s a -v example.xls'.
How do I scan a document with YARA rules?➕
To scan with YARA rules, use 'oledump.py -y sample.yara example.xls'.
How can I use plugins with oledump.py?➕
You can load plugins with the '-p' option. For example, to use the HTTP heuristics plugin, run 'oledump.py -p plugin_http_heuristics example.xls'.
What is the command to view a specific stream in a file?➕
To view a specific stream, use 'oledump.py -s [stream number] example.xls'. For example, 'oledump.py -s 3 example.xls' views stream number 3.