Vivisect

Common errors

• Exception: Address (xxxx) not in maps!

  cause This error typically indicates that Vivisect's analysis tried to access a memory address that is not part of the loaded binary's memory map. This can happen with malformed binaries, incomplete file loading, or issues during auto-analysis.
  fix Verify the integrity of the binary file. Ensure the `vw.loadFromFile()` or `vw.loadFromFd()` call is successful before `vw.analyze()`. For unusual binary types, you might need to manually configure memory maps or use a custom loader if the standard parsers (PE, Elf) are insufficient.

• Python 2 workspace not loading in Python 3 Vivisect.

  cause Workspaces saved with Python 2 versions of Vivisect (especially using the default 'basicfile' storage, which relies on Python's `pickle`) are not compatible with Python 3 due to fundamental differences in object serialization.
  fix Before upgrading to Python 3 Vivisect, use a Python 2 Vivisect installation (v0.2.1) to convert old workspaces to the `msgpack` format. For example, `python2 -m vivisect.storage.tools.convert <old_workspace.viv> --name <new_workspace.mpviv>`. The `msgpack` format is cross-version compatible.

• GUI console not showing typing or interactive shell issues.

  cause When running the Vivisect GUI (`vivbin`) from a console, the interactive Python shell or function emulator can sometimes interfere with terminal settings.
  fix If the command line stops responding or showing input, try typing `stty sane` and pressing Enter (blindly if necessary) to reset the terminal settings. If multiple emulators/CLIs are active, you may need to reset the console state via `Plugins -> Ion -> Reset Console In Use` if using the VivisectION extension.

Warnings

• breaking Vivisect underwent a significant, backwards-incompatible transition from Python 2 (v0.x.x) to Python 3 (v1.0.0 and above). Old workspaces saved in Python 2's 'basicfile' format are not directly compatible with Python 3 versions.
  Fix: Use the conversion script (vivisect.storage.tools.convert) available in vivisect v0.2.1 (Python 2) or v1.0.1+ (Python 3) to migrate old 'basicfile' workspaces to the 'msgpack' format. Example: `python2 -m vivisect.storage.tools.convert <basicfile_workspace>`
• breaking Some API signatures changed during the Python 2 to Python 3 migration, notably for memory read/write operations. Scripts written for older Python 2 versions may require adjustments.
  Fix: Consult the Vivisect documentation and migration guide for specific API changes and update your code accordingly.
• gotcha When installing Vivisect with GUI support on Ubuntu, installing `PyQt5` via `pip install "vivisect[gui]"` might lead to issues.
  Fix: On Ubuntu, it is often more stable to install `PyQt5` and `PyQtWebkit` using the system package manager first: `sudo apt install python3-pyqt5 python3-pyqt5.qtwebkit`, then install `vivisect` without the `[gui]` extra.

Install

• pip install vivisect Core library (headless)
• pip install "vivisect[gui]" With GUI components (requires PyQt5)

Imports

• vivisect

  import vivisect

  Primary import for the VivWorkspace and core functionality
• vivisect.const

  import vivisect.const as v_const

  For accessing various constants like location types (LOC_OP, LOC_IMPORT) and xref types (REF_CODE, REF_PTR)
• PE

  import PE

  For direct parsing of Portable Executable (PE) files without a full workspace
• Elf

  import Elf

  For direct parsing of Executable and Linkable Format (ELF) files without a full workspace

Quickstart

This quickstart demonstrates how to initialize a Vivisect workspace, load a binary file, perform auto-analysis, and then programmatically access discovered functions and code locations. It illustrates the fundamental steps for static analysis.

import vivisect
import os

# Create a dummy binary file for demonstration
dummy_bin_path = 'temp_dummy.bin'
with open(dummy_bin_path, 'wb') as f:
    f.write(b'\x90\x90\x90\xc3') # NOP NOP NOP RET

try:
    # Create a VivWorkspace instance
    vw = vivisect.VivWorkspace()

    # Load a binary file into the workspace
    # Replace 'path/to/your/binary.exe' with a real binary or use the dummy
    vw.loadFromFile(dummy_bin_path)

    # Perform auto-analysis on the loaded binary
    print("Starting analysis...")
    vw.analyze()
    print("Analysis complete.")

    # Example: Get functions discovered by analysis
    functions = vw.getFunctions()
    print(f"Found {len(functions)} functions:")
    for fva in functions:
        f_name = vw.getName(fva)
        print(f"  0x{fva:x}: {f_name}")

    # Example: Get locations (e.g., instructions)
    locations = vw.getLocations()
    print(f"Found {len(locations)} locations:")
    for va, size, ltype, tinfo in locations:
        op = vw.getOpcode(va)
        print(f"  0x{va:x}: {op.mnem} {op.opers_str}")

finally:
    # Clean up the dummy file
    if os.path.exists(dummy_bin_path):
        os.remove(dummy_bin_path)