olevba

Analyze a file, showing both macro code and analysis results

$ olevba [path/to/file]

$ olevba -r [path/to/directory]

$ olevba [[-p|--password]] [password] [path/to/encrypted_file]

$ olevba [[-a|--analysis]] [path/to/file]

$ olevba [[-c|--code]] [path/to/file]

$ olevba --decode [path/to/file]

olevba [options] <file> [<file2> ...]

-h, --help
    Show the help message and exit.

-v, --version
    Show the program's version number and exit.

-a, --analyze
    Perform analysis of the VBA macros (default behavior, often used for clarity).

-c, --code
    Display only the VBA source code found in the document(s).

-d, --decompress
    Decompress and display the raw VBA stream content without analysis.

-r, --regex <regex>
    Provide a Python regular expression to search within the VBA code. Matching lines will be highlighted.

--json
    Output analysis results in JSON format, suitable for programmatic parsing and integration into automated workflows.

--disable-colors
    Disable colored output, useful when redirecting output to a file or for compatibility with specific terminal emulators.

--loglevel <level>
    Set the logging level for diagnostic messages (e.g., debug, info, warning, error).

--no-extract-macros
    Only list the presence of macros in the document; do not extract or analyze their content.

--reveal
    Attempt to reveal potentially obfuscated strings or values present in the VBA code.

--lax
    Do not fail on malformed OLE/OpenXML files; try to parse them with a best-effort approach.

olevba is a powerful command-line tool from the oletools suite designed for the static analysis of Microsoft Office OLE and OpenXML files. Its primary purpose is to extract and analyze VBA (Visual Basic for Applications) macros embedded within documents such as .doc, .xls, .ppt, .docm, .xlsm, .pptm, .docx, .xlsx, and .pptx.

It plays a crucial role in cybersecurity and malware analysis by identifying potentially malicious VBA code. olevba can detect suspicious keywords, common IOCs (Indicators of Compromise), and auto-executable macro functions (e.g., AutoOpen, Workbook_Open, Document_Open). It can also decompress VBA streams, attempt to reveal obfuscated strings, and provide the extracted source code for deeper inspection. By performing static analysis, it helps analysts quickly triage suspicious documents without executing potentially dangerous code, providing insights into macro behavior and potential threats.

As a static analysis tool, olevba does not execute the VBA macros. Therefore, it may be bypassed by advanced obfuscation techniques, highly dynamic code that builds malicious payloads at runtime, or shellcode execution which is beyond the scope of VBA analysis. It relies on known patterns and keywords, so novel or highly polymorphic malware might evade detection. Always combine static analysis with dynamic analysis for comprehensive security assessments of suspicious documents.

Security analysts frequently use olevba as a first-pass tool to quickly assess the risk posed by suspicious Office documents. It helps in identifying whether a document contains macros, if those macros are auto-executing, and if they contain suspicious patterns indicative of malware. The output often guides further investigation, either by manually reviewing the extracted code for deeper insights or by subjecting the document to dynamic analysis in a sandboxed environment for behavioral insights.

olevba's output is structured to highlight critical information. It typically displays a summary, including detected OLE streams, VBA code, and identified IOCs. Warnings about suspicious keywords, potential shellcode, or network indicators are clearly flagged. Auto-executable functions (like AutoOpen, Workbook_Open, Document_Open) are noted, indicating the macro's potential to run without user interaction. The extracted VBA source code is also provided, allowing for detailed manual review of the macro's logic and structure.

olevba is an integral part of the oletools project, an open-source suite of Python tools developed by Philippe Lagadec. The project emerged to provide robust capabilities for analyzing Microsoft OLE and OpenXML files, particularly in the context of cybersecurity and malware analysis. olevba specifically focuses on VBA macro analysis, evolving over time to address new obfuscation techniques and malicious macro patterns, making it a staple in incident response and threat intelligence workflows.

oleid(1), mraptor(1), file(1), strings(1), peepdf(1)