angr 9.2.192__cp311-cp311-macosx_10_12_x86_64.whl

angr/knowledge_plugins/key_definitions/uses.py

@@ -0,0 +1,178 @@
+# pylint:disable=unsubscriptable-object
+from __future__ import annotations
+from typing import Any, TYPE_CHECKING
+
+from angr.utils.cowdict import DefaultChainMapCOW
+from angr.code_location import CodeLocation
+
+if TYPE_CHECKING:
+    from .definition import Definition
+
+
+class Uses:
+    """
+    Describes uses (including the use location and the use expression) for definitions.
+    """
+
+    __slots__ = ("_uses_by_definition", "_uses_by_location")
+
+    def __init__(
+        self,
+        uses_by_definition: DefaultChainMapCOW | None = None,
+        uses_by_location: DefaultChainMapCOW | None = None,
+    ):
+        self._uses_by_definition: DefaultChainMapCOW[Definition, set[tuple[CodeLocation, Any | None]]] = (
+            DefaultChainMapCOW(default_factory=set, collapse_threshold=25)
+            if uses_by_definition is None
+            else uses_by_definition
+        )
+        self._uses_by_location: DefaultChainMapCOW[CodeLocation, set[tuple[Definition, Any | None]]] = (
+            DefaultChainMapCOW(default_factory=set, collapse_threshold=25)
+            if uses_by_location is None
+            else uses_by_location
+        )
+
+    def add_use(self, definition: Definition, codeloc: CodeLocation, expr: Any | None = None):
+        """
+        Add a use for a given definition.
+
+        :param definition:  The definition that is used.
+        :param codeloc:     The code location where the use occurs.
+        :param expr:        The expression that uses the specified definition at this location.
+        """
+        self._uses_by_definition = self._uses_by_definition.clean()
+        self._uses_by_definition[definition].add((codeloc, expr))
+        self._uses_by_location = self._uses_by_location.clean()
+        self._uses_by_location[codeloc].add((definition, expr))
+
+    def get_uses(self, definition: Definition) -> set[CodeLocation]:
+        """
+        Retrieve the uses of a given definition.
+
+        :param definition: The definition for which we get the uses.
+        """
+        return {codeloc for codeloc, _ in self._uses_by_definition.get(definition, set())}
+
+    def get_uses_with_expr(self, definition: Definition) -> set[tuple[CodeLocation, Any | None]]:
+        """
+        Retrieve the uses and the corresponding expressions of a given definition.
+
+        :param definition: The definition for which we get the uses and the corresponding expressions.
+        """
+        return self._uses_by_definition.get(definition, set())
+
+    def remove_use(self, definition: Definition, codeloc: CodeLocation, expr: Any | None = None) -> None:
+        """
+        Remove one use of a given definition.
+
+        :param definition:  The definition of which to remove the uses.
+        :param codeloc:     The code location where the use is.
+        :param expr:        The expression that uses the definition at the given location.
+        :return:            None
+        """
+        if definition in self._uses_by_definition and codeloc in self._uses_by_definition[definition]:
+            self._uses_by_definition = self._uses_by_definition.clean()
+            if expr is None:
+                for codeloc_, expr_ in list(self._uses_by_definition[definition]):
+                    if codeloc_ == codeloc:
+                        self._uses_by_definition[definition].remove((codeloc_, expr_))
+            else:
+                self._uses_by_definition[definition].remove((codeloc, expr))
+
+        if codeloc in self._uses_by_location:
+            self._uses_by_location = self._uses_by_location.clean()
+            for item in list(self._uses_by_location[codeloc]):
+                if item[0] == definition:
+                    self._uses_by_location[codeloc].remove(item)
+
+    def remove_uses(self, definition: Definition):
+        """
+        Remove all uses of a given definition.
+
+        :param definition:  The definition of which to remove the uses.
+        :return:            None
+        """
+        if definition in self._uses_by_definition:
+            self._uses_by_definition = self._uses_by_definition.clean()
+            codeloc_and_ids = self._uses_by_definition[definition]
+            del self._uses_by_definition[definition]
+
+            self._uses_by_location = self._uses_by_location.clean()
+            for codeloc, _ in codeloc_and_ids:
+                for item in list(self._uses_by_location[codeloc]):
+                    if item[0] == definition:
+                        self._uses_by_location[codeloc].remove(item)
+
+    def get_uses_by_location(
+        self, codeloc: CodeLocation, exprs: bool = False
+    ) -> set[Definition] | set[tuple[Definition, Any | None]]:
+        """
+        Retrieve all definitions that are used at a given location.
+
+        :param codeloc: The code location.
+        :return:        A set of definitions that are used at the given location.
+        """
+        if exprs:
+            return self._uses_by_location.get(codeloc, set())
+        return {item[0] for item in self._uses_by_location.get(codeloc, set())}
+
+    def get_uses_by_insaddr(
+        self, ins_addr: int, exprs: bool = False
+    ) -> set[Definition] | set[tuple[Definition, Any | None]]:
+        """
+        Retrieve all definitions that are used at a given location specified by the instruction address.
+
+        :param ins_addr:    The instruction address.
+        :return:            A set of definitions that are used at the given location.
+        """
+
+        all_uses = set()
+        for codeloc, uses in self._uses_by_location.items():
+            if codeloc.ins_addr == ins_addr:
+                all_uses |= uses
+
+        if exprs:
+            return all_uses
+        return {item[0] for item in all_uses}
+
+    def copy(self) -> Uses:
+        """
+        Copy the instance.
+
+        :return:    Return a new <Uses> instance containing the same data.
+        """
+        return Uses(
+            uses_by_definition=self._uses_by_definition.copy(),
+            uses_by_location=self._uses_by_location.copy(),
+        )
+
+    def merge(self, other: Uses) -> bool:
+        """
+        Merge an instance of <Uses> into the current instance.
+
+        :param other: The other <Uses> from which the data will be added to the current instance.
+        :return: True if any merge occurred, False otherwise
+        """
+        merge_occurred = False
+
+        for k, v in other._uses_by_definition.items():
+            if k not in self._uses_by_definition:
+                self._uses_by_definition = self._uses_by_definition.clean()
+                self._uses_by_definition[k] = v
+                merge_occurred = True
+            elif not v.issubset(self._uses_by_definition[k]):
+                merge_occurred = True
+                self._uses_by_definition = self._uses_by_definition.clean()
+                self._uses_by_definition[k] = self._uses_by_definition[k] | v
+
+        for k, v in other._uses_by_location.items():
+            if k not in self._uses_by_location:
+                self._uses_by_location = self._uses_by_location.clean()
+                self._uses_by_location[k] = v
+                merge_occurred = True
+            elif not v.issubset(self._uses_by_location[k]):
+                merge_occurred = True
+                self._uses_by_location = self._uses_by_location.clean()
+                self._uses_by_location[k] = self._uses_by_location[k] | v
+
+        return merge_occurred

