Guard pathspec file inputs in high-level commands

GHSA-hh9p-6wh2-4mfc reports that high-level rm and checkout wrappers
forwarded pathspec file options without GitPython's unsafe-option policy.
A regression showed that both commands surfaced multi-line pathspec data in
Git errors, while reset consumed the same caller-selected file without a
validation error. The audit also found that reset's positional commit could
carry the option before its argument separator.

Define one shared unsafe pathspec-file option list and apply it to
IndexFile.remove, Head.checkout, and HEAD.reset before invoking Git. Check
reset's positional commit as well as keyword options, retain the standard
allow_unsafe_options escape hatch for trusted callers, and cover abbreviated
long-option spellings.

An audit against Git cf5497b14c5a24f10c13f7e0ee85cb95af13ea6a
(v2.55.0.windows.3-16-gcf5497b14c) found pathspec-file support in add,
checkout/restore, commit, reset, rm, and stash. GitPython has no arbitrary
high-level option forwarding to the other commands, and git mv does not
support this option.

Validated with focused rejection and opt-in tests, 214 affected-module
regressions, Ruff, basedpyright, and git diff --check.

Author: codex

git/cmd.py

@@ -654,6 +654,12 @@ class Git(metaclass=_GitMeta):
         "--upload-pack",
     ]
 
+    unsafe_git_pathspec_from_file_options = [
+        # Reads pathspecs from a caller-controlled file. Some commands include an
+        # unmatched pathspec in their error output, which can disclose the file.
+        "--pathspec-from-file",
+    ]
+
     def __getstate__(self) -> Dict[str, Any]:
         return slots_to_dict(self, exclude=self._excluded_)
 

git/index/base.py

@@ -1022,6 +1022,7 @@ def remove(
         self,
         items: Union[PathLike, Sequence[Union[PathLike, Blob, BaseIndexEntry, "Submodule"]]],
         working_tree: bool = False,
+        allow_unsafe_options: bool = False,
         **kwargs: Any,
     ) -> List[str]:
         R"""Remove the given items from the index and optionally from the working tree
@@ -1052,6 +1053,10 @@ def remove(
             physically removing the respective file. This may fail if there are
             uncommitted changes in it.
 
+        :param allow_unsafe_options:
+            Allow unsafe options such as ``--pathspec-from-file`` to be passed to
+            :manpage:`git-rm(1)`.
+
         :param kwargs:
             Additional keyword arguments to be passed to :manpage:`git-rm(1)`, such as
             ``r`` to allow recursive removal.
@@ -1063,6 +1068,11 @@ def remove(
             This is interesting to know in case you have provided a directory or globs.
             Paths are relative to the repository.
         """
+        if not allow_unsafe_options:
+            Git.check_unsafe_options(
+                options=Git._option_candidates([], kwargs),
+                unsafe_options=Git.unsafe_git_pathspec_from_file_options,
+            )
         args = []
         if not working_tree:
             args.append("--cached")

git/refs/head.py

@@ -19,6 +19,7 @@
 
 from typing import Any, Sequence, TYPE_CHECKING, Union
 
+from git.cmd import Git
 from git.types import Commit_ish, PathLike
 
 if TYPE_CHECKING:
@@ -62,6 +63,7 @@ def reset(
         index: bool = True,
         working_tree: bool = False,
         paths: Union[PathLike, Sequence[PathLike], None] = None,
+        allow_unsafe_options: bool = False,
         **kwargs: Any,
     ) -> "HEAD":
         """Reset our HEAD to the given commit optionally synchronizing the index and
@@ -84,12 +86,21 @@ def reset(
             Single path or list of paths relative to the git root directory
             that are to be reset. This allows to partially reset individual files.
 
+        :param allow_unsafe_options:
+            Allow unsafe options such as ``--pathspec-from-file`` to be passed to
+            :manpage:`git-reset(1)`.
+
         :param kwargs:
             Additional arguments passed to :manpage:`git-reset(1)`.
 
         :return:
             self
         """
+        if not allow_unsafe_options:
+            Git.check_unsafe_options(
+                options=Git._option_candidates([commit], kwargs),
+                unsafe_options=Git.unsafe_git_pathspec_from_file_options,
+            )
         mode: Union[str, None]
         mode = "--soft"
         if index:
@@ -234,7 +245,12 @@ def rename(self, new_path: PathLike, force: bool = False) -> "Head":
         self.path = "%s/%s" % (self._common_path_default, new_path)
         return self
 
-    def checkout(self, force: bool = False, **kwargs: Any) -> Union["HEAD", "Head"]:
+    def checkout(
+        self,
+        force: bool = False,
+        allow_unsafe_options: bool = False,
+        **kwargs: Any,
+    ) -> Union["HEAD", "Head"]:
         """Check out this head by setting the HEAD to this reference, by updating the
         index to reflect the tree we point to and by updating the working tree to
         reflect the latest index.
@@ -246,6 +262,10 @@ def checkout(self, force: bool = False, **kwargs: Any) -> Union["HEAD", "Head"]:
             If ``False``, :exc:`~git.exc.GitCommandError` will be raised in that
             situation.
 
+        :param allow_unsafe_options:
+            Allow unsafe options such as ``--pathspec-from-file`` to be passed to
+            :manpage:`git-checkout(1)`.
+
         :param kwargs:
             Additional keyword arguments to be passed to git checkout, e.g.
             ``b="new_branch"`` to create a new branch at the given spot.
@@ -261,6 +281,11 @@ def checkout(self, force: bool = False, **kwargs: Any) -> Union["HEAD", "Head"]:
             the HEAD detached which is allowed and possible, but remains a special state
             that some tools might not be able to handle.
         """
