cozy.session — cozy 1.1 documentation

# `cozy.session`

## Module Contents

### Classes

`RunResult` | This class is used for storing the results of running a session.
`_SessionExploration` |
`_SessionDirectiveExploration` |
`_SessionBasicExploration` |
`Session` | A session is a particular run of a project, consisting of attached directives (asserts/assumes).

### Functions

`_on_mem_write`(state) |
`_save_states`(states) |

### Attributes

`_mem_write_ctr` |

class cozy.session.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.

  Variables:

    - deadended (list[DeadendedState]) – States that reached normal termination.

    - errored (list[ErrorState]) – States that reached an error state. This may be triggered for example by program errors such as division by 0, or by reaching a `cozy.directive.ErrorDirective`.

    - asserts_failed (list[AssertFailed]) – States where an assertion was able to be falsified.

    - assume_warnings (list[tuple[Assume, SimState]]) – An assume warning occurs when a `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.

  property assertion_triggered: bool

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

    Returns:

      True if there were assertions triggered.

    Return type:

      bool

  __str__()

    Return str(self).

  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.

    Parameters:

      - args (any) – The arguments to concretize

      - concrete_arg_mapper (Callable[[any], any] | None) – 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.

      - num_examples (int) – The maximum number of concrete examples to show the user for each errored state.

    Returns:

      The report as a string

    Return type:

      str

  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.

    Parameters:

      - args (any) – The arguments to concretize

      - concrete_arg_mapper (Callable[[any], any] | None) – 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.

      - num_examples (int) – The maximum number of concrete examples to show the user for each assertion failed state.

    Returns:

      The report as a string

    Return type:

      str

cozy.session._mem_write_ctr = 0

cozy.session._on_mem_write(state)

cozy.session._save_states(states)

class cozy.session._SessionExploration(session: Session, cache_intermediate_states: bool = False)
  abstract explore(simgr)

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

  Bases: `_SessionExploration`

  explore(simgr)

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

  Bases: `_SessionExploration`

  explore(simgr)

class cozy.session.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.

  Variables:

    - state (angr.SimState) – The initial state tied to this particular session. You can access this member to modify properties of the state before a run.

    - proj (cozy.project.Project) – The Project tied to this session.

    - start_fun (str | int | None) – The starting function tied to this session. If start_fun is None, then the session starts in an entry state.

    - directives (list[Directive]) – The directives added to this session.

    - has_run (bool) – True if the `cozy.project.Session.run()` method has been called, otherwise False.

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

  property memory
  property mem

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

  property start_fun_addr
  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.

    Parameters:

      - filename (str) – The filename of the new file.

      - simfile (angr.SimFile) – The file to make available to the simulated program.

    Returns:

      None

    Return type:

      None

  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 `run()` method is called.

    Parameters:

      num_bytes (int) – The number of bytes to allocate.

    Returns:

      A pointer to the allocated memory block.

    Return type:

      int

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

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

    Parameters:

      - addr (int) – Address to store the data at.

      - data (claripy.ast.bits) – The data to store in memory.

      - kwargs – Additional keyword arguments to pass to state.memory.store

  add_directives(*directives: cozy.directive.Directive) → None

    Adds multiple directives to the session.

    Parameters:

      directives (Directive) – The directives to add.

    Returns:

      None

    Return type:

      None

  add_constraints(*constraints: claripy.ast.bool) → None

    Adds multiple constraints to the session’s state.

    Parameters:

      constraints (claripy.ast.bool) – The constraints to add

    Returns:

      None

    Return type:

      None

  _call(args: list[claripy.ast.bits], cache_intermediate_states: bool = False, ret_addr: int | None = None) → angr.sim_manager.SimulationManager
  _session_exploration(cache_intermediate_states: bool = False) → _SessionExploration
  _run_result(simgr: angr.sim_manager.SimulationManager, sess_exploration: _SessionExploration) → RunResult
  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.

    Parameters:

      - args (list[claripy.ast.bits]) – 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.

      - cache_intermediate_states (bool) – 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.

      - ret_addr (int | None) – What address to return to if calling as a function

    Returns:

      The result of running this session.

    Return type:

      RunResult