Package com.code_intelligence.jazzer.api

Class Jazzer

java.lang.Object
com.code_intelligence.jazzer.api.Jazzer
public final class Jazzer extends Object
Static helper methods that hooks can use to provide feedback to the fuzzer.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_NUM_COUNTERS
    Default number of counters allocated for each call site of a method that requires registering a range of artificial coverage counters, e.g., Jazzer maximize API.
    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.

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    exploreState(byte state)
    Convenience overload of exploreState(byte, int) that allows using automatically generated call-site identifiers.
    static void
    exploreState(byte state, int id)
    Instructs the fuzzer to attain as many possible values for state as possible.
    static void
    guideTowardsContainment(String haystack, 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(String current, String target, int id)
    Instructs the fuzzer to guide its mutations towards making current equal to target.
    static void
    maximize(long value, long minValue, long maxValue)
    Convenience overload of maximize(long, long, long, int, int) that uses DEFAULT_NUM_COUNTERS counters and an automatically generated call-site id.
    static void
    maximize(long value, long minValue, long maxValue, int numCounters)
    Convenience overload of maximize(long, long, long, int, int) that uses a custom number of counters and an automatically generated call-site id.
    static void
    maximize(long value, long minValue, long maxValue, int numCounters, int id)
    Core implementation of the hill-climbing maximize API.
    static void
    minimize(long value, long minValue, long maxValue)
    Convenience overload of minimize(long, long, long, int, int) that uses DEFAULT_NUM_COUNTERS counters and an automatically generated call-site id.
    static void
    minimize(long value, long minValue, long maxValue, int numCounters)
    Convenience overload of minimize(long, long, long, int, int) that uses a custom number of counters and an automatically generated call-site id.
    static void
    minimize(long value, long minValue, long maxValue, int numCounters, int id)
    Core implementation of the hill-climbing minimize API.
    static void
    onFuzzTargetReady(Runnable callback)
    Register a callback to be executed right before the fuzz target is executed for the first time.
    static void
    reportFindingFromHook(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 Details

    • DEFAULT_NUM_COUNTERS

      public static final int DEFAULT_NUM_COUNTERS
      Default number of counters allocated for each call site of a method that requires registering a range of artificial coverage counters, e.g., Jazzer maximize API. The user's value range is linearly mapped onto this many counters.
      See Also:

    • 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 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 Details

    • guideTowardsEquality

      public static void guideTowardsEquality(String current, 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(String haystack, 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 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).

      Each unique state value is tracked via libFuzzer's counter bucketing mechanism, enabling us to represent 8 different states for each coverage counter. As a result, all 256 byte values are distinguished by mapping each to a unique (counter, bucket) pair across 32 counters. See: https://github.com/llvm/llvm-project/blob/972e73b812cb7b6dd349c7c07daae73314f29e8f/compiler-rt/lib/fuzzer/FuzzerTracePC.h#L213-L235

      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

    • exploreState

      public static void exploreState(byte state)
      Convenience overload of exploreState(byte, int) that allows using automatically generated call-site identifiers. During instrumentation, calls to this method are replaced with calls to exploreState(byte, int) using a unique id for each call site.

      Without instrumentation, this is a no-op.

      Parameters:
      state - a numeric encoding of a state that should be varied by the fuzzer
      See Also:

    • maximize

      public static void maximize(long value, long minValue, long maxValue, int numCounters, int id)
      Core implementation of the hill-climbing maximize API. It maps value from the range [minValue, maxValue] onto numCounters coverage counters via linear interpolation, then sets all counters from 0 to the mapped offset.

      Values below minValue produce no signal. Values above maxValue are clamped.

      Must be invoked with the same minValue, maxValue, and numCounters for a given id across all calls. Passing different values is illegal.

      Parameters:
      value - the value to maximize
      minValue - the minimum expected value (inclusive)
      maxValue - the maximum expected value (inclusive); must be >= minValue
      numCounters - the number of counters to allocate; must be > 0
      id - a unique identifier for this call site (must be consistent across runs)
      Throws:
      JazzerApiException - if maxValue < minValue or numCounters <= 0

    • maximize

      public static void maximize(long value, long minValue, long maxValue)
      Convenience overload of maximize(long, long, long, int, int) that uses DEFAULT_NUM_COUNTERS counters and an automatically generated call-site id.

      During instrumentation, calls to this method are replaced by a hook that supplies a unique id for each call site. Without instrumentation, this is a no-op. 

      
 // Maximize temperature in [0, 4500]
 Jazzer.maximize(temperature, 0, 4500);
      Parameters:
      value - the value to maximize
      minValue - the minimum expected value (inclusive)
      maxValue - the maximum expected value (inclusive)
      See Also:

    • maximize

      public static void maximize(long value, long minValue, long maxValue, int numCounters)
      Convenience overload of maximize(long, long, long, int, int) that uses a custom number of counters and an automatically generated call-site id.

      During instrumentation, calls to this method are replaced by a hook that supplies a unique id for each call site. Without instrumentation, this is a no-op.

      Parameters:
      value - the value to maximize
      minValue - the minimum expected value (inclusive)
      maxValue - the maximum expected value (inclusive)
      numCounters - the number of counters to allocate; must be > 0
      See Also:

    • minimize

      public static void minimize(long value, long minValue, long maxValue, int numCounters, int id)
      Core implementation of the hill-climbing minimize API. It maps value from the range [minValue, maxValue] onto numCounters coverage counters via inverse linear interpolation, then sets all counters from 0 to the mapped offset.

      Lower values produce more signal (more counters set), which causes the fuzzer to prefer inputs that result in lower values. Values above maxValue produce no signal. Values below minValue are clamped.

      Must be invoked with the same minValue, maxValue, and numCounters for a given id across all calls. Passing different values is illegal.

      Parameters:
      value - the value to minimize
      minValue - the minimum expected value (inclusive)
      maxValue - the maximum expected value (inclusive); must be >= minValue
      numCounters - the number of counters to allocate; must be > 0
      id - a unique identifier for this call site (must be consistent across runs)
      Throws:
      JazzerApiException - if maxValue < minValue or numCounters <= 0

    • minimize

      public static void minimize(long value, long minValue, long maxValue)
      Convenience overload of minimize(long, long, long, int, int) that uses DEFAULT_NUM_COUNTERS counters and an automatically generated call-site id.

      During instrumentation, calls to this method are replaced by a hook that supplies a unique id for each call site. Without instrumentation, this is a no-op. 

      
 // Minimize temperature in [0, 4000]
 Jazzer.minimize(temperature, 0, 4000);
      Parameters:
      value - the value to minimize
      minValue - the minimum expected value (inclusive)
      maxValue - the maximum expected value (inclusive)
      See Also:

    • minimize

      public static void minimize(long value, long minValue, long maxValue, int numCounters)
      Convenience overload of minimize(long, long, long, int, int) that uses a custom number of counters and an automatically generated call-site id.

      During instrumentation, calls to this method are replaced by a hook that supplies a unique id for each call site. Without instrumentation, this is a no-op.

      Parameters:
      value - the value to minimize
      minValue - the minimum expected value (inclusive)
      maxValue - the maximum expected value (inclusive)
      numCounters - the number of counters to allocate; must be > 0
      See Also:

    • reportFindingFromHook

      public static void reportFindingFromHook(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

    • onFuzzTargetReady

      public static void onFuzzTargetReady(Runnable callback)
      Register a callback to be executed right before the fuzz target is executed for the first time.

      This can be used to disable hooks until after Jazzer has been fully initializing, e.g. to prevent Jazzer internals from triggering hooks on Java standard library classes.

      Parameters:
      callback - the callback to execute