Class Jazzer


  • public final class Jazzer
    extends java.lang.Object
    Helper class with static methods that interact with Jazzer at runtime.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int SEED
      A 32-bit random number that hooks can use to make pseudo-random choices between multiple possible mutations they could guide the fuzzer towards.
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <T1> void autofuzz​(FuzzedDataProvider data, Consumer1<T1> func)
      Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath.
      static <T1,​T2>
      void
      autofuzz​(FuzzedDataProvider data, Consumer2<T1,​T2> func)
      Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath.
      static <T1,​T2,​T3>
      void
      autofuzz​(FuzzedDataProvider data, Consumer3<T1,​T2,​T3> func)
      Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath.
      static <T1,​T2,​T3,​T4>
      void
      autofuzz​(FuzzedDataProvider data, Consumer4<T1,​T2,​T3,​T4> func)
      Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath.
      static <T1,​T2,​T3,​T4,​T5>
      void
      autofuzz​(FuzzedDataProvider data, Consumer5<T1,​T2,​T3,​T4,​T5> func)
      Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath.
      static <T1,​R>
      R
      autofuzz​(FuzzedDataProvider data, Function1<T1,​R> func)
      Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath.
      static <T1,​T2,​R>
      R
      autofuzz​(FuzzedDataProvider data, Function2<T1,​T2,​R> func)
      Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath.
      static <T1,​T2,​T3,​R>
      R
      autofuzz​(FuzzedDataProvider data, Function3<T1,​T2,​T3,​R> func)
      Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath.
      static <T1,​T2,​T3,​T4,​R>
      R
      autofuzz​(FuzzedDataProvider data, Function4<T1,​T2,​T3,​T4,​R> func)
      Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath.
      static <T1,​T2,​T3,​T4,​T5,​R>
      R
      autofuzz​(FuzzedDataProvider data, Function5<T1,​T2,​T3,​T4,​T5,​R> func)
      Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath.
      static <T> T consume​(FuzzedDataProvider data, java.lang.Class<T> type)
      Attempts to construct an instance of type from the fuzzer input using only public methods available on the classpath.
      static void exploreState​(byte state, int id)
      Instructs the fuzzer to attain as many possible values for the absolute value of state as possible.
      static void guideTowardsContainment​(java.lang.String haystack, java.lang.String needle, int id)
      Instructs the fuzzer to guide its mutations towards making haystack contain needle as a substring.
      static void guideTowardsEquality​(byte[] current, byte[] target, int id)
      Instructs the fuzzer to guide its mutations towards making current equal to target.
      static void guideTowardsEquality​(java.lang.String current, java.lang.String target, int id)
      Instructs the fuzzer to guide its mutations towards making current equal to target.
      static void reportFindingFromHook​(java.lang.Throwable finding)
      Make Jazzer report the provided Throwable as a finding.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • SEED

        public static final int SEED
        A 32-bit random number that hooks can use to make pseudo-random choices between multiple possible mutations they could guide the fuzzer towards. Hooks must not base the decision whether or not to report a finding on this number as this will make findings non-reproducible. This is the same number that libFuzzer uses as a seed internally, which makes it possible to deterministically reproduce a previous fuzzing run by supplying the seed value printed by libFuzzer as the value of the -seed.
    • Method Detail

      • autofuzz

        public static <T1,​R> R autofuzz​(FuzzedDataProvider data,
                                              Function1<T1,​R> func)
        Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath. Note: This function is inherently heuristic and may fail to execute func in meaningful ways for a number of reasons.
        Parameters:
        data - the FuzzedDataProvider instance provided to fuzzerTestOneInput.
        func - a method reference for the function to autofuzz. If there are multiple overloads, resolve ambiguities by explicitly casting to Function1 with (partially) specified type variables, e.g. (Function1<String, ?>) String::new.
        Returns:
        the return value of func, or null if autofuzz failed to invoke the function.
        Throws:
        java.lang.Throwable - any Throwable thrown by func, or an AutofuzzConstructionException if autofuzz failed to construct the arguments for the call. The Throwable is thrown unchecked.
      • autofuzz

        public static <T1,​T2,​R> R autofuzz​(FuzzedDataProvider data,
                                                       Function2<T1,​T2,​R> func)
        Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath. Note: This function is inherently heuristic and may fail to execute func in meaningful ways for a number of reasons.
        Parameters:
        data - the FuzzedDataProvider instance provided to fuzzerTestOneInput.
        func - a method reference for the function to autofuzz. If there are multiple overloads, resolve ambiguities by explicitly casting to Function2 with (partially) specified type variables.
        Returns:
        the return value of func, or null if autofuzz failed to invoke the function.
        Throws:
        java.lang.Throwable - any Throwable thrown by func, or an AutofuzzConstructionException if autofuzz failed to construct the arguments for the call. The Throwable is thrown unchecked.
      • autofuzz

        public static <T1,​T2,​T3,​R> R autofuzz​(FuzzedDataProvider data,
                                                                Function3<T1,​T2,​T3,​R> func)
        Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath. Note: This function is inherently heuristic and may fail to execute func in meaningful ways for a number of reasons.
        Parameters:
        data - the FuzzedDataProvider instance provided to fuzzerTestOneInput.
        func - a method reference for the function to autofuzz. If there are multiple overloads, resolve ambiguities by explicitly casting to Function3 with (partially) specified type variables.
        Returns:
        the return value of func, or null if autofuzz failed to invoke the function.
        Throws:
        java.lang.Throwable - any Throwable thrown by func, or an AutofuzzConstructionException if autofuzz failed to construct the arguments for the call. The Throwable is thrown unchecked.
      • autofuzz

        public static <T1,​T2,​T3,​T4,​R> R autofuzz​(FuzzedDataProvider data,
                                                                         Function4<T1,​T2,​T3,​T4,​R> func)
        Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath. Note: This function is inherently heuristic and may fail to execute func in meaningful ways for a number of reasons.
        Parameters:
        data - the FuzzedDataProvider instance provided to fuzzerTestOneInput.
        func - a method reference for the function to autofuzz. If there are multiple overloads, resolve ambiguities by explicitly casting to Function4 with (partially) specified type variables.
        Returns:
        the return value of func, or null if autofuzz failed to invoke the function.
        Throws:
        java.lang.Throwable - any Throwable thrown by func, or an AutofuzzConstructionException if autofuzz failed to construct the arguments for the call. The Throwable is thrown unchecked.
      • autofuzz

        public static <T1,​T2,​T3,​T4,​T5,​R> R autofuzz​(FuzzedDataProvider data,
                                                                                  Function5<T1,​T2,​T3,​T4,​T5,​R> func)
        Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath. Note: This function is inherently heuristic and may fail to execute func in meaningful ways for a number of reasons.
        Parameters:
        data - the FuzzedDataProvider instance provided to fuzzerTestOneInput.
        func - a method reference for the function to autofuzz. If there are multiple overloads, resolve ambiguities by explicitly casting to Function5 with (partially) specified type variables.
        Returns:
        the return value of func, or null if autofuzz failed to invoke the function.
        Throws:
        java.lang.Throwable - any Throwable thrown by func, or an AutofuzzConstructionException if autofuzz failed to construct the arguments for the call. The Throwable is thrown unchecked.
      • autofuzz

        public static <T1> void autofuzz​(FuzzedDataProvider data,
                                         Consumer1<T1> func)
        Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath. Note: This function is inherently heuristic and may fail to execute func in meaningful ways for a number of reasons.
        Parameters:
        data - the FuzzedDataProvider instance provided to fuzzerTestOneInput.
        func - a method reference for the function to autofuzz. If there are multiple overloads, resolve ambiguities by explicitly casting to Consumer1 with explicitly specified type variable.
        Throws:
        java.lang.Throwable - any Throwable thrown by func, or an AutofuzzConstructionException if autofuzz failed to construct the arguments for the call. The Throwable is thrown unchecked.
      • autofuzz

        public static <T1,​T2> void autofuzz​(FuzzedDataProvider data,
                                                  Consumer2<T1,​T2> func)
        Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath. Note: This function is inherently heuristic and may fail to execute func in meaningful ways for a number of reasons.
        Parameters:
        data - the FuzzedDataProvider instance provided to fuzzerTestOneInput.
        func - a method reference for the function to autofuzz. If there are multiple overloads, resolve ambiguities by explicitly casting to Consumer2 with (partially) specified type variables.
        Throws:
        java.lang.Throwable - any Throwable thrown by func, or an AutofuzzConstructionException if autofuzz failed to construct the arguments for the call. The Throwable is thrown unchecked.
      • autofuzz

        public static <T1,​T2,​T3> void autofuzz​(FuzzedDataProvider data,
                                                           Consumer3<T1,​T2,​T3> func)
        Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath. Note: This function is inherently heuristic and may fail to execute func in meaningful ways for a number of reasons.
        Parameters:
        data - the FuzzedDataProvider instance provided to fuzzerTestOneInput.
        func - a method reference for the function to autofuzz. If there are multiple overloads, resolve ambiguities by explicitly casting to Consumer3 with (partially) specified type variables.
        Throws:
        java.lang.Throwable - any Throwable thrown by func, or an AutofuzzConstructionException if autofuzz failed to construct the arguments for the call. The Throwable is thrown unchecked.
      • autofuzz

        public static <T1,​T2,​T3,​T4> void autofuzz​(FuzzedDataProvider data,
                                                                    Consumer4<T1,​T2,​T3,​T4> func)
        Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath. Note: This function is inherently heuristic and may fail to execute func in meaningful ways for a number of reasons.
        Parameters:
        data - the FuzzedDataProvider instance provided to fuzzerTestOneInput.
        func - a method reference for the function to autofuzz. If there are multiple overloads, resolve ambiguities by explicitly casting to Consumer4 with (partially) specified type variables.
        Throws:
        java.lang.Throwable - any Throwable thrown by func, or an AutofuzzConstructionException if autofuzz failed to construct the arguments for the call. The Throwable is thrown unchecked.
      • autofuzz

        public static <T1,​T2,​T3,​T4,​T5> void autofuzz​(FuzzedDataProvider data,
                                                                             Consumer5<T1,​T2,​T3,​T4,​T5> func)
        Attempts to invoke func with arguments created automatically from the fuzzer input using only public methods available on the classpath. Note: This function is inherently heuristic and may fail to execute func in meaningful ways for a number of reasons.
        Parameters:
        data - the FuzzedDataProvider instance provided to fuzzerTestOneInput.
        func - a method reference for the function to autofuzz. If there are multiple overloads, resolve ambiguities by explicitly casting to Consumer5 with (partially) specified type variables.
        Throws:
        java.lang.Throwable - any Throwable thrown by func, or an AutofuzzConstructionException if autofuzz failed to construct the arguments for the call. The Throwable is thrown unchecked.
      • consume

        public static <T> T consume​(FuzzedDataProvider data,
                                    java.lang.Class<T> type)
        Attempts to construct an instance of type from the fuzzer input using only public methods available on the classpath. Note: This function is inherently heuristic and may fail to return meaningful values for a variety of reasons.
        Parameters:
        data - the FuzzedDataProvider instance provided to fuzzerTestOneInput.
        type - the Class to construct an instance of.
        Returns:
        an instance of type constructed from the fuzzer input, or null if autofuzz failed to create an instance.
      • guideTowardsEquality

        public static void guideTowardsEquality​(java.lang.String current,
                                                java.lang.String target,
                                                int id)
        Instructs the fuzzer to guide its mutations towards making current equal to target. If the relation between the raw fuzzer input and the value of current is relatively complex, running the fuzzer with the argument -use_value_profile=1 may be necessary to achieve equality.
        Parameters:
        current - a non-constant string observed during fuzz target execution
        target - a string that current should become equal to, but currently isn't
        id - a (probabilistically) unique identifier for this particular compare hint
      • guideTowardsEquality

        public static void guideTowardsEquality​(byte[] current,
                                                byte[] target,
                                                int id)
        Instructs the fuzzer to guide its mutations towards making current equal to target. If the relation between the raw fuzzer input and the value of current is relatively complex, running the fuzzer with the argument -use_value_profile=1 may be necessary to achieve equality.
        Parameters:
        current - a non-constant byte array observed during fuzz target execution
        target - a byte array that current should become equal to, but currently isn't
        id - a (probabilistically) unique identifier for this particular compare hint
      • guideTowardsContainment

        public static void guideTowardsContainment​(java.lang.String haystack,
                                                   java.lang.String needle,
                                                   int id)
        Instructs the fuzzer to guide its mutations towards making haystack contain needle as a substring. If the relation between the raw fuzzer input and the value of haystack is relatively complex, running the fuzzer with the argument -use_value_profile=1 may be necessary to satisfy the substring check.
        Parameters:
        haystack - a non-constant string observed during fuzz target execution
        needle - a string that should be contained in haystack as a substring, but currently isn't
        id - a (probabilistically) unique identifier for this particular compare hint
      • exploreState

        public static void exploreState​(byte state,
                                        int id)
        Instructs the fuzzer to attain as many possible values for the absolute value of state as possible. Call this function from a fuzz target or a hook to help the fuzzer track partial progress (e.g. by passing the length of a common prefix of two lists that should become equal) or explore different values of state that is not directly related to code coverage (see the MazeFuzzer example). Note: This hint only takes effect if the fuzzer is run with the argument -use_value_profile=1.
        Parameters:
        state - a numeric encoding of a state that should be varied by the fuzzer
        id - a (probabilistically) unique identifier for this particular state hint
      • reportFindingFromHook

        public static void reportFindingFromHook​(java.lang.Throwable finding)
        Make Jazzer report the provided Throwable as a finding. Note: This method must only be called from a method hook. In a fuzz target, simply throw an exception to trigger a finding.
        Parameters:
        finding - the finding that Jazzer should report