Package com.code_intelligence.jazzer.api

Annotation Interface MethodHook

@Retention(RUNTIME) @Target(METHOD) @Repeatable(MethodHooks.class) @Documented public @interface MethodHook
Registers the annotated method as a hook that should run before, instead or after the method specified by the annotation parameters.

Depending on type() this method will be called after, instead or before every call to the target method and has access to its parameters and return value. The target method is specified by targetClassName() and targetMethod(). In case of an overloaded method, targetMethodDescriptor() can be used to restrict the application of the hook to a particular overload.

The signature of the annotated method must be as follows (this does not restrict the method name and parameter names, which are arbitrary), depending on the value of type():

HookType.BEFORE 

 public static void hook(MethodHandle method, Object thisObject, Object[] arguments, int hookId)
Arguments:

  • method: A MethodHandle representing the original method. The original method can be invoked via MethodHandle.invokeWithArguments(Object...). This requires passing thisObject as the first argument if the method is not static. This argument can be null.
  • thisObject: An Object containing the implicit this argument to the original method. If the original method is static, this argument will be null.
  • arguments: An array of Objects containing the arguments passed to the original method. Primitive types (e.g. boolean) will be wrapped into their corresponding wrapper type (e.g. Boolean).
  • hookId: A random int identifying the particular call site.This can be used to derive additional coverage information.
HookType.REPLACE 

 public static Object hook(MethodHandle method, Object thisObject, Object[] arguments, int hookId)
The return type may alternatively be taken to be the exact return type of target method or a wrapper type thereof. The returned object will be casted and unwrapped automatically.

Arguments:

  • method: A MethodHandle representing the original method. The original method can be invoked via MethodHandle.invokeWithArguments(Object...). This requires passing thisObject as the first argument if the method is not static. This argument can be null.
  • thisObject: An Object containing the implicit this argument to the original method. If the original method is static, this argument will be null.
  • arguments: An array of Objects containing the arguments passed to the original method. Primitive types (e.g. boolean) will be wrapped into their corresponding wrapper type (e.g. Boolean).
  • hookId: A random int identifying the particular call site.This can be used to derive additional coverage information.

Return value: the value that should take the role of the value the target method would have returned

HookType.AFTER 

 public static void hook(MethodHandle method, Object thisObject, Object[] arguments, int hookId,
 Object returnValue)
Arguments:

  • method: A MethodHandle representing the original method. The original method can be invoked via MethodHandle.invokeWithArguments(Object...). This requires passing thisObject as the first argument if the method is not static. This argument can be null.
  • thisObject: An Object containing the implicit this argument to the original method. If the original method is static, this argument will be null.
  • arguments: An array of Objects containing the arguments passed to the original method. Primitive types (e.g. boolean) will be wrapped into their corresponding wrapper type (e.g. Boolean).
  • hookId: A random int identifying the particular call site.This can be used to derive additional coverage information.
  • returnValue: An Object containing the return value of the invocation of the original method. Primitive types (e.g. boolean) will be wrapped into their corresponding wrapper type (e.g. Boolean). If the original method has return type void, this value will be null.

    Multiple HookType.BEFORE and HookType.AFTER hooks are allowed to reference the same target method. Exclusively one HookType.REPLACE hook may reference a target method, no other types allowed. Attention must be paid to not guide the Fuzzer in different directions via Jazzer's guideTowardsXY methods in the different hooks.

  • Element Details

    • type

      HookType type
      The time at which the annotated method should be called.

      If this is HookType.BEFORE, the annotated method will be called before the target method and has access to its arguments.

      If this is HookType.REPLACE, the annotated method will be called instead of the target method. It has access to its arguments and can return a value that will replace the target method's return value.

      If this is HookType.AFTER, the annotated method will be called after the target method and has access to its arguments and return value.

      Returns:
      when the hook should be called

    • targetClassName

      String targetClassName
      The name of the class that contains the method that should be hooked, as returned by Class.getName().

      If an interface or abstract class is specified, also calls to all implementations and subclasses available on the classpath during startup are hooked, respectively. Interfaces and subclasses are not taken into account for concrete classes.

      Examples:

      Returns:
      the name of the class containing the method to be hooked

    • targetMethod

      String targetMethod
      The name of the method to be hooked. Use "<init>" for constructors.

      Examples:

      Returns:
      the name of the method to be hooked

    • targetMethodDescriptor

      String targetMethodDescriptor
      The descriptor of the method to be hooked. This is only needed if there are multiple methods with the same name and not all of them should be hooked.

      The descriptor of a method is an internal representation of the method's signature, which includes the types of its parameters and its return value. For more information on descriptors, see the JVM Specification, Section 4.3.3 and MethodType.toMethodDescriptorString()

      Returns:
      the descriptor of the method to be hooked
      Default:
      ""

    • additionalClassesToHook

      String[] additionalClassesToHook
      Array of additional classes to hook.

      Hooks are applied on call sites. This means that classes calling the one defined in this annotation need to be instrumented to actually execute the hook. This property can be used to hook normally ignored classes.

      Returns:
      fully qualified class names to hook
      Default:
      {}