feat(file): add allowed_path_traversal_elements to file_path (upstream PR #2397)

Ports upstream PR #2397: file_path() gains an optional
allowed_path_traversal_elements sequence, whose segments (e.g. '.', '..')
may be randomly picked as directory components, to generate test cases for
directory traversal detection.

Fixes applied on top of the upstream patch:
- rewrote paths faker/ -> faker2/ for the renamed package
- resolved conflict in faker2/providers/file/__init__.py: the fork renamed
  the local variable 'seperator' -> 'separator'
- tests/providers/test_file.py: the last assertion's regex only matched
  depth=2 while the call requests depth=3; it now expects four
  '\\[\w.]+' segments (3 directories + the file name)
- tests/providers/test_file.py: removed trailing whitespace (flake8 W293)
  and reformatted the call for black --line-length 120

Author: jqueguiner

faker2/providers/file/__init__.py

@@ -275,6 +275,7 @@ def file_path(
         extension: Optional[Union[str, Sequence[str]]] = None,
         absolute: Optional[bool] = True,
         file_system_rule: Literal["linux", "windows"] = "linux",
+        allowed_path_traversal_elements: Optional[Sequence[str]] = None,
     ) -> str:
         """Generate an pathname to a file.
 
@@ -295,6 +296,11 @@ def file_path(
         if ``file_system`` is set (default="linux"), the generated path uses
         specified file system path standard, the list of valid file systems include:
         ``'windows'``, ``'linux'``.
+        If ``allowed_path_traversal_elements`` is set, it should be a sequence
+        of path-traversal segments (e.g. ``['.', '..']``) that may be randomly
+        included as directory components. This is useful for generating test
+        cases for directory traversal attack detection. Default is ``None``,
+        meaning no traversal elements are included.
 
         :sample: size=10
         :sample: depth=3
@@ -304,6 +310,7 @@ def file_path(
         :sample: extension=''
         :sample: extension=["a", "bc", "def"]
         :sample: depth=5, category='video', extension='abcdef', file_system='windows'
+        :sample: depth=3, allowed_path_traversal_elements=['.', '..']
         """
 
         if extension is not None and not isinstance(extension, str):
@@ -321,7 +328,11 @@ def file_path(
 
         path: str = self.file_name(category, extension)
         for _ in range(0, depth):
-            path = f"{self.generator.word()}{separator}{path}"
+            if allowed_path_traversal_elements:
+                segment = self.random_element(list(allowed_path_traversal_elements) + [self.generator.word()])
+            else:
+                segment = self.generator.word()
+            path = f"{segment}{separator}{path}"
 
         return root + path if absolute else path
 

tests/providers/test_file.py

@@ -51,6 +51,18 @@ def test_file_path(self):
             file_path = self.fake.file_path(file_system_rule="windows", category="image", absolute=True)
             assert re.search(r"^[a-zA-Z]:\\\w+\\\w+\.\w+", file_path)
             assert re.search(r"\\\w+\\\w+\.(bmp|gif|jpeg|jpg|png|tiff)$", file_path)
+            file_path = self.fake.file_path(depth=3, allowed_path_traversal_elements=[".", ".."])
+            assert re.search(r"\/[\w.]+\/[\w.]+\/[\w.]+\.\w+", file_path)
+            assert file_path.startswith("/")
+            file_path = self.fake.file_path(depth=3, allowed_path_traversal_elements=None)
+            assert re.search(r"\/\w+\/\w+\/\w+\.\w+", file_path)
+            file_path = self.fake.file_path(depth=3, allowed_path_traversal_elements=[".."])
+            assert re.search(r"\/[\w.]+\/[\w.]+\/[\w.]+\.\w+", file_path)
+            assert file_path.startswith("/")
+            file_path = self.fake.file_path(
+                depth=3, file_system_rule="windows", allowed_path_traversal_elements=[".", ".."]
+            )
+            assert re.search(r"^[a-zA-Z]:\\[\w.]+\\[\w.]+\\[\w.]+\\[\w.]+\.\w+", file_path)
 
     def test_unix_device(self):
         reg_device = re.compile(r"^/dev/(vd|sd|xvd)[a-z]$")