feat: add @ValuePool to propagate values to types #975

oetr · 2025-10-10T16:26:34Z

This allows the users provide values directly to types by annotating them with @ValuePool.
All types, other than those that need cached-based mutators, are supported.

  public static Stream<?> myPool() {
    return Stream.of(
        "0123456789abcdef".repeat(50),
        "sitting duck suprime".repeat(53),
        123);
  }

  @FuzzTest
  @ValuePool("myPool")
  public static void fuzzerTestOneInput(
      @NotNull @WithUtf8Length(max = 10000) String data,
      @NotNull @WithUtf8Length(max = 10000) String data2) {
    if (data.equals("0123456789abcdef".repeat(50))
        && data2.equals("sitting duck suprime".repeat(53))) {
      throw new FuzzerSecurityIssueLow("Found the long string!");
    }
  }

Copilot

Pull Request Overview

This PR adds dictionary provider support to the mutation framework, enabling users to provide custom dictionary values for fuzzing through the @DictionaryProvider annotation. The implementation:

Introduces MutatorRuntime class to provide runtime information (including the fuzz test method) to mutators
Adds @DictionaryProvider annotation that references static methods returning Stream<?> of dictionary values
Updates all MutatorFactory implementations to accept MutatorRuntime parameter
Implements dictionary support for String and integral mutators using weighted sampling
Adds SamplingUtils with Vose's alias method for efficient O(1) weighted sampling
Includes comprehensive tests for the new functionality

Reviewed Changes

Copilot reviewed 85 out of 85 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`DictionaryProvider.java`	New annotation for specifying dictionary provider methods with probability control
`MutatorRuntime.java`	New runtime info class providing fuzz test method to mutators
`DictionaryProviderSupport.java`	Helper methods to extract dictionary values from provider methods
`IgnoreRecursiveConflicts.java`	Meta-annotation to allow duplicate annotations during type hierarchy propagation
`SamplingUtils.java`	Weighted sampling utilities using Vose's alias method
`StringMutatorFactory.java`	Implements dictionary support for String mutators
`IntegralMutatorFactory.java`	Implements dictionary support for integral type mutators
`MutatorFactory.java`	Updated interface to accept `MutatorRuntime` parameter
`ArgumentsMutator.java`	Forwards method-level `@DictionaryProvider` annotations to parameters
`TestSupport.java`	Adds helper methods for creating dummy `MutatorRuntime` in tests
All other factory files	Updated to pass through `MutatorRuntime` parameter

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/main/java/com/code_intelligence/jazzer/mutation/utils/IgnoreRecursiveConflicts.java

tests/src/test/java/com/example/ValuePoolFuzzerLongString.java

tests/src/test/java/com/example/DictionaryProviderFuzzerLongString.java

...in/java/com/code_intelligence/jazzer/mutation/mutator/libfuzzer/LibFuzzerMutatorFactory.java

simonresch

Cool feature!

I'm not entirely sure that the ability to have different dictionaries per field warrants the added complexity & state in the MutatorRuntime. Is this an essential part of the custom dictionary in your opinion? Having a single @DictionaryProvider per fuzz test could simplify the mutator instantiation and maybe even make it simpler to use for users.
Otherwise my main concern would be the duplication with DictionaryEntry and similar annotations (see other comment).

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

src/main/java/com/code_intelligence/jazzer/mutation/support/DictionaryProviderSupport.java

src/main/java/com/code_intelligence/jazzer/mutation/support/ValuePoolSupport.java

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

src/main/java/com/code_intelligence/jazzer/mutation/support/TypeSupport.java

src/main/java/com/code_intelligence/jazzer/mutation/mutator/collection/ArrayMutatorFactory.java

simonresch · 2025-11-03T15:09:43Z

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

