declib 4.0.2__tar.gz → 4.1.0__tar.gz

{declib-4.0.2 → declib-4.1.0}/PKG-INFO

@@ -1,10 +1,9 @@
 Metadata-Version: 2.4
 Name: declib
-Version: 4.0.2
+Version: 4.1.0
 Summary: Your Only Decompiler API Lib - A generic API to script in and out of decompilers
-License: BSD 2 Clause
+License-Expression: BSD-2-Clause
 Project-URL: Homepage, https://github.com/binsync/declib
-Classifier: License :: OSI Approved :: BSD License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.12

{declib-4.0.2 → declib-4.1.0}/declib/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "4.0.2"
+__version__ = "4.1.0"
 
 
 import logging

{declib-4.0.2 → declib-4.1.0}/declib/api/decompiler_client.py

@@ -437,6 +437,8 @@ class DecompilerClient:
                         raise ValueError(error_msg)
                     elif error_type == "AttributeError":
                         raise AttributeError(error_msg)
+                    elif error_type == "NotImplementedError":
+                        raise NotImplementedError(error_msg)
                     else:
                         raise RuntimeError(f"{error_type}: {error_msg}")
                 
@@ -562,6 +564,70 @@ class DecompilerClient:
     def read_memory(self, addr: int, size: int) -> Optional[bytes]:
         """Read raw bytes from the loaded program."""
         return self._send_request({"type": "method_call", "method_name": "read_memory", "args": [addr, size]})
+
+    def search_bytes(self, pattern: bytes, max_results: int = 100) -> List[int]:
+        """Return lifted addresses where the byte pattern occurs."""
+        return self._send_request({"type": "method_call", "method_name": "search_bytes", "args": [pattern, max_results]})
+
+    def list_imports(self) -> List:
+        """Return (lifted_addr, name, library) tuples for imported symbols."""
+        return self._send_request({"type": "method_call", "method_name": "list_imports"})
+
+    def backend_eval(self, code: str, mode: str = "eval") -> Dict:
+        """UNSAFE: run arbitrary Python in the backend process. See the interface docstring."""
+        return self._send_request({"type": "method_call", "method_name": "backend_eval", "args": [code], "kwargs": {"mode": mode}})
+
+    def define_function(self, addr: int) -> bool:
+        """Create a function at ``addr`` (lifted)."""
+        return self._send_request({"type": "method_call", "method_name": "define_function", "args": [addr]})
+
+    def define_code(self, addr: int) -> bool:
+        """Turn the bytes at ``addr`` (lifted) into an instruction."""
+        return self._send_request({"type": "method_call", "method_name": "define_code", "args": [addr]})
+
+    def define_data(self, addr: int, type_str: Optional[str] = None, size: Optional[int] = None) -> bool:
+        """Define data at ``addr`` (lifted), optionally with a C type."""
+        return self._send_request({"type": "method_call", "method_name": "define_data", "args": [addr, type_str, size]})
+
+    def undefine(self, addr: int, size: int = 1) -> bool:
+        """Undefine code/data at ``addr`` (lifted)."""
+        return self._send_request({"type": "method_call", "method_name": "undefine", "args": [addr, size]})
+
+    def save(self, path: Optional[str] = None) -> bool:
+        """Persist the backend's analysis to disk. Raises NotImplementedError for in-memory backends."""
+        return self._send_request({"type": "method_call", "method_name": "save", "args": [path]})
+
+    def set_persist_on_close(self, value: bool) -> bool:
+        """Control whether the backend flushes to disk on teardown."""
+        return self._send_request({"type": "method_call", "method_name": "set_persist_on_close", "args": [value]})
+
+    def get_comment(self, addr: int) -> Optional[Comment]:
+        """Return the Comment at ``addr`` (lifted), or None. Direct read, no cache."""
+        return self._send_request({"type": "method_call", "method_name": "get_comment", "args": [addr]})
+
+    def delete_comment(self, addr: int) -> bool:
+        """Delete any comment at ``addr`` (lifted)."""
+        return self._send_request({"type": "method_call", "method_name": "delete_comment", "args": [addr]})
+
+    def get_global_var(self, addr: int) -> Optional[GlobalVariable]:
+        """Return the GlobalVariable at ``addr`` (lifted), or None. Direct read, no cache."""
+        return self._send_request({"type": "method_call", "method_name": "get_global_var", "args": [addr]})
+
+    def get_patch(self, addr: int) -> Optional[Patch]:
+        """Return the Patch at ``addr`` (lifted), or None. Direct read, no cache."""
+        return self._send_request({"type": "method_call", "method_name": "get_patch", "args": [addr]})
+
+    def delete_patch(self, addr: int) -> bool:
+        """Revert the patch at ``addr`` (lifted)."""
+        return self._send_request({"type": "method_call", "method_name": "delete_patch", "args": [addr]})
+
+    def get_function_signature(self, func_addr: int) -> Optional[str]:
+        """Return the C prototype string for the function at ``func_addr`` (lifted)."""
+        return self._send_request({"type": "method_call", "method_name": "get_function_signature", "args": [func_addr]})
+
+    def set_function_signature(self, func_addr: int, prototype: str) -> bool:
+        """Apply a full C prototype (return type + argument types/names)."""
+        return self._send_request({"type": "method_call", "method_name": "set_function_signature", "args": [func_addr, prototype]})
     
     def get_callgraph(self, only_names=False):
         """Get the call graph"""

