{"id":2622,"library":"oletools","title":"oletools: OLE Analysis Tools","description":"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.","status":"active","version":"0.60.2","language":"en","source_language":"en","source_url":"https://github.com/decalage2/oletools","tags":["malware analysis","security","office files","ole","vba","dfir","structured storage"],"install":[{"cmd":"pip install oletools","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for decrypting encrypted MS Office files.","package":"msoffcrypto-tool","optional":false},{"reason":"Used for parsing XML-based Office documents (e.g., OOXML files).","package":"lxml","optional":false}],"imports":[{"symbol":"VBA_Parser","correct":"from oletools.olevba import VBA_Parser"},{"symbol":"OleID","correct":"from oletools.oleid import OleID"},{"symbol":"OleObject","correct":"from oletools.oleobj import OleObject"}],"quickstart":{"code":"import os\nfrom oletools.olevba import VBA_Parser, get_filepath_or_data\n\n# Create a dummy OLE file for demonstration\ndummy_file_path = 'dummy_macro.doc'\nwith open(dummy_file_path, 'wb') as f:\n    # A very basic, non-functional OLE header structure\n    # In a real scenario, this would be a proper MS Office file\n    f.write(b'\\xD0\\xCF\\x11\\xE0\\xA1\\xB1\\x1A\\xE1\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00')\n    f.write(b'\\x00' * 500) # Padding to make it somewhat resemble a file\n\ntry:\n    # Initialize VBA_Parser with the file path\n    # olevba handles file paths and file-like objects\n    vbaparser = VBA_Parser(dummy_file_path)\n\n    if vbaparser.detect_vba_macros():\n        print(f\"VBA Macros detected in {dummy_file_path}:\")\n        # Analyze and print macro details\n        results = vbaparser.analyze_macros()\n        for kw, description, typ, filename, original_code, code in results:\n            print(f\"  [{typ}] {kw}: {description}\")\n            if code:\n                print(f\"    Code:\\n{code[:200]}...\")\n    else:\n        print(f\"No VBA macros detected in {dummy_file_path}.\")\n\n    vbaparser.close()\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Clean up the dummy file\n    if os.path.exists(dummy_file_path):\n        os.remove(dummy_file_path)","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to oletools v0.60.2 or newer when using Python 3.12.","message":"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.","severity":"breaking","affected_versions":"<0.60.2"},{"fix":"Ensure `msoffcrypto-tool` is installed alongside `oletools` by running `pip install oletools[full]` or `pip install oletools msoffcrypto-tool lxml`.","message":"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.","severity":"gotcha","affected_versions":">=0.54.2"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<0.54"},{"fix":"Upgrade to oletools v0.60.2 or newer to ensure robust parsing of a wider range of potentially malicious OLE documents.","message":"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.","severity":"gotcha","affected_versions":"<0.60.2"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}