Skip to content

Commit 8439407

Browse files
codexByron
authored andcommitted
docs(security): inherit Git's threat model explicitly
<!-- agent --> `SECURITY.md` described supported versions and vulnerability reporting without defining which repository inputs are trusted. This left the distinction between untrusted repository content and locally supplied administration data unclear. Document that both GitPython backends inherit Git's threat model directly. Summarize the trust placed in local configuration and hooks, the limits of ownership checks and filesystem confinement, and Git's guidance for obtaining a clean copy of an untrusted repository. Link to Git's documentation on GitHub and keep violations of its intended security boundaries reportable, including bugs that also affect Git. Checked the summary against the local Git reference at `6de20f6092dcf9bdb1c8efe03db4b70c82b423dd`. `git diff --check` passes. No runtime tests were run because this change only updates documentation. Assisted-by: GPT 6.0 Astra Co-authored-by: GPT 6.0 Astra <codex@openai.com>
1 parent caa039f commit 8439407

1 file changed

Lines changed: 31 additions & 0 deletions

File tree

‎SECURITY.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,37 @@ Only the latest version of GitPython can receive security updates. If a vulnerab
99
| 3.x.x | :white_check_mark: |
1010
| < 3.0 | :x: |
1111

12+
## Threat Model
13+
14+
GitPython inherits its threat model directly from Git. The trust boundaries in
15+
[Git's security documentation](https://github.com/git/git/blob/master/Documentation/git.adoc#security)
16+
apply to both the CLI and Gix backends:
17+
18+
- **Repository content may be untrusted.** Cloning an untrusted repository and
19+
inspecting its history are supported operations. A clone creates local
20+
repository metadata without copying the source repository's configuration or
21+
hooks. Tracked files, including `.gitmodules`, remain untrusted input.
22+
- **Local repository metadata must be trusted.** Running commands in an
23+
attacker-supplied `.git` directory, bare repository, or surrounding worktree is
24+
unsafe: configuration and hooks can execute commands. This includes repositories
25+
received in archives or copied directories. Owning the extracted files or listing
26+
a repository in `safe.directory` does not make its contents trustworthy.
27+
- **Repository paths are not a sandbox.** Git supports metadata and working trees
28+
in [separate locations](https://github.com/git/git/blob/master/Documentation/git-clone.adoc),
29+
including metadata reached through gitfiles or symlinks.
30+
GitPython does not promise that all filesystem access stays within a checkout
31+
or `.git` directory. Paths supplied by untrusted repository content must still
32+
receive Git's intended protections.
33+
34+
For an untrusted repository directory, Git recommends obtaining a clean copy with
35+
`git clone --no-local` before running other commands. Serving the source through
36+
`git-upload-pack` still has an attack surface; Git recommends using an
37+
unprivileged user for additional isolation. See
38+
[Git's `git-upload-pack` security guidance](https://github.com/git/git/blob/master/Documentation/git-upload-pack.adoc#security).
39+
40+
Violations of these trust boundaries or bypasses of Git's intended protections
41+
remain reportable, including cases where Git itself is affected.
42+
1243
## Reporting a Vulnerability
1344

1445
Please report private portions of a vulnerability to <https://github.com/gitpython-developers/GitPython/security/advisories/new>. Doing so helps to receive updates and collaborate on the matter, without disclosing it publicly right away.

0 commit comments

Comments
 (0)