cozy.session
¶
Module Contents¶
Classes¶
This class is used for storing the results of running a 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¶
|
|
|
|
|
Attributes¶
- 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