angr 9.2.103__py3-none-manylinux2014_aarch64.whl

angr/knowledge_plugins/key_definitions/atoms.py

@@ -0,0 +1,314 @@
+from typing import Union
+from enum import Enum, auto
+
+import claripy
+import ailment
+from archinfo import Arch, RegisterOffset
+
+from ...calling_conventions import SimFunctionArgument, SimRegArg, SimStackArg
+from ...engines.light import SpOffset
+from .heap_address import HeapAddress
+
+
+class AtomKind(Enum):
+    """
+    An enum indicating the class of an atom
+    """
+
+    REGISTER = auto()
+    MEMORY = auto()
+    TMP = auto()
+    GUARD = auto()
+    CONSTANT = auto()
+
+
+class Atom:
+    """
+    This class represents a data storage location manipulated by IR instructions.
+
+    It could either be a Tmp (temporary variable), a Register, a MemoryLocation.
+    """
+
+    __slots__ = ("_hash", "size")
+
+    def __init__(self, size):
+        """
+        :param size:  The size of the atom in bytes
+        """
+        self.size = size
+        self._hash = None
+
+    def __repr__(self):
+        raise NotImplementedError()
+
+    @property
+    def bits(self) -> int:
+        return self.size * 8
+
+    @property
+    def _size(self):
+        return self.size
+
+    @_size.setter
+    def _size(self, v):
+        self.size = v
+
+    @staticmethod
+    def from_ail_expr(expr: ailment.Expr.Expression, arch: Arch, full_reg: bool = False) -> "Register":
+        if isinstance(expr, ailment.Expr.Register):
+            if full_reg:
+                reg_name = arch.translate_register_name(expr.reg_offset)
+                return Register(arch.registers[reg_name][0], arch.registers[reg_name][1], arch)
+            else:
+                return Register(expr.reg_offset, expr.size, arch)
+        raise TypeError(f"Expression type {type(expr)} is not yet supported")
+
+    @staticmethod
+    def from_argument(
+        argument: SimFunctionArgument, arch: Arch, full_reg=False, sp: int | None = None
+    ) -> Union["Register", "MemoryLocation"]:
+        """
+        Instanciate an `Atom` from a given argument.
+
+        :param argument: The argument to create a new atom from.
+        :param arch: The argument representing archinfo architecture for argument.
+        :param full_reg: Whether to return an atom indicating the entire register if the argument only specifies a
+                        slice of the register.
+        :param sp:      The current stack offset. Optional. Only used when argument is a SimStackArg.
+        """
+        if isinstance(argument, SimRegArg):
+            if full_reg:
+                return Register(arch.registers[argument.reg_name][0], arch.registers[argument.reg_name][1], arch)
+            else:
+                return Register(arch.registers[argument.reg_name][0] + argument.reg_offset, argument.size, arch)
+        elif isinstance(argument, SimStackArg):
+            if sp is None:
+                raise ValueError("You must provide a stack pointer to translate a SimStackArg")
+            return MemoryLocation(
+                SpOffset(arch.bits, argument.stack_offset + sp), argument.size, endness=arch.memory_endness
+            )
+        else:
+            raise TypeError("Argument type %s is not yet supported." % type(argument))
+
+    @staticmethod
+    def reg(thing: str | RegisterOffset, size: int | None = None, arch: Arch | None = None) -> "Register":
+        """
+        Create a Register atom.
+
+        :param thing:   The register offset (e.g., project.arch.registers["rax"][0]) or the register name (e.g., "rax").
+        :param size:    Size of the register atom. Must be provided when creating the atom using a register offset.
+        :param arch:    The architecture. Must be provided when creating the atom using a register name.
+        :return:        The Register Atom object.
+        """
+
+        if isinstance(thing, str):
+            if arch is None:
+                raise ValueError(
+                    "Cannot create a Register Atom by register name without having an architecture "
+                    "specified through arch!"
+                )
+            if thing not in arch.registers:
+                raise ValueError(f"Unknown register name {thing} for architecture {arch.name}")
+            reg_offset, size_ = arch.registers[thing]
+            if size is None:
+                size = size_
+        elif isinstance(thing, RegisterOffset):
+            reg_offset = thing
+            if size is None:
+                raise ValueError("You must provide a size when specifying the register offset")
+        else:
+            raise TypeError(
+                "Unsupported type of register. It must be a string (for register name) or an int (for "
+                "register offset)"
+            )
+        return Register(reg_offset, size, arch=arch)
+
+    register = reg
+
+    @staticmethod
+    def mem(addr: SpOffset | HeapAddress | int, size: int, endness: str | None = None) -> "MemoryLocation":
+        """
+        Create a MemoryLocation atom,
+
+        :param addr:        The memory location. Can be an SpOffset for stack variables, an int for global memory
+                            variables, or a HeapAddress for items on the heap.
+        :param size:        Size of the atom.
+        :param endness:     Optional, either "Iend_LE" or "Iend_BE".
+        :return:            The MemoryLocation Atom object.
+        """
+        return MemoryLocation(addr, size, endness=endness)
+
+    memory = mem
+
+    def _identity(self):
+        raise NotImplementedError()
+
+    def __hash__(self):
+        if self._hash is None:
+            self._hash = hash(self._identity())
+        return self._hash
+
+    def __eq__(self, other):
+        return type(self) is type(other) and self._identity() == other._identity()
+
+
+class GuardUse(Atom):
+    """
+    Implements a guard use.
+    """
+
+    __slots__ = ("target",)
+
+    def __init__(self, target):
+        super().__init__(0)
+        self.target = target
+
+    def __repr__(self):
+        return "<Guard %#x>" % self.target
+
+    def _identity(self):
+        return (self.target,)
+
+
+class ConstantSrc(Atom):
+    """
+    Represents a constant.
+    """
+
+    __slots__ = ("value",)
+
+    def __init__(self, value: int, size: int):
+        super().__init__(size)
+        self.value: int = value
+
+    def __repr__(self):
+        return f"<Const {self.value}>"
+
+    def _identity(self):
+        return (self.value, self.size)
+
+
+class Tmp(Atom):
+    """
+    Represents a variable used by the IR to store intermediate values.
+    """
+
+    __slots__ = ("tmp_idx",)
+
+    def __init__(self, tmp_idx: int, size: int):
+        super().__init__(size)
+        self.tmp_idx = tmp_idx
+
+    def __repr__(self):
+        return "<Tmp %d>" % self.tmp_idx
+
+    def _identity(self):
+        return hash(("tmp", self.tmp_idx))
+
+
+class Register(Atom):
+    """
+    Represents a given CPU register.
+
+    As an IR abstracts the CPU design to target different architectures, registers are represented as a separated memory
+    space.
+    Thus a register is defined by its offset from the base of this memory and its size.
+
+    :ivar int reg_offset:    The offset from the base to define its place in the memory bloc.
+    :ivar int size:          The size, in number of bytes.
+    """
+
+    __slots__ = (
+        "reg_offset",
+        "arch",
+    )
+
+    def __init__(self, reg_offset: RegisterOffset, size: int, arch: Arch | None = None):
+        super().__init__(size)
+
+        self.reg_offset = reg_offset
+        self.arch = arch
+
+    def __repr__(self):
+        return "<Reg %s<%d>>" % (self.name, self.size)
+
+    def _identity(self):
+        return (self.reg_offset, self.size)
+
+    @property
+    def name(self) -> str:
+        return (
+            str(self.reg_offset) if self.arch is None else self.arch.translate_register_name(self.reg_offset, self.size)
+        )
+
+
+class MemoryLocation(Atom):
+    """
+    Represents a memory slice.
+
+    It is characterized by its address and its size.
+    """
+
+    __slots__ = (
+        "addr",
+        "endness",
+    )
+
+    def __init__(self, addr: SpOffset | HeapAddress | int, size: int, endness: str | None = None):
+        """
+        :param int addr: The address of the beginning memory location slice.
+        :param int size: The size of the represented memory location, in bytes.
+        """
+        super().__init__(size)
+
+        self.addr: SpOffset | int | claripy.ast.BV = addr
+        self.endness = endness
+
+    def __repr__(self):
+        address_format = hex(self.addr) if type(self.addr) is int else self.addr
+        stack_format = " (stack)" if self.is_on_stack else ""
+        size = "%d" % self.size if isinstance(self.size, int) else self.size
+
+        return f"<Mem {address_format}<{size}>{stack_format}>"
+
+    @property
+    def is_on_stack(self) -> bool:
+        """
+        True if this memory location is located on the stack.
+        """
+        return isinstance(self.addr, SpOffset)
+
+    @property
+    def symbolic(self) -> bool:
+        if isinstance(self.addr, int):
+            return False
+        elif isinstance(self.addr, SpOffset):
+            return type(self.addr.offset) is not int
+        return True
+
+    def __eq__(self, other):
+        # pylint:disable=isinstance-second-argument-not-valid-type
+        return (
+            type(other) is MemoryLocation
+            and (
+                self.addr is other.addr
+                if (isinstance(self.addr, claripy.ast.BV) or isinstance(other.addr, claripy.ast.BV))
+                else self.addr == other.addr
+            )
+            and self.size == other.size
+            and self.endness == other.endness
+        )
+
+    __hash__ = Atom.__hash__
+
+    def _identity(self):
+        return self.addr, self.size, self.endness
+
+
+atom_kind_mapping = {
+    AtomKind.REGISTER: Register,
+    AtomKind.MEMORY: MemoryLocation,
+    AtomKind.TMP: Tmp,
+    AtomKind.GUARD: GuardUse,
+    AtomKind.CONSTANT: ConstantSrc,
+}

