feat: add user-defined allow-predicate to file path traversal sanitizer

Author: oetr

sanitizers/src/main/java/com/code_intelligence/jazzer/sanitizers/FilePathTraversal.java

@@ -27,6 +27,7 @@
 import java.util.Optional;
 import java.util.concurrent.ThreadLocalRandom;
 import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.Predicate;
 import java.util.function.Supplier;
 
 /**
@@ -47,6 +48,8 @@ public class FilePathTraversal {
   // Set via reflection by Jazzer's BugDetectors API.
   public static final AtomicReference<Supplier<Path>> target =
       new AtomicReference<>(() -> DEFAULT_TARGET);
+  public static final AtomicReference<Predicate<Path>> checkPath =
+      new AtomicReference<>((Path ignored) -> true);
 
   // When guiding the fuzzer towards the target path, sometimes both the absolute and relative paths
   // are valid. In this case, we toggle between them randomly.
@@ -271,20 +274,8 @@ private static void detectAndGuidePathTraversal(Object obj, int hookId) {
     if (obj == null) {
       return;
     }
-    Path targetPath = target.get().get();
-
-    // Users can set the atomic function to return null to disable the sanitizer.
-    if (targetPath == null) {
-      return;
-    }
-    targetPath = targetPath.normalize();
 
-    Path currentDir = Paths.get("").toAbsolutePath();
-    Path absTarget = toAbsolutePath(targetPath, currentDir).orElse(null);
-    Path relTarget = toRelativePath(targetPath, currentDir).orElse(null);
-    if (absTarget == null && relTarget == null) {
-      return;
-    }
+    Path targetPath = target.get().get();
 
     String query;
     if (obj instanceof Path) {
@@ -305,11 +296,41 @@ private static void detectAndGuidePathTraversal(Object obj, int hookId) {
       return;
     }
 
+    Predicate<Path> checkAllowed = checkPath.get();
+    boolean isPathAllowed = checkAllowed == null || checkAllowed.test(Paths.get(query).normalize());
+    if (!isPathAllowed) {
+      Jazzer.reportFindingFromHook(
+            new FuzzerSecurityIssueCritical(
+                  "File path traversal: "
+                        + query
+                        + "\n   Path is not allowed by the user-defined predicate."
+                        + "\n   Current path traversal fuzzing target: "
+                        + targetPath));
+    }
+
+    // Users can set the atomic function to return null to disable the fuzzer guidance.
+    if (targetPath == null) {
+      return;
+    }
+    targetPath = targetPath.normalize();
+
+    Path currentDir = Paths.get("").toAbsolutePath();
+    Path absTarget = toAbsolutePath(targetPath, currentDir).orElse(null);
+    Path relTarget = toRelativePath(targetPath, currentDir).orElse(null);
+    if (absTarget == null && relTarget == null) {
+      return;
+    }
+
     if ((absTarget != null && absTarget.toString().equals(query))
         || (relTarget != null && relTarget.toString().equals(query))) {
       Jazzer.reportFindingFromHook(
-          new FuzzerSecurityIssueCritical("File path traversal: " + query));
+          new FuzzerSecurityIssueCritical(
+              "File path traversal: "
+                  + query
+                  + "\n   Reached current path traversal fuzzing target: "
+                  + targetPath));
     }
+
     if (absTarget != null && relTarget != null) {
       if (guideTowardsAbsoluteTargetPath) {
         Jazzer.guideTowardsContainment(query, relTarget.toString(), hookId);

src/main/java/com/code_intelligence/jazzer/api/BugDetectors.java

@@ -19,6 +19,7 @@
 import java.nio.file.Path;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.BiPredicate;
+import java.util.function.Predicate;
 import java.util.function.Supplier;
 
 /** Provides static functions that configure the behavior of bug detectors provided by Jazzer. */
@@ -88,11 +89,13 @@ public static SilentCloseable allowNetworkConnections(
       getSanitizerVariable("com.code_intelligence.jazzer.sanitizers.FilePathTraversal", "target");
 
   /**
-   * Sets the target for file path traversal sanitization.
+   * Sets the target for file path traversal sanitization. If the target is reached, a finding is
+   * thrown. The target is also used to guide the fuzzer to intentionally trigger file path
+   * traversal.
    *
    * <p>By default, the file path traversal target is set to {@code "../jazzer-traversal"}.
    *
-   * <p>Setting the target to {@code () -> null } will disable file path traversal sanitization.
+   * <p>Setting the target path to {@code null } will disable the guidance.
    *
    * <p>By wrapping the call into a try-with-resources statement, the target can be configured to
    * apply to individual parts of the fuzz test only:
@@ -111,6 +114,37 @@ public static SilentCloseable setFilePathTraversalTarget(Supplier<Path> pathTrav
     return setSanitizerVariable(pathTraversalTarget, currentPathTraversalTarget);
   }
 
+  private static final AtomicReference<Predicate<Path>> currentCheckPath =
+      getSanitizerVariable(
+          "com.code_intelligence.jazzer.sanitizers.FilePathTraversal", "checkPath");
+
+  /**
+   * Sets the predicate that determines if a file path is allowed to be accessed. Paths that
+   * are not allowed will trigger a file path traversal finding. If you use this method, don't
+   * forget to set the fuzzing target with {@code setFilePathTraversalTarget} that aligns with this
+   * predicate, because both {@code target} and {@code checkPath} can trigger a finding
+   * independently.
+   *
+   * <p>By default, all file paths are allowed. Setting the predicate to {@code false} will trigger
+   * a file path traversal finding for any file path access.
+   *
+   * <p>By wrapping the call into a try-with-resources statement, the predicate can be configured to
+   * apply to individual parts of the fuzz test only:
+   *
+   * <pre>{@code
+   * try (SilentCloseable unused = BugDetectors.setFilePathTraversalAllowPath(
+   *     (Path p) -> p.toString().contains("secret"))) {
+   *   // Perform operations that require file path traversal sanitization
+   * }
+   * }</pre>
+   *
+   * @param checkPath a predicate that evaluates to {@code true} if the file path is allowed
+   * @return a {@link SilentCloseable} that restores the previously set predicate when closed
+   */
+  public static SilentCloseable setFilePathTraversalAllowPath(Predicate<Path> checkPath) {
+    return setSanitizerVariable(checkPath, currentCheckPath);
+  }
+
   private static <T> AtomicReference<T> getSanitizerVariable(
       String sanitizerClassName, String fieldName) {
     try {