angr 9.2.166__cp310-abi3-manylinux_2_28_aarch64.whl

angr/emulator.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import logging
+from enum import Enum
+
+from angr.engines.concrete import ConcreteEngine, HeavyConcreteState
+from angr.errors import AngrError
+
+
+log = logging.getLogger(name=__name__)
+
+
+class EmulatorException(AngrError):
+    """Base class for exceptions raised by the Emulator."""
+
+
+class EngineException(EmulatorException):
+    """Exception raised when the emulator encounters an unhandlable error in the engine."""
+
+
+class StateDivergedException(EmulatorException):
+    """Exception raised when an engine returns multiple successors."""
+
+
+class EmulatorStopReason(Enum):
+    """
+    Enum representing the reason for stopping the emulator.
+    """
+
+    INSTRUCTION_LIMIT = "instruction_limit"
+    BREAKPOINT = "breakpoint"
+    NO_SUCCESSORS = "no_successors"
+    MEMORY_ERROR = "memory_error"
+    FAILURE = "failure"
+    EXIT = "exit"
+
+
+class Emulator:
+    """
+    Emulator is a utility that adapts an angr `ConcreteEngine` to a more
+    user-friendly interface for concrete execution. It only supports concrete
+    execution and requires a ConcreteEngine.
+
+    Saftey: This class is not thread-safe. It should only be used in a
+    single-threaded context. It can be safely shared between multiple threads,
+    provided that only one thread is using it at a time.
+    """
+
+    _engine: ConcreteEngine
+    _state: HeavyConcreteState
+
+    def __init__(self, engine: ConcreteEngine, init_state: HeavyConcreteState):
+        """
+        :param engine: The `ConcreteEngine` to use for emulation.
+        :param init_state: The initial state to use for emulation.
+        """
+        self._engine = engine
+        self._state = init_state
+
+    @property
+    def state(self) -> HeavyConcreteState:
+        """
+        The current state of the emulator.
+        """
+        return self._state
+
+    @property
+    def breakpoints(self) -> set[int]:
+        """
+        The set of currently set breakpoints.
+        """
+        return self._engine.get_breakpoints()
+
+    def add_breakpoint(self, addr: int) -> None:
+        """
+        Add a breakpoint at the given address.
+
+        :param addr: The address to set the breakpoint at.
+        """
+        self._engine.add_breakpoint(addr)
+
+    def remove_breakpoint(self, addr: int) -> None:
+        """
+        Remove a breakpoint at the given address, if present.
+
+        :param addr: The address to remove the breakpoint from.
+        """
+        self._engine.remove_breakpoint(addr)
+
+    def run(self, num_inst: int | None = None) -> EmulatorStopReason:
+        """
+        Execute the emulator.
+        """
+        completed_engine_execs = 0
+        num_inst_executed: int = 0
+        while self._state.history.jumpkind != "Ijk_Exit":
+            # Check if there is a breakpoint at the current address
+            if completed_engine_execs > 0 and self._state.addr in self._engine.get_breakpoints():
+                return EmulatorStopReason.BREAKPOINT
+
+            # Check if we've already executed the requested number of instructions
+            if num_inst is not None and num_inst_executed >= num_inst:
+                return EmulatorStopReason.INSTRUCTION_LIMIT
+
+            # Calculate remaining instructions for this engine execution
+            remaining_inst: int | None = None
+            if num_inst is not None:
+                remaining_inst = num_inst - num_inst_executed
+
+            # Run the engine to get successors
+            try:
+                successors = self._engine.process(self._state, num_inst=remaining_inst)
+            except EngineException as e:
+                raise EngineException(f"Engine encountered an error: {e}") from e
+
+            # Handle cases with an unexpected number of successors
+            if len(successors.successors) == 0:
+                return EmulatorStopReason.NO_SUCCESSORS
+            if len(successors.successors) > 1:
+                log.warning("Concrete engine returned multiple successors")
+
+            # Set the state before raising further exceptions
+            self._state = successors.successors[0]
+
+            # Track the number of instructions executed using the state's history
+            if self._state.history.recent_instruction_count > 0:
+                num_inst_executed += self._state.history.recent_instruction_count
+
+            if successors.successors[0].history.jumpkind == "Ijk_SigSEGV":
+                return EmulatorStopReason.MEMORY_ERROR
+
+            completed_engine_execs += 1
+
+        return EmulatorStopReason.EXIT
+
+
+__all__ = (
+    "Emulator",
+    "EmulatorException",
+    "EmulatorStopReason",
+    "EngineException",
+    "StateDivergedException",
+)

