cozy.execution_graph

Module Contents

Classes

ExecutionGraph

This class is used to store a networkx.DiGraph, decorated with SimStates, representing the full history of a symbolic program execution.

Functions

_serialize_diff(diff[, nice_name_a, nice_name_b])

_serialized_field_diff(diff)

dump_comparison(→ None)

Generates and saves JSON data for Cozy-Viz.

visualize_comparison(proj_a, proj_b, rslt_a, rslt_b, ...)

Generates and visualizes JSON data for Cozy-Viz.

_generate_comparison(→ tuple[networkx.DiGraph, ...)

Generates JSON data for Cozy-Viz.

cozy.execution_graph._serialize_diff(diff, nice_name_a: collections.abc.Callable[[int], str | None] | None = None, nice_name_b: collections.abc.Callable[[int], str | None] | None = None)
cozy.execution_graph._serialized_field_diff(diff: any)
cozy.execution_graph.dump_comparison(proj_a: cozy.project.Project, proj_b: cozy.project.Project, rslt_a: cozy.session.RunResult, rslt_b: cozy.session.RunResult, comparison_results: cozy.analysis.Comparison, file_name_a: str, file_name_b: str, concrete_post_processor: collections.abc.Callable[[any], any] | None = None, include_vex: bool = False, include_simprocs: bool = False, flag_syscalls: bool = False, include_actions: bool = False, include_debug: bool = False, include_side_effects: bool = True, args: any = [], num_examples: int = 0) None

Generates and saves JSON data for Cozy-Viz.

Generates JSON data for Cozy-Viz from the results of two symbolic executions, and saves the result to two files, one for pre and one for post.

Parameters:
  • proj_a (Project) – The project associated with the first execuction.

  • proj_b (Project) – The project associated with the second execuction.

  • rslt_a (RunResult) – The result of the first execution.

  • rslt_b (RunResult) – The result of the second execution.

  • comparison_results (analysis.Comparison) – The comparison we wish to dump.

  • file_name_a (str) – The filename for the JSON serializing the first execution

  • file_name_b (str) – The filename for the JSON serializing the second execution

  • concrete_post_processor (Callable [[any],any] | None, optional) – 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. Default None.

  • include_vex (bool, optional) – whether to, for each SimState, generate the corresponding VEX IR and include the result in the JSON. Default False.

  • include_simprocs (bool, optional) – whether to, for each SimState, flag any SimProcedure locations occurring in the corrsponding basic block. Default False.

  • include_simprocs – whether to include a listing of SimProcedures called in each basic block. Default False.

  • include_actions (bool, optional) – whether to include logging of read/write operations on memory and registers. Default False.

  • include_debug (bool, optional) – whether to include debugging information recovered from DWARF metadata. Default False.

  • include_side_effects (bool, optional) – whether to include cozy side effects, like virtual prints, if present. Default True.

  • args (any, optional) – The input arguments to concretize. This argument may be a Python datastructure, the concretizer will make a deep copy with claripy symbolic variables replaced with concrete values. See cozy.analysis.CompatiblePair. Default = [].

  • num_examples (int, optional) – The number of concrete examples to generate and incorporate into the JSON, for each dead-end state. Default 0.

cozy.execution_graph.visualize_comparison(proj_a: cozy.project.Project, proj_b: cozy.project.Project, rslt_a: cozy.session.RunResult, rslt_b: cozy.session.RunResult, comparison_results: cozy.analysis.Comparison, concrete_post_processor: collections.abc.Callable[[any], any] | None = None, include_vex: bool = False, include_simprocs: bool = False, flag_syscalls: bool = False, include_actions: bool = False, include_debug: bool = False, include_side_effects: bool = True, args: any = [], num_examples: int = 0, open_browser=False, port=8080)

Generates and visualizes JSON data for Cozy-Viz.

Generates JSON data suitable for visual comparison using Cozy-Viz from the results of two symbolic executions, and launches a server to view the data.

Parameters:
  • proj_a (Project) – The project associated with the first execuction.

  • proj_b (Project) – The project associated with the second execuction.

  • rslt_a (RunResult) – The result of the first execution.

  • rslt_b (RunResult) – The result of the second execution.

  • comparison_results (analysis.Comparison) – The comparison we wish to dump.

  • concrete_post_processor (Callable [[any],any] | None, optional) – 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. Default None.

  • include_vex (bool, optional) – whether to, for each SimState, generate the corresponding VEX IR and include the result in the JSON. Default False.

  • include_simprocs (bool, optional) – whether to include a listing of SimProcedures called in each basic block. Default False.

  • include_actions (bool, optional) – whether to include logging of read/write operations on memory and registers. Default False.

  • include_debug (bool, optional) – whether to include debugging information recovered from DWARF metadata. Default False.

  • include_side_effects (bool, optional) – whether to include cozy side effects, like virtual prints, if present. Default True.

  • args (any, optional) – The input arguments to concretize. This argument may be a Python datastructure, the concretizer will make a deep copy with claripy symbolic variables replaced with concrete values. See cozy.analysis.CompatiblePair. Default [].

  • num_examples (int, optional) – The number of concrete examples to generate and incorporate into the JSON, for each dead-end state. Default 0.

  • open_browser (bool, optional) – Automatically open cozy-viz with the comparison data loaded. Default False.

  • port (int, optional) – The port to serve cozy-viz on. Default 8080.

cozy.execution_graph._generate_comparison(proj_a: cozy.project.Project, proj_b: cozy.project.Project, rslt_a: cozy.session.RunResult, rslt_b: cozy.session.RunResult, comparison_results: cozy.analysis.Comparison, concrete_post_processor: collections.abc.Callable[[any], any] | None = None, include_vex: bool = False, include_simprocs: bool = False, flag_syscalls: bool = False, include_actions: bool = False, include_debug: bool = False, include_side_effects: bool = True, args: any = [], num_examples: int = 0) tuple[networkx.DiGraph, networkx.DiGraph]

Generates JSON data for Cozy-Viz.

Generates JSON data suitable for visual comparison using Cozy-Viz from the results of two symbolic executions.

Parameters:
  • proj_a (Project) – The project associated with the first execuction.

  • proj_b (Project) – The project associated with the second execuction.

  • rslt_a (RunResult) – The result of the first execution.

  • rslt_b (RunResult) – The result of the second execution.

  • concrete_post_processor (Callable [[any],any] | None, optional) – 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. Default None.

  • include_vex (bool, optional) – whether to, for each SimState, generate the corresponding VEX IR and include the result in the JSON. Default False.

  • include_simprocs (bool, optional) – whether to include a listing of SimProcedures called in each basic block. Default False.

  • include_actions (bool, optional) – whether to include logging of read/write operations on memory and registers. Default False.

  • include_debug (bool, optional) – whether to include debugging information recovered from DWARF metadata. Default False.

  • include_side_effects (bool, optional) – whether to include cozy side effects, like virtual prints, if present. Default True.

  • args (any, optional) – The input arguments to concretize. This argument may be a Python datastructure, the concretizer will make a deep copy with claripy symbolic variables replaced with concrete values. See cozy.analysis.CompatiblePair. Default = [].

  • num_examples (int, optional) – The number of concrete examples to generate and incorporate into the JSON, for each dead-end state. Default 0.

Return (networkx.DiGraph, networkx.DiGraph):

A pair of directed graphs representing the two symbolic executions.

class cozy.execution_graph.ExecutionGraph(proj: cozy.project.Project, result: cozy.session.RunResult)

This class is used to store a networkx.DiGraph, decorated with SimStates, representing the full history of a symbolic program execution. It constructs an ExecutionGraph, from a project and the results of an executed project session.

Variables:
  • proj (Project) – the project associated with the execution.

  • result (RunResult) – the result of the execution.

_get_bbl_asm(b: angr.block.Block)

An internal method which renders the assembly corresponding to a given basic block as a formatted string

Parameters:

b (Block) – The block to render.

Return str:

The rendered string.

_list_simprocs(b: angr.block.Block)

An internal method which lists SimProcedure calls occuring in a block

Parameters:

b (Block) – the block to scan

_has_syscall(b: angr.block.Block)

An internal method which checks whether the jumpkind of a Block is a syscall.

Parameters:

b (Block) – the relevant Block

Return bool:

Whether the jumpkind is a syscall

_list_actions(child: angr.SimState | angr.state_plugins.SimStateHistory, parent: angr.SimState)
reconstruct_bbl_addr_graph()

Convert the SimState-decorated graph into a graph decorated with integers, carrying symbolic program execution data in the attributes stdout, stderr, contents (this holds a basic block), constraints, actions (optionally) and state.

Return networkx.DiGraph:

The resulting graph.

reconstruct_bbl_pp_graph()

Convert the SimState-decorated graph into a graph decorated with integers, carrying symbolic program execution data in the attributes stdout, stderr, contents, constraints ,`vex` and state. The difference from reconstruct_bbl_addr_graph() is that the data is now pretty-printed and suitable for serialization.

Return networkx.DiGraph:

The resulting graph.

dump_bbp_pp_cytoscape(name: str)

Dump the graph as cytoscapejs readable JSON.

Parameters:

name (str) – The filename for the generated json.