declib 3.8.0__py3-none-any.whl

declib/__init__.py

@@ -0,0 +1,9 @@
+__version__ = "3.8.0"
+
+
+import logging
+logging.getLogger("declib").addHandler(logging.NullHandler())
+from declib.logger import Loggers
+loggers = Loggers()
+del Loggers
+del logging

declib/__main__.py

@@ -0,0 +1,190 @@
+import argparse
+import sys
+import logging
+
+from declib.plugin_installer import DecLibPluginInstaller
+
+_l = logging.getLogger(__name__)
+
+
+def install():
+    DecLibPluginInstaller().install()
+
+
+def start_server(
+    socket_path=None, decompiler=None, binary_path=None, headless=False,
+    server_id=None, project_dir=None,
+):
+    """Start the DecompilerServer (AF_UNIX socket-based)"""
+    try:
+        from declib.api.decompiler_server import DecompilerServer
+        from declib.api.decompiler_interface import DecompilerInterface
+
+        # Configure logging
+        logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+
+        # Prepare interface kwargs
+        interface_kwargs = {}
+        if decompiler:
+            interface_kwargs['force_decompiler'] = decompiler
+        if binary_path:
+            interface_kwargs['binary_path'] = binary_path
+        if headless:
+            interface_kwargs['headless'] = headless
+        if project_dir:
+            interface_kwargs['project_dir'] = project_dir
+
+        # Create and start server
+        if socket_path:
+            _l.info(f"Starting AF_UNIX DecompilerServer on {socket_path}")
+        else:
+            _l.info("Starting AF_UNIX DecompilerServer with auto-generated socket path")
+        if interface_kwargs:
+            _l.info(f"Interface options: {interface_kwargs}")
+
+        with DecompilerServer(socket_path=socket_path, server_id=server_id, **interface_kwargs) as server:
+            _l.info("Server started successfully. Press Ctrl+C to stop.")
+            _l.info("Connect with: DecompilerClient.discover('unix://{}')".format(server.socket_path))
+            try:
+                server.wait_for_shutdown()
+            except KeyboardInterrupt:
+                _l.info("Shutting down server...")
+
+    except ImportError as e:
+        _l.error(f"Failed to import required modules: {e}")
+        sys.exit(1)
+    except Exception as e:
+        _l.error(f"Failed to start server: {e}")
+        sys.exit(1)
+
+
+def test_client(server_url=None):
+    """Test the DecompilerClient connection"""
+    try:
+        from declib.api.decompiler_client import DecompilerClient
+        
+        # Configure logging
+        logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+        
+        if server_url:
+            _l.info(f"Testing connection to DecompilerServer at {server_url}")
+        else:
+            _l.info("Testing connection to auto-discovered DecompilerServer")
+        
+        with DecompilerClient.discover(server_url=server_url) as client:
+            _l.info(f"Successfully connected to {client.name} decompiler")
+            _l.info(f"Binary path: {client.binary_path}")
+            _l.info(f"Binary hash: {client.binary_hash}")
+            _l.info(f"Decompiler available: {client.decompiler_available}")
+            
+            # Test fast artifact collections (benchmark performance)
+            import time
+            start_time = time.time()
+            functions = list(client.functions.items())
+            end_time = time.time()
+            _l.info(f"Retrieved {len(functions)} functions in {end_time - start_time:.3f}s")
+            
+            start_time = time.time()
+            comments = list(client.comments.keys())
+            end_time = time.time()
+            _l.info(f"Retrieved {len(comments)} comment keys in {end_time - start_time:.3f}s")
+            
+            _l.info("✅ Client test completed successfully!")
+            
+    except ImportError as e:
+        _l.error(f"Failed to import required modules: {e}")
+        sys.exit(1)
+    except Exception as e:
+        _l.error(f"Client test failed: {e}")
+        sys.exit(1)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+            description="""
+            The DecLib Command Line Util. This is the script interface to DecLib that allows you to install and run 
+            the Ghidra UI for running plugins, and start the DecompilerServer. 
+            """,
+            epilog="""
+            Examples:
+            declib --install | 
+            declib --server --socket-path /tmp/my_server.sock | 
+            declib --server --decompiler ghidra --binary-path /path/to/binary --headless
+            """
+    )
+    parser.add_argument(
+        "--install", action="store_true", help="""
+        Install all the DecLib plugins to every decompiler. 
+        """
+    )
+    parser.add_argument(
+        "--single-decompiler-install", nargs=2, metavar=('decompiler', 'path'), help="Install DAILA into a single decompiler. Decompiler must be one of: ida, ghidra, binja, angr."
+    )
+    parser.add_argument(
+        "--server", action="store_true", help="""
+        Start the DecompilerServer to expose DecompilerInterface APIs over AF_UNIX sockets.
+        """
+    )
+    parser.add_argument(
+        "--server-url", help="""
+        URL of the DecompilerServer to connect to (e.g., unix:///tmp/server.sock). 
+        If not specified, will auto-discover running servers.
+        """
+    )
+    parser.add_argument(
+        "--socket-path", help="""
+        Path for the AF_UNIX socket (default: auto-generated in temp directory).
+        """
+    )
+    parser.add_argument(
+        "--decompiler", choices=["ida", "ghidra", "binja", "angr"], help="""
+        Force a specific decompiler for the server. If not specified, auto-detection will be used.
+        """
+    )
+    parser.add_argument(
+        "--binary-path", help="""
+        Path to the binary file to analyze (required for headless mode).
+        """
+    )
+    parser.add_argument(
+        "--headless", action="store_true", help="""
+        Run the decompiler in headless mode (no GUI). Requires --binary-path.
+        """
+    )
+    parser.add_argument(
+        "--server-id", help="""
+        Explicit server ID to use; if omitted, a unique one is generated.
+        """
+    )
+    parser.add_argument(
+        "--project-dir", help="""
+        Directory where the backend should store its project/database files
+        (Ghidra project, IDA .id*, etc.). If omitted, backend defaults apply
+        (Ghidra creates a project next to the binary; IDA writes .id* next
+        to the binary).
+        """
+    )
+    args = parser.parse_args()
+
+    if args.single_decompiler_install:
+        decompiler, path = args.single_decompiler_install
+        DecLibPluginInstaller().install(interactive=False, paths_by_target={decompiler: path})
+    elif args.install:
+        install()
+    elif args.server:
+        if args.headless and not args.binary_path:
+            parser.error("--headless requires --binary-path")
+        start_server(
+            socket_path=args.socket_path,
+            decompiler=args.decompiler,
+            binary_path=args.binary_path,
+            headless=args.headless,
+            server_id=args.server_id,
+            project_dir=args.project_dir,
+        )
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

declib/api/__init__.py

@@ -0,0 +1,13 @@
+from .artifact_lifter import ArtifactLifter
+from .decompiler_interface import DecompilerInterface
+from .type_parser import CTypeParser, CType
+
+from .decompiler_interface import (
+    DecompilerInterface
+)
+from .artifact_lifter import (
+    ArtifactLifter
+)
+from .type_parser import (
+    CTypeParser, CType
+)

declib/api/artifact_dict.py

@@ -0,0 +1,153 @@
+import typing
+import logging
+
+from declib.artifacts import (
+    Artifact, Comment, Enum, FunctionHeader, Function, FunctionArgument,
+    GlobalVariable, Patch, Segment, StackVariable, Struct, StructMember, Typedef
+)
+
+if typing.TYPE_CHECKING:
+    from declib.api import DecompilerInterface
+
+_l = logging.getLogger(__name__)
+
+
+class ArtifactDict(dict):
+    """
+    The ArtifactDict is a Dictionary wrapper around the getting/setting/listing of artifacts in the decompiler. This
+    allows for a more pythonic interface to the decompiler artifacts. For example, instead of doing:
+    deci._set_function(func)
+
+    You can do:
+    >>> deci.functions[func.addr] = func
+
+    This class is not meant to be instantiated directly, but rather through the DecompilerInterface class.
+    There is currently some interesting affects and caveats to using this class:
+    - When you list artifacts, by calling list(), you will get a light copy of the artifacts. This means that if you
+        modify the artifacts in the list, they will not be reflected in the decompiler. You also do need get current
+        data in the decompiler, only an acknowledgement that the artifact exists.
+    - You must reassign the artifact to the dictionary to update the decompiler.
+    - When assigning something to the dictionary, it must always be in its lifted form. You will also only get lifted
+        artifacts back from the dictionary.
+    - For convience, you can access functions by their lowered address
+    """
+
+    def __init__(self, artifact_cls, deci: "DecompilerInterface", error_on_duplicate=False, scopable=False):
+        super().__init__()
+
+        self._deci = deci
+        self._error_on_duplicate = error_on_duplicate
+        self._scopable = scopable
+        self._art_function = {
+            # ArtifactType: (setter, getter, lister)
+            Function: (self._deci._set_function, self._deci._get_function, self._deci._functions, self._deci._del_function),
+            StackVariable: (self._deci._set_stack_variable, self._deci._get_stack_variable, self._deci._stack_variables, self._deci._del_stack_variable),
+            GlobalVariable: (self._deci._set_global_variable, self._deci._get_global_var, self._deci._global_vars, self._deci._del_global_var),
+            Struct: (self._deci._set_struct, self._deci._get_struct, self._deci._structs, self._deci._del_struct),
+            Enum: (self._deci._set_enum, self._deci._get_enum, self._deci._enums, self._deci._del_enum),
+            Typedef: (self._deci._set_typedef, self._deci._get_typedef, self._deci._typedefs, self._deci._del_typedef),
+            Comment: (self._deci._set_comment, self._deci._get_comment, self._deci._comments, self._deci._del_comment),
+            Patch: (self._deci._set_patch, self._deci._get_patch, self._deci._patches, self._deci._del_patch),
+            Segment: (self._deci._set_segment, self._deci._get_segment, self._deci._segments, self._deci._del_segment)
+        }
+
+        functions = self._art_function.get(artifact_cls, None)
+        if functions is None:
+            raise ValueError(f"Attempting to create a dict for a Artifact class that is not supported: {artifact_cls}")
+
+        self._artifact_class = artifact_cls
+        self._artifact_setter, self._artifact_getter, self._artifact_lister, self._artifact_remover = functions
+
+    def __len__(self):
+        return len(self._artifact_lister())
+
+    def _lifted_art_lister(self):
+        d = self._artifact_lister()
+        d_items = list(d.items())
+        if not d_items:
+            return {}
+
+        is_addr = hasattr(d_items[0][1], "addr")
+        new_d = {}
+        for k, v in d_items:
+            if is_addr:
+                k = self._deci.art_lifter.lift_addr(k)
+            new_d[k] = self._deci.art_lifter.lift(v)
+
+        return new_d
+
+    def __getitem__(self, item):
+        """
+        Takes a lifted identifier as input and returns a lifted artifact
+        """
+        if isinstance(item, int):
+            item = self._deci.art_lifter.lower_addr(item)
+        if self._scopable and not self._deci.supports_type_scopes:
+            item, _ = self._deci.art_lifter.parse_scoped_type(item)
+
+        art = self._artifact_getter(item)
+        if art is None:
+            raise KeyError
+
+        return self._deci.art_lifter.lift(art)
+
+    def __setitem__(self, key, value):
+        """
+        Both key and value must be lifted artifacts
+        """
+        if not isinstance(value, self._artifact_class):
+            raise ValueError(f"Attempting to set a value of type {type(value)} to a dict of type {self._artifact_class}")
+
+        if isinstance(key, int):
+            key = self._deci.art_lifter.lower_addr(key)
+        if self._scopable and not self._deci.supports_type_scopes:
+            key, _ = self._deci.art_lifter.parse_scoped_type(key)
+
+        art = self._deci.art_lifter.lower(value)
+        if not self._artifact_setter(art) and self._error_on_duplicate:
+            raise ValueError(f"Set value {value} is already present at key {key}")
+
+    def __contains__(self, item):
+        if isinstance(item, int):
+            item = self._deci.art_lifter.lower_addr(item)
+        if self._scopable and not self._deci.supports_type_scopes:
+            item, _ = self._deci.art_lifter.parse_scoped_type(item)
+
+        data = self._artifact_getter(item)
+        return data is not None
+
+    def __delitem__(self, key):
+        if isinstance(key, int):
+            key = self._deci.art_lifter.lower_addr(key)
+        if self._scopable and not self._deci.supports_type_scopes:
+            key, _ = self._deci.art_lifter.parse_scoped_type(key)
+
+        art = self._artifact_getter(key)
+        if isinstance(art, Struct):
+            self._artifact_remover(key)
+            self._deci.struct_changed(art, deleted=True)
+        else:
+            self._artifact_remover(key)
+
+    def __iter__(self):
+        return iter(self._lifted_art_lister())
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__}: {self._artifact_class.__name__} len={self.__len__()}>"
+
+    def __str__(self):
+        return f"{self._lifted_art_lister()}"
+
+    def keys(self):
+        return self._lifted_art_lister().keys()
+
+    def values(self):
+        return self._lifted_art_lister().values()
+
+    def items(self):
+        return self._lifted_art_lister().items()
+
+    def get(self, key, default=None):
+        if key in self:
+            return self[key]
+        return default