+        if not allow_unsafe_options:
+            Git.check_unsafe_options(
+                options=Git._option_candidates([], kwargs),
+                unsafe_options=Git.unsafe_git_pathspec_from_file_options,
+            )
         kwargs["f"] = force
         if kwargs["f"] is False:
             kwargs.pop("f")

test/test_git.py

@@ -215,6 +215,18 @@ def test_option_candidates_ignore_untransformed_kwargs(self):
 
         self.assertEqual(options, ["--max-count"])
 
+    def test_option_candidates_include_falsey_non_boolean_values(self):
+        kwargs = {"pathspec_from_file": 0}
+        candidates = Git._option_candidates(kwargs=kwargs)
+
+        self.assertEqual(candidates, ["--pathspec-from-file"])
+        self.assertEqual(self.git.transform_kwargs(**kwargs), ["--pathspec-from-file=0"])
+        with self.assertRaises(UnsafeOptionError):
+            Git.check_unsafe_options(
+                options=candidates,
+                unsafe_options=Git.unsafe_git_pathspec_from_file_options,
+            )
+
     def test_option_candidates_include_split_single_char_option_values(self):
         cases = [
             ({"n": "--upload-pack=helper"}, ["-n", "--upload-pack=helper"], ["--upload-pack"]),

test/test_index.py

@@ -212,6 +212,32 @@ def test_checkout_rejects_unsafe_prefix(self, rw_repo):
             rw_repo.index.checkout(prefix=f"{target}/", allow_unsafe_options=True)
             self.assertTrue(osp.isfile(osp.join(target, "CHANGES")))
 
+    @with_rw_repo("HEAD")
+    def test_remove_rejects_pathspec_from_file(self, rw_repo):
+        with tempfile.TemporaryDirectory() as tdir:
+            pathspecs = Path(tdir) / "pathspecs"
+            pathspecs.write_bytes(b"unmatched-path-one\nunmatched-path-two")
+            for option_name in ("pathspec_from_file", "pathspec_from"):
+                with self.assertRaises(UnsafeOptionError):
+                    rw_repo.index.remove(
+                        [],
+                        pathspec_file_nul=True,
+                        **{option_name: str(pathspecs)},
+                    )
+
+    @with_rw_repo("HEAD")
+    def test_remove_allows_explicit_pathspec_from_file(self, rw_repo):
+        with tempfile.TemporaryDirectory() as tdir:
+            pathspecs = Path(tdir) / "pathspecs"
+            pathspecs.write_bytes(b"CHANGES\0")
+            removed = rw_repo.index.remove(
+                [],
+                pathspec_from_file=str(pathspecs),
+                pathspec_file_nul=True,
+                allow_unsafe_options=True,
+            )
+            assert "CHANGES" in removed
+
     def __init__(self, *args):
         super().__init__(*args)
         self._reset_progress()

test/test_refs.py

@@ -262,6 +262,51 @@ def test_head_checkout_detached_head(self, rw_repo):
         assert isinstance(res, SymbolicReference)
         assert res.name == "HEAD"
 
+    @with_rw_repo("HEAD")
+    def test_head_checkout_rejects_pathspec_from_file(self, rw_repo):
+        with tempfile.TemporaryDirectory() as tdir:
+            pathspecs = Path(tdir) / "pathspecs"
+            pathspecs.write_bytes(b"unmatched-path-one\nunmatched-path-two")
+            for option_name in ("pathspec_from_file", "pathspec_from"):
+                with self.assertRaises(UnsafeOptionError):
+                    rw_repo.active_branch.checkout(
+                        pathspec_file_nul=True,
+                        **{option_name: str(pathspecs)},
+                    )
+
+    @with_rw_repo("HEAD")
+    def test_head_reset_rejects_pathspec_from_file(self, rw_repo):
+        with tempfile.TemporaryDirectory() as tdir:
+            pathspecs = Path(tdir) / "pathspecs"
+            pathspecs.write_bytes(b"unmatched-path-one\nunmatched-path-two")
+            for option_name in ("pathspec_from_file", "pathspec_from"):
+                with self.assertRaises(UnsafeOptionError):
+                    rw_repo.head.reset(
+                        pathspec_file_nul=True,
+                        **{option_name: str(pathspecs)},
+                    )
+            for option_name in ("--pathspec-from-file", "--pathspec-from"):
+                with self.assertRaises(UnsafeOptionError):
+                    rw_repo.head.reset(
+                        f"{option_name}={pathspecs}",
+                        pathspec_file_nul=True,
+                    )
+
+    @with_rw_repo("HEAD")
+    def test_head_commands_allow_explicit_pathspec_from_file(self, rw_repo):
+        with tempfile.TemporaryDirectory() as tdir:
+            pathspecs = Path(tdir) / "pathspecs"
+            pathspecs.write_bytes(b"CHANGES\0")
+            options = {
+                "pathspec_from_file": str(pathspecs),
+                "pathspec_file_nul": True,
+                "allow_unsafe_options": True,
+            }
+            head = rw_repo.head
+            branch = rw_repo.active_branch
+            assert head.reset(**options) is head
+            assert branch.checkout(**options) == branch
+
     @with_rw_repo("0.1.6")
     def test_head_reset(self, rw_repo):
         cur_head = rw_repo.head