angr 9.2.148__py3-none-macosx_11_0_arm64.whl → 9.2.150__py3-none-macosx_11_0_arm64.whl

angr/analyses/decompiler/utils.py

@@ -723,6 +723,23 @@ def structured_node_is_simple_return(
     return False
 
 
+def structured_node_is_simple_return_strict(node: BaseNode | SequenceNode | MultiNode | ailment.Block) -> bool:
+    """
+    Returns True iff the node exclusively contains a return statement.
+    """
+    if isinstance(node, (SequenceNode, MultiNode)) and node.nodes:
+        flat_blocks = _flatten_structured_node(node)
+        if len(flat_blocks) != 1:
+            return False
+        node = flat_blocks[-1]
+
+    return (
+        isinstance(node, ailment.Block)
+        and len(node.statements) == 1
+        and isinstance(node.statements[0], ailment.Stmt.Return)
+    )
+
+
 def is_statement_terminating(stmt: ailment.statement.Statement, functions) -> bool:
     if isinstance(stmt, ailment.Stmt.Return):
         return True
@@ -851,11 +868,16 @@ def peephole_optimize_stmts(block, stmt_opts):
                     r = opt.optimize(stmt, stmt_idx=stmt_idx, block=block)
                     if r is not None and r is not stmt:
                         stmt = r
+                        if r == ():
+                            # the statement is gone; no more redo
+                            redo = False
+                            break
                         redo = True
                         break
 
         if stmt is not None and stmt is not old_stmt:
-            statements.append(stmt)
+            if stmt != ():
+                statements.append(stmt)
             any_update = True
         else:
             statements.append(old_stmt)

angr/analyses/disassembly.py

@@ -1159,6 +1159,7 @@ class Disassembly(Analysis):
         show_bytes: bool = False,
         ascii_only: bool | None = None,
         color: bool = True,
+        min_edge_depth: int = 0,
     ) -> str:
         """
         Render the disassembly to a string, with optional edges and addresses.
@@ -1288,7 +1289,7 @@ class Disassembly(Analysis):
             for f, t in sorted(edges_by_line, key=lambda e: abs(e[0] - e[1])):
                 add_edge_to_buffer(edge_buf, ref_buf, f, t, lambda s: ansi_color(s, edge_col), ascii_only=ascii_only)
                 add_edge_to_buffer(ref_buf, ref_buf, f, t, ascii_only=ascii_only)
-            max_edge_depth = max(map(len, ref_buf))
+            max_edge_depth = max(*map(len, ref_buf), min_edge_depth)
 
             # Justify edge and combine with disassembly
             for i, line in enumerate(buf):

angr/analyses/patchfinder.py

@@ -97,7 +97,7 @@ class PatchFinderAnalysis(Analysis):
     # - Looking for instruction partials broken by a patch (nodecode)
     # - Unusual stack manipulation
 
-    atypical_alignments: list[Function]
+    atypical_alignments: list[AtypicallyAlignedFunction]
     possibly_patched_out: list[PatchedOutFunctionality]
 
     def __init__(self):

angr/analyses/s_reaching_definitions/s_rda_view.py

@@ -130,6 +130,7 @@ class SRDAView:
 
             for stmt in reversed(stmts):
                 r = predicate(stmt)
+                predicate_returned_true |= r
                 should_break = (predicate_returned_true and r is False) if consecutive else r
                 if should_break:
                     break

angr/analyses/typehoon/lifter.py

@@ -13,6 +13,7 @@ from angr.sim_type import (
     SimTypeArray,
     SimTypeFloat,
     SimTypeDouble,
+    SimCppClass,
 )
 from .typeconsts import BottomType, Int8, Int16, Int32, Int64, Pointer32, Pointer64, Struct, Array, Float32, Float64
 
@@ -77,6 +78,24 @@ class TypeLifter:
         obj.field_names = field_names
         return obj
 
+    def _lift_SimCppClass(self, ty: SimCppClass) -> TypeConstant | BottomType:
+        if ty in self.memo:
+            return BottomType()
+
+        obj = Struct(fields={}, name=ty.name, is_cppclass=True)
+        self.memo[ty] = obj
+        converted_fields = {}
+        field_names = {}
+        ty_offsets = ty.offsets
+        for field_name, simtype in ty.members.items():
+            if field_name not in ty_offsets:
+                return BottomType()
+            converted_fields[ty_offsets[field_name]] = self.lift(simtype)
+            field_names[ty_offsets[field_name]] = field_name
+        obj.fields = converted_fields
+        obj.field_names = field_names
+        return obj
+
     def _lift_SimTypeArray(self, ty: SimTypeArray) -> Array:
         elem_type = self.lift(ty.elem_type)
         return Array(elem_type, count=ty.length)
@@ -96,6 +115,7 @@ _mapping = {
     SimTypeLongLong: TypeLifter._lift_SimTypeLongLong,
     SimTypePointer: TypeLifter._lift_SimTypePointer,
     SimStruct: TypeLifter._lift_SimStruct,
+    SimCppClass: TypeLifter._lift_SimCppClass,
     SimTypeArray: TypeLifter._lift_SimTypeArray,
     SimTypeFloat: TypeLifter._lift_SimTypeFloat,
     SimTypeDouble: TypeLifter._lift_SimTypeDouble,

angr/analyses/typehoon/simple_solver.py

@@ -181,7 +181,7 @@ class Sketch:
 
     def __init__(self, solver: SimpleSolver, root: TypeVariable):
         self.root: SketchNode = SketchNode(root)
-        self.graph = networkx.DiGraph()
+        self.graph = networkx.MultiDiGraph()
         self.node_mapping: dict[TypeVariable | DerivedTypeVariable, SketchNodeBase] = {}
         self.solver = solver
 
@@ -200,7 +200,7 @@ class Sketch:
             for label in typevar.labels:
                 succs = []
                 for _, dst, data in self.graph.out_edges(node, data=True):
-                    if "label" in data and data["label"] == label:
+                    if "label" in data and data["label"] == label and dst not in succs:
                         succs.append(dst)
                 if len(succs) > 1:
                     _l.warning(
@@ -215,6 +215,11 @@ class Sketch:
         return node
 
     def add_edge(self, src: SketchNodeBase, dst: SketchNodeBase, label) -> None:
+        # ensure the label does not already exist in existing edges
+        if self.graph.has_edge(src, dst):
+            for data in self.graph.get_edge_data(src, dst).values():
+                if "label" in data and data["label"] == label:
+                    return
         self.graph.add_edge(src, dst, label=label)
 
     def add_constraint(self, constraint: TypeConstraint) -> None:
@@ -315,7 +320,7 @@ class ConstraintGraphNode:
             tag_str = "R"
         else:
             tag_str = "U"
-        forgotten_str = "PRE" if FORGOTTEN.PRE_FORGOTTEN else "POST"
+        forgotten_str = "PRE" if self.forgotten == FORGOTTEN.PRE_FORGOTTEN else "POST"
         s = f"{self.typevar}#{variance_str}.{tag_str}.{forgotten_str}"
         if ":" in s:
             return '"' + s + '"'
@@ -820,6 +825,7 @@ class SimpleSolver:
         """
 
         graph = networkx.DiGraph()