angr/engines/__init__.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from .engine import SimEngine
+from .failure import SimEngineFailure
+from .hook import HooksMixin
+from .procedure import ProcedureEngine, ProcedureMixin
+from .soot import SootMixin
+from .successors import SimSuccessors, SuccessorsEngine
+from .syscall import SimEngineSyscall
+from .unicorn import SimEngineUnicorn
+from .vex import HeavyResilienceMixin, HeavyVEXMixin, SimInspectMixin, SuperFastpathMixin, TrackActionsMixin
+
+
+class UberEngine(
+    SimEngineFailure,
+    SimEngineSyscall,
+    HooksMixin,
+    SimEngineUnicorn,
+    SuperFastpathMixin,
+    TrackActionsMixin,
+    SimInspectMixin,
+    HeavyResilienceMixin,
+    SootMixin,
+    HeavyVEXMixin,
+):
+    """
+    The default execution engine for angr. This engine includes mixins for most
+    common functionality in angr, including VEX IR, unicorn, syscall handling,
+    and simprocedure handling.
+
+    For some performance-sensitive applications, you may want to create a custom
+    engine with only the necessary mixins.
+    """
+
+
+__all__ = [
+    "HeavyResilienceMixin",
+    "HeavyVEXMixin",
+    "HooksMixin",
+    "ProcedureEngine",
+    "ProcedureMixin",
+    "SimEngine",
+    "SimEngineFailure",
+    "SimEngineSyscall",
+    "SimEngineUnicorn",
+    "SimInspectMixin",
+    "SimSuccessors",
+    "SootMixin",
+    "SuccessorsEngine",
+    "SuperFastpathMixin",
+    "TrackActionsMixin",
+    "UberEngine",
+]
+
+
+try:
+    from .pcode import HeavyPcodeMixin
+
+    class UberEnginePcode(
+        SimEngineFailure, SimEngineSyscall, HooksMixin, HeavyPcodeMixin
+    ):  # pylint:disable=abstract-method
+        pass
+
+    __all__.append("UberEnginePcode")
+
+except ImportError:
+    pass

angr/engines/concrete.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import logging
+import typing
+from abc import abstractmethod, ABCMeta
+from typing_extensions import override
+
+import claripy
+from angr.engines.successors import SimSuccessors, SuccessorsEngine
+from angr.sim_state import SimState
+
+log = logging.getLogger(__name__)
+
+
+HeavyConcreteState = SimState[int, int]
+
+
+class ConcreteEngine(SuccessorsEngine, metaclass=ABCMeta):
+    """
+    ConcreteEngine extends SuccessorsEngine and adds APIs for managing breakpoints.
+    """
+
+    @abstractmethod
+    def get_breakpoints(self) -> set[int]:
+        """Return the set of currently set breakpoints."""
+
+    @abstractmethod
+    def add_breakpoint(self, addr: int) -> None:
+        """Add a breakpoint at the given address."""
+
+    @abstractmethod
+    def remove_breakpoint(self, addr: int) -> None:
+        """Remove a breakpoint at the given address, if present."""
+
+    @abstractmethod
+    def process_concrete(self, state: HeavyConcreteState, num_inst: int | None = None) -> HeavyConcreteState:
+        """
+        Process the concrete state and return a HeavyState object.
+
+        :param state: The concrete state to process.
+        :return: A HeavyState object representing the processed state.
+        """
+
+    @override
+    def process_successors(
+        self, successors: SimSuccessors, *, num_inst: int | None = None, **kwargs: dict[str, typing.Any]
+    ):
+        if len(kwargs) > 0:
+            log.warning("ConcreteEngine.process_successors received unknown kwargs: %s", kwargs)
+
+        # TODO: Properly error here when the state is not a HeavyConcreteState
+        # Alternatively, we could make SimSuccessors generic over the state type too
+        concrete_state = typing.cast(HeavyConcreteState, self.state)
+
+        concrete_successor = self.process_concrete(concrete_state, num_inst=num_inst)
+        successors.add_successor(
+            concrete_successor,
+            concrete_successor.ip,
+            claripy.true(),
+            concrete_successor.history.jumpkind,
+            add_guard=False,
+        )
+        successors.processed = True
+
+
+__all__ = ["ConcreteEngine", "HeavyConcreteState"]

