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;
 
 /**
@@ -36,17 +37,19 @@
  *
  * <p>The default target is "../jazzer-traversal"."
  *
- * <p>Users may customize a customize the target by the BugDetectors API, e.g. by {@code
+ * <p>Users may customize the target using the BugDetectors API, e.g. by {@code
  * BugDetectors.setFilePathTraversalTarget(() -> Path.of("..", "jazzer-traversal"))}.
  *
- * <p>This does not currently check for reading metadata from the target file.
+ * <p>TODO: This sanitizer does not currently check for reading metadata from the target file.
  */
 public class FilePathTraversal {
   public static final Path DEFAULT_TARGET = Paths.get("..", "jazzer-traversal");
 
   // 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,23 +296,54 @@ 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);
-      } else {
         Jazzer.guideTowardsContainment(query, absTarget.toString(), hookId);
+      } else {
+        Jazzer.guideTowardsContainment(query, relTarget.toString(), hookId);
       }
       if (--toggleCounter <= 0) {
         guideTowardsAbsoluteTargetPath = !guideTowardsAbsoluteTargetPath;
         toggleCounter = ThreadLocalRandom.current().nextInt(1, MAX_TARGET_FOCUS_COUNT + 1);
       }
-    } else
+    } else {
       Jazzer.guideTowardsContainment(
           query, (absTarget != null ? absTarget : 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,14 @@ 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>By default, the file path traversal target is set to return {@code "../jazzer-traversal"}.
    *
-   * <p>Setting the target to {@code () -> null } will disable file path traversal sanitization.
+   * <p>Setting the path traversal target supplier to return {@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 +115,36 @@ 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 {