Package com.atlassian.bamboo.file

Class SafeFileOperationFactory<T>

java.lang.Object
com.atlassian.bamboo.file.SafeFileOperationFactory<T>
Type Parameters:
T - the type of file operation to create, e.g. File or Path
Direct Known Subclasses:
SafeFileFactory, SafePathFactory
public abstract class SafeFileOperationFactory<T> extends Object
Factory for creating "file operations" with validation against path traversal vulnerabilities. "File operation" is an object of any type that offers file-related operations, such as creating a file, reading a file, etc. It ensures that the file paths used in these operations are safe and within a secure directory.

This class is designed to be extended for specific file operations, see SafeFileFactory and SafePathFactory.

Since:
12.0.0

  • Constructor Details

    • SafeFileOperationFactory

      public SafeFileOperationFactory()

  • Method Details

    • withSecureDirectory

      public SafeFileOperationFactory<T> withSecureDirectory(@NotNull @NotNull String secureDirectory)
      Sets the secure directory path where the file is expected to be accessed.

      If the path used to create the file operation is not within this secure directory, create() will throw an IllegalArgumentException.

      Parameters:
      secureDirectory - the secure directory path where the file is expected to be accessed

    • withSecureDirectory

      public SafeFileOperationFactory<T> withSecureDirectory(File secureDirectory)
      Sets the secure directory path where the file is expected to be accessed.

      If the path used to create the file operation is not within this secure directory, create() will throw an IllegalArgumentException.

      Parameters:
      secureDirectory - the secure directory where the file is expected to be accessed

    • withSecureDirectory

      public SafeFileOperationFactory<T> withSecureDirectory(Path secureDirectory)
      Sets the secure directory path where the file is expected to be accessed.

      If the path used to create the file operation is not within this secure directory, create() will throw an IllegalArgumentException.

      Parameters:
      secureDirectory - the secure directory where the file is expected to be accessed

    • create

      public final T create()
      Creates a file operation in a secure directory validating the path against path traversal vulnerabilities. withSecureDirectory(String) has to be called before!
      Returns:
      a file operation instance that is created in the secure directory
      Throws:
      IllegalArgumentException - when the path contains path traversal constructs or is outside the secure directory

    • createWithoutValidation

      public final T createWithoutValidation(@NotNull @NotNull SafeFileOperationFactory.NoValidationReason reason)
      Creates a file operation without validating the path.

      It's forbidden to use this method if it's possible that a path to the file or directory we want to operate on can contain user input

      Parameters:
      reason - the reason for skipping validation, e.g. if the path is hard-coded or immutable
      Returns:
      a file operation instance that is created without the validation

    • toPath

      protected abstract String toPath()
      Returns the path to the file. This should be the file to which the file operator give the access. e.g. for java.io.File it would be java.io.File#getPath()
      Returns:
      the path as a string

    • get

      protected abstract T get()