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)

_on_simprocedure(state)

_save_states(states)

Attributes

_mem_write_ctr

_malloc_name_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._malloc_name_ctr = 0
cozy.session._on_simprocedure(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, name=None) 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