angr/engines/engine.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import abc
+from typing import Generic, TypeVar
+
+
+import angr
+
+StateType = TypeVar("StateType")
+ResultType = TypeVar("ResultType")
+DataType_co = TypeVar("DataType_co", covariant=True)
+
+
+class SimEngine(Generic[StateType, ResultType], metaclass=abc.ABCMeta):
+    """
+    A SimEngine is a type which understands how to perform execution on a state.
+    """
+
+    state: StateType
+
+    def __init__(self, project: angr.Project):
+        self.project = project
+        self.arch = self.project.arch
+
+    def __getstate__(self):
+        return (self.project,)
+
+    def __setstate__(self, state):
+        self.project = state[0]

angr/engines/failure.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import logging
+
+from angr.errors import AngrExitError
+from .successors import SuccessorsEngine
+from .procedure import ProcedureMixin
+
+l = logging.getLogger(name=__name__)
+
+
+class SimEngineFailure(SuccessorsEngine, ProcedureMixin):
+    def process_successors(self, successors, **kwargs):
+        state = self.state
+        jumpkind = state.history.parent.jumpkind if state.history and state.history.parent else None
+
+        if jumpkind in ("Ijk_EmFail", "Ijk_MapFail") or (jumpkind is not None and jumpkind.startswith("Ijk_Sig")):
+            raise AngrExitError(f"Cannot execute following jumpkind {jumpkind}")
+
+        if jumpkind == "Ijk_Exit":
+            from angr.procedures import SIM_PROCEDURES
+
+            l.debug("Execution terminated at %#x", state.addr)
+            terminator = SIM_PROCEDURES["stubs"]["PathTerminator"](project=self.project)
+            return self.process_procedure(state, successors, terminator, **kwargs)
+
+        return super().process_successors(successors, **kwargs)

