{"id":5151,"library":"cle","title":"CLE: Common Library for Executables","description":"CLE (Common Library for Executables) is a Python library that loads binaries and their associated libraries, resolves imports, and provides an abstraction of process memory, mimicking how an operating system's loader would present them. It is a core component of the larger angr binary analysis framework. The current version is 9.2.209, and it maintains an active release cadence as part of the angr project.","status":"active","version":"9.2.209","language":"en","source_language":"en","source_url":"https://github.com/angr/cle","tags":["binary analysis","loader","executables","memory mapping","reverse engineering","security"],"install":[{"cmd":"pip install cle","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for lifting binary code to an intermediate representation (VEX), essential for deeper analysis.","package":"pyvex","optional":false},{"reason":"Required for loading and parsing Microsoft Portable Executable (PE) binaries (e.g., Windows executables).","package":"pefile","optional":true},{"reason":"Provides architecture information necessary for binary analysis.","package":"archinfo","optional":false}],"imports":[{"note":"The primary interface is typically accessed through the top-level 'cle' module, rather than direct import from submodules like 'cle.loader'.","wrong":"from cle.loader import Loader","symbol":"Loader","correct":"import cle\nloader = cle.Loader(...)"}],"quickstart":{"code":"import cle\nimport os\n\n# For demonstration, use a common system binary like '/bin/ls'\n# On Windows, you might use a path to an executable like 'C:\\Windows\\System32\\calc.exe'\nbinary_path = os.environ.get('CLE_BINARY_PATH', '/bin/ls')\n\ntry:\n    ld = cle.Loader(binary_path)\n\n    print(f\"Loaded binary: {ld.main_object.binary_path}\")\n    print(f\"Entry point: {hex(ld.main_object.entry)}\")\n    print(\"Shared objects:\")\n    for obj_name, obj_data in ld.shared_objects.items():\n        print(f\"  - {obj_name}: {obj_data}\")\n\n    # Example of accessing an import\n    if '__libc_start_main' in ld.main_object.imports:\n        libc_main_reloc = ld.main_object.imports['__libc_start_main']\n        print(f\"Address of __libc_start_main GOT entry: {hex(libc_main_reloc.addr)}\")\n\nexcept Exception as e:\n    print(f\"Error loading binary {binary_path}: {e}\")\n    print(\"Please ensure the binary exists and is a valid executable format for CLE.\")","lang":"python","description":"This quickstart demonstrates how to load a binary file using `cle.Loader`, access its entry point, list its shared objects, and inspect an imported symbol. Replace `/bin/ls` with a path to an actual executable on your system for a functional example. Environment variable `CLE_BINARY_PATH` can be used to specify the binary."},"warnings":[{"fix":"Upgrade your Python environment to 3.10+ and update your code to be Python 3 compliant. Review the `angr` migration guide for more details on changes in APIs like `Clemory`.","message":"When migrating from older versions of `cle` (prior to `angr 8`), Python 2 is no longer supported. All code must be migrated to Python 3.","severity":"breaking","affected_versions":"< 8.x.x"},{"fix":"Ensure all memory operations and data handling correctly use `bytes` objects. Avoid using `cbackers` and `read_bytes_c` as they are no longer recommended due to performance improvements making them unnecessary.","message":"The `Clemory` API (accessed via `project.loader.memory`) underwent significant refactoring with `angr 8`, specifically around replacing Python 2 string types with Python 3's `bytes`. Functions like `cbackers` and `read_bytes_c` are deprecated.","severity":"breaking","affected_versions":"All versions before angr 8 / cle 8"},{"fix":"Update code that inspects or compares symbol types to use the new Enum representations. Consult the `cle` API documentation for the specific Enum classes and members.","message":"Symbol types in CLE (e.g., accessed via `main_object.imports`) are now represented using Enums instead of potentially raw string or integer values, as introduced in `angr 8.19.7.25` (cle#177).","severity":"breaking","affected_versions":"< 8.19.7.25"},{"fix":"If `auto_load_libs` is `False`, explicitly specify required library paths using the `ld_path` option, or manually load them. Be aware of the implications for memory layout and symbol resolution.","message":"By default, `cle.Loader` attempts to automatically load shared libraries. If the `auto_load_libs` option is set to `False`, dependencies requested by loaded objects will not be resolved, potentially leading to incomplete memory maps or unresolved symbols.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always install the relevant optional dependencies for the binary formats you intend to analyze. Check the `cle` documentation for specific backend requirements.","message":"Loading certain binary formats (e.g., PE for Windows executables) requires optional Python packages like `pefile`. If these dependencies are not installed, `cle` may fail to load the binary or provide incomplete analysis without a clear error message indicating the missing package.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}