declib/api/artifact_lifter.py

@@ -0,0 +1,161 @@
+import logging
+import typing
+
+from declib.artifacts import StackVariable, Artifact, FunctionArgument, StructMember, Typedef, Enum, Struct
+from declib.api.type_parser import CTypeParser
+
+if typing.TYPE_CHECKING:
+    from declib.api import DecompilerInterface
+
+_l = logging.getLogger(name=__name__)
+
+
+class ArtifactLifter:
+    SCOPE_DELIMITER = "::"
+
+    def __init__(self, deci: "DecompilerInterface", types=None):
+        self.deci = deci
+        self.type_parser = CTypeParser(extra_types=types)
+
+    #
+    # Public API
+    #
+
+    def lift(self, artifact: Artifact):
+        return self._lift_or_lower_artifact(artifact, "lift")
+
+    def lower(self, artifact: Artifact):
+        return self._lift_or_lower_artifact(artifact, "lower")
+
+    #
+    # Special handlers for scopes
+    #
+
+    @staticmethod
+    def parse_scoped_type(type_str: str) -> tuple[str, str | None]:
+        """
+        Parses a scoped type string into its base type and scope.
+        Note: the scope can be None if the type is not scoped.
+
+        Examples:
+        'stdint::uint32_t' -> ('uint32_t', 'stdint')
+        'uint32_t' -> ('uint32_t', None)
+        """
+        if not type_str:
+            return "", None
+
+        # check if the type is scoped
+        scope = None
+        deli = ArtifactLifter.SCOPE_DELIMITER
+        if deli in type_str:
+            scope_parts = type_str.split(deli)
+            base_type = scope_parts[-1]
+            scope = deli.join(scope_parts[:-1])
+        else:
+            base_type = type_str
+
+        return base_type, scope
+
+    @staticmethod
+    def scoped_type_to_str(name: str, scope: str | None = None) -> str:
+        """
+        Converts a name and scope into a scoped type string.
+        Note: the scope can be None if the type is not scoped.
+        """
+        return name if not scope else f"{scope}::{name}"
+
+    #
+    # Override Mandatory Funcs
+    #
+
+    def lift_type(self, type_str: str) -> str:
+        return type_str
+
+    def lift_addr(self, addr: int) -> int:
+        base_addr = self.deci.binary_base_addr
+        if addr < base_addr:
+            self.deci.warning(f"Lifting an address that appears already lifted: {addr}...")
+
+        return addr - base_addr
+
+    def lift_stack_offset(self, offset: int, func_addr: int) -> int:
+        pass
+
+    def lower_type(self, type_str: str) -> str:
+        if self.SCOPE_DELIMITER in type_str and not self.deci.supports_type_scopes:
+            type_str, scope = self.scoped_type_to_str(type_str)
+
+        return type_str
+
+    def lower_addr(self, addr: int) -> int:
+        base_addr = self.deci.binary_base_addr
+        if addr >= base_addr != 0:
+            self.deci.warning(f"Lowering an address that appears already lowered: {addr}...")
+
+        return addr + base_addr
+
+    def lower_stack_offset(self, offset: int, func_addr: int) -> int:
+        pass
+
+    #
+    # Private
+    #
+
+    def _lift_or_lower_artifact(self, artifact, mode):
+        target_attrs = ("name", "type", "offset", "addr", "func_addr", "line_map")
+        if mode not in ("lower", "lift"):
+            return None
+
+        if not isinstance(artifact, Artifact):
+            return artifact
+        lifted_art = artifact.copy()
+        # correct simple properties in the artifact
+        for attr in target_attrs:
+            if hasattr(lifted_art, attr):
+                curr_val = getattr(lifted_art, attr)
+                if curr_val is None:
+                    continue
+
+                # special handling for stack variables
+                if attr == "offset":
+                    if not isinstance(artifact, StackVariable):
+                        continue
+                    lifting_func = getattr(self, f"{mode}_stack_offset")
+                    setattr(lifted_art, attr, lifting_func(curr_val, lifted_art.addr))
+                # special handling for decompilation
+                elif attr == "line_map":
+                    lifted_line_map = {}
+                    lift_or_lower_func = self.lift_addr if mode == "lift" else self.lower_addr
+                    for k, v in curr_val.items():
+                        lifted_line_map[k] = {lift_or_lower_func(_v) for _v in v}
+
+                    setattr(lifted_art, attr, lifted_line_map)
+                # special handling for types that have names
+                elif attr == "name":
+                    if not isinstance(artifact, (Typedef, Enum, Struct)):
+                        continue
+                    lifted_type = self.lift_type(curr_val) if mode == "lift" else self.lower_type(curr_val)
+                    setattr(lifted_art, attr, lifted_type)
+                else:
+                    attr_func_name = attr if attr != "func_addr" else "addr"
+                    lifting_func = getattr(self, f"{mode}_{attr_func_name}")
+                    setattr(lifted_art, attr, lifting_func(curr_val))
+
+        # recursively correct nested artifacts
+        for attr in lifted_art.__slots__:
+            attr_val = getattr(lifted_art, attr)
+            if not attr_val:
+                continue
+
+            # nested function headers
+            if attr == "header":
+                setattr(lifted_art, attr, self._lift_or_lower_artifact(attr_val, mode))
+            # nested args, stack_vars, or struct_members
+            elif isinstance(attr_val, dict):
+                nested_arts = {}
+                for k, v in attr_val.items():
+                    nested_art = self._lift_or_lower_artifact(v, mode)
+                    nested_arts[nested_art.offset if isinstance(nested_art, (StackVariable, FunctionArgument, StructMember)) else k] = nested_art
+                setattr(lifted_art, attr, nested_arts)
+
+        return lifted_art