cozy.directive — cozy 1.1 documentation

# `cozy.directive`

## Module Contents

### Classes

`Directive` | Abstract base class for all directives.
`Assert` | An assert directive sets a breakpoint at a certain address. An assert is triggered if there is a concrete input which would cause the assertion condition to be satisfied.
`Assume` | An assume directive sets a breakpoint at a certain address. An assume simply adds an extra constraint to the state's accumulated constraints before resuming execution. An assume is useful for adding a precondition.
`VirtualPrint` | This directive is used to log some piece of information about the program in a list attached to the state. When execution reaches the desired address, the log function will be called, and the result will be saved inside the state's globals dictionary.
`ErrorDirective` | If the program execution reaches the desired address, the state will be considered to be in an errored state and will be moved to the errored cache. This state will have no further execution.

class cozy.directive.Directive

  Abstract base class for all directives.

class cozy.directive.Assert(addr: int, condition_fun: collections.abc.Callable[[angr.SimState], claripy.ast.bool], info_str: str | None = None)

  Bases: `Directive`

  An assert directive sets a breakpoint at a certain address. An assert is triggered if there is a concrete input which would cause the assertion condition to be satisfied.

  Variables:

    - addr (int) – The program address this assert is attached to.

    - condition_fun (Callable[[SimState], claripy.ast.bool]) – When the program reaches the desired address, the SimState will be passed to this function, and an assertion condition should be returned. This is then used internally by the SAT solver, along with the state’s accumulated constraints.

    - info_str (str | None) – Human readable label for this assertion, printed to the user if the assert is triggered.

  Constructor for an Assert object.

  Parameters:

    - addr (int) – The address at which the assert will be triggered.

    - condition_fun (Callable[[SimState], claripy.ast.bool]) – When the program reaches the desired address, the SimState will be passed to this function, and an assertion condition should be returned. This is then used internally by the SAT solver, along with the state’s accumulated constraints.

    - info_str (str | None) – Human readable label for this assertion, printed to the user if the assert is triggered.

  static from_fun_offset(project, fun_name: str, offset: int, condition_fun: collections.abc.Callable[[angr.SimState], claripy.ast.bool], info_str: str | None = None)

    Factory for an Assert object set at a certain offset from a function start.

    Parameters:

      - project (cozy.project.Project) – The project which this assert is attached to. The project is used to compute the address of the assert.

      - str (fun_name) – The name of the function in which this assert will be located.

      - int (offset) – The offset into the function in which this assert will be located.

      - condition_fun (Callable[[SimState], claripy.ast.bool]) – When the program reaches the desired address, the SimState will be passed to this function, and an assertion condition should be returned. This is then used internally by the SAT solver, along with the state’s accumulated constraints.

      - info_str (str | None) – Human readable label for this assertion, printed to the user if the assert is triggered.

    Returns:

      A new Assert object at the desired function offset.

    Return type:

      Assert

class cozy.directive.Assume(addr: int, condition_fun: collections.abc.Callable[[angr.SimState], claripy.ast.bool], info_str: str | None = None)

  Bases: `Directive`

  An assume directive sets a breakpoint at a certain address. An assume simply adds an extra constraint to the state’s accumulated constraints before resuming execution. An assume is useful for adding a precondition.

  Variables:

    - addr (int) – The program address this assume is attached to.

    - condition_fun (Callable[[SimState], claripy.ast.bool]) – When the program reaches the desired address, the SimState will be passed to this function, and a condition should be returned. This condition is then attached to the state’s set of constraints.

    - info_str (str | None) – Human readable label for this assume.

  Constructor for an Assume object.

  Parameters:

    - addr (int) – The address at which the assume will be triggered.

    - condition_fun (Callable[[SimState], claripy.ast.bool]) – When the program reaches the desired address, the SimState will be passed to this function, and an assumption should be returned. This assumption is attached to the state’s constraints for future execution.

    - info_str (str | None) – Human readable label for this assume.

  static from_fun_offset(project, fun_name: str, offset: int, condition_fun: collections.abc.Callable[[angr.SimState], claripy.ast.bool], info_str: str | None = None)

    Factory for an Assume object set at a certain offset from a function start.

    Parameters:

      - project (cozy.project.Project) – The project this assume is attached to.

      - str (fun_name) – The name of the function in which this assume will be located.

      - int (offset) – The offset into the function in which this assume will be located.

      - condition_fun (Callable[[SimState], claripy.ast.bool]) – When the program reaches the desired address, the SimState will be passed to this function, and an assumption should be returned. This assumption is attached to the state’s constraints for future execution.

      - info_str (str | None) – Human readable label for this assume.

    Returns:

      A new Assume object at the desired function offset.

    Return type:

      Assume

