cozy.project
¶
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). |
|
Represents a project for a single executable |
Functions¶
|
Attributes¶
- 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:
- 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: