Registry / data / oletools

oletools

JSON →
library0.60.2pypypi✓ verified 24d ago

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.

pip install oletools
INSTALL
IMPORT
SIG · OLETOOLS
O
oletools
datapythonv0.60.2
Install
3.0s avg
Import
475ms
Disk
39MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.60.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.484s · 40.5MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.0s · import 0.466s · 41MB
39MB installed
● package 39MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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)
oleid --version
Debug
Known issues
breakingPython 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.
affects: <0.60.2
gotchaThe `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`.
affects: >=0.54.2
deprecatedSeparate 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.
affects: <0.54
gotchaParsing 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.
affects: <0.60.2
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'oletools'
The 'oletools' package or one of its submodules cannot be found by the Python interpreter, typically because it's not installed in the active environment or the Python path is incorrectly configured.
fix
Install the package using pip: `pip install oletools` or `pip install -U oletools[full]` for all optional dependencies.
OSError: not an OLE2 structured storage file
The file provided to an oletools component (often via the underlying `olefile` library) is not a valid OLE2 Compound Document File Format, meaning it's either a different file type or a malformed OLE file.
fix
Ensure the input file is indeed a Microsoft Office document (pre-2007) or another OLE2 structured storage file. Verify the file type before processing, for instance, by checking its magic bytes or using `ftguess` (part of oletools) to identify its format.
AttributeError: 'NoneType' object has no attribute 'splitlines'
This error often occurs within `olevba` when it attempts to process VBA code that was not successfully extracted or is empty, resulting in a `None` value where a string (with a `splitlines` method) is expected.
fix
This usually indicates an issue with the input file itself, such as a malformed document or a VBA stream that `olevba` cannot parse. While there's no direct code fix for the error in user space, reporting the specific file to the oletools developers can help improve parsing robustness. As a workaround, check if the VBA code extraction yielded `None` before attempting string operations.
WARNING: The scripts ezhexviewer.exe, ... olevba.exe ... are installed in 'C:\Users\...\Scripts' which is not on PATH.
During installation, pip installed the `oletools` command-line scripts into a directory that is not included in the system's PATH environment variable, preventing them from being executed directly from the command line.
fix
Add the reported directory (e.g., `C:\Users\Daniel\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.9_qbz5n2kfra8p0\LocalCache\local-packages\Python39\Scripts` on Windows) to your system's PATH environment variable. Alternatively, you can run the scripts by providing their full path or by prefixing them with `python -m oletools.<tool_name>`, e.g., `python -m oletools.olevba`.
Upgrade
Version history
0.60.2latest on PyPI · released Jul 2, 2024
Audit
Dependencies
msoffcrypto-toolrequiredRequired for decrypting encrypted MS Office files.
lxmlrequiredUsed for parsing XML-based Office documents (e.g., OOXML files).
Agent activity
11 hits · last 30 days
node
8
Amazon
1
OpenAI (training)
1
Resources
oletools — pip install oletools · libregistry