{"id":10340,"library":"viv-utils","title":"viv-utils","description":"viv-utils (version 0.8.1) is a Python library providing utilities for binary analysis, specifically designed to complement vivisect. It offers helper functions and abstractions for common tasks like extracting information from vivisect workspaces, navigating control flow graphs, and working with function metadata. Its release cadence is somewhat infrequent, driven by the needs of its primary developers and the broader vivisect ecosystem.","status":"active","version":"0.8.1","language":"en","source_language":"en","source_url":"https://github.com/williballenthin/viv-utils","tags":["binary analysis","reverse engineering","vivisect","static analysis","dynamic analysis"],"install":[{"cmd":"pip install viv-utils","lang":"bash","label":"Install viv-utils"}],"dependencies":[{"reason":"Core dependency for vivisect workspace interaction (pip installable since v0.8.0 of viv-utils)","package":"vivisect_v8","optional":false},{"reason":"Used for various data structures and memoization","package":"mnemonist","optional":false},{"reason":"Provides progress bars for long-running operations","package":"tqdm","optional":false}],"imports":[{"note":"The primary entry point to wrap a vivisect workspace is in the `api` submodule.","wrong":"import viv_utils; viv_utils.from_vivisect(...)","symbol":"from_vivisect","correct":"from viv_utils.api import from_vivisect"},{"note":"The emulator component is located in its own submodule.","wrong":"from viv_utils import VivEmulator","symbol":"VivEmulator","correct":"from viv_utils.emulator import VivEmulator"}],"quickstart":{"code":"import viv_utils.api as viv_api\nfrom unittest.mock import MagicMock\n\n# --- Start Minimal Mock for Demonstrative vivisect Workspace ---\n# In a real scenario, 'vw' would be an actual vivisect.VivWorkspace\n# loaded with a binary and analyzed (e.g., vw.loadFromFile(\"path/to/binary\"); vw.analyze()).\n\nclass MockVivWorkspace:\n    def __init__(self):\n        self.arch = \"amd64\" # Required by viv_utils\n        self._functions = {\n            0x1000: {\"name\": \"entry_point\", \"blocks_count\": 3},\n            0x1050: {\"name\": \"utility_func\", \"blocks_count\": 2},\n        }\n\n    def getMetaInfo(self, key, default=None):\n        # viv_utils queries meta info, e.g., 'Platform'\n        return {\"Platform\": \"windows\"}.get(key, default)\n\n    def getFunctions(self):\n        return list(self._functions.keys())\n\n    def getFunction(self, va):\n        if va not in self._functions:\n            return None\n        # viv_utils expects specific attributes on the function object\n        func_data = self._functions[va]\n        mock_func = MagicMock()\n        mock_func.va = va\n        mock_func.name = func_data[\"name\"]\n        mock_func.basic_blocks = [MagicMock() for _ in range(func_data[\"blocks_count\"])] # Simulate basic blocks\n        mock_func.getBasicBlocks.return_value = {0x1000: (0x10, 5)} # dummy for internal access if needed\n        return mock_func\n    \n    def getComments(self, va): return None # Often queried\n    def getCodeBlocks(self): return [] # Often queried\n    def getVivTaint(self): return MagicMock() # For emulator, though not used in this quickstart\n\nvw = MockVivWorkspace()\n# --- End Minimal Mock ---\n\n# Wrap the mock vivisect workspace with viv-utils API\nutils_workspace = viv_api.from_vivisect(vw)\n\nprint(\"Listing functions from the viv-utils wrapped workspace:\")\nfor func in utils_workspace.get_functions():\n    print(f\"  Function VA: {hex(func.va)}, Name: '{func.name}', Basic Blocks: {len(func.basic_blocks)}\")\n\n# Example: Access a specific function by VA\ntarget_va = 0x1050\ntarget_func = utils_workspace.get_function(target_va)\n\nif target_func:\n    print(f\"\\nDetails for function '{target_func.name}' at {hex(target_func.va)}:\")\n    print(f\"  Number of basic blocks: {len(target_func.basic_blocks)}\")\nelse:\n    print(f\"\\nFunction at {hex(target_va)} not found.\")","lang":"python","description":"This quickstart demonstrates how to initialize `viv-utils` with a `vivisect` workspace (using a minimal mock for runnable example) and iterate through functions, accessing their basic properties. In a real scenario, `vw` would be a fully loaded and analyzed `vivisect.VivWorkspace` object."},"warnings":[{"fix":"Ensure you have `vivisect_v8` installed: `pip install vivisect-v8`. Uninstall any older vivisect installations if they cause conflicts.","message":"Starting with `viv-utils` v0.8.0, the library explicitly requires `vivisect_v8>=1.0.0`. Older versions of `vivisect` (e.g., those installed directly from GitHub without the `_v8` suffix or prior to `vivisect_v8`'s release) are no longer compatible.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Always ensure your `vivisect.VivWorkspace` object has been loaded from a binary and fully analyzed before passing it to `viv_utils.api.from_vivisect()`.","message":"The `viv_utils` API relies on a fully analyzed `vivisect.VivWorkspace` object. If the underlying workspace (`vw`) has not been properly loaded from a binary and `vw.analyze()` called, many `viv-utils` methods like `get_functions()` or `get_function()` might return empty results or raise `AttributeError` if attempting to access unpopulated fields.","severity":"gotcha","affected_versions":"All"},{"fix":"Verify that your `vivisect_v8` installation is complete and compatible. If using `VivEmulator`, ensure your `vivisect` workspace has been sufficiently analyzed to populate necessary taint tracking or memory emulation structures.","message":"Some functionalities, especially related to emulation (`viv_utils.emulator.VivEmulator`), might expect specific methods or data structures to be present in the `vivisect.VivWorkspace` object or its internal components. Using a partially initialized or very old `vivisect` workspace can lead to `AttributeError`.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the required vivisect package: `pip install vivisect-v8`","cause":"The `vivisect_v8` package, a core dependency, is not installed or not accessible.","error":"ModuleNotFoundError: No module named 'vivisect_v8'"},{"fix":"Ensure `vw` in `viv_api.from_vivisect(vw)` is an actual, initialized `vivisect.VivWorkspace` instance, not `None`.","cause":"You likely passed `None` instead of a `vivisect.VivWorkspace` object to `viv_utils.api.from_vivisect()`.","error":"AttributeError: 'NoneType' object has no attribute 'arch'"},{"fix":"Upgrade `vivisect_v8` to the latest version (`pip install --upgrade vivisect-v8`). If you have conflicting `vivisect` installations, remove the older ones.","cause":"An older or incomplete `vivisect` installation might be missing methods required by `viv_utils.emulator.VivEmulator`.","error":"AttributeError: 'VivWorkspace' object has no attribute 'getVivTaint'"}]}