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). You can malloc memory for storage prior to running the session. Once you are ready to run the session, use the run method.

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]], postconditions_failed: list[cozy.terminal_state.PostconditionFailedState])

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

property postcondition_triggered: bool

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

Returns:

True if there were postcondition assertions triggered.

Return type:

bool

__str__()

Return str(self).

report(args: any, concrete_post_processor: collections.abc.Callable[[any], any] | None = None, num_examples: int = 3) str

Creates a composite human readable report with information about errored states, asserts failed, and postconditions failed.

Parameters:
  • args (any) – The arguments to concretize

  • concrete_post_processor (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.

Returns:

The report as a string

Return type:

str

report_errored(args: any, concrete_post_processor: 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_post_processor (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_postconditions_failed(args: any, concrete_post_processor: collections.abc.Callable[[any], any] | None = None, num_examples: int = 3) str

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

Parameters:
  • args (any) – The arguments to concretize

  • concrete_post_processor (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

report_asserts_failed(args: any, concrete_post_processor: 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_post_processor (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_info: bool = True)
abstract explore(simgr)
class cozy.session._SessionDirectiveExploration(session: Session, cache_intermediate_info: bool = True)

Bases: _SessionExploration

check_postconditions(simgr)
explore(simgr)
class cozy.session._SessionBasicExploration(session: Session, cache_intermediate_info: bool = True)

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. :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 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_info: bool = True, ret_addr: int | None = None) angr.sim_manager.SimulationManager
_session_exploration(cache_intermediate_info: bool = True) _SessionExploration
_run_result(simgr: angr.sim_manager.SimulationManager, sess_exploration: _SessionExploration) RunResult
run(args: list[claripy.ast.bits], cache_intermediate_info: bool = True, 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_info (bool) – If this flag is True, then information about intermediate states will be

cached. 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