diff --git a/src/main/java/org/kiwiproject/validation/DirectoryPath.java b/src/main/java/org/kiwiproject/validation/DirectoryPath.java index 8b11c7be..bcf2ad02 100644 --- a/src/main/java/org/kiwiproject/validation/DirectoryPath.java +++ b/src/main/java/org/kiwiproject/validation/DirectoryPath.java @@ -15,7 +15,9 @@ import java.lang.annotation.Target; /** - * The annotated element must point to an existing directory. + * The annotated element must point to an existing directory. Please read the implementation note regarding + * intended usage of this annotation with respect to the potential for + * Path Traversal attacks. *

* By default does not permit null values. If the element being validated allows {@code null} values, you can * set {@link #allowNull()} to {@code true}. @@ -39,6 +41,12 @@ * {@literal @}DirectoryPath(ensureReadable = true, ensureWritable = true, mkdirs = true) * private String tempDir; * + * + * @implNote This annotation is not intended to validate user input from client-side applications, because of the + * possibility of Path Traversal attacks. Instead, + * the intended usage is to validate application configuration parameters, e.g. an application reads a local + * configuration file at startup. Even this is not 100% safe, since the configuration could come from a remote + * location such as a configuration service, so users should understand the usage risks and mitigate when possible. */ @Documented @Constraint(validatedBy = {DirectoryPathValidator.class}) diff --git a/src/main/java/org/kiwiproject/validation/DirectoryPathValidator.java b/src/main/java/org/kiwiproject/validation/DirectoryPathValidator.java index 99e28b8b..cc0ed556 100644 --- a/src/main/java/org/kiwiproject/validation/DirectoryPathValidator.java +++ b/src/main/java/org/kiwiproject/validation/DirectoryPathValidator.java @@ -18,6 +18,9 @@ *

* As mentioned in the documentation for {@link DirectoryPath}, this may also attempt to create the directory * if it does not already exist, which may be an unexpected side-effect. + * + * @implNote Please read the implementation note in {@link DirectoryPath} regarding the possibility of + * Path Traversal attacks. */ @Slf4j public class DirectoryPathValidator implements ConstraintValidator { diff --git a/src/main/java/org/kiwiproject/validation/FilePath.java b/src/main/java/org/kiwiproject/validation/FilePath.java index fe5130ae..dc3ff6f3 100644 --- a/src/main/java/org/kiwiproject/validation/FilePath.java +++ b/src/main/java/org/kiwiproject/validation/FilePath.java @@ -15,7 +15,9 @@ import java.lang.annotation.Target; /** - * The annotated element must point to an existing file. + * The annotated element must point to an existing file. Please read the implementation note regarding + * intended usage of this annotation with respect to the potential for + * Path Traversal attacks. *

* By default does not permit null values. If the element being validated allows {@code null} values, you can * set {@link #allowNull()} to {@code true}. @@ -29,6 +31,12 @@ * {@literal @}FilePath(allowNull = true) * public String getLocation() { return this.location; } * + * + * @implNote This annotation is not intended to validate user input from client-side applications, because of the + * possibility of Path Traversal attacks. Instead, + * the intended usage is to validate application configuration parameters, e.g. an application reads a local + * configuration file at startup. Even this is not 100% safe, since the configuration could come from a remote + * location such as a configuration service, so users should understand the usage risks and mitigate when possible. */ @Documented @Constraint(validatedBy = {FilePathValidator.class}) diff --git a/src/main/java/org/kiwiproject/validation/FilePathValidator.java b/src/main/java/org/kiwiproject/validation/FilePathValidator.java index ffa3b920..8ee3de4e 100644 --- a/src/main/java/org/kiwiproject/validation/FilePathValidator.java +++ b/src/main/java/org/kiwiproject/validation/FilePathValidator.java @@ -11,6 +11,9 @@ /** * Validates that a string value is a valid path, exists, and is a regular file (not a directory). + * + * @implNote Please read the implementation note in {@link FilePath} regarding the possibility of + * Path Traversal attacks. */ @Slf4j public class FilePathValidator implements ConstraintValidator {