angr/knowledge_plugins/key_definitions/constants.py

@@ -0,0 +1,23 @@
+import enum
+
+DEBUG = False
+
+#
+# Observation point types
+#
+
+
+class ObservationPointType(enum.IntEnum):
+    """
+    Enum to replace the previously generic constants
+    This makes it possible to annotate where they are expected by typing something as ObservationPointType
+    instead of Literal[0,1]
+    """
+
+    OP_BEFORE = 0
+    OP_AFTER = 1
+
+
+# For backwards compatibility
+OP_BEFORE = ObservationPointType.OP_BEFORE
+OP_AFTER = ObservationPointType.OP_AFTER

angr/knowledge_plugins/key_definitions/definition.py

@@ -0,0 +1,217 @@
+from typing import Optional, Literal, TypeVar, Generic
+from dataclasses import dataclass
+import logging
+
+from angr.knowledge_plugins.variables.variable_manager import VariableManagerInternal
+from angr.sim_variable import SimTemporaryVariable
+from angr.sim_variable import SimMemoryVariable
+from angr.sim_variable import SimStackVariable
+from angr.sim_variable import SimRegisterVariable
+from angr.misc.ux import once
+
+from ...engines.light import SpOffset
+from ...code_location import CodeLocation, ExternalCodeLocation
+from .atoms import Atom, MemoryLocation, Register, Tmp, AtomKind, atom_kind_mapping
+from .tag import Tag
+from ...sim_variable import SimVariable
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class DefinitionMatchPredicate:
+    """
+    A dataclass indicating several facts which much all must match in order for a definition to match. Largely an
+    internal class; don't worry about this.
+    """
+
+    kind: AtomKind | type[Atom] | None = None
+    bbl_addr: int | None = None
+    ins_addr: int | None = None
+    variable: SimVariable | None = None
+    variable_manager: VariableManagerInternal | None | Literal[False] = None
+    stack_offset: int | None = None
+    reg_name: str | int | None = None
+    heap_offset: int | None = None
+    global_addr: int | None = None
+    tmp_idx: int | None = None
+    const_val: int | None = None
+    extern: bool | None = None
+
+    @staticmethod
+    def construct(predicate: Optional["DefinitionMatchPredicate"] = None, **kwargs) -> "DefinitionMatchPredicate":
+        if predicate is None:
+            predicate = DefinitionMatchPredicate(**kwargs)
+            predicate.normalize()
+        return predicate
+
+    def normalize(self):
+        if self.variable is not None:
+            if isinstance(self.variable, SimRegisterVariable):
+                self.reg_name = self.variable.reg
+            elif isinstance(self.variable, SimStackVariable):
+                if self.variable.base != "bp":
+                    log.warning("Cannot match against variables with %s base (need bp)", self.variable.base)
+                else:
+                    self.stack_offset = self.variable.offset
+            elif isinstance(self.variable, SimMemoryVariable):
+                # TODO region
+                if isinstance(self.variable.addr, int):
+                    self.global_addr = self.variable.addr
+                else:
+                    log.warning(
+                        "Cannot match against memory variable with %s addr (need int)",
+                        type(self.variable.addr).__name__,
+                    )
+            elif isinstance(self.variable, SimTemporaryVariable):
+                self.tmp_idx = self.variable.tmp_id
+            else:
+                log.warning(
+                    "Cannot match against definition to %s (need reg, stack, mem, or tmp)", type(self.variable).__name__
+                )
+
+        if self.reg_name is not None:
+            self.kind = AtomKind.REGISTER
+        elif self.stack_offset is not None or self.heap_offset is not None or self.global_addr is not None:
+            self.kind = AtomKind.MEMORY
+        elif self.const_val is not None:
+            self.kind = AtomKind.CONSTANT
+        elif self.tmp_idx is not None:
+            self.kind = AtomKind.TMP
+
+    def matches(self, defn: "Definition") -> bool:
+        if self.variable is not None:
+            if self.variable_manager is False:
+                pass
+            elif self.variable_manager is not None:
+                if not self.variable_manager.is_variable_used_at(
+                    self.variable, (defn.codeloc.bbl_addr, defn.codeloc.stmt_idx)
+                ):
+                    return False
+            elif once("definition_matches_no_variable_manager"):
+                log.warning(
+                    "Cannot match definitions to variables on the basis of locations without a variable manager."
+                )
+                log.warning("Pass variable_manager=False to acknowledge this explicitly.")
+        if self.bbl_addr is not None and defn.codeloc.block_addr != self.bbl_addr:
+            return False
+        if self.ins_addr is not None and defn.codeloc.ins_addr != self.ins_addr:
+            return False
+        if self.extern is not None and isinstance(defn.codeloc, ExternalCodeLocation) != self.extern:
+            return False
+
+        if self.kind is not None:
+            if not isinstance(self.kind, type):
+                self.kind = atom_kind_mapping[self.kind]
+            if not isinstance(defn.atom, self.kind):
+                return False
+
+        if isinstance(defn.atom, Register):
+            if self.reg_name is not None:
+                if isinstance(self.reg_name, int):
+                    if not defn.atom.reg_offset <= self.reg_name < defn.atom.reg_offset + defn.atom.size:
+                        return False
+                elif isinstance(self.reg_name, str):
+                    if defn.atom.arch is not None:
+                        if self.reg_name != defn.atom.name:
+                            return False
+                    else:
+                        log.warning(
+                            "Attempting to match by register name against a definition which does not have an arch"
+                        )
+                        return False
+                else:
+                    raise TypeError(self.reg_name)
+        elif isinstance(defn.atom, MemoryLocation):
+            if self.stack_offset is not None:
+                if (
+                    not isinstance(defn.atom.addr, SpOffset)
+                    or defn.atom.addr.base != "sp"  # TODO???????
+                    or defn.atom.addr.offset != self.stack_offset
+                ):
+                    return False
+        elif isinstance(defn.atom, Tmp):
+            if self.tmp_idx is not None and self.tmp_idx != defn.atom.tmp_idx:
+                return False
+
+        return True
+
+
+A = TypeVar("A", bound=Atom)
+
+
+class Definition(Generic[A]):
+    """
+    An atom definition.
+
+    :ivar atom:     The atom being defined.
+    :ivar codeloc:  Where this definition is created in the original binary code.
+    :ivar dummy:    Tell whether the definition should be considered dummy or not. During simplification by AILment,
+                    definitions marked as dummy will not be removed.
+    :ivar tags:     A set of tags containing information about the definition gathered during analyses.
+    """
+
+    __slots__ = (
+        "atom",
+        "codeloc",
+        "dummy",
+        "tags",
+        "_hash",
+    )
+
+    def __init__(self, atom: A, codeloc: CodeLocation, dummy: bool = False, tags: set[Tag] | None = None):
+        self.atom: A = atom
+        self.codeloc: CodeLocation = codeloc
+        self.dummy: bool = dummy
+        self.tags = tags or set()
+        self._hash = None
+
+    def __eq__(self, other):
+        return self.atom == other.atom and self.codeloc == other.codeloc
+
+    def __repr__(self):
+        if not self.tags:
+            return "<Definition {{Atom:{}, Codeloc:{}}}{}>".format(
+                self.atom, self.codeloc, "" if not self.dummy else "dummy"
+            )
+        else:
+            return "<Definition {{Tags:{}, Atom:{}, Codeloc:{}}}{}>".format(
+                repr(self.tags), self.atom, self.codeloc, "" if not self.dummy else " dummy"
+            )
+
+    def __str__(self):
+        pretty_tags = "\n".join([str(tag) for tag in self.tags])
+        return f"Definition:\n" f"Atom: {self.atom}\n" f"CodeLoc: {self.codeloc}\n" f"Tags: {pretty_tags}"
+
+    def __hash__(self):
+        if self._hash is None:
+            self._hash = hash((self.atom, self.codeloc))
+        return self._hash
+
+    @property
+    def offset(self) -> int:
+        if isinstance(self.atom, Register):
+            return self.atom.reg_offset
+        elif isinstance(self.atom, MemoryLocation):
+            if isinstance(self.atom.addr, SpOffset):
+                return self.atom.addr.offset
+            else:
+                return self.atom.addr
+        else:
+            raise ValueError("Unsupported operation offset on %s." % type(self.atom))
+
+    @property
+    def size(self) -> int:
+        if isinstance(self.atom, Register):
+            return self.atom.size
+        elif isinstance(self.atom, MemoryLocation):
+            return self.atom.bits // 8
+        else:
+            raise ValueError("Unsupported operation size on %s." % type(self.atom))
+
+    def matches(self, **kwargs) -> bool:
+        """
+        Return whether this definition has certain characteristics.
+
+        """
+        return DefinitionMatchPredicate.construct(**kwargs).matches(self)

angr/knowledge_plugins/key_definitions/environment.py

@@ -0,0 +1,92 @@
+import claripy
+
+from .undefined import Undefined, UNDEFINED
+
+
+class Environment:
+    """
+    Represent the environment in which a program runs.
+    It's a mapping of variable names, to `claripy.ast.Base` that should contain possible addresses, or <UNDEFINED>, at
+    which their respective values are stored.
+
+    **Note**: The <Environment> object does not store the values associated with variables themselves.
+    """
+
+    __slots__ = ("_environment",)
+
+    def __init__(self, environment: dict[str | Undefined, set[claripy.ast.Base]] = None):
+        self._environment: dict[str | Undefined, set[claripy.ast.Base]] = environment or {}
+
+    def get(self, names: set[str]) -> tuple[set[claripy.ast.Base], bool]:
+        """
+        :param names: Potential values for the name of the environment variable to get the pointers of.
+        :return:
+            The potential addresses of the values the environment variable can take;
+            And a boolean value telling whether all the names were known of the internal representation (i.e. will be
+            False if one of the queried variable was not found).
+        """
+        has_unknown = not all(map(lambda name: name in self._environment.keys(), names))
+
+        def _get(name):
+            if not isinstance(name, (str, Undefined)):
+                raise TypeError("get(): Expected str, or Undefined, got %s" % type(name).__name__)
+            return self._environment.get(name, {UNDEFINED})
+
+        pointers = set()
+        for values in map(_get, names):
+            pointers |= values
+
+        return pointers, has_unknown
+
+    def set(self, name: str | Undefined, pointers: set[claripy.ast.Base]):
+        """
+        :param name: Name of the environment variable to which we will associate the pointers.
+        :param pointers: New addresses where the new values of the environment variable are located.
+        """
+        if not isinstance(name, (str, Undefined)):
+            raise TypeError("set(): Expected str, or Undefined, got %s" % type(name).__name__)
+        self._environment[name] = pointers
+
+    def __str__(self):
+        return "Environment: %s" % self._environment
+
+    def __repr__(self):
+        return "Environment: %s" % self._environment
+
+    def __eq__(self, other: object) -> bool:
+        assert isinstance(other, Environment), "Cannot compare Environment with %s" % type(other).__name__
+        return self._environment == other._environment
+
+    def merge(self, *others: "Environment") -> tuple["Environment", bool]:
+        new_env = self._environment
+
+        for other in others:
+            if not isinstance(other, Environment):
+                raise TypeError("Cannot merge Environment with %s" % type(other).__name__)
+
+            keys = set(new_env.keys())
+            keys |= other._environment.keys()
+
+            def _dataset_from_key(key, environment1, environment2):
+                v = environment1.get(key, None)
+                w = environment2.get(key, None)
+                # Because the key is coming from one of them, they cannot be both `None`.
+                if v is None:
+                    return w
+                if w is None:
+                    return v
+                return v | w
+
+            new_env = dict(map(lambda k: (k, _dataset_from_key(k, new_env, other._environment)), keys))
+
+        merge_occurred = new_env != self._environment
+        return Environment(environment=new_env), merge_occurred
+
+    def compare(self, other: "Environment") -> bool:
+        for k in set(self._environment.keys()).union(set(other._environment.keys())):
+            if k not in self._environment:
+                return False
+            if k in self._environment and k in other._environment:
+                if not self._environment[k].issuperset(other._environment[k]):
+                    return False
+        return True

angr/knowledge_plugins/key_definitions/heap_address.py

@@ -0,0 +1,32 @@
+from .undefined import Undefined
+
+
+class HeapAddress:
+    """
+    The representation of an address on the heap.
+    """
+
+    def __init__(self, value: int | Undefined):
+        self._value = value
+
+    @property
+    def value(self):
+        return self._value
+
+    def __repr__(self):
+        address_as_string = ("%#x" % self._value) if isinstance(self._value, int) else ("%s" % self._value)
+        return "HeapAddress<%s>" % address_as_string
+
+    def __add__(self, value):
+        if not isinstance(value, int):
+            raise TypeError("Can only add int to HeapAddress, got %s" % type(value).__name__)
+        return HeapAddress(self.value + value)
+
+    def __radd__(self, value):
+        return self.__add__(value)
+
+    def __eq__(self, other):
+        return isinstance(other, HeapAddress) and self._value == other._value
+
+    def __hash__(self):
+        return hash(self._value)