{declib-4.0.2 → declib-4.1.0}/declib/api/decompiler_interface.py

@@ -528,6 +528,181 @@ class DecompilerInterface:
         """
         raise NotImplementedError
 
+    def get_comment(self, addr) -> Optional[Comment]:
+        """Return the lifted Comment at ``addr`` (lifted), or None.
+
+        Reads the backend directly rather than through the light-artifact
+        cache, so a comment set moments earlier is immediately visible.
+        """
+        lowered = self.art_lifter.lower_addr(addr)
+        cmt = self._get_comment(lowered)
+        return self.art_lifter.lift(cmt) if cmt is not None else None
+
+    def delete_comment(self, addr) -> bool:
+        """Delete any comment at ``addr`` (lifted). True if one was removed."""
+        lowered = self.art_lifter.lower_addr(addr)
+        return self._del_comment(lowered)
+
+    def get_global_var(self, addr) -> Optional[GlobalVariable]:
+        """Return the lifted GlobalVariable at ``addr`` (lifted), or None.
+
+        Direct backend read (bypasses the light-artifact cache), so a global
+        renamed/retyped moments earlier is immediately visible.
+        """
+        lowered = self.art_lifter.lower_addr(addr)
+        gvar = self._get_global_var(lowered)
+        return self.art_lifter.lift(gvar) if gvar is not None else None
+
+    def get_patch(self, addr) -> Optional[Patch]:
+        """Return the lifted Patch at ``addr`` (lifted), or None (direct read)."""
+        lowered = self.art_lifter.lower_addr(addr)
+        patch = self._get_patch(lowered)
+        return self.art_lifter.lift(patch) if patch is not None else None
+
+    def delete_patch(self, addr) -> bool:
+        """Revert the patch at ``addr`` (lifted). True if bytes were reverted."""
+        lowered = self.art_lifter.lower_addr(addr)
+        return self._del_patch(lowered)
+
+    def get_function_signature(self, func_addr) -> Optional[str]:
+        """Return the C prototype string for the function at ``func_addr`` (lifted)."""
+        from declib.api.prototype import format_prototype
+
+        func = self.functions[func_addr]
+        if func is None or func.header is None:
+            return None
+        return format_prototype(func.header)
+
+    def set_function_signature(self, func_addr, prototype: str) -> bool:
+        """Apply a full C prototype (return type + argument types/names).
+
+        The generic implementation parses the prototype and overwrites the
+        function's existing parameters positionally, then re-applies the
+        header through the normal set path. It retypes/renames the parameters
+        the backend already recognizes; it does not add or remove parameters.
+        Backends with an atomic prototype-set API (IDA's ``SetType``) override
+        this for fidelity.
+        """
+        from declib.api.prototype import parse_prototype
+
+        ret_type, arg_specs = parse_prototype(prototype)
+        func = self.functions[func_addr]
+        if func is None or func.header is None:
+            return False
+        if ret_type:
+            func.header.type = ret_type
+        for (_off, arg), (atype, aname) in zip(sorted(func.header.args.items()), arg_specs):
+            if atype and atype != "...":
+                arg.type = atype
+            if aname:
+                arg.name = aname
+        return bool(self.set_artifact(func))
+
+    # ------------------------------------------------------------------
+    # Persistence
+    # ------------------------------------------------------------------
+    #: Whether the backend should flush its analysis to disk when the
+    #: interface is torn down (``shutdown()`` -> ``_deinit_headless_components``).
+    #: Backends override the default to match their native behavior (IDA
+    #: discards on close, Ghidra saves on close). ``set_persist_on_close``
+    #: flips it so ``decompiler stop --save/--discard`` can control the final
+    #: flush without an extra round-trip.
+    persist_on_close: bool = False
+
+    def save(self, path: Optional[str] = None) -> bool:
+        """Persist the current analysis to the backend's on-disk database/project.
+
+        This is the durable-artifact primitive: after ``save()`` returns True,
+        renames/retypes/comments made through DecLib survive a stop + reload of
+        the same project directory. Backends that hold no persistent database
+        (e.g. angr, which is purely in-memory) raise ``NotImplementedError``.
+
+        @param path: Optional explicit output path. When ``None`` the backend
+            writes to whatever database/project it already has open.
+        @return: True on success.
+        """
+        raise NotImplementedError("This backend does not support saving to disk.")
+
+    def set_persist_on_close(self, value: bool) -> bool:
+        """Control whether teardown flushes analysis to disk.
+
+        Used by ``decompiler stop --save/--discard`` to decide the final flush
+        for backends (like Ghidra) that persist on close by default.
+        """
+        self.persist_on_close = bool(value)
+        return True
+
+    def search_bytes(self, pattern: bytes, max_results: int = 100) -> List[int]:
+        """Return lifted addresses where the raw byte ``pattern`` occurs.
+
+        Subclasses with a native byte-search API override this. The base
+        raises ``NotImplementedError`` so the CLI can report the capability as
+        unsupported for backends (e.g. angr) that lack one.
+        """
+        raise NotImplementedError("Byte search is not implemented for this backend.")
+
+    # ------------------------------------------------------------------
+    # Code/data repair (define / undefine)
+    # ------------------------------------------------------------------
+    def define_function(self, addr) -> bool:
+        """Create a function at ``addr`` (lifted). Repairs missed analysis."""
+        raise NotImplementedError("define_function is not implemented for this backend.")
+
+    def define_code(self, addr) -> bool:
+        """Turn the bytes at ``addr`` (lifted) into an instruction."""
+        raise NotImplementedError("define_code is not implemented for this backend.")
+
+    def define_data(self, addr, type_str: Optional[str] = None, size: Optional[int] = None) -> bool:
+        """Define data at ``addr`` (lifted), optionally with a C type."""
+        raise NotImplementedError("define_data is not implemented for this backend.")
+
+    def undefine(self, addr, size: int = 1) -> bool:
+        """Undefine code/data at ``addr`` (lifted). Removes a function if one starts here."""
+        raise NotImplementedError("undefine is not implemented for this backend.")
+
+    def list_imports(self) -> List[Tuple[int, str, str]]:
+        """Return ``(lifted_addr, name, library)`` tuples for imported symbols.
+
+        Subclasses override with a native import enumeration. The base raises
+        ``NotImplementedError``.
+        """
+        raise NotImplementedError("Import listing is not implemented for this backend.")
+
+    def backend_eval(self, code: str, mode: str = "eval") -> Dict:
+        """UNSAFE escape hatch: run arbitrary Python inside the backend process.
+
+        The code executes with this interface bound to ``deci`` and full access
+        to the backend's own Python API (``idaapi``, the Ghidra ``flat_api`` via
+        ``deci.flat_api``, ``deci.project`` for angr, ``deci.bv`` for Binary
+        Ninja, ...). This is deliberately backend-specific and not portable — it
+        exists for the cases the abstracted API doesn't cover.
+
+        @param code: Python source. ``mode='eval'`` evaluates a single
+            expression and returns its ``repr``; ``mode='exec'`` runs
+            statements, capturing stdout and any variable named ``result``.
+        @return: ``{"ok", "result", "stdout", "traceback"}``. (The failure key is
+            ``traceback`` rather than ``error`` on purpose — the client/server
+            wire protocol reserves a top-level ``error`` key for RPC failures.)
+        """
+        import io
+        import contextlib
+        import traceback as _traceback
+
+        env = {"deci": self, "__name__": "__declib_backend_eval__"}
+        out = io.StringIO()
+        try:
+            with contextlib.redirect_stdout(out):
+                if mode == "exec":
+                    exec(code, env)  # noqa: S102 - intentional escape hatch
+                    value = env.get("result", None)
+                    result = repr(value) if value is not None else ""
+                else:
+                    result = repr(eval(code, env))  # noqa: S307 - intentional escape hatch
+            return {"ok": True, "result": result, "stdout": out.getvalue(), "traceback": None}
+        except Exception:  # noqa: BLE001 - surface any backend error verbatim
+            return {"ok": False, "result": None, "stdout": out.getvalue(),
+                    "traceback": _traceback.format_exc()}
+
     def get_callgraph(self, only_names=False) -> nx.DiGraph:
         """
         Returns the callgraph of the binary. This is a dict of function addresses to a list of function addresses

