:py:mod:`cozy.concolic.exploration`
===================================

.. py:module:: cozy.concolic.exploration


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   cozy.concolic.exploration.ConcolicSim
   cozy.concolic.exploration._ExploreMode
   cozy.concolic.exploration.JointConcolicSim




.. py:class:: ConcolicSim(concrete_init: dict[claripy.BVS, claripy.BVV] | set[claripy.BVS] | frozenset[claripy.BVS], deferred_stash='deferred', check_only_recent_constraints=True)


   Bases: :py:obj:`angr.ExplorationTechnique`

   This class implements concolic execution without using an external emulator
   like QEMU or Unicorn. This class functions by storing a concrete assignment
   for each symbolic variable. When the state branches, the assignment is
   substituted into both children's constraints. If the substitution results
   in the constraints evaluating to false, that child is placed in the deferred
   stash. By querying the simulation manager's active stash length, we can
   tell when the concrete execution ends. When concrete execution ends, we
   can either choose a new concrete substitution ourselves and set it with
   the :py:meth:`ConcolicDeferred.set_concrete` method. Alternatively we
   can take one of the deferred states and generate and autogenerate a new
   concrete substitution by finding a satisfying assignment for that state's
   constraints.

   ConcolicSim constructor

   :param dict[claripy.BVS, claripy.BVV] | set[claripy.BVS] | frozenset[claripy.BVS] concrete_init: Used to        initialize the concrete value. If this value is a substitution dictionary, then that dictionary is used as our        concrete input. If this value is a set or frozenset, then a substituting dictionary is autogenerated, subject        to the initial state's constraints.
   :param string deferred_stash: The name of the deferred stash
   :param bool check_only_recent_constraints: If this value is true, then whenever child states are created, only        the new constraints are checked with respect to the concrete substitution. Here we assume that the parent of        the child already satisfied the concrete input on a previous iteration, so it's safe to only check with respect        to the new constraints.

   .. py:method:: setup(simgr)

      Perform any initialization on this manager you might need to do.

      :param angr.SimulationManager simgr:    The simulation manager to which you have just been added


   .. py:method:: is_satisfied(constraints: list[claripy.ast.bool]) -> bool

      Substitutes the current concrete input into the constraints, and returns True if the constraints are True after
      the substitution is made.

      :param list[claripy.ast.bool] constraints: The constraints in which the concrete solution will be substituted.
      :rtype: bool
      :return: If the constraints are True after substitution, then True is returned. Otherwise returns False.


   .. py:method:: _set_replacement_dict(concrete)


   .. py:method:: set_concrete(simgr, concrete: dict[Union[claripy.BVS, claripy.FPS], Union[claripy.BVV, claripy.FPV]])

      Sets the concrete input via a substitution dictionary. All the symbols used by the program should have concrete
      values provided for them. The active and deferred stash will be mutated to ensure that only states which
      are satisfied by the concrete substitution are active.

      :param dict[claripy.BVS, claripy.BVV] concrete: A dictionary mapping each symbol to its concrete value.


   .. py:method:: _generate_concrete(simgr: angr.SimulationManager, from_stash: list[angr.SimState], symbols: set[claripy.BVS] | frozenset[claripy.BVS], candidate_heuristic: collections.abc.Callable[[list[angr.SimState]], angr.SimState] | None = None)


   .. py:method:: generate_concrete(simgr: angr.SimulationManager, symbols: set[claripy.BVS] | frozenset[claripy.BVS], candidate_heuristic: collections.abc.Callable[[list[angr.SimState]], angr.SimState] | None = None)

      Autogenerates a new concrete input by choosing a deferred state and finding a satisfying assignment
      with respect to that state's constraints. The symbols provided will be used to internally generate
      a substitution dictionary. The candidate_heuristic is used to choose a state from the current stash
      of deferred states. If no heuristic is provided, the last state in the deferred stash will be chosen next.
      If there are any active states in the simulation manager, a ValueError will be thrown.

      :param angr.SimulationManager simgr: The simulation manager
      :param set[claripy.BVS] | frozenset[claripy.BVS] symbols: The symbols that we will generate a substitution for.
      :param Callable[[list[angr.SimState]], angr.SimState] | None candidate_heuristic: The heuristic that should be        used to choose the deferred state that should be explored further. Note that this function should mutate its        input list (ie, remove the desired state), and return that desired state.


   .. py:method:: filter(simgr, state, **kwargs)

      Perform filtering on which stash a state should be inserted into.

      If the state should be filtered, return the name of the stash to move the state to.
      If you want to modify the state before filtering it, return a tuple of the stash to move the state to and the
      modified state.
      To defer to the original categorization procedure, return the result of ``simgr.filter(state, **kwargs)``

      If the user provided a ``filter_func`` in their step or run command, it will appear here.

      :param angr.SimulationManager simgr:
      :param angr.SimState state:



