VBA P-Code Disassembler

Warnings

• gotcha Prior to v1.2.1, pcodedmp only officially supported Python 2.6+. Attempting to use older versions on Python 3.x will likely result in compatibility errors.
  Fix: Upgrade to version 1.2.1 or newer for Python 3.x support: `pip install --upgrade pcodedmp`.
• gotcha Before v1.2.3, installation via `pip install pcodedmp` was not fully supported, requiring manual setup. Users attempting to install or use older versions might encounter difficulties.
  Fix: Ensure you are using version 1.2.3 or newer for straightforward `pip` installation.
• gotcha While support for 64-bit Office documents and VBA7 features (like `PtrSafe`) improved in versions 1.1.0 and 1.2.1, the library's README still notes known limitations. Disassembly of some complex or obscure 64-bit specific p-code instructions might be incomplete or incorrect.
  Fix: Be aware of potential edge cases when analyzing highly complex or specifically obfuscated 64-bit VBA macros. Consult the project's 'Known problems' section in the README for details.
• deprecated In v1.2.5, output functions like `dump_file` gained an `output_file` parameter, allowing explicit control over where disassembly output is written. While implicitly writing to `sys.stdout` still works by default, explicitly passing `output_file=sys.stdout` or a file handle is the recommended and more robust approach.
  Fix: Update calls to `dump_file` or `dump_stream` to explicitly pass `output_file=sys.stdout` or an open file object for cleaner output handling: `dump_file(filename, output_file=my_file_handle)`.

Install

• pip install pcodedmp Install stable version

Imports

• dump_file

  from pcodedmp.pcodedmp import dump_file

  The main functions like `dump_file` reside in the `pcodedmp.py` module within the `pcodedmp` package structure, thus requiring the explicit `pcodedmp.pcodedmp` import path.
• dump_stream

  from pcodedmp.pcodedmp import dump_stream

  For disassembling a specific VBA stream directly.

Quickstart

This quickstart demonstrates how to use `pcodedmp` to disassemble VBA p-code from an Office document. It shows how to call the `dump_file` function and capture its output. Replace the placeholder `document_path` with an actual path to a `.docm`, `.xlsm`, or `.pptm` file containing VBA macros. The example gracefully handles `FileNotFoundError` and other exceptions.

import os
import io
import sys
from pcodedmp.pcodedmp import dump_file

# This library processes existing Office documents containing VBA macros.
# Replace 'path/to/your/document.docm' with the actual path to your target file.
# For example, create a simple .docm file with a basic macro (e.g., MsgBox 'Hello').
#
# If the file does not exist, the library will raise a FileNotFoundError.
# This example is designed to be runnable and show the expected output,
# whether it's successful disassembly or an error due to a missing file.
document_path = "path/to/your/document.docm" # Replace with a real path if you have one.

# Capture stdout to inspect the disassembly output without writing to console
original_stdout = sys.stdout
captured_output = io.StringIO()
sys.stdout = captured_output

try:
    print(f"Attempting to disassemble VBA p-code from: {document_path}")
    # The dump_file function writes output to sys.stdout by default.
    # You can also specify an output file: dump_file(document_path, output_file=open('output.txt', 'w'))
    dump_file(document_path)

    # Get the captured output
    output_lines = captured_output.getvalue().strip().split('\n')
    print("\n--- Disassembly Attempt Result ---")
    if output_lines and output_lines[0].startswith('VBA p-code disassembler'): # Check for actual content
        print("\n".join(output_lines[:10])) # Print first 10 lines of actual disassembly
        if len(output_lines) > 10:
            print("...")
        print(f"(Full output length: {len(output_lines)} lines)")
    else:
        # No relevant output from disassembly, likely an error message from the library itself
        print("No relevant disassembly output. See error messages below if any.")

except FileNotFoundError:
    print(f"\nERROR: Input file not found at '{document_path}'.")
    print("Please replace 'path/to/your/document.docm' with a valid path to an Office document containing VBA.")
except Exception as e:
    print(f"\nAn unexpected error occurred: {e}")
finally:
    sys.stdout = original_stdout # Restore original stdout

print("\nQuickstart finished. Check the 'Disassembly Attempt Result' above.")