codevanta 0.1.0__py3-none-any.whl

codevanta/analysis/decompilers/__init__.py

@@ -0,0 +1,250 @@
+"""Pluggable decompiler providers: real decompilers when installed, native always.
+
+CODEVANTA can render one function with three different providers, and picks one
+without ever assuming a third-party package is present:
+
+===========  ==============================================  =====================
+ backend      runs when                                       output
+===========  ==============================================  =====================
+ ``ghidra``   ``pyghidra`` imports **and** ``GHIDRA_INSTALL_DIR``  Ghidra's C
+              points at a Ghidra installation
+ ``angr``     ``angr`` imports                                angr's C
+ ``native``   always                                           heuristic pseudo-C
+===========  ==============================================  =====================
+
+Only the last one is a CODEVANTA dependency: the optional backends import their
+heavy module lazily inside ``availability()`` / ``decompile()``, so this package
+imports and answers :func:`available_backends` on a machine with neither angr nor
+Ghidra, and never raises ``ImportError`` for a missing decompiler.
+
+Public API
+----------
+* :class:`BackendAvailability` -- ``name``, ``available``, a non-empty ``reason``
+  and the ``requires`` tuple for each backend, in the order ``ghidra``, ``angr``,
+  ``native``.
+* :class:`BackendResult` -- ``text``, ``backend``, ``language``, ``warnings`` and
+  :class:`Evidence`, with a JSON-safe :meth:`BackendResult.to_dict`.
+* :class:`DecompilerBackend` -- the protocol a provider implements.
+* :func:`available_backends` -- probe all three, in order.
+* :func:`get_backend` -- look one up by name; an unknown name raises
+  :class:`AnalysisError` listing the supported set.
+* :func:`decompile_function` -- the one entry point callers need.
+
+Selection policy
+----------------
+``backend="native"`` always works. ``backend="angr"`` / ``"ghidra"`` are strict:
+when the backend is unavailable the call raises :class:`AnalysisError` whose
+message carries the probe's reason (install hint included) -- it never leaks an
+``ImportError`` and never silently substitutes another provider.
+``backend="auto"`` (the default) prefers the first available external backend in
+the order ``ghidra``, ``angr`` and falls back to ``native``; whatever it chose,
+the returned :class:`BackendResult` carries one warning per unavailable backend
+naming that backend and its reason, so a fallback is never silent.
+
+Budgets are validated once, here (:func:`codevanta.analysis.decompilers.base.
+require_budget`), before any backend is touched: an out-of-range
+``max_instructions`` / ``max_blocks`` raises regardless of the backend.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from pathlib import Path
+
+from codevanta.analysis.decompile import (
+    DEFAULT_MAX_BLOCKS,
+    DEFAULT_MAX_INSTRUCTIONS,
+    MAX_MAX_BLOCKS,
+    MAX_MAX_INSTRUCTIONS,
+)
+from codevanta.core.loader import BinaryInfo
+from codevanta.core.report import AnalysisError
+
+from .angr_backend import AngrBackend
+from .base import (
+    LANGUAGE,
+    BackendAvailability,
+    BackendResult,
+    DecompilerBackend,
+    NativeBackend,
+    require_budget,
+)
+from .ghidra_backend import GhidraBackend
+
+__all__ = [
+    "AUTO",
+    "LANGUAGE",
+    "AngrBackend",
+    "BackendAvailability",
+    "BackendResult",
+    "DecompilerBackend",
+    "GhidraBackend",
+    "NativeBackend",
+    "available_backends",
+    "decompile_function",
+    "get_backend",
+    "require_budget",
+    "supported_backends",
+]
+
+#: External backends in preference order for ``backend="auto"``.
+_EXTERNAL_ORDER: tuple[str, ...] = ("ghidra", "angr")
+
+#: Every supported backend, in report order (external ones first).
+_BACKEND_ORDER: tuple[str, ...] = (*_EXTERNAL_ORDER, "native")
+
+#: Backend instances by name; one shared stateless instance each.
+_BACKENDS: dict[str, DecompilerBackend] = {
+    backend.name: backend for backend in (GhidraBackend(), AngrBackend(), NativeBackend())
+}
+
+#: Name used by :func:`decompile_function` to mean "pick for me".
+AUTO = "auto"
+
+
+def supported_backends() -> tuple[str, ...]:
+    """Return the supported backend names, in report order."""
+    return _BACKEND_ORDER
+
+
+def _probe(backend: DecompilerBackend) -> BackendAvailability:
+    """Run one availability probe, turning a crash into an "unavailable" record."""
+    try:
+        return backend.availability()
+    except Exception as exc:  # a broken optional dependency must never break discovery
+        return BackendAvailability(
+            name=backend.name,
+            available=False,
+            reason=f"the availability probe itself failed ({type(exc).__name__}: {exc})",
+            requires=tuple(backend.requires),
+        )
+
+
+def available_backends() -> tuple[BackendAvailability, ...]:
+    """Probe every backend without installing or launching anything.
+
+    Returns:
+        One record per supported backend, always in the order ``ghidra``, ``angr``,
+        ``native``. Unavailable records always carry a non-empty reason.
+    """
+    return tuple(_probe(_BACKENDS[name]) for name in _BACKEND_ORDER)
+
+
+def get_backend(name: str) -> DecompilerBackend:
+    """Return the backend registered under ``name``.
+
+    Args:
+        name: ``ghidra``, ``angr`` or ``native``; matched case-insensitively and
+            ignoring surrounding whitespace.
+
+    Returns:
+        The shared backend instance. Availability is *not* checked here; call
+        :meth:`DecompilerBackend.availability` or use :func:`decompile_function`.
+
+    Raises:
+        AnalysisError: When the name is unknown; the message lists the supported set.
+    """
+    key = name.strip().lower() if isinstance(name, str) else ""
+    backend = _BACKENDS.get(key)
+    if backend is None:
+        raise AnalysisError(
+            f"unknown decompiler backend {name!r}; supported backends: {', '.join(_BACKEND_ORDER)}"
+        )
+    return backend
+
+
+def _unavailable_message(availability: BackendAvailability) -> str:
+    """Explain why a strictly requested backend cannot run."""
+    return (
+        f"decompiler backend {availability.name!r} is unavailable: {availability.reason}; "
+        "use backend='auto' to fall back to another provider, or backend='native'"
+    )
+
+
+def decompile_function(
+    path: str | Path,
+    info: BinaryInfo,
+    address: int,
+    backend: str = AUTO,
+    max_instructions: int = DEFAULT_MAX_INSTRUCTIONS,
+    max_blocks: int = DEFAULT_MAX_BLOCKS,
+) -> BackendResult:
+    """Decompile one function with the requested backend.
+
+    Args:
+        path: Binary the function lives in (opened read-only; never executed).
+        info: Loaded metadata for ``path``.
+        address: Virtual address of the function.
+        backend: ``"auto"`` (default), ``"native"``, ``"angr"`` or ``"ghidra"``.
+        max_instructions: Instruction budget, validated against
+            :data:`~codevanta.analysis.decompile.MAX_MAX_INSTRUCTIONS`.
+        max_blocks: Block budget, validated against
+            :data:`~codevanta.analysis.decompile.MAX_MAX_BLOCKS`.
+
+    Returns:
+        The :class:`BackendResult` of whichever backend produced the text.
+
+    Raises:
+        AnalysisError: On an unknown backend name, on an out-of-range budget, when
+            a strictly requested backend is unavailable (the message carries the
+            reason), or when the backend itself rejects the request. A missing
+            optional dependency never surfaces as ``ImportError``.
+    """
+    instruction_budget = require_budget("max_instructions", max_instructions, MAX_MAX_INSTRUCTIONS)
+    block_budget = require_budget("max_blocks", max_blocks, MAX_MAX_BLOCKS)
+    if not isinstance(backend, str):
+        raise AnalysisError(f"backend must be a string, not {type(backend).__name__}")
+    key = backend.strip().lower() or AUTO
+    if key == AUTO:
+        return _decompile_auto(path, info, address, instruction_budget, block_budget)
+    chosen = get_backend(key)
+    availability = _probe(chosen)
+    if not availability.available:
+        raise AnalysisError(_unavailable_message(availability))
+    return chosen.decompile(
+        path,
+        info,
+        address,
+        max_instructions=instruction_budget,
+        max_blocks=block_budget,
+    )
+
+
+def _decompile_auto(
+    path: str | Path,
+    info: BinaryInfo,
+    address: int,
+    max_instructions: int,
+    max_blocks: int,
+) -> BackendResult:
+    """Pick the best available provider and record every fallback in ``warnings``."""
+    probes = tuple(_probe(_BACKENDS[name]) for name in _EXTERNAL_ORDER)
+    notes = [
+        f"auto: backend {probe.name!r} was unavailable and skipped: {probe.reason}"
+        for probe in probes
+        if not probe.available
+    ]
+    for probe in probes:
+        if not probe.available:
+            continue
+        try:
+            result = _BACKENDS[probe.name].decompile(
+                path,
+                info,
+                address,
+                max_instructions=max_instructions,
+                max_blocks=max_blocks,
+            )
+        except AnalysisError as exc:
+            notes.append(f"auto: backend {probe.name!r} failed and was skipped: {exc}")
+            continue
+        return replace(result, warnings=(*notes, *result.warnings))
+
+    result = _BACKENDS["native"].decompile(
+        path,
+        info,
+        address,
+        max_instructions=max_instructions,
+        max_blocks=max_blocks,
+    )
+    return replace(result, warnings=(*notes, *result.warnings))

codevanta/analysis/decompilers/angr_backend.py

@@ -0,0 +1,251 @@
+"""angr decompiler backend (optional dependency, imported lazily).
+
+``angr`` ships a decompiler analysis on top of its CFG recovery, so it is the
+cheapest way to get real pseudo-C without an external process. The package is
+*not* a hard requirement of CODEVANTA: nothing here is imported until
+:meth:`AngrBackend.availability` or :meth:`AngrBackend.decompile` runs, so
+``import codevanta.analysis.decompilers`` never fails on a machine without angr.
+
+Pipeline: ``angr.Project(path)`` (no shared libraries, no DWARF) -> ``CFGFast``
+-> ``project.analyses.Decompiler(function, cfg=cfg.model)`` -> ``codegen.text``.
+
+Budgeting: angr exposes no instruction or block budget on ``CFGFast`` and none on
+``Decompiler``. The work is bounded *indirectly* -- the CFG starts from the one
+requested address and indirect-jump resolution is disabled -- and the resulting
+block count is checked against ``max_blocks`` afterwards, which can only be
+reported as a warning. ``max_instructions`` cannot be enforced at all; both
+budgets are recorded in the evidence so a reader can see what was asked for.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from codevanta.analysis.decompile import (
+    DEFAULT_MAX_BLOCKS,
+    DEFAULT_MAX_INSTRUCTIONS,
+    MAX_MAX_BLOCKS,
+    MAX_MAX_INSTRUCTIONS,
+)
+from codevanta.core.loader import BinaryInfo
+from codevanta.core.report import AnalysisError
+from codevanta.evidence.confidence import Confidence
+from codevanta.evidence.models import Evidence
+
+from .base import (
+    LANGUAGE,
+    BackendAvailability,
+    BackendResult,
+    require_budget,
+)
+
+__all__ = ["AngrBackend", "INSTALL_HINT", "NAME"]
+
+#: Backend identifier.
+NAME = "angr"
+
+#: What a user has to install for this backend to become available.
+INSTALL_HINT = "pip install angr"
+
+#: Evidence source label.
+_SOURCE = "angr.decompiler"
+
+#: Evidence method label.
+_METHOD = "analyses.Decompiler"
+
+#: Comment emitted when angr's decompiler produced no code.
+_EMPTY_TEXT = "/* angr produced no pseudocode for 0x{address:x} */"
+
+
+def _unavailable(availability: BackendAvailability) -> AnalysisError:
+    """Build the error raised when a caller asked for an unavailable backend."""
+    return AnalysisError(
+        f"decompiler backend {availability.name!r} is unavailable: {availability.reason}; "
+        "use backend='native' or backend='auto' instead"
+    )
+
+
+class AngrBackend:
+    """Decompilation through angr's ``analyses.Decompiler``.
+
+    Attributes:
+        name: ``"angr"``.
+        requires: ``("angr",)``.
+    """
+
+    name: str = NAME
+    requires: tuple[str, ...] = ("angr",)
+
+    def availability(self) -> BackendAvailability:
+        """Probe ``import angr``; never raises, never installs anything."""
+        try:
+            import angr
+        except ImportError as exc:
+            return BackendAvailability(
+                name=self.name,
+                available=False,
+                reason=(
+                    f"the 'angr' package is not installed ({type(exc).__name__}: {exc}); "
+                    f"install it with '{INSTALL_HINT}'"
+                ),
+                requires=self.requires,
+            )
+        except Exception as exc:  # a broken install must not break discovery
+            return BackendAvailability(
+                name=self.name,
+                available=False,
+                reason=(
+                    f"importing 'angr' failed ({type(exc).__name__}: {exc}); "
+                    f"reinstall it with '{INSTALL_HINT}'"
+                ),
+                requires=self.requires,
+            )
+        version = str(getattr(angr, "__version__", "unknown"))
+        return BackendAvailability(
+            name=self.name,
+            available=True,
+            reason=f"angr {version} is importable; CFGFast + analyses.Decompiler can run",
+            requires=self.requires,
+        )
+
+    def decompile(
+        self,
+        path: str | Path,
+        info: BinaryInfo,
+        address: int,
+        max_instructions: int = DEFAULT_MAX_INSTRUCTIONS,
+        max_blocks: int = DEFAULT_MAX_BLOCKS,
+    ) -> BackendResult:
+        """Decompile ``address`` with angr's decompiler analysis.
+
+        Args:
+            path: Binary to analyse (opened read-only by angr; never executed).
+            info: Loaded metadata; angr loads the file itself, so only the path
+                is used. Kept for a uniform backend signature.
+            address: Virtual address of the function to decompile.
+            max_instructions: Recorded and validated, but see the module
+                docstring: angr cannot enforce an instruction budget.
+            max_blocks: Checked against the recovered block count after the fact;
+                an overrun becomes a warning, not an error.
+
+        Returns:
+            The rendering plus any warnings angr could not prevent.
+
+        Raises:
+            AnalysisError: When angr is unavailable, a budget is out of range,
+                angr cannot load the file, or no function is recovered.
+        """
+        instruction_budget = require_budget(
+            "max_instructions", max_instructions, MAX_MAX_INSTRUCTIONS
+        )
+        block_budget = require_budget("max_blocks", max_blocks, MAX_MAX_BLOCKS)
+        availability = self.availability()
+        if not availability.available:
+            raise _unavailable(availability)
+
+        import angr
+
+        warnings: list[str] = []
+        try:
+            project = angr.Project(str(path), auto_load_libs=False, load_debug_info=False)
+        except Exception as exc:
+            raise AnalysisError(
+                f"angr could not load {str(path)!r}: {type(exc).__name__}: {exc}"
+            ) from exc
+        cfg = _recover_cfg(project, address)
+        function = _lookup_function(cfg, address)
+        try:
+            analysis = project.analyses.Decompiler(function, cfg=cfg.model)
+        except Exception as exc:
+            raise AnalysisError(
+                f"angr could not decompile 0x{address:x}: {type(exc).__name__}: {exc}"
+            ) from exc
+
+        text = _codegen_text(analysis)
+        if not text.strip():
+            warnings.append(
+                f"angr returned no decompilation for 0x{address:x}: the analysis "
+                "produced no codegen text, so the rendering is a placeholder comment"
+            )
+            text = _EMPTY_TEXT.format(address=address)
+
+        block_count = len(list(getattr(function, "blocks", ()) or ()))
+        if block_count > block_budget:
+            warnings.append(
+                f"angr decompiled {block_count} block(s), above max_blocks={block_budget}; "
+                "angr exposes no block budget, so the text is complete rather than truncated"
+            )
+
+        version = _angr_version(angr)
+        evidence = Evidence(
+            source=_SOURCE,
+            method=_METHOD,
+            confidence=Confidence.MEDIUM,
+            address=address,
+            detail=(
+                f"angr {version} decompiled the CFGFast function at 0x{address:x} "
+                f"({block_count} block(s)); angr exposes no instruction or block budget, so "
+                f"max_instructions={instruction_budget} could not be enforced and "
+                f"max_blocks={block_budget} is checked afterwards only"
+            ),
+            extra={
+                "backend": self.name,
+                "angr_version": version,
+                "max_instructions": instruction_budget,
+                "max_blocks": block_budget,
+                "block_count": block_count,
+            },
+        )
+        return BackendResult(
+            text=text,
+            backend=self.name,
+            language=LANGUAGE,
+            warnings=tuple(warnings),
+            evidence=evidence,
+        )
+
+
+def _angr_version(module: Any) -> str:
+    """Return the installed angr version, or ``"unknown"``."""
+    return str(getattr(module, "__version__", "unknown"))
+
+
+def _recover_cfg(project: Any, address: int) -> Any:
+    """Recover a CFG bounded to the one function start at ``address``.
+
+    Indirect-jump resolution and data-reference discovery are switched off
+    because both widen the scan without helping a single function. The keyword set
+    differs across angr releases and angr rejects an unknown arch-specific option
+    with ``KeyError`` (not ``TypeError``), so both are treated as "try the minimal
+    call": ``function_starts`` alone is the option that does the actual bounding.
+    """
+    try:
+        return project.analyses.CFGFast(
+            function_starts=[address],
+            resolve_indirect_jumps=False,
+            data_references=False,
+            normalize=True,
+        )
+    except (TypeError, KeyError):
+        return project.analyses.CFGFast(function_starts=[address])
+
+
+def _lookup_function(cfg: Any, address: int) -> Any:
+    """Return the recovered function at ``address`` or raise :class:`AnalysisError`."""
+    function = cfg.kb.functions.get(address)
+    if function is None:
+        raise AnalysisError(
+            f"angr recovered no function at 0x{address:x}; the address may not be a "
+            "function start or may be unreachable"
+        )
+    return function
+
+
+def _codegen_text(analysis: Any) -> str:
+    """Extract the pseudo-C text from a ``Decompiler`` analysis result."""
+    codegen = getattr(analysis, "codegen", None)
+    if codegen is None:
+        return ""
+    text = getattr(codegen, "text", "")
+    return "" if text is None else str(text)