declib-4.1.0/declib/api/prototype.py

@@ -0,0 +1,91 @@
+"""Parsing and formatting of C function prototypes.
+
+Shared by the CLI (``signature`` command) and the DecompilerInterface's
+``set_function_signature`` so both agree on how a prototype string maps to a
+return type + argument (type, name) pairs.
+"""
+import re
+from typing import List, Optional, Tuple
+
+
+def split_c_args(body: str) -> List[str]:
+    """Split a C argument list on top-level commas (respecting () <> [] nesting)."""
+    parts, depth, cur = [], 0, ""
+    for ch in body:
+        if ch in "(<[":
+            depth += 1
+        elif ch in ")>]":
+            depth -= 1
+        if ch == "," and depth == 0:
+            parts.append(cur)
+            cur = ""
+        else:
+            cur += ch
+    if cur.strip():
+        parts.append(cur)
+    return parts
+
+
+def norm_c_type(t: str) -> str:
+    """Normalize whitespace and pointer spacing in a C type string."""
+    return re.sub(r"\s+", " ", t.replace("*", " * ")).replace(" * ", " *").strip()
+
+
+def parse_prototype(proto: str) -> Tuple[str, List[Tuple[str, Optional[str]]]]:
+    """Parse ``ret name(argtype argname, ...)`` -> (return_type, [(type, name), ...]).
+
+    Handles pointer return/argument types, ``void`` argument lists, and varargs
+    (``...``). Argument names are optional. Raises ``ValueError`` on malformed
+    input.
+    """
+    proto = proto.strip().rstrip(";").strip()
+    open_i = proto.find("(")
+    if open_i == -1:
+        raise ValueError("no argument list '(...)' found")
+    close_i = proto.rfind(")")
+    head = proto[:open_i].strip()
+    body = proto[open_i + 1:close_i].strip()
+
+    m = re.search(r"[A-Za-z_]\w*\s*$", head)
+    if not m:
+        raise ValueError(f"cannot find a function name in {head!r}")
+    ret_type = head[:m.start()].strip()
+    if not ret_type:
+        raise ValueError("missing return type")
+
+    args: List[Tuple[str, Optional[str]]] = []
+    if body and body != "void":
+        for raw in split_c_args(body):
+            raw = raw.strip()
+            if raw == "...":
+                args.append(("...", None))
+                continue
+            am = re.search(r"[A-Za-z_]\w*\s*$", raw)
+            if am and not raw.endswith("*"):
+                aname = am.group().strip()
+                atype = raw[:am.start()].strip()
+                if not atype:  # bare type, no name (e.g. "int")
+                    atype, aname = raw, None
+            else:
+                atype, aname = raw, None
+            args.append((norm_c_type(atype), aname))
+    return norm_c_type(ret_type), args
+
+
+def format_prototype(header) -> str:
+    """Render a declib FunctionHeader as a C prototype string."""
+    ret = header.type or "void"
+    name = header.name or "sub"
+    parts = []
+    for _off, arg in sorted(header.args.items()):
+        atype = arg.type or "int"
+        aname = arg.name or ""
+        if not aname:
+            parts.append(atype)
+        else:
+            # Glue a pointer type to the name: "char *" + "b" -> "char *b".
+            sep = "" if atype.endswith("*") else " "
+            parts.append(f"{atype}{sep}{aname}")
+    arg_str = ", ".join(parts) if parts else "void"
+    ret_sep = "" if ret.endswith("*") else " "
+    return f"{ret}{ret_sep}{name}({arg_str})"