angr/engines/hook.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+import logging
+
+from .successors import SuccessorsEngine
+from .procedure import ProcedureMixin
+from archinfo.arch_soot import SootAddressDescriptor
+
+l = logging.getLogger(name=__name__)
+
+
+# pylint: disable=abstract-method,unused-argument,arguments-differ
+class HooksMixin(SuccessorsEngine, ProcedureMixin):
+    """
+    A SimEngine mixin which adds a SimSuccessors handler which will look into the project's hooks and run the hook at
+    the current address.
+
+    Will respond to the following parameters provided to the step stack:
+
+    - procedure:        A SimProcedure instance to force-run instead of consulting the current hooks
+    - ret_to:           An address to force-return-to at the end of the procedure
+    """
+
+    def _lookup_hook(self, state, procedure):
+        # TODO this is moderately controversial. If the jumpkind was NoHook and the user provided the procedure
+        # argument, which takes precedence?
+        # tentative guess: passed argument takes priority
+        if procedure is not None:
+            return procedure
+
+        # we have at this point entered the next step - we should check the "previous" jumpkind
+        if state.history and state.history.parent and state.history.parent.jumpkind == "Ijk_NoHook":
+            return None
+
+        if type(state._ip) is not int and state._ip.symbolic:
+            # symbolic IP is not supported
+            return None
+
+        addr = state.addr
+        procedure = self.project._sim_procedures.get(addr, None)
+        if procedure is not None:
+            return procedure
+
+        if not state.arch.name.startswith("ARM") or addr & 1 != 1:
+            return None
+
+        procedure = self.project._sim_procedures.get(addr - 1, None)
+        if procedure is not None:
+            return procedure
+
+        return None
+
+    def process_successors(self, successors, *, procedure=None, **kwargs):
+        state = self.state
+        if procedure is None:
+            procedure = self._lookup_hook(state, procedure)
+        if procedure is None:
+            return super().process_successors(successors, procedure=procedure, **kwargs)
+
+        if isinstance(procedure.addr, SootAddressDescriptor):
+            l.debug("Running %s (originally at %r)", repr(procedure), procedure.addr)
+        else:
+            l.debug(
+                "Running %s (originally at %s)",
+                repr(procedure),
+                procedure.addr if procedure.addr is None else hex(procedure.addr),
+            )
+
+        return self.process_procedure(state, successors, procedure, **kwargs)

angr/engines/icicle.py