+        constraints = self._get_transitive_subtype_constraints(constraints)
         for constraint in constraints:
             if isinstance(constraint, Subtype):
                 self._constraint_graph_add_edges(
@@ -830,6 +836,33 @@ class SimpleSolver:
         self._constraint_graph_recall_forget_split(graph)
         return graph
 
+    @staticmethod
+    def _get_transitive_subtype_constraints(constraints: set[TypeConstraint]) -> set[TypeConstraint]:
+        """
+        Apply the S-Trans rule: a <: b, b <: c => a <: c
+        """
+        tv2supertypes = defaultdict(set)
+        for constraint in constraints:
+            if isinstance(constraint, Subtype):
+                tv2supertypes[constraint.sub_type].add(constraint.super_type)
+
+        new_constraints = set()
+        while True:
+            changed = False
+            for subtype, supertypes in tv2supertypes.items():
+                supertypes_copy = set(supertypes)
+                for supertype in supertypes_copy:
+                    if supertype in tv2supertypes:
+                        for supertype_ in tv2supertypes[supertype]:
+                            if supertype_ not in supertypes_copy:
+                                changed = True
+                                supertypes.add(supertype_)
+                                new_constraints.add(Subtype(subtype, supertype_))
+            if not changed:
+                break
+
+        return constraints | new_constraints
+
     @staticmethod
     def _constraint_graph_add_recall_edges(graph: networkx.DiGraph, node: ConstraintGraphNode) -> None:
         while True:
@@ -1234,21 +1267,21 @@ class SimpleSolver:
                     offset_to_maxsize[base] = max(offset_to_maxsize[base], (last_label.offset - base) + access_size)
                     offset_to_sizes[base].add(access_size)
 
-            node_to_base = {}
+            idx_to_base = {}
 
-            for labels, succ in path_and_successors:
+            for idx, (labels, _) in enumerate(path_and_successors):
                 last_label = labels[-1] if labels else None
                 if isinstance(last_label, HasField):
                     prev_offset = next(offset_to_base.irange(maximum=last_label.offset, reverse=True))
-                    node_to_base[succ] = offset_to_base[prev_offset]
+                    idx_to_base[idx] = offset_to_base[prev_offset]
 
             node_by_offset = defaultdict(set)
 
-            for labels, succ in path_and_successors:
+            for idx, (labels, succ) in enumerate(path_and_successors):
                 last_label = labels[-1] if labels else None
                 if isinstance(last_label, HasField):
-                    if succ in node_to_base:
-                        node_by_offset[node_to_base[succ]].add(succ)
+                    if idx in idx_to_base:
+                        node_by_offset[idx_to_base[idx]].add(succ)
                     else:
                         node_by_offset[last_label.offset].add(succ)
 

angr/analyses/typehoon/translator.py

@@ -105,7 +105,10 @@ class TypeTranslator:
 
         name = tc.name if tc.name else self.struct_name()
 
-        s = sim_type.SimStruct({}, name=name).with_arch(self.arch)
+        if tc.is_cppclass:
+            s = sim_type.SimCppClass(name=name).with_arch(self.arch)
+        else:
+            s = sim_type.SimStruct({}, name=name).with_arch(self.arch)
         self.structs[tc] = s
 
         next_offset = 0

angr/analyses/typehoon/typeconsts.py

@@ -114,6 +114,18 @@ class Int512(Int):
         return "int512"
 
 
+class IntVar(Int):
+    def __init__(self, size):
+        self._size = size
+
+    @property
+    def size(self) -> int:
+        return self._size
+
+    def __repr__(self, memo=None):
+        return "intvar"
+
+
 class Float(TypeConstant):
     def __repr__(self, memo=None) -> str:
         return "floatbase"
@@ -211,10 +223,11 @@ class Array(TypeConstant):
 
 
 class Struct(TypeConstant):
-    def __init__(self, fields=None, name=None, field_names=None):
+    def __init__(self, fields=None, name=None, field_names=None, is_cppclass: bool = False):
         self.fields = {} if fields is None else fields  # offset to type
         self.name = name
         self.field_names = field_names
+        self.is_cppclass = is_cppclass
 
     def _hash(self, visited: set[int]):
         if id(self) in visited:
@@ -236,9 +249,9 @@ class Struct(TypeConstant):
 
     @memoize
     def __repr__(self, memo=None):
-        prefix = "struct"
+        prefix = "CppClass" if self.is_cppclass else "struct"
         if self.name:
-            prefix = f"struct {self.name}"
+            prefix = f"{prefix} {self.name}"
         return (
             prefix
             + "{"
@@ -312,9 +325,7 @@ def int_type(bits: int) -> Int:
         256: Int256,
         512: Int512,
     }
-    if bits in mapping:
-        return mapping[bits]()
-    raise TypeError(f"Not a known size of int: {bits}")
+    return mapping[bits]() if bits in mapping else IntVar(bits)
 
 
 def float_type(bits: int) -> Float | None:

angr/analyses/typehoon/typehoon.py

@@ -10,7 +10,7 @@ from angr.sim_variable import SimVariable, SimStackVariable
 from .simple_solver import SimpleSolver
 from .translator import TypeTranslator
 from .typeconsts import Struct, Pointer, TypeConstant, Array, TopType
-from .typevars import Equivalence, Subtype, TypeVariable
+from .typevars import Equivalence, Subtype, TypeVariable, DerivedTypeVariable
 
 if TYPE_CHECKING:
     from angr.sim_type import SimType
@@ -187,6 +187,10 @@ class Typehoon(Analysis):
         if self._ground_truth and self.simtypes_solution is not None:
             self.simtypes_solution.update(self._ground_truth)
 
+    @staticmethod
+    def _resolve_derived(tv):
+        return tv.type_var if isinstance(tv, DerivedTypeVariable) else tv
+
     def _solve(self):
         typevars = set()
         if self._var_mapping:
@@ -198,9 +202,10 @@ class Typehoon(Analysis):
             for constraint in self._constraints[self.func_var]:
                 if isinstance(constraint, Subtype):
                     if isinstance(constraint.sub_type, TypeVariable):
-                        typevars.add(constraint.sub_type)
+                        typevars.add(self._resolve_derived(constraint.sub_type))
                     if isinstance(constraint.super_type, TypeVariable):
-                        typevars.add(constraint.super_type)
+                        typevars.add(self._resolve_derived(constraint.super_type))
+
         solver = SimpleSolver(self.bits, self._constraints, typevars, stackvar_max_sizes=self._stackvar_max_sizes)
         self.solution = solver.solution
 
@@ -214,13 +219,16 @@ class Typehoon(Analysis):
         if not self.solution:
             return
 
+        memo = set()
         for tv in list(self.solution.keys()):
             if self._must_struct and tv in self._must_struct:
                 continue
             sol = self.solution[tv]
-            specialized = self._specialize_struct(sol)
+            specialized = self._specialize_struct(sol, memo=memo)
             if specialized is not None:
                 self.solution[tv] = specialized
+            else:
+                memo.add(sol)
 
     def _specialize_struct(self, tc, memo: set | None = None):
         if isinstance(tc, Pointer):
@@ -240,7 +248,11 @@ class Typehoon(Analysis):
                 return field0
 
             # are all fields the same?
-            if len(tc.fields) > 1 and all(tc.fields[off] == field0 for off in offsets):
+            if (
+                len(tc.fields) > 1
+                and not self._is_pointer_to(field0, tc)
+                and all(tc.fields[off] == field0 for off in offsets)
+            ):
                 # are all fields aligned properly?
                 try:
                     alignment = field0.size
@@ -251,12 +263,19 @@ class Typehoon(Analysis):
                     max_offset = offsets[-1]
                     field0_size = 1
                     if not isinstance(field0, TopType):
-                        field0_size = field0.size
+                        try:
+                            field0_size = field0.size
+                        except NotImplementedError:
+                            field0_size = 1
                     count = (max_offset + field0_size) // alignment
                     return Array(field0, count=count)
 
         return None
 
+    @staticmethod
+    def _is_pointer_to(pointer_to: TypeConstant, base_type: TypeConstant) -> bool:
+        return isinstance(pointer_to, Pointer) and pointer_to.basetype == base_type
+
     def _translate_to_simtypes(self):
         """
         Translate solutions in type variables to solutions in SimTypes.

angr/analyses/variable_recovery/engine_ail.py

@@ -4,6 +4,7 @@ from typing import TYPE_CHECKING, cast
 import logging
 
 import ailment
+from ailment.constant import UNDETERMINED_SIZE
 import claripy
 from unique_log_filter import UniqueLogFilter
 
@@ -30,8 +31,15 @@ class SimEngineVRAIL(
     The engine for variable recovery on AIL.
     """
 
-    def __init__(self, *args, call_info=None, vvar_to_vvar: dict[int, int] | None, **kwargs):
-        super().__init__(*args, **kwargs)
+    def __init__(
+        self,
+        *args,
+        call_info=None,
+        vvar_to_vvar: dict[int, int] | None,
+        vvar_type_hints: dict[int, typeconsts.TypeConstant] | None = None,
+        **kwargs,
+    ):
+        super().__init__(*args, vvar_type_hints=vvar_type_hints, **kwargs)
 
         self._reference_spoffset: bool = False
         self.call_info = call_info or {}
@@ -100,6 +108,13 @@ class SimEngineVRAIL(
         else:
             l.warning("Unsupported dst type %s.", dst_type)
 
+    def _handle_stmt_WeakAssignment(self, stmt) -> None:
+        src = self._expr(stmt.src)
+        dst = self._expr(stmt.dst)
+        if isinstance(src, RichR) and isinstance(dst, RichR) and src.typevar is not None and dst.typevar is not None:
+            tc = typevars.Subtype(src.typevar, dst.typevar)
+            self.state.add_type_constraint(tc)
+
     def _handle_stmt_Store(self, stmt: ailment.Stmt.Store):
         addr_r = self._expr_bv(stmt.addr)
         data = self._expr(stmt.data)
@@ -325,7 +340,9 @@ class SimEngineVRAIL(
         addr_r = self._expr_bv(expr.addr)
         size = expr.size
 
-        return self._load(addr_r, size, expr=expr)
+        if size != UNDETERMINED_SIZE:
+            return self._load(addr_r, size, expr=expr)
+        return self._top(8)
 
     def _handle_expr_VirtualVariable(self, expr: ailment.Expr.VirtualVariable):
         return self._read_from_vvar(expr, expr=expr, vvar_id=self._mapped_vvarid(expr.varid))
@@ -419,6 +436,29 @@ class SimEngineVRAIL(
             self._reference(richr, codeloc, src=expr)
         return richr
 
+    def _handle_unop_Reference(self, expr: ailment.Expr.UnaryOp):
+        if isinstance(expr.operand, ailment.Expr.VirtualVariable) and expr.operand.was_stack:
+            off = expr.operand.stack_offset
+            refbase_typevar = self.state.stack_offset_typevars.get(off, None)
+            if refbase_typevar is None:
+                # allocate a new type variable
+                refbase_typevar = typevars.TypeVariable()
+                self.state.stack_offset_typevars[off] = refbase_typevar
+
+            ref_typevar = typevars.TypeVariable()
+            access_derived_typevar = self._create_access_typevar(ref_typevar, False, None, 0)
+            load_constraint = typevars.Subtype(refbase_typevar, access_derived_typevar)
+            self.state.add_type_constraint(load_constraint)
+
+            value_v = self.state.stack_address(off)
+            richr = RichR(value_v, typevar=ref_typevar)
+            codeloc = self._codeloc()
+            self._ensure_variable_existence(richr, codeloc, src_expr=expr.operand)
+            if self._reference_spoffset:
+                self._reference(richr, codeloc, src=expr.operand)
+            return richr
+        return RichR(self.state.top(expr.bits))
+
     def _handle_expr_BasePointerOffset(self, expr):
         # TODO
         return self._top(expr.bits)
@@ -433,7 +473,7 @@ class SimEngineVRAIL(
     def _handle_binop_Add(self, expr):
         arg0, arg1 = expr.operands
         r0, r1 = self._expr_pair(arg0, arg1)
-        compute = r0.data + r1.data  # type: ignore
+        compute = r0.data + r1.data if r0.data.size() == r1.data.size() else self.state.top(expr.bits)  # type: ignore
 
         type_constraints = set()
         # create a new type variable and add constraints accordingly
@@ -844,7 +884,6 @@ class SimEngineVRAIL(
         self._expr(expr.operands[0])
         return RichR(self.state.top(expr.bits))
 
-    _handle_unop_Reference = _handle_unop_Default
     _handle_unop_Dereference = _handle_unop_Default
     _handle_unop_Clz = _handle_unop_Default
     _handle_unop_Ctz = _handle_unop_Default

angr/analyses/variable_recovery/engine_base.py

@@ -70,9 +70,12 @@ class SimEngineVRBase(
     and storing data.
     """
 
-    def __init__(self, project, kb):
+    def __init__(self, project, kb, vvar_type_hints: dict[int, typeconsts.TypeConstant] | None = None):
         super().__init__(project)
 
+        self.vvar_type_hints: dict[int, typeconsts.TypeConstant] = (
+            vvar_type_hints if vvar_type_hints is not None else {}
+        )
         self.kb = kb
         self.vvar_region: dict[int, Any] = {}
 
@@ -453,13 +456,19 @@ class SimEngineVRBase(
                 # assign a new type variable to it
                 typevar = typevars.TypeVariable()
                 self.state.typevars.add_type_variable(variable, typevar)
-                # create constraints
             else:
                 typevar = self.state.typevars.get_type_variable(variable)
+
+            # create constraints accordingly
+
             self.state.add_type_constraint(typevars.Subtype(richr.typevar, typevar))
-            # the constraint below is a default constraint that may conflict with more specific ones with different
-            # sizes; we post-process at the very end of VRA to remove conflicting default constraints.
-            self.state.add_type_constraint(typevars.Subtype(typevar, typeconsts.int_type(variable.size * 8)))
+            if vvar.varid in self.vvar_type_hints:
+                # handle type hints
+                self.state.add_type_constraint(typevars.Subtype(typevar, self.vvar_type_hints[vvar.varid]))
+            else:
+                # the constraint below is a default constraint that may conflict with more specific ones with different
+                # sizes; we post-process at the very end of VRA to remove conflicting default constraints.
+                self.state.add_type_constraint(typevars.Subtype(typevar, typeconsts.int_type(variable.size * 8)))
 
         return variable
 
@@ -978,14 +987,22 @@ class SimEngineVRBase(
             value = self.state.top(size * self.project.arch.byte_width)
             if create_variable:
                 # create a new variable if necessary
-                variable = SimRegisterVariable(
-                    offset,
-                    size if force_variable_size is None else force_variable_size,
-                    ident=self.state.variable_manager[self.func_addr].next_variable_ident("register"),
-                    region=self.func_addr,
-                )
+
+                # check if there is an existing variable for the atom at this location already
+                existing_vars: set[tuple[SimVariable, int]] = self.state.variable_manager[
+                    self.func_addr
+                ].find_variables_by_atom(self.block.addr, self.stmt_idx, expr)
+                if not existing_vars:
+                    variable = SimRegisterVariable(
+                        offset,
+                        size if force_variable_size is None else force_variable_size,
+                        ident=self.state.variable_manager[self.func_addr].next_variable_ident("register"),
+                        region=self.func_addr,
+                    )
+                    self.state.variable_manager[self.func_addr].add_variable("register", offset, variable)
+                else:
+                    variable = next(iter(existing_vars))[0]
                 value = self.state.annotate_with_variables(value, [(0, variable)])
-                self.state.variable_manager[self.func_addr].add_variable("register", offset, variable)
             self.state.register_region.store(offset, value)
             value_list = [{value}]
         else:
@@ -1131,6 +1148,12 @@ class SimEngineVRBase(
         if var is not None and var.size != vvar.size:
             # ignore the variable and the associated type if we are only reading part of the variable
             return RichR(value, variable=var)
+
+        # handle type hints
+        if vvar.varid in self.vvar_type_hints:
+            assert isinstance(typevar, typevars.TypeVariable)
+            self.state.add_type_constraint(typevars.Subtype(typevar, self.vvar_type_hints[vvar.varid]))
+
         return RichR(value, variable=var, typevar=typevar)
 
     def _create_access_typevar(

angr/analyses/variable_recovery/variable_recovery_fast.py

@@ -12,21 +12,25 @@ import ailment
 from ailment.expression import VirtualVariable
 
 import angr.errors
+from angr import SIM_TYPE_COLLECTIONS
 from angr.analyses import AnalysesHub
 from angr.storage.memory_mixins.paged_memory.pages.multi_values import MultiValues
 from angr.block import Block
 from angr.errors import AngrVariableRecoveryError, SimEngineError
 from angr.knowledge_plugins import Function
+from angr.knowledge_plugins.key_definitions import atoms
 from angr.sim_variable import SimStackVariable, SimRegisterVariable, SimVariable, SimMemoryVariable
 from angr.engines.vex.claripy.irop import vexop_to_simop
 from angr.analyses import ForwardAnalysis, visitors
 from angr.analyses.typehoon.typevars import Equivalence, TypeVariable, TypeVariables, Subtype, DerivedTypeVariable
-from angr.analyses.typehoon.typeconsts import Int
+from angr.analyses.typehoon.typeconsts import Int, TypeConstant, BottomType, TopType
+from angr.analyses.typehoon.lifter import TypeLifter
 from .variable_recovery_base import VariableRecoveryBase, VariableRecoveryStateBase
 from .engine_vex import SimEngineVRVEX
 from .engine_ail import SimEngineVRAIL
 import contextlib
 
+
 if TYPE_CHECKING:
     from angr.analyses.typehoon.typevars import TypeConstraint
 
@@ -241,6 +245,7 @@ class VariableRecoveryFast(ForwardAnalysis, VariableRecoveryBase):  # pylint:dis
         unify_variables=True,
         func_arg_vvars: dict[int, tuple[VirtualVariable, SimVariable]] | None = None,
         vvar_to_vvar: dict[int, int] | None = None,
+        type_hints: list[tuple[atoms.VirtualVariable | atoms.MemoryLocation, str]] | None = None,
     ):
         if not isinstance(func, Function):
             func = self.kb.functions[func]
@@ -269,8 +274,17 @@ class VariableRecoveryFast(ForwardAnalysis, VariableRecoveryBase):  # pylint:dis
         self._func_arg_vvars = func_arg_vvars
         self._unify_variables = unify_variables
 
+        # handle type hints
+        self.vvar_type_hints = {}
+        if type_hints:
+            self._parse_type_hints(type_hints)
+
         self._ail_engine: SimEngineVRAIL = SimEngineVRAIL(
-            self.project, self.kb, call_info=call_info, vvar_to_vvar=self.vvar_to_vvar
+            self.project,
+            self.kb,
+            call_info=call_info,
+            vvar_to_vvar=self.vvar_to_vvar,
+            vvar_type_hints=self.vvar_type_hints,
         )
         self._vex_engine: SimEngineVRVEX = SimEngineVRVEX(self.project, self.kb, call_info=call_info)
 
@@ -617,5 +631,22 @@ class VariableRecoveryFast(ForwardAnalysis, VariableRecoveryBase):  # pylint:dis
             if adjusted:
                 state.register_region.store(self.project.arch.sp_offset, sp_v)
 
+    def _parse_type_hints(self, type_hints: list[tuple[atoms.VirtualVariable | atoms.MemoryLocation, str]]) -> None:
+        self.vvar_type_hints = {}
+        for loc, type_hint_str in type_hints:
+            if isinstance(loc, atoms.VirtualVariable):
+                type_hint = self._parse_type_hint(type_hint_str)
+                if type_hint is not None:
+                    self.vvar_type_hints[loc.varid] = type_hint
+            # TODO: Handle other types of locations
+
+    def _parse_type_hint(self, type_hint_str: str) -> TypeConstant | None:
+        ty = SIM_TYPE_COLLECTIONS["cpp::std"].get(type_hint_str)
+        if ty is None:
+            return None
+        ty = ty.with_arch(self.project.arch)
+        lifted = TypeLifter(self.project.arch.bits).lift(ty)
+        return None if isinstance(lifted, (BottomType, TopType)) else lifted
+
 
 AnalysesHub.register_default("VariableRecoveryFast", VariableRecoveryFast)