.. py:class:: _ExploreMode(*args, **kwds)


   Bases: :py:obj:`enum.Enum`

   Create a collection of name/value pairs.

   Example enumeration:

   >>> class Color(Enum):
   ...     RED = 1
   ...     BLUE = 2
   ...     GREEN = 3

   Access them by:

   - attribute access::

   >>> Color.RED
   <Color.RED: 1>

   - value lookup:

   >>> Color(1)
   <Color.RED: 1>

   - name lookup:

   >>> Color['RED']
   <Color.RED: 1>

   Enumerations can be iterated over, and know how many members they have:

   >>> len(Color)
   3

   >>> list(Color)
   [<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

   Methods can be added to enumerations, and members can have their own
   attributes -- see the documentation for details.

   .. py:attribute:: EXPLORE_LEFT
      :value: 0

      

   .. py:attribute:: EXPLORE_RIGHT
      :value: 1

      


.. py:class:: JointConcolicSim(simgr_left: angr.SimulationManager, simgr_right: angr.SimulationManager, symbols: set[claripy.BVS] | frozenset[claripy.BVS], left_explorer: ConcolicSim, right_explorer: ConcolicSim, candidate_heuristic_left: collections.abc.Callable[[list[angr.SimState]], angr.SimState] | None = None, candidate_heuristic_right: collections.abc.Callable[[list[angr.SimState]], angr.SimState] | None = None)


   Jointly runs two SimulationManager objects by concretizing symbols, then running the left and right simulations
   with the same concrete input. This joint simulator alternates between the left and right simulations
   when generating new concrete inputs.

   :param SimulationManager simgr_left: The first simulation manager to run in concolic execution
   :param SimulationManager simgr_right: The second simulation manager to run in concolic execution.
   :param ConcolicSim left_explorer: The first exploration method to use for concolic execution. Note that        this exploration technique will be attached to the left simulation manager.
   :param ConcolicSim right_explorer: The second exploration method to use for concolic execution. Note that        this exploration technique will be attached to the right simulation manager.
   :param Callable[[list[angr.SimState]], angr.SimState] | None candidate_heuristic_left: The heuristic that        should be used to choose the deferred state that should be explored further. Note that this function should        mutate its input list (ie, remove the desired state), and return that desired state. Note that some        pre-made candidate heuristic techniques can be found in the :py:mod:`cozy.concolic.heuristics` module.
   :param Callable[[list[angr.SimState]], angr.SimState] | None candidate_heuristic_right: The heuristic that        should be used to choose the deferred state that should be explored further. Note that this function should        mutate its input list (ie, remove the desired state), and return that desired state. Note that some        pre-made candidate heuristic techniques can be found in the :py:mod:`cozy.concolic.heuristics` module.

   .. py:method:: _swap_explore_mode()


   .. py:method:: _generate_concrete(from_stash_left, from_stash_right)


   .. py:method:: explore(explore_fun_left: collections.abc.Callable[[angr.SimulationManager], None] | None = None, explore_fun_right: collections.abc.Callable[[angr.SimulationManager], None] | None = None, termination_fun_left: collections.abc.Callable[[angr.SimulationManager], bool] | None = None, termination_fun_right: collections.abc.Callable[[angr.SimulationManager], bool] | None = None) -> None

      Explores the simulations given in the left and right simulation manager.

      :param Callable[[SimulationManager], None] | None explore_fun_left: If this parameter is not None, then        instead of :py:meth:`SimulationManager.explore` being called to do the exploration, we call explore_fun_left        instead.
      :param Callable[[SimulationManager], None] | None explore_fun_right: If this parameter is not None, then        instead of :py:meth:`SimulationManager.explore` being called to do the exploration, we call explore_fun_right        instead.
      :param Callable[[SimulationManager], bool] | None termination_fun_left: Every time we finish exploring one        concrete input, this function is called to determine if the exploration should terminate. If both termination        functions return True, then exploration is halted and this function returns. If this parameter is None, then        the left simulation manager will terminate only when no further exploration is possible (ie, execution is        complete). Pre-made termination functions can be found in the :py:mod:`cozy.concolic.heuristics` module.
      :param Callable[[SimulationManager], bool] | None termination_fun_right: Every time we finish exploring one        concrete input, this function is called to determine if the exploration should terminate. If both termination        functions return True, then exploration is halted and this function returns. If this parameter is None, then        the right simulation manager will terminate only when no further exploration is possible (ie, execution is        complete). Pre-made termination functions can be found in the :py:mod:`cozy.concolic.heuristics` module.
      :return: None
      :rtype: None