@@ -0,0 +1,278 @@
+"""icicle.py: An angr engine that uses Icicle to execute code."""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing_extensions import override
+
+import pypcode
+from archinfo import Arch, Endness
+
+from angr.engines.concrete import ConcreteEngine, HeavyConcreteState
+from angr.engines.failure import SimEngineFailure
+from angr.engines.hook import HooksMixin
+from angr.engines.syscall import SimEngineSyscall
+from angr.rustylib.icicle import Icicle, VmExit, ExceptionCode
+
+log = logging.getLogger(__name__)
+
+
+PROCESSORS_DIR = os.path.join(os.path.dirname(pypcode.__file__), "processors")
+
+
+@dataclass
+class IcicleStateTranslationData:
+    """
+    Represents the saved information needed to convert an Icicle state back
+    to an angr state.
+    """
+
+    base_state: HeavyConcreteState
+    registers: set[str]
+    writable_pages: set[int]
+    initial_cpu_icount: int
+
+
+class IcicleEngine(ConcreteEngine):
+    """
+    An angr engine that uses Icicle to execute concrete states. The purpose of
+    this implementation is to provide a high-performance concrete execution
+    engine in angr. While historically, angr has focused on symbolic execution,
+    better support for concrete execution enables new use cases such as fuzzing
+    in angr. This is ideal for testing bespoke binary targets, such as
+    microcontroller firmware, which may be difficult to correctly harness for
+    use with traditional fuzzing engines.
+
+    This class is the base class for the Icicle engine. It implements execution
+    by creating an Icicle instance, copying the state from angr to Icicle, and then
+    running the Icicle instance. The results are then copied back to the angr
+    state. It is likely the case that this can be improved by re-using the Icicle
+    instance across multiple runs and only copying the state when necessary.
+
+    For a more complete implementation, use the UberIcicleEngine class, which
+    intends to provide a more complete set of features, such as hooks and syscalls.
+    """
+
+    breakpoints: set[int]
+
+    def __init__(self, *args, **kwargs):
+        """
+        Initialize the IcicleEngine. This sets up the breakpoints set and
+        initializes the parent class.
+        """
+        super().__init__(*args, **kwargs)
+        self.breakpoints = set()
+
+    @staticmethod
+    def __make_icicle_arch(arch: Arch) -> str | None:
+        """
+        Convert an angr architecture to an Icicle architecture. Not particularly
+        accurate, just a set of heuristics to get the right architecture. When
+        adding a new architecture, this function may need to be updated.
+        """
+        if arch.linux_name == "arm":
+            return "armv7a" if arch.memory_endness == Endness.LE else "armeb"
+        return arch.linux_name
+
+    @staticmethod
+    def __is_arm(icicle_arch: str) -> bool:
+        """
+        Check if the architecture is arm based on the address.
+        """
+        return icicle_arch.startswith(("arm", "thumb"))
+
+    @staticmethod
+    def __is_thumb(icicle_arch: str, addr: int) -> bool:
+        """
+        Check if the architecture is thumb based on the address.
+        """
+        return IcicleEngine.__is_arm(icicle_arch) and addr & 1 == 1
+
+    @staticmethod
+    def __get_pages(state: HeavyConcreteState) -> set[int]:
+        """
+        Unfortunately, the memory model doesn't have a way to get all pages.
+        Instead, we can get all of the backers from the loader, then all of the
+        pages from the PagedMemoryMixin and then do some math.
+        """
+        pages = set()
+        page_size = state.memory.page_size
+
+        # pages from loader segments
+        proj = state.project
+        if proj is not None:
+            for addr, backer in proj.loader.memory.backers():
+                start = addr // page_size
+                end = (addr + len(backer) - 1) // page_size
+                pages.update(range(start, end + 1))
+
+        # pages from the memory model
+        pages.update(state.memory._pages)
+
+        return pages
+
+    @staticmethod
+    def __convert_angr_state_to_icicle(state: HeavyConcreteState) -> tuple[Icicle, IcicleStateTranslationData]:
+        icicle_arch = IcicleEngine.__make_icicle_arch(state.arch)
+        if icicle_arch is None:
+            raise ValueError("Unsupported architecture")
+
+        proj = state.project
+        if proj is None:
+            raise ValueError("IcicleEngine requires a project to be set")
+
+        emu = Icicle(icicle_arch, PROCESSORS_DIR, True, True)
+
+        copied_registers = set()
+
+        # To create a state in Icicle, we need to do the following:
+        # 1. Copy the register values
+        for register in state.arch.register_list:
+            register = register.vex_name.lower() if register.vex_name is not None else register.name
+            try:
+                emu.reg_write(register, state.solver.eval(state.registers.load(register), cast_to=int))
+                copied_registers.add(register)
+            except KeyError:
+                log.debug("Register %s not found in icicle", register)
+
+        # Unset the thumb bit if necessary
+        if IcicleEngine.__is_thumb(icicle_arch, state.addr):
+            emu.pc = state.addr & ~1
+            emu.isa_mode = 1
+        elif "arm" in icicle_arch:  # Hack to work around us calling it r15t
+            emu.pc = state.addr
+
+        # Special case for x86 gs register
+        if state.arch.name == "X86":
+            emu.reg_write("GS_OFFSET", state.registers.load("gs").concrete_value << 16)
+
+        # 2. Copy the memory contents
+
+        mapped_pages = IcicleEngine.__get_pages(state)
+        writable_pages = set()
+        for page_num in mapped_pages:
+            addr = page_num * state.memory.page_size
+            size = state.memory.page_size
+            perm_bits = state.memory.permissions(addr).concrete_value
+            emu.mem_map(addr, size, perm_bits)
+            memory = state.memory.concrete_load(addr, size)
+            emu.mem_write(addr, memory)
+
+            if perm_bits & 2:
+                writable_pages.add(page_num)
+
+        # Add breakpoints for simprocedures
+        for addr in proj._sim_procedures:
+            emu.add_breakpoint(addr)
+
+        translation_data = IcicleStateTranslationData(
+            base_state=state,
+            registers=copied_registers,
+            writable_pages=writable_pages,
+            initial_cpu_icount=emu.cpu_icount,
+        )
+
+        # 3. Copy edge hitmap
+        edge_hitmap = state.history.last_edge_hitmap
+        if edge_hitmap is not None:
+            emu.edge_hitmap = edge_hitmap
+
+        return (emu, translation_data)
+
+    @staticmethod
+    def __convert_icicle_state_to_angr(
+        emu: Icicle, translation_data: IcicleStateTranslationData, status: VmExit
+    ) -> HeavyConcreteState:
+        state = translation_data.base_state.copy()
+
+        # 1. Copy the register values
+        for register in translation_data.registers:
+            state.registers.store(register, emu.reg_read(register))
+
+        if IcicleEngine.__is_arm(emu.architecture):  # Hack to work around us calling it r15t
+            state.registers.store("pc", (emu.pc | 1) if emu.isa_mode == 1 else emu.pc)
+
+        # 2. Copy the memory contents
+        for page_num in translation_data.writable_pages:
+            addr = page_num * state.memory.page_size
+            state.memory.store(addr, emu.mem_read(addr, state.memory.page_size))
+
+        # 3. Set history
+        # 3.1 history.jumpkind
+        exc = emu.exception_code
+        if status == VmExit.UnhandledException:
+            if exc in (
+                ExceptionCode.ReadUnmapped,
+                ExceptionCode.ReadPerm,
+                ExceptionCode.WriteUnmapped,
+                ExceptionCode.WritePerm,
+                ExceptionCode.ExecViolation,
+            ):
+                state.history.jumpkind = "Ijk_SigSEGV"
+            elif exc == ExceptionCode.Syscall:
+                state.history.jumpkind = "Ijk_Syscall"
+            elif exc == ExceptionCode.Halt:
+                state.history.jumpkind = "Ijk_Exit"
+            elif exc == ExceptionCode.InvalidInstruction:
+                state.history.jumpkind = "Ijk_NoDecode"
+            else:
+                state.history.jumpkind = "Ijk_EmFail"
+        else:
+            state.history.jumpkind = "Ijk_Boring"
+
+        # 3.2 history.recent_bbl_addrs
+        # Skip the last block, because it will be added by Successors
+        state.history.recent_bbl_addrs.extend([b[0] for b in emu.recent_blocks][:-1])
+
+        # 3.3. Set history.recent_instruction_count
+        state.history.recent_instruction_count = emu.cpu_icount - translation_data.initial_cpu_icount
+
+        # 3.4. Set edge hitmap
+        state.history.edge_hitmap = emu.edge_hitmap
+
+        return state
+
+    @override
+    def get_breakpoints(self) -> set[int]:
+        """Return the set of currently set breakpoints."""
+        return self.breakpoints
+
+    @override
+    def add_breakpoint(self, addr: int) -> None:
+        """Add a breakpoint at the given address."""
+        self.breakpoints.add(addr)
+
+    @override
+    def remove_breakpoint(self, addr: int) -> None:
+        """Remove a breakpoint at the given address, if present."""
+        self.breakpoints.discard(addr)
+
+    @override
+    def process_concrete(self, state: HeavyConcreteState, num_inst: int | None = None) -> HeavyConcreteState:
+        emu, translation_data = self.__convert_angr_state_to_icicle(state)
+
+        # Set breakpoints, skip the current PC. This assumes that if running
+        # with a breakpoint at the current PC, then the user has already done
+        # the necessary handling and is resuming execution.
+        for addr in self.breakpoints:
+            if emu.pc != addr:
+                emu.add_breakpoint(addr)
+
+        # Set the instruction count limit
+        if num_inst is not None and num_inst > 0:
+            emu.icount_limit = num_inst
+
+        # Run it
+        status = emu.run()
+
+        return IcicleEngine.__convert_icicle_state_to_angr(emu, translation_data, status)
+
+
+class UberIcicleEngine(SimEngineFailure, SimEngineSyscall, HooksMixin, IcicleEngine):
+    """
+    An extension of the IcicleEngine that uses mixins to add support for
+    syscalls and hooks. Most users will prefer to use this engine instead of the
+    IcicleEngine directly.
+    """