Block unsafe checkout-index and tag file options

GHSA-3f7w-8rr8-f37f reports that caller-controlled options forwarded by IndexFile.checkout() and TagReference.create() can make Git write to or read from arbitrary filesystem paths.

Add regression coverage proving the unsafe options are rejected by default while preserving the explicit allow_unsafe_options escape hatch. Reuse GitPython's existing option candidate normalization and unsafe-option guard at both public API boundaries.

Git baseline: a23bace963d508bd96983cc637131392d3face18. Documentation/git-checkout-index.adoc defines --prefix as prepending an output path, and Documentation/git-tag.adoc defines -F/--file as reading a tag message from a file.

Validation:
- uv run --with-editable .[test] pytest -q (focused security tests: 3 passed)
- uv run --with-editable .[test] pytest -q test/test_index.py test/test_refs.py (56 passed, 2 unrelated fixture failures due to absent master branch)
- uvx ruff check (touched files)
- uvx ruff format --check (touched files)
- git diff --check

Author: codex

git/index/base.py

@@ -130,6 +130,8 @@ class IndexFile(LazyMixin, git_diff.Diffable, Serializable):
     index directly before operating on it using the git command.
     """
 
+    unsafe_git_checkout_index_options = ["--prefix"]
+
     __slots__ = ("repo", "version", "entries", "_extension_data", "_file_path")
 
     _VERSION = 2
@@ -1212,6 +1214,7 @@ def checkout(
         paths: Union[None, Iterable[PathLike]] = None,
         force: bool = False,
         fprogress: Callable = lambda *args: None,
+        allow_unsafe_options: bool = False,
         **kwargs: Any,
     ) -> Union[None, Iterator[PathLike], Sequence[PathLike]]:
         """Check out the given paths or all files from the version known to the index
@@ -1238,6 +1241,9 @@ def checkout(
             no explicit paths are given. Otherwise progress information will be send
             prior and after a file has been checked out.
 
+        :param allow_unsafe_options:
+            Allow unsafe options, such as ``--prefix``.
+
         :param kwargs:
             Additional arguments to be passed to :manpage:`git-checkout-index(1)`.
 
@@ -1261,6 +1267,12 @@ def checkout(
             i.e. if you want :manpage:`git-checkout(1)`-like behaviour, use
             ``head.checkout`` instead of ``index.checkout``.
         """
+        if not allow_unsafe_options:
+            Git.check_unsafe_options(
+                options=Git._option_candidates([], kwargs),
+                unsafe_options=self.unsafe_git_checkout_index_options,
+            )
+
         args = ["--index"]
         if force:
             args.append("--force")

git/refs/tag.py

@@ -16,6 +16,7 @@
 
 from typing import Any, TYPE_CHECKING, Type, Union
 
+from git.cmd import Git
 from git.types import AnyGitObject, PathLike
 
 if TYPE_CHECKING:
@@ -42,6 +43,8 @@ class TagReference(Reference):
 
     __slots__ = ()
 
+    unsafe_git_tag_options = ["--file", "-F"]
+
     _common_default = "tags"
     _common_path_default = Reference._common_path_default + "/" + _common_default
 
@@ -92,6 +95,7 @@ def create(
         reference: Union[str, "SymbolicReference"] = "HEAD",
         logmsg: Union[str, None] = None,
         force: bool = False,
+        allow_unsafe_options: bool = False,
         **kwargs: Any,
     ) -> "TagReference":
         """Create a new tag reference.
@@ -121,12 +125,21 @@ def create(
         :param force:
             If ``True``, force creation of a tag even though that tag already exists.
 
+        :param allow_unsafe_options:
+            Allow unsafe options, such as ``--file``.
+
         :param kwargs:
             Additional keyword arguments to be passed to :manpage:`git-tag(1)`.
 
         :return:
             A new :class:`TagReference`.
         """
+        if not allow_unsafe_options:
+            Git.check_unsafe_options(
+                options=Git._option_candidates([], kwargs),
+                unsafe_options=cls.unsafe_git_tag_options,
+            )
+
         if "ref" in kwargs and kwargs["ref"]:
             reference = kwargs["ref"]
 

test/test_index.py

@@ -31,6 +31,7 @@
     HookExecutionError,
     InvalidGitRepositoryError,
     UnmergedEntriesError,
+    UnsafeOptionError,
 )
 from git.index.fun import hook_path, run_commit_hook
 from git.index.typ import BaseIndexEntry, IndexEntry
@@ -202,6 +203,15 @@ def _make_hook(git_dir, name, content, make_exec=True):
 
 @ddt.ddt
 class TestIndex(TestBase):
+    @with_rw_repo("HEAD")
+    def test_checkout_rejects_unsafe_prefix(self, rw_repo):
+        with tempfile.TemporaryDirectory() as target:
+            with self.assertRaises(UnsafeOptionError):
+                rw_repo.index.checkout(prefix=f"{target}/")
+
+            rw_repo.index.checkout(prefix=f"{target}/", allow_unsafe_options=True)
+            self.assertTrue(osp.isfile(osp.join(target, "CHANGES")))
+
     def __init__(self, *args):
         super().__init__(*args)
         self._reset_progress()

test/test_refs.py

@@ -23,6 +23,7 @@
     SymbolicReference,
     TagReference,
 )
+from git.exc import UnsafeOptionError
 from git.objects.tag import TagObject
 import git.refs as refs
 from git.util import Actor
@@ -60,6 +61,18 @@ def test_from_path(self):
         # Check remoteness
         assert Reference(self.rorepo, "refs/remotes/origin").is_remote()
 
+    @with_rw_repo("HEAD")
+    def test_tag_create_rejects_unsafe_file_options(self, rw_repo):
+        with tempfile.NamedTemporaryFile("w", encoding="utf-8") as message:
+            message.write("private tag message")
+            message.flush()
+            for index, option in enumerate(({"F": message.name}, {"file": message.name})):
+                with self.assertRaises(UnsafeOptionError):
+                    TagReference.create(rw_repo, f"unsafe-{index}", **option)
+
+            tag = TagReference.create(rw_repo, "allowed-file", F=message.name, allow_unsafe_options=True)
+            self.assertEqual(tag.tag.message, "private tag message")
+
     def test_from_pathlike(self):
         # Should be able to create any reference directly.
         for ref_type in (Reference, Head, TagReference, RemoteReference):