angr/knowledge_plugins/labels.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+from archinfo.arch_arm import is_arm_arch
+import cle
+
+from .plugin import KnowledgeBasePlugin
+
+
+class Labels(KnowledgeBasePlugin):
+    def __init__(self, kb):
+        super().__init__(kb=kb)
+        self._labels = {}
+        self._reverse_labels = {}
+
+        is_arm = is_arm_arch(kb._project.arch)
+        for obj in kb._project.loader.all_objects:
+            for v in obj.symbols:
+                if is_arm and v.name in {"$d", "$t", "$a"}:
+                    continue
+                if (
+                    v.name
+                    and not v.is_import
+                    and v.type
+                    not in {
+                        cle.SymbolType.TYPE_OTHER,
+                    }
+                ):
+                    self._labels[v.rebased_addr] = v.name
+                    self._reverse_labels[v.name] = v.rebased_addr
+            try:
+                for v, k in obj.plt.items():
+                    self._labels[k] = v
+            except AttributeError:
+                pass
+
+        # Artificial labels for the entry point
+        entry = kb._project.loader.main_object.entry
+        if entry not in self._labels:
+            lbl = "_start"
+            self._labels[entry] = self.get_unique_label(lbl)
+
+    def __iter__(self):
+        """
+        Iterate over all labels (the strings)
+        Use .lookup(name) if you need to find the address to it.
+        """
+        return self._reverse_labels.__iter__()
+
+    def __getitem__(self, k):
+        return self._labels[k]
+
+    def __setitem__(self, k, v):
+        del self[k]
+        self._labels[k] = v
+        self._reverse_labels[v] = k
+        if k in self._kb.functions:
+            self._kb.functions[k]._name = v
+
+    def __delitem__(self, k):
+        if k in self._labels:
+            l = self._labels[k]
+            if l in self._reverse_labels:
+                del self._reverse_labels[l]
+            del self._labels[k]
+
+    def __contains__(self, k):
+        return k in self._labels
+
+    def items(self):
+        return self._labels.items()
+
+    def get(self, addr, default=None):
+        """
+        Get a label as string for a given address
+        Same as .labels[x]
+        """
+        return self._labels.get(addr, default)
+
+    def lookup(self, name, default=None):
+        """
+        Returns an address to a given label
+        To show all available labels, iterate over .labels or list(b.kb.labels)
+        """
+        return self._reverse_labels.get(name, default)
+
+    def copy(self):
+        o = Labels(self._kb)
+        o._labels = dict(self._labels.items())
+        o._reverse_labels = dict(self._reverse_labels.items())
+
+    def get_unique_label(self, label):
+        """
+        Get a unique label name from the given label name.
+
+        :param str label:   The desired label name.
+        :return:            A unique label name.
+        """
+
+        if label not in self._reverse_labels:
+            return label
+
+        # use it as the prefix
+        i = 1
+        while True:
+            new_label = f"{label}_{i}"
+            if new_label not in self._reverse_labels:
+                return new_label
+            i += 1
+
+
+KnowledgeBasePlugin.register_default("labels", Labels)

