{"id":9388,"library":"vivisect","title":"Vivisect","description":"Vivisect is a pure Python disassembler, debugger, emulator, and static analysis framework. It is a comprehensive toolkit for reverse engineering, offering powerful APIs for analyzing various binary formats (PE, ELF, IHEX, SREC, or blob) across multiple architectures. The library is actively maintained, with regular releases providing new features and fixes.","status":"active","version":"1.3.2","language":"en","source_language":"en","source_url":"https://github.com/vivisect/vivisect","tags":["static analysis","disassembler","debugger","emulator","reverse engineering","binary analysis","security"],"install":[{"cmd":"pip install vivisect","lang":"bash","label":"Core library (headless)"},{"cmd":"pip install \"vivisect[gui]\"","lang":"bash","label":"With GUI components (requires PyQt5)"}],"dependencies":[{"reason":"Required for the graphical user interface (GUI) components.","package":"PyQt5","optional":true}],"imports":[{"note":"Primary import for the VivWorkspace and core functionality","symbol":"vivisect","correct":"import vivisect"},{"note":"For accessing various constants like location types (LOC_OP, LOC_IMPORT) and xref types (REF_CODE, REF_PTR)","symbol":"vivisect.const","correct":"import vivisect.const as v_const"},{"note":"For direct parsing of Portable Executable (PE) files without a full workspace","symbol":"PE","correct":"import PE"},{"note":"For direct parsing of Executable and Linkable Format (ELF) files without a full workspace","symbol":"Elf","correct":"import Elf"}],"quickstart":{"code":"import vivisect\nimport os\n\n# Create a dummy binary file for demonstration\ndummy_bin_path = 'temp_dummy.bin'\nwith open(dummy_bin_path, 'wb') as f:\n    f.write(b'\\x90\\x90\\x90\\xc3') # NOP NOP NOP RET\n\ntry:\n    # Create a VivWorkspace instance\n    vw = vivisect.VivWorkspace()\n\n    # Load a binary file into the workspace\n    # Replace 'path/to/your/binary.exe' with a real binary or use the dummy\n    vw.loadFromFile(dummy_bin_path)\n\n    # Perform auto-analysis on the loaded binary\n    print(\"Starting analysis...\")\n    vw.analyze()\n    print(\"Analysis complete.\")\n\n    # Example: Get functions discovered by analysis\n    functions = vw.getFunctions()\n    print(f\"Found {len(functions)} functions:\")\n    for fva in functions:\n        f_name = vw.getName(fva)\n        print(f\"  0x{fva:x}: {f_name}\")\n\n    # Example: Get locations (e.g., instructions)\n    locations = vw.getLocations()\n    print(f\"Found {len(locations)} locations:\")\n    for va, size, ltype, tinfo in locations:\n        op = vw.getOpcode(va)\n        print(f\"  0x{va:x}: {op.mnem} {op.opers_str}\")\n\nfinally:\n    # Clean up the dummy file\n    if os.path.exists(dummy_bin_path):\n        os.remove(dummy_bin_path)\n","lang":"python","description":"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."},"warnings":[{"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>`","message":"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.","severity":"breaking","affected_versions":"<1.0.0 to >=1.0.0"},{"fix":"Consult the Vivisect documentation and migration guide for specific API changes and update your code accordingly.","message":"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.","severity":"breaking","affected_versions":"<1.0.0 to >=1.0.0"},{"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.","message":"When installing Vivisect with GUI support on Ubuntu, installing `PyQt5` via `pip install \"vivisect[gui]\"` might lead to issues.","severity":"gotcha","affected_versions":"All versions with GUI"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"Exception: Address (xxxx) not in maps!"},{"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.","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.","error":"Python 2 workspace not loading in Python 3 Vivisect."},{"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.","cause":"When running the Vivisect GUI (`vivbin`) from a console, the interactive Python shell or function emulator can sometimes interfere with terminal settings.","error":"GUI console not showing typing or interactive shell issues."}]}