feat: @valuepool - propagate user values to types

This adds a new user-facing annotation @valuepool for wiring values
directly to type mutators.

ValuePoolMutatorFactory is prepended before (almost) every mutator.

Author: oetr

selffuzz/src/test/java/com/code_intelligence/selffuzz/mutation/ArgumentsMutatorFuzzTest.java

@@ -50,9 +50,9 @@ public class ArgumentsMutatorFuzzTest {
   static List<ArgumentsMutator> mutators =
       methods.stream()
           .map(
-              m ->
-                  ArgumentsMutator.forMethod(Mutators.newFactory(), m)
-                      .orElseThrow(() -> new IllegalArgumentException("Invalid method: " + m)))
+              method ->
+                  ArgumentsMutator.forMethod(Mutators.newFactory(), method)
+                      .orElseThrow(() -> new IllegalArgumentException("Invalid method: " + method)))
           .collect(Collectors.toList());
 
   static {

src/main/java/com/code_intelligence/jazzer/junit/BUILD.bazel

@@ -38,6 +38,7 @@ java_library(
         "//examples/junit/src/test/java/com/example:__pkg__",
         "//selffuzz/src/test/java/com/code_intelligence/selffuzz:__subpackages__",
         "//src/test/java/com/code_intelligence/jazzer/junit:__pkg__",
+        "//src/test/java/com/code_intelligence/jazzer/mutation/support:__pkg__",
     ],
     exports = [
         ":lifecycle",

src/main/java/com/code_intelligence/jazzer/mutation/ArgumentsMutator.java

@@ -23,6 +23,7 @@
 import static java.util.Arrays.stream;
 import static java.util.stream.Collectors.joining;
 
+import com.code_intelligence.jazzer.mutation.annotation.ValuePool;
 import com.code_intelligence.jazzer.mutation.api.ExtendedMutatorFactory;
 import com.code_intelligence.jazzer.mutation.api.PseudoRandom;
 import com.code_intelligence.jazzer.mutation.api.SerializingMutator;
@@ -31,6 +32,8 @@
 import com.code_intelligence.jazzer.mutation.engine.SeededPseudoRandom;
 import com.code_intelligence.jazzer.mutation.mutator.Mutators;
 import com.code_intelligence.jazzer.mutation.support.Preconditions;
+import com.code_intelligence.jazzer.mutation.support.TypeSupport;
+import com.code_intelligence.jazzer.mutation.support.ValuePoolRegistry;
 import com.code_intelligence.jazzer.utils.Log;
 import java.io.ByteArrayInputStream;
 import java.io.IOException;
@@ -75,15 +78,15 @@ private static String prettyPrintMethod(Method method) {
   }
 
   public static ArgumentsMutator forMethodOrThrow(Method method) {
-    return forMethod(Mutators.newFactory(), method)
+    return forMethod(Mutators.newFactory(new ValuePoolRegistry(method)), method)
         .orElseThrow(
             () ->
                 new IllegalArgumentException(
                     "Failed to construct mutator for " + prettyPrintMethod(method)));
   }
 
   public static Optional<ArgumentsMutator> forMethod(Method method) {
-    return forMethod(Mutators.newFactory(), method);
+    return forMethod(Mutators.newFactory(new ValuePoolRegistry(method)), method);
   }
 
   public static Optional<ArgumentsMutator> forMethod(
@@ -97,11 +100,20 @@ public static Optional<ArgumentsMutator> forMethod(
       Log.error(validationError.getMessage());
       throw validationError;
     }
+
+    ValuePool[] valuePools = method.getAnnotationsByType(ValuePool.class);
+
     return toArrayOrEmpty(
             stream(method.getAnnotatedParameterTypes())
                 .map(
                     type -> {
-                      Optional<SerializingMutator<?>> mutator = mutatorFactory.tryCreate(type);
+                      // Forward all @ValuePool annotations of the fuzz test method to each
+                      // arg.
+                      AnnotatedType t = type;
+                      for (ValuePool dict : valuePools) {
+                        t = TypeSupport.withExtraAnnotations(t, dict);
+                      }
+                      Optional<SerializingMutator<?>> mutator = mutatorFactory.tryCreate(t);
                       if (!mutator.isPresent()) {
                         Log.error(
                             String.format(

src/main/java/com/code_intelligence/jazzer/mutation/BUILD.bazel

@@ -12,6 +12,7 @@ java_library(
         "//src/main/java/com/code_intelligence/jazzer/mutation/engine",
         "//src/main/java/com/code_intelligence/jazzer/mutation/mutator",
         "//src/main/java/com/code_intelligence/jazzer/mutation/support",
+        "//src/main/java/com/code_intelligence/jazzer/mutation/utils",
         "//src/main/java/com/code_intelligence/jazzer/utils:log",
     ],
 )

src/main/java/com/code_intelligence/jazzer/mutation/annotation/ValuePool.java

@@ -0,0 +1,94 @@
+/*
+ * Copyright 2024 Code Intelligence GmbH
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.code_intelligence.jazzer.mutation.annotation;
+
+import static com.code_intelligence.jazzer.mutation.utils.PropertyConstraint.RECURSIVE;
+import static java.lang.annotation.ElementType.TYPE_USE;
+import static java.lang.annotation.RetentionPolicy.RUNTIME;
+
+import com.code_intelligence.jazzer.mutation.utils.IgnoreRecursiveConflicts;
+import com.code_intelligence.jazzer.mutation.utils.PropertyConstraint;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.Target;
+
+/**
+ * Provides values to user-selected mutator types to start fuzzing from. Currently supported
+ * mutators are:
+ *
+ * <ul>
+ *   <li>String mutator
+ *   <li>Integral mutators (byte, short, int, long)
+ * </ul>
+ *
+ * <p>This annotation can be applied to fuzz test methods and any parameter type or subtype. By
+ * default, this annotation is propagated to all nested subtypes unless specified otherwise via the
+ * {@link #constraint()} attribute.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * public class MyFuzzTargets {
+ *
+ *   static Stream<?> valluesVisibleByAllArgumentMutators() {
+ *     return Stream.of("example1", "example2", "example3", 1232187321, -182371);
+ *   }
+ *
+ *   static Stream<?> valuesVisibleOnlyByAnotherInput() {
+ *     return Stream.of("code-intelligence.com", "secret.url.1082h3u21ibsdsazuvbsa.com");
+ *   }
+ *
+ *   @ValuePool("valuesVisibleByAllArgumentMutators")
+ *   @FuzzTest
+ *   public void fuzzerTestOneInput(String input, @ValuePool("valuesVisibleOnlyByAnotherInput") String anotherInput) {
+ *     // Fuzzing logic here
+ *   }
+ * }
+ * }</pre>
+ *
+ * In this example, the mutator for the String parameter {@code input} of the fuzz test method
+ * {@code fuzzerTestOneInput} will be using the values returned by {@code provide} method during
+ * mutation, while the mutator for String {@code anotherInput} will use values from both methods:
+ * from the method-level {@code ValuePool} annotation that uses {@code provide} and the
+ * parameter-level {@code ValuePool} annotation that uses {@code provideSomethingElse}.
+ */
+@Target({ElementType.METHOD, TYPE_USE})
+@Retention(RUNTIME)
+@IgnoreRecursiveConflicts
+@PropertyConstraint
+public @interface ValuePool {
+  /**
+   * Specifies supplier methods that generate values for fuzzing the annotated method or type. The
+   * specified supplier methods must be static and return a {@code Stream <?>} of values. The values
+   * don't need to match the type of the annotated method or parameter exactly. The mutation
+   * framework will extract only the values that are compatible with the target type.
+   */
+  String[] value() default {""};
+
+  /**
+   * This {@code ValuePool} will be used with probability {@code 1/p} by the mutator responsible for
+   * fitting types. Not all mutators respect this probability.
+   */
+  double p() default 0.1;
+
+  /**
+   * Defines the scope of the annotation. Possible values are defined in {@link
+   * com.code_intelligence.jazzer.mutation.utils.PropertyConstraint}. By default it's {@code
+   * RECURSIVE}.
+   */
+  String constraint() default RECURSIVE;
+}

src/main/java/com/code_intelligence/jazzer/mutation/mutator/Mutators.java

@@ -27,18 +27,23 @@
 import com.code_intelligence.jazzer.mutation.mutator.libfuzzer.LibFuzzerMutators;
 import com.code_intelligence.jazzer.mutation.mutator.proto.ProtoMutators;
 import com.code_intelligence.jazzer.mutation.mutator.time.TimeMutators;
+import com.code_intelligence.jazzer.mutation.support.ValuePoolRegistry;
 import java.util.stream.Stream;
 
 public final class Mutators {
   private Mutators() {}
 
   public static ExtendedMutatorFactory newFactory() {
+    return newFactory(null);
+  }
+
+  public static ExtendedMutatorFactory newFactory(ValuePoolRegistry valuePoolRegistry) {
     return ChainedMutatorFactory.of(
         new IdentityCache(),
         NonNullableMutators.newFactories(),
-        LangMutators.newFactories(),
+        LangMutators.newFactories(valuePoolRegistry),
         CollectionMutators.newFactories(),
-        ProtoMutators.newFactories(),
+        ProtoMutators.newFactories(valuePoolRegistry),
         LibFuzzerMutators.newFactories(),
         TimeMutators.newFactories(),
         // Keep generic aggregate mutators last in case a concrete type is also an aggregate type.

src/main/java/com/code_intelligence/jazzer/mutation/mutator/lang/LangMutators.java

@@ -17,15 +17,21 @@
 package com.code_intelligence.jazzer.mutation.mutator.lang;
 
 import com.code_intelligence.jazzer.mutation.api.MutatorFactory;
+import com.code_intelligence.jazzer.mutation.support.ValuePoolRegistry;
 import java.util.stream.Stream;
 
 public final class LangMutators {
   private LangMutators() {}
 
   public static Stream<MutatorFactory> newFactories() {
+    return newFactories(null);
+  }
+
+  public static Stream<MutatorFactory> newFactories(ValuePoolRegistry valuePoolRegistry) {
     return Stream.of(
         // DON'T EVER SORT THESE! The order is important for the mutator engine to work correctly.
         new NullableMutatorFactory(),
+        new ValuePoolMutatorFactory(valuePoolRegistry),
         new BooleanMutatorFactory(),
         new FloatingPointMutatorFactory(),
         new IntegralMutatorFactory(),

src/main/java/com/code_intelligence/jazzer/mutation/mutator/lang/StringMutatorFactory.java

@@ -17,7 +17,9 @@
 package com.code_intelligence.jazzer.mutation.mutator.lang;
 
 import static com.code_intelligence.jazzer.mutation.combinator.MutatorCombinators.mutateThenMapToImmutable;
-import static com.code_intelligence.jazzer.mutation.support.TypeSupport.*;
+import static com.code_intelligence.jazzer.mutation.support.TypeSupport.findFirstParentIfClass;
+import static com.code_intelligence.jazzer.mutation.support.TypeSupport.notNull;
+import static com.code_intelligence.jazzer.mutation.support.TypeSupport.withLength;
 
 import com.code_intelligence.jazzer.mutation.annotation.Ascii;
 import com.code_intelligence.jazzer.mutation.annotation.UrlSegment;