+import java.lang.annotation.Target;
+
+/**
+ * Provides dictionary values to user-selected mutator types. Currently supported mutators are:


I suspect that users might be confused on when to use the DictionaryProvider and when to use other dictionary annotations like DictionaryEntry, DictionaryFile.
"user-selected mutator types" might also not be descriptive enough and end with users annotating a myFuzzTest(byte[] data) fuzz test with @DictionaryProvider without realizing that the values are not used.

Would it make sense to add the @DictionaryProvider values in addition to the libFuzzer dictionary file? Otherwise I could foresee situations where one wants to specify the same dictionary entries with @DictionaryProvider and @DictionaryEntry.

Renamed to @ValuePool

Values are not really dictionary entries that libfuzzer limits to 64 bytes

I think, instead of pouring these values into a dictionary, we should always use the mutation framework even when the user only has fuzzTestMethod(byte[] data), so that ValuePool will always work in a consistent manner. WDYT? We can fix that in another PR after discussing it

src/main/java/com/code_intelligence/jazzer/mutation/support/ValuePoolSupport.java

In addition to primitive arrays, these types are now also supported: - List<Integer> [] - List<Integer> [][][]

Allow annotations to be inherited at multiple levels of the type hierarchy, enabling both broad and specific configuration of mutators. Use case: Configure mutators that share common types. For example, annotate a fuzz test method to apply default settings to all String mutators, while still allowing individual String parameters to override those settings with different values. Without this feature, an annotation could only appear once in the inheritance chain, preventing this layered configuration approach.

@valuepool

This adds a new user-facing annotation @valuepool for wiring values directly to type mutators. ValuePoolMutatorFactory is prepended before (almost) every mutator.

simonresch

Thanks for the changes! I really like the ValuePool name and the more centralized implementation. Really cool that it works for (almost) all mutators. Only have some minor comments regarding doc strings. Nice work!

simonresch · 2025-11-24T08:58:57Z

src/main/java/com/code_intelligence/jazzer/mutation/support/TypeSupport.java

+    if (type instanceof Class<?>) {
+      return Optional.of((Class<?>) type);
+    } else if (type instanceof ParameterizedType) {
+      return Optional.of((Class<?>) ((ParameterizedType) type).getRawType());


The raw type of a ParameterizedType does not have to be a Class<?>, no? Maybe something line return extractRawClass((ParameterizedType) type).getRawType()); would make sense?

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

simonresch · 2025-11-24T09:30:05Z

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

+ * }</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


Should this be {@code valluesVisibleByAllArgumentMutators}?

simonresch · 2025-11-24T09:30:51Z

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

+ * {@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}.


And here valuesVisibleOnlyByAnotherInput.

simonresch · 2025-11-24T09:49:30Z

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

+  String[] value();
+
+  /**
+   * This {@code ValuePool} will be used with probability {@code 1/p} by the mutator responsible for


Should this be {@code p} instead of 1/p?

simonresch · 2025-11-24T12:05:51Z

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

+            mutator.read(new DataInputStream(new ByteArrayInputStream(originalSerialized)));
+        mutator.write(roundTrip, new DataOutputStream(byteStream));
+        byte[] roundTripSerialized = byteStream.toByteArray();
+        return Arrays.equals(originalSerialized, roundTripSerialized);


For what mutator types do we need the roundtrip check? Wouldn't it be enough to check if the mutator.write(...) call does not throw, to filter out e.g. CachedConstructorMutators or values where the type does not match?

Ah, this will also make sure that the value pool values respect other annotations of the particular mutator, correct? Clever!
Minor: Could be worth a comment that lists what this serialization stable entails.

simonresch · 2025-11-24T15:10:58Z

src/main/java/com/code_intelligence/jazzer/mutation/support/ValuePoolRegistry.java

+  public double extractFirstProbability(AnnotatedType type) {
+    // If there are several @ValuePool annotations on the type, this will take the most
+    // immediate one, because @ValuePool is not repeatable.
+    ValuePool[] dictObj = type.getAnnotationsByType(ValuePool.class);


Minor: dictObj should probably be something like valuePoolAnnotations.

oetr force-pushed the CIF-1785-dictionary-provider branch 15 times, most recently from 958d54a to d164e3c Compare October 16, 2025 23:50

oetr force-pushed the CIF-1785-dictionary-provider branch 3 times, most recently from 5eac7ec to 5069fb3 Compare October 28, 2025 19:20

oetr changed the title ~~feat: dictionary provider for selected types~~ feat: dictionary provider for Strings and Integrals Oct 28, 2025

oetr marked this pull request as ready for review October 28, 2025 19:25

Copilot AI review requested due to automatic review settings October 28, 2025 19:25

Copilot AI reviewed Oct 28, 2025

View reviewed changes

oetr force-pushed the CIF-1785-dictionary-provider branch 5 times, most recently from 0044fb9 to 84707f2 Compare October 30, 2025 12:42

simonresch reviewed Nov 3, 2025

View reviewed changes

oetr force-pushed the CIF-1785-dictionary-provider branch from 84707f2 to c64c841 Compare November 19, 2025 12:17

oetr marked this pull request as draft November 19, 2025 12:17

oetr force-pushed the CIF-1785-dictionary-provider branch 5 times, most recently from 1ca7569 to b29031b Compare November 21, 2025 01:34

feat: allow creation of parameterized and generic array types

90e92bc

In addition to primitive arrays, these types are now also supported: - List<Integer> [] - List<Integer> [][][]

oetr changed the title ~~feat: dictionary provider for Strings and Integrals~~ feat: add @ValuePool to propagate values to types Nov 21, 2025

oetr force-pushed the CIF-1785-dictionary-provider branch from b29031b to ba90fe6 Compare November 21, 2025 11:10

feat: @valuepool - propagate user values to types

4cbb978

This adds a new user-facing annotation @valuepool for wiring values directly to type mutators. ValuePoolMutatorFactory is prepended before (almost) every mutator.

oetr force-pushed the CIF-1785-dictionary-provider branch 2 times, most recently from 7fc2b50 to 4cbb978 Compare November 21, 2025 13:17

oetr marked this pull request as ready for review November 21, 2025 13:53

simonresch approved these changes Nov 24, 2025

View reviewed changes

feat: add @ValuePool to propagate values to types #975

Are you sure you want to change the base?

feat: add @ValuePool to propagate values to types #975

Uh oh!

Conversation

oetr commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

simonresch left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

oetr Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

simonresch left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

oetr commented Oct 10, 2025 •

edited

Loading

oetr Nov 21, 2025 •

edited

Loading