:py:mod:`cozy.session`
======================

.. py:module:: cozy.session


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

Classes
~~~~~~~

.. autoapisummary::

   cozy.session.RunResult
   cozy.session._SessionExploration
   cozy.session._SessionDirectiveExploration
   cozy.session._SessionBasicExploration
   cozy.session.Session



Functions
~~~~~~~~~

.. autoapisummary::

   cozy.session._on_mem_write
   cozy.session._save_states



Attributes
~~~~~~~~~~

.. autoapisummary::

   cozy.session._mem_write_ctr


.. py:class:: RunResult(deadended: list[cozy.terminal_state.DeadendedState], errored: list[cozy.terminal_state.ErrorState], asserts_failed: list[cozy.terminal_state.AssertFailedState], assume_warnings: list[tuple[cozy.directive.Assume, angr.SimState]])


   This class is used for storing the results of running a session.

   :ivar list[DeadendedState] deadended: States that reached normal termination.
   :ivar list[ErrorState] errored: States that reached an error state. This may be triggered for example by program errors such as division by 0, or by reaching a :py:class:`cozy.directive.ErrorDirective`.
   :ivar list[AssertFailed] asserts_failed: States where an assertion was able to be falsified.
   :ivar list[tuple[Assume, SimState]] assume_warnings: An assume warning occurs when a :py:class:`~cozy.directive.Assume` is reached, and the added assumption contradicts the constraints for that state. This means that due to the assumption, the new constraints are not satisfiable.

   .. py:property:: assertion_triggered
      :type: bool

      Returns True if there were any assertions triggered during this run.

      :return: True if there were assertions triggered.
      :rtype: bool


   .. py:method:: __str__()

      Return str(self).


   .. py:method:: report_errored(args: any, concrete_arg_mapper: collections.abc.Callable[[any], any] | None = None, num_examples: int = 3) -> str

      Creates a human readable report about a list of errored states.

      :param any args: The arguments to concretize
      :param Callable[[any], any] | None concrete_arg_mapper: This function is used to post-process concretized versions of args before they are added to the return string. Some examples of this function include converting an integer to a negative number due to use of two's complement, or slicing off parts of the argument based on another part of the input arguments.
      :param int num_examples: The maximum number of concrete examples to show the user for each errored state.
      :return: The report as a string
      :rtype: str


   .. py:method:: report_asserts_failed(args: any, concrete_arg_mapper: collections.abc.Callable[[any], any] | None = None, num_examples: int = 3) -> str

      Creates a human readable report about a list of failed assertions.

      :param any args: The arguments to concretize
      :param Callable[[any], any] | None concrete_arg_mapper: This function is used to post-process concretized versions of args before they are added to the return string. Some examples of this function include converting an integer to a negative number due to use of two's complement, or slicing off parts of the argument based on another part of the input arguments.
      :param int num_examples: The maximum number of concrete examples to show the user for each assertion failed state.
      :return: The report as a string
      :rtype: str



.. py:data:: _mem_write_ctr
   :value: 0

   

.. py:function:: _on_mem_write(state)


.. py:function:: _save_states(states)


.. py:class:: _SessionExploration(session: Session, cache_intermediate_states: bool = False)


   .. py:method:: explore(simgr)
      :abstractmethod:



.. py:class:: _SessionDirectiveExploration(session: Session, cache_intermediate_states: bool = False)


   Bases: :py:obj:`_SessionExploration`

   .. py:method:: explore(simgr)



.. py:class:: _SessionBasicExploration(session: Session, cache_intermediate_states: bool = False)


   Bases: :py:obj:`_SessionExploration`

   .. py:method:: explore(simgr)



.. py:class:: Session(proj, start_fun: str | int | None = None)


   A session is a particular run of a project, consisting of attached directives (asserts/assumes).
   You can malloc memory for storage prior to running the session.
   Once you are ready to run the session, use the run method.

   :ivar angr.SimState state: The initial state tied to this particular session. You can access this member to modify properties of the state before a run.
   :ivar cozy.project.Project proj: The Project tied to this session.
   :ivar str | int | None start_fun: The starting function tied to this session. If start_fun is None, then the session starts in an entry state.
   :ivar list[Directive] directives: The directives added to this session.
   :ivar bool has_run: True if the :py:meth:`cozy.project.Session.run` method has been called, otherwise False.

   Constructs a session derived from a project. The :py:meth:`cozy.project.Project.session` is the preferred method for creating a session, not this constructor.

   .. py:property:: memory


   .. py:property:: mem

      Access memory using a dict-like interface. This property simply forwards to state.mem


   .. py:property:: start_fun_addr


   .. py:method:: store_fs(filename: str, simfile: angr.SimFile) -> None

      Stores a file in a virtual filesystem available during execution. This method simply forwards the arguments to state.fs.insert.

      :param str filename: The filename of the new file.
      :param angr.SimFile simfile: The file to make available to the simulated program.
      :return: None
      :rtype: None


   .. py:method:: malloc(num_bytes: int) -> int

      Mallocs a fixed amount of memory using the angr heap simulation plugin. Useful for setting things up in memory before the :py:meth:`~cozy.project.Project.run` method is called.

      :param int num_bytes: The number of bytes to allocate.
      :return: A pointer to the allocated memory block.
      :rtype: int


   .. py:method:: store(addr: int, data: claripy.ast.bits, **kwargs)

      Stores data at some address. This method simply forwards the arguments to state.memory.store.

      :param int addr: Address to store the data at.
      :param claripy.ast.bits data: The data to store in memory.
      :param kwargs: Additional keyword arguments to pass to state.memory.store


   .. py:method:: add_directives(*directives: cozy.directive.Directive) -> None

      Adds multiple directives to the session.

      :param Directive directives: The directives to add.
      :return: None
      :rtype: None


   .. py:method:: add_constraints(*constraints: claripy.ast.bool) -> None

      Adds multiple constraints to the session's state.

      :param claripy.ast.bool constraints: The constraints to add
      :return: None
      :rtype: None


   .. py:method:: _call(args: list[claripy.ast.bits], cache_intermediate_states: bool = False, ret_addr: int | None = None) -> angr.sim_manager.SimulationManager


   .. py:method:: _session_exploration(cache_intermediate_states: bool = False) -> _SessionExploration


   .. py:method:: _run_result(simgr: angr.sim_manager.SimulationManager, sess_exploration: _SessionExploration) -> RunResult


   .. py:method:: run(args: list[claripy.ast.bits], cache_intermediate_states: bool = False, ret_addr: int | None = None) -> RunResult

      Runs a session to completion, either starting from the start_fun used to create the session, or from the        program start. Note that currently a session may be run only once. If run is called multiple times, a        RuntimeError will be thrown.

      :param list[claripy.ast.bits] args: The arguments to pass to the function. angr will utilize the function's        type signature to figure out the calling convention to use with the arguments.
      :param bool cache_intermediate_states: If this flag is True, then intermediate execution states will be cached,        preventing their garbage collection. This is required for dumping the execution graph which is used in        visualization.
      :param int | None ret_addr: What address to return to if calling as a function
      :return: The result of running this session.
      :rtype: RunResult



