cozy.directive

Module Contents

Classes

Directive

Abstract base class for all directives.

AssertType

An enum to determine the type of assertion.

Assert

An assert directive sets a breakpoint at a certain address.

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.

Breakpoint

This directive is used to halt execution at some particular address, and pass the current state to the provided

Postcondition

A Postcondition is a special type of assertion that is executed on terminal states for which execution has been

class cozy.directive.Directive

Abstract base class for all directives.

class cozy.directive.AssertType(*args, **kwds)

Bases: enum.Enum

An enum to determine the type of assertion.

ASSERT_MUST = 0

This type of assert will be triggered if the assertion condition can be falsified. This assertion type replicates the behaviour of assertions as used in a typical testing environment. More precisely, this assertion uses universal quantification. The assertion fails if the following condition does not hold: forall x . P(x), where x is the program input, and P is the assertion condition.

ASSERT_CAN = 1

This type of assert will be triggered if the assertion condition cannot be satisfied, under the constraints of the local state. This assertion type is a dual to ASSERT_MUST, and an exact analogue does not exist from typical testing environments. More precisely, this assertion uses existential quantification. The assertion fails if the following condition does not hold: exists x . P(x), where x is the program input, P is the assertion condition, and C is the state’s constraints.

ASSERT_CAN_GLOBAL = 2

This is type of assert is like ASSERT_CAN, but is computed under a global setting. If on any path the local assertion exists x . P(x) holds, then all cases where the assertion failed will be scrubbed from the output. This is much the same E from computation tree logic, which is also a global property. Note that this assertion type should only be used in cases where the exploration is complete - ie all states can be explored.

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

Bases: Directive

An assert directive sets a breakpoint at a certain address.

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.

  • assert_type (AssertType) – The type of assert.

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.

  • assert_type (AssertType) – The type of assert to construct.

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, assert_type: AssertType = AssertType.ASSERT_MUST)

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.

  • assert_type (AssertType) – The type of assert to construct.

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_post_processor: collections.abc.Callable[[claripy.ast.Base], any] | None = None, info_str: str = 'Unknown Virtual Print: ', label=None)

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.

  • label (str) – Internal label used for side effect alignment. Side effects (including virtual prints) are diffed if they have the same label.

  • concrete_post_processor (Callable[[claripy.ast.Base], any] | None) – concrete_post_processor 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_post_processor is useful. In this example concrete_post_processor 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_post_processor (Callable[[claripy.ast.Base], any] | None) – concrete_post_processor 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_post_processor is useful. In this example concrete_post_processor 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.

  • label (str) – Internal label used for side effect alignment. Side effects (including virtual prints) are diffed if they have the same label.

effect_concrete_post_processor(concrete_value)
static from_fun_offset(project, fun_name: str, offset: int, log_fun: collections.abc.Callable[[angr.SimState], claripy.ast.Base], concrete_post_processor: collections.abc.Callable[[claripy.ast.Base], any] | None = None, info_str: str | None = None, label=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.

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

  • concrete_post_processor (Callable[[claripy.ast.Base], any] | None) – concrete_post_processor 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_post_processor is useful. In this example concrete_post_processor 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.

  • label (str) – Internal label used for side effect alignment. Side effects (including virtual prints) are diffed if they have the same label.

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

class cozy.directive.Breakpoint(addr: int, breakpoint_fun: collections.abc.Callable[[angr.SimState], None])

Bases: Directive

This directive is used to halt execution at some particular address, and pass the current state to the provided breakpoint function, which can then either modify the state or do some other side effect (like executing a Python print() call).

Variables:
  • addr (int) – The program address this breakpoint is attached to.

  • breakpoint_fun (Callable[[SimState], None]) – This function takes in the state reached by the program at the attachment point.

Constructor for a VirtualPrint object.

Parameters:
  • addr (int) – The program address this breakpoint is attached to.

  • breakpoint_fun (Callable[[SimState], None]) – This function takes in the state reached by the program at the attachment point.

static from_fun_offset(project, fun_name: str, offset: int, breakpoint_fun: collections.abc.Callable[[angr.SimState], 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.

  • breakpoint_fun (Callable[[SimState], None]) – This function takes in the state reached by the program at the attachment point.

Returns:

A new Breakpoint object at the desired function offset.

Return type:

Breakpoint

class cozy.directive.Postcondition(condition_fun: collections.abc.Callable[[angr.SimState], claripy.ast.bool], info_str: str | None = None, assert_type=AssertType.ASSERT_MUST)

Bases: Directive

A Postcondition is a special type of assertion that is executed on terminal states for which execution has been completed. This is identical to attaching an ASSERT_MUST assertion to all return points. This type of property is useful for verifying that a property holds in all terminal states. Note that if you are looking to add a precondition, you can add your proposition to the session before the run via cozy.Session.add_constraints().

Parameters:
  • condition_fun (Callable[[SimState], claripy.ast.bool]) – When the program reaches a terminal state, 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 postcondition assertion, printed to the user if the assert is triggered.

  • assert_type (AssertType) – The type of assert to construct.