cozy.project

Module Contents

Classes

RunResult

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

Session

A session is a particular run of a project, consisting of attached directives (asserts/assumes).

Project

Represents a project for a single executable

Functions

_on_mem_write(state)

Attributes

_mem_write_ctr

class cozy.project.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.project._mem_write_ctr = 0
cozy.project._on_mem_write(state)
class cozy.project.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 (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.

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

_save_states(states)
_save_constraints(states)
run(*args: claripy.ast.bits, cache_intermediate_states: bool = False, cache_constraints: 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 (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.

  • cache_constraints (bool) – If this flag is True, then the intermediate execution state’s constraints will be cached, which is required for performing memoized binary search when diffing states.

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

Returns:

The result of running this session.

Return type:

RunResult

class cozy.project.Project(binary_path: str, fun_prototypes: dict[str | int, str] | None = None)

Represents a project for a single executable

Variables:
  • angr_proj (angr.Project) – The angr project created for this cozy project.

  • fun_prototypes (dict[str | int, str]) – Maps function names or function addresses to their type signatures.

Constructor for a project.

Parameters:
  • binary_path (str) – The path to the binary to analyze.

  • fun_prototypes (dict[str | int, str] | None) – Initial dictionary that maps function names or addresses to their type signatures. If None is passed, fun_prototypes is initialized to the empty dictionary.

object_ranges(obj_filter: collections.abc.Callable[[cle.Backend], bool] | None = None) list[range]

Returns the ranges of the objects stored in the executable (for example: ELF objects). If obj_filter is specified, only objects that pass the filter make it into the return list.

Parameters:

obj_filter (Callable[[Backend], bool] | None) – Used to filter certain objects from the output list.

Returns:

A list of memory ranges.

Return type:

list[range]

find_symbol_addr(sym_name: str) int

Finds the rebased addressed of a symbol. Functions are the most common symbol type.

Parameters:

sym_name (str) – The symbol to lookup.

Returns:

The rebased symbol address

Return type:

int

add_prototype(fun: str | int, fun_prototype: str) None

Adds a function prototype to this project.

Parameters:
  • fun (str | int) – The function’s name or address.

  • fun_prototype (str) – The function’s type signature.

Returns:

None

Return type:

None

session(start_fun: str | int | None = None) Session

Returns a new session derived from this project.

Parameters:

start_fun (str | int | None) – The name or address of the function which this session will start with. If None is specified, then the program will start at the entry point (main function).

Returns:

The fresh session.

Return type:

Session