class cozy.directive.VirtualPrint(addr: int, log_fun: collections.abc.Callable[[angr.SimState], claripy.ast.Base], concrete_mapper: collections.abc.Callable[[claripy.ast.Base], any] | None = None, info_str: str = 'Unknown Virtual Print: ')

  Bases: `Directive`

  This directive is used to log some piece of information about the program in a list attached to the state. When execution reaches the desired address, the log function will be called, and the result will be saved inside the state’s globals dictionary.

  Variables:

    - addr (int) – The program address this virutal print is attached to.

    - log_fun (Callable[[SimState], claripy.ast.Base]) – This function takes in the current state and returns a claripy AST which should be logged. This value may be symbolic.

    - info_str (str) – Human readable label for this virtual print.

    - concrete_mapper (Callable[[claripy.ast.Base], any] | None) – concrete_mapper takes as input a concretized version of the output from log_fun and returns a result which is printed to the screen. For example, a log fun may return state.regs.eax to log the value of eax. But if eax represents a 32 bit signed value, we want to pretty print to negative number. This is where concrete_mapper is useful. In this example concrete_mapper would take a concrete bit vector representing a possible value of EAX and return a Python integer (which can be negative). This is what is shown to the user.

  Constructor for a VirtualPrint object.

  Parameters:

    - addr (int) – The program address this virutal print is attached to.

    - log_fun (Callable[[SimState], claripy.ast.Base]) – This function takes in the current state and returns a claripy AST which should be logged. This value may be symbolic.

    - concrete_mapper (Callable[[claripy.ast.Base], any] | None) – concrete_mapper takes as input a concretized version of the output from log_fun and returns a result which is printed to the screen. For example, a log fun may return state.regs.eax to log the value of eax. But if eax represents a 32 bit signed value, we want to pretty print to negative number. This is where concrete_mapper is useful. In this example concrete_mapper would take a concrete bit vector representing a possible value of EAX and return a Python integer (which can be negative). This is what is shown to the user.

    - info_str (str) – Human readable label for this virtual print.

  static from_fun_offset(project, fun_name: str, offset: int, log_fun: collections.abc.Callable[[angr.SimState], claripy.ast.Base], concrete_mapper: collections.abc.Callable[[claripy.ast.Base], any] | None = None, info_str: str | None = None)

    Factory for VirtualPrint object set at a certain offset from a function start.

    Parameters:

      - project (cozy.project.Project) – The project which this virtual print is attached to. The project is used to compute the address of the virtual print.

      - fun_name (str) – The name of the function in which this virtual print will be located.

      - offset (int) – The offset into the function in which this virtual print will be located.

      - concrete_mapper (Callable[[claripy.ast.Base], any] | None) – concrete_mapper takes as input a concretized version of the output from log_fun and returns a result which is printed to the screen. For example, a log fun may return state.regs.eax to log the value of eax. But if eax represents a 32 bit signed value, we want to pretty print to negative number. This is where concrete_mapper is useful. In this example concrete_mapper would take a concrete bit vector representing a possible value of EAX and return a Python integer (which can be negative). This is what is shown to the user.

      - info_str (str) – Human readable label for this virtual print.

    Returns:

      A new VirtualPrint object at the desired function offset.

    Return type:

      VirtualPrint

class cozy.directive.ErrorDirective(addr: int, info_str: str | None = None)

  Bases: `Directive`

  If the program execution reaches the desired address, the state will be considered to be in an errored state and will be moved to the errored cache. This state will have no further execution.

  Variables:

    - addr (int) – The program address this error directive is attached to.

    - str – Human readable information for this error directive.

  Constructor for an ErrorDirective object.

  Parameters:

    - addr (int) – The program address this error directive is attached to.

    - info_str (str) – Human readable information for this error directive.

  static from_fun_offset(project, fun_name: str, offset: int, info_str: str | None = None)

    Factory for ErrorDirective object set at a certain offset from a function start.

    Parameters:

      - project (cozy.project.Project) – The project this error directive should be attached to.

      - fun_name (str) – The name of the function in which this error directive will be located.

      - offset (int) – The offset into the function in which this error directive will be located.

      - info_str (str | None) – Human readable information for this error directive.

    Returns:

      A new ErrorDirective object at the desired function offset.

    Return type:

      ErrorDirective