angr/knowledge_plugins/obfuscations.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from .plugin import KnowledgeBasePlugin
+
+
+class Obfuscations(KnowledgeBasePlugin):
+    """
+    Store discovered information and artifacts about (string) obfuscation techniques in the project.
+    """
+
+    def __init__(self, kb):
+        super().__init__(kb)
+
+        self.obfuscated_strings_analyzed: bool = False
+        self.type1_deobfuscated_strings = {}
+        self.type1_string_loader_candidates = set()
+        self.type2_deobfuscated_strings = {}
+        self.type2_string_loader_candidates = set()
+        self.type3_deobfuscated_strings = {}  # from the address of the call instruction to the actual string (in bytes)
+
+        self.obfuscated_apis_analyzed: bool = False
+        self.type1_deobfuscated_apis: dict[int, tuple[str, str]] = {}
+        self.type2_deobfuscated_apis: dict[int, str] = {}
+        self.type3_deobfuscated_apis: dict[int, tuple[str, str]] = {}
+
+    def copy(self):
+        o = Obfuscations(self._kb)
+        o.type1_deobfuscated_strings = dict(self.type1_deobfuscated_strings)
+        o.type1_string_loader_candidates = self.type1_string_loader_candidates.copy()
+        o.type2_deobfuscated_strings = dict(self.type2_deobfuscated_strings)
+        o.type2_string_loader_candidates = self.type2_string_loader_candidates.copy()
+        o.type3_deobfuscated_strings = self.type3_deobfuscated_strings.copy()
+
+        o.type1_deobfuscated_apis = self.type1_deobfuscated_apis.copy()
+        o.type2_deobfuscated_apis = self.type2_deobfuscated_apis.copy()
+        o.type3_deobfuscated_apis = self.type3_deobfuscated_apis.copy()
+        return o
+
+
+KnowledgeBasePlugin.register_default("obfuscations", Obfuscations)

