cozy.execution_graph — cozy 1.1 documentation

# `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) |
`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)

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_arg_mapper: 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, 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_arg_mapper (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.

    - 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_arg_mapper: 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, 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_arg_mapper (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.

    - 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_arg_mapper: 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, 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_arg_mapper (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.

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