angr/knowledge_plugins/patches.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+from cle.address_translator import AddressTranslator
+from sortedcontainers import SortedDict
+
+from .plugin import KnowledgeBasePlugin
+
+
+# TODO: Serializable
+class Patch:
+    def __init__(self, addr, new_bytes, comment: str | None = None):
+        self.addr = addr
+        self.new_bytes = new_bytes
+        self.comment = comment
+
+    def __len__(self):
+        return len(self.new_bytes)
+
+
+class PatchManager(KnowledgeBasePlugin):
+    """
+    A placeholder-style implementation for a binary patch manager. This class should be significantly changed in the
+    future when all data about loaded binary objects are loaded into angr knowledge base from CLE. As of now, it only
+    stores byte-level replacements.
+
+    Patches should not overlap, but it's user's responsibility to check for and avoid overlapping patches.
+    """
+
+    def __init__(self, kb):
+        super().__init__(kb=kb)
+
+        self._patches: dict[int, Patch] = SortedDict()
+        self._patched_entry_state = None
+
+    def add_patch(self, addr, new_bytes, comment: str | None = None):
+        self._patches[addr] = Patch(addr, new_bytes, comment=comment)
+        self._patched_entry_state = None
+
+    def add_patch_obj(self, patch: Patch):
+        self._patches[patch.addr] = patch
+        self._patched_entry_state = None
+
+    def remove_patch(self, addr):
+        if addr in self._patches:
+            del self._patches[addr]
+        self._patched_entry_state = None
+
+    def patch_addrs(self):
+        return self._patches.keys()
+
+    def get_patch(self, addr):
+        """
+        Get patch at the given address.
+
+        :param int addr:    The address of the patch.
+        :return:            The patch if there is one starting at the address, or None if there isn't any.
+        :rtype:             Patch or None
+        """
+        return self._patches.get(addr, None)
+
+    def get_all_patches(self, addr, size):
+        """
+        Retrieve all patches that cover a region specified by [addr, addr+size).
+
+        :param int addr:    The address of the beginning of the region.
+        :param int size:    Size of the region.
+        :return:            A list of patches.
+        :rtype:             list
+        """
+        patches = []
+        for patch_addr in self._patches.irange(maximum=addr + size - 1, reverse=True):
+            p = self._patches[patch_addr]
+            if self.overlap(p.addr, p.addr + len(p), addr, addr + size):
+                patches.append(p)
+            else:
+                break
+        return patches[::-1]
+
+    def keys(self):
+        return self._patches.keys()
+
+    def items(self):
+        return self._patches.items()
+
+    def values(self):
+        return self._patches.values()
+
+    def copy(self):
+        o = PatchManager(self._kb)
+        o._patches = self._patches.copy()
+
+    @staticmethod
+    def overlap(a0, a1, b0, b1):
+        return a0 <= b0 < a1 or a0 <= b1 < a1 or b0 <= a0 < b1
+
+    def apply_patches_to_binary(self, binary_bytes: bytes | None = None, patches: list[Patch] | None = None) -> bytes:
+        if patches is None:
+            patches = sorted(self._patches.values(), key=lambda x: x.addr)
+
+        if binary_bytes is None:
+            with open(self._kb._project.loader.main_object.binary, "rb") as f:
+                binary_bytes = f.read()
+        for patch in patches:
+            # convert addr to file offset
+            at = AddressTranslator.from_mva(patch.addr, self._kb._project.loader.main_object)
+            file_offset = at.to_raw()
+
+            if file_offset < len(binary_bytes) and file_offset + len(patch.new_bytes) < len(binary_bytes):
+                binary_bytes = (
+                    binary_bytes[:file_offset] + patch.new_bytes + binary_bytes[file_offset + len(patch.new_bytes) :]
+                )
+
+        return binary_bytes
+
+    def apply_patches_to_state(self, state):
+        for patch in self._patches.values():
+            state.memory.store(patch.addr, patch.new_bytes)
+
+    @property
+    def patched_entry_state(self):
+        if self._patched_entry_state is None:
+            self._patched_entry_state = self._kb._project.factory.entry_state()
+            self.apply_patches_to_state(self._patched_entry_state)
+        return self._patched_entry_state
+
+
+KnowledgeBasePlugin.register_default("patches", PatchManager)

angr/knowledge_plugins/plugin.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from angr.knowledge_base import KnowledgeBase
+
+default_plugins = {}
+
+
+class KnowledgeBasePlugin:
+    def __init__(self, kb: KnowledgeBase):
+        # This call is needed, because some Plugins like TypesStore inherit from KnowledgeBasePlugin and something else
+        # So we still need to call the constructor of the other class.
+        super().__init__()
+        self._kb = kb
+
+    def copy(self):
+        raise NotImplementedError
+
+    @staticmethod
+    def register_default(name, cls):
+        if name in default_plugins:
+            raise Exception(f"{default_plugins[name]} is already set as the default for {name}")
+        default_plugins[name] = cls

angr/knowledge_plugins/propagations/__init__.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from .propagation_model import PropagationModel
+from .propagation_manager import PropagationManager
+
+
+__all__ = (
+    "PropagationManager",
+    "PropagationModel",
+)

angr/knowledge_plugins/propagations/prop_value.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+from typing import Any, TYPE_CHECKING
+from collections.abc import Iterable, Generator
+
+import claripy
+import angr.ailment as ailment
+
+if TYPE_CHECKING:
+    from angr.code_location import CodeLocation
+
+
+class Detail:
+    """
+    A companion class used together with PropValue. It describes stored information at each offset (in bytes).
+
+    :ivar def_at:   Where this expression is defined, or None if it was never explicitly defined in the current block
+                    or the current function.
+    """
+
+    __slots__ = ("def_at", "expr", "size")
+
+    def __init__(self, size: int, expr: ailment.Expression | None, def_at: CodeLocation | None):
+        self.size = size
+        self.expr = expr
+        self.def_at = def_at
+
+    def __repr__(self) -> str:
+        return f"{self.size:x}: {self.expr}@{self.def_at}"
+
+
+# The base value
+
+
+class PropValue:
+    """
+    Describes immutable basic value type that is used in Propagator.
+    """
+
+    __slots__ = (
+        "offset_and_details",
+        "value",
+    )
+
+    def __init__(self, value: claripy.ast.Bits, offset_and_details: dict[int, Detail] | None = None):
+        self.value = value
+        self.offset_and_details = offset_and_details
+
+    @property
+    def needs_details(self):
+        return not bool(self.offset_and_details)
+
+    @property
+    def one_expr(self) -> ailment.Expression | None:
+        """
+        Get the expression that starts at offset 0 and covers the entire PropValue. Returns None if there are no
+        expressions or multiple expressions.
+        """
+        if self.offset_and_details and len(self.offset_and_details) == 1 and 0 in self.offset_and_details:
+            detail = self.offset_and_details[0]
+            if detail.size == self.value.size() // 8:
+                return detail.expr
+        return None
+
+    @property
+    def one_defat(self) -> CodeLocation | None:
+        """
+        Get the definition location of the expression that starts at offset 0 and covers the entire PropValue. Returns
+        None if there are no expressions or multiple expressions.
+        """
+        if self.offset_and_details and len(self.offset_and_details) == 1 and 0 in self.offset_and_details:
+            detail = self.offset_and_details[0]
+            if detail.size == self.value.size() // 8:
+                return detail.def_at
+        return None
+
+    def to_label(self):
+        raise NotImplementedError
+
+    def with_details(self, size: int, expr: ailment.Expression, def_at: CodeLocation) -> PropValue:
+        return PropValue(self.value, offset_and_details={0: Detail(size, expr, def_at)})
+
+    def all_exprs(self) -> Generator[ailment.Expression]:
+        if not self.offset_and_details:
+            return
+        for detail in self.offset_and_details.values():
+            yield detail.expr
+
+    def non_zero_exprs(self) -> Generator[ailment.Expression]:
+        if not self.offset_and_details:
+            return
+        for detail in self.offset_and_details.values():
+            if isinstance(detail.expr, ailment.Expr.Const) and detail.expr.value == 0:
+                continue
+            yield detail.expr
+
+    @staticmethod
+    def chop_value(value: claripy.ast.Bits, begin_offset, end_offset) -> claripy.ast.Bits:
+        if begin_offset == end_offset:
+            chop_start = value.size() - begin_offset * 8 - 1
+            chop_end = value.size() - end_offset * 8 - 1
+        else:
+            chop_start = value.size() - begin_offset * 8 - 1
+            chop_end = value.size() - end_offset * 8
+        if chop_end - chop_start + 1 == value.size():
+            # fast path: no chopping
+            return value
+        if isinstance(value, claripy.ast.FP):
+            # converting the FP value to an AST so that we can chop
+            value = claripy.fpToIEEEBV(value)
+        return value[chop_start:chop_end]
+
+    def value_and_labels(self) -> Generator[tuple[int, claripy.ast.Bits, int, dict | None]]:
+        if not self.offset_and_details:
+            return
+        keys = sorted(self.offset_and_details.keys())
+        if keys[0] != 0:
+            # missing details at 0
+            yield 0, self.chop_value(self.value, 0, keys[0]), keys[0], None
+
+        end_offset = 0
+        for idx, offset in enumerate(keys):
+            detail = self.offset_and_details[offset]
+            end_offset = offset + detail.size
+            label = {"expr": detail.expr, "def_at": detail.def_at}
+            yield offset, self.chop_value(self.value, offset, end_offset), end_offset - offset, label
+
+            # gap detection
+            if idx != len(keys) - 1:
+                next_offset = keys[idx + 1]
+                if end_offset != next_offset:
+                    yield end_offset, self.chop_value(
+                        self.value, end_offset, next_offset
+                    ), next_offset - end_offset, None
+
+        # final gap detection
+        if end_offset < self.value.size() // 8:
+            yield end_offset, self.chop_value(
+                self.value, end_offset, self.value.size() // 8
+            ), self.value.size() // 8 - end_offset, None
+
+    @staticmethod
+    def from_value_and_labels(
+        value: claripy.ast.Bits, labels: Iterable[tuple[int, int, int, dict[str, Any]]]
+    ) -> PropValue:
+        if not labels:
+            return PropValue(value)
+        offset_and_details = {}
+        for offset, offset_in_expr, size, label in labels:
+            expr = label["expr"]
+            if expr is not None:
+                if offset_in_expr != 0:
+                    expr = PropValue.extract_ail_expression(offset_in_expr * 8, size * 8, expr)
+                elif size < expr.size:
+                    expr = PropValue.extract_ail_expression(0, size * 8, expr)
+                elif size > expr.size:
+                    expr = PropValue.extend_ail_expression((size - expr.size) * 8, expr)
+            offset_and_details[offset] = Detail(size, expr, label["def_at"])
+        return PropValue(value, offset_and_details=offset_and_details)
+
+    @staticmethod
+    def from_value_and_details(value: claripy.ast.Bits, size: int, expr: ailment.Expression, def_at: CodeLocation):
+        d = Detail(size, expr, def_at)
+        return PropValue(value, offset_and_details={0: d})
+
+    @staticmethod
+    def extract_ail_expression(
+        start: int, bits: int, expr: ailment.Expr.Expression | None
+    ) -> ailment.Expr.Expression | None:
+        if expr is None:
+            return None
+
+        if isinstance(expr, ailment.Expr.Const):
+            mask = (1 << bits) - 1
+            return ailment.Expr.Const(expr.idx, expr.variable, (expr.value >> start) & mask, bits, **expr.tags)
+
+        if start == 0:
+            return ailment.Expr.Convert(None, expr.bits, bits, False, expr, **expr.tags)
+        a = ailment.Expr.BinaryOp(
+            None, "Shr", (expr, ailment.Expr.Const(None, None, bits, expr.bits)), False, **expr.tags
+        )
+        return ailment.Expr.Convert(None, a.bits, bits, False, a, **expr.tags)
+
+    @staticmethod
+    def extend_ail_expression(bits: int, expr: ailment.Expr.Expression | None) -> ailment.Expr.Expression | None:
+        if expr is None:
+            return None
+        if isinstance(expr, ailment.Expr.Const):
+            return ailment.Expr.Const(expr.idx, expr.variable, expr.value, bits + expr.bits, **expr.tags)
+        if isinstance(expr, ailment.Expr.Convert):
+            return ailment.Expr.Convert(None, expr.from_bits, bits + expr.to_bits, False, expr.operand, **expr.tags)
+        return ailment.Expr.Convert(None, expr.bits, bits + expr.bits, False, expr, **expr.tags)