[RFC/PATCH] Suggestion: Safe Hook Verification for Unzipped/Local Repositories

[RFC/PATCH] Suggestion: Safe Hook Verification for Unzipped/Local Repositories

[Jamison Phillips]

Hello Git Community,

I would like to propose a defensive security enhancement regarding how
Git handles hooks in repositories initialized outside of standard 'git
clone' pathways (such as repositories downloaded and extracted via
ZIP/tarball archives).

---
THE PROBLEM:
When a user clones a repository, Git safely excludes the '.git/hooks'
directory. However, if a developer downloads a project as a ZIP
archive from an untrusted third party and extracts it, the archive can
contain a fully formed '.git/hooks' directory populated with
malicious, executable scripts.

The moment the developer runs a standard command like 'git checkout'
or 'git status' inside this unzipped folder, the hooks execute
immediately without user consent or awareness. This is an active
vector for supply-chain malware insertion on developer workstations.

---
PROPOSED FEATURE:
I suggest implementing a "Safe Hook Verification" mechanism with the
following logic:

1. First-Time Intercept: If Git detects executable scripts inside
'.git/hooks' on a repository that does not have an explicit local
clearance, it should halt execution and prompt the user: "Warning:
This repository contains local hooks that have not been approved. Run
them? (y/N)".

2. Out-of-Directory Verification State: If the user approves ('y'),
Git should log this approval by saving a unique cryptographic hash of
the approved hooks to a global state directory outside of the
repository's working tree (e.g., inside
~/.config/git/approved_hooks/).

3. Subsequent Runs: On future commands, Git will check the current
hooks against the global hash map. If they match, they run silently.
If a hook file is modified or a new repository is unzipped, the prompt
appears again.

---
IMPACT:
This would close a massive blind spot for developers interacting with
shared zipped codebases, enforcing a model of explicit consent before
third-party code is executed locally by the VCS.

I look forward to hearing your thoughts on the feasibility or
alternative architectures for this defense-in-depth feature.

Regards,
Jamison Phillips

Re: [RFC/PATCH] Suggestion: Safe Hook Verification for Unzipped/Local Repositories

[brian m. carlson]

[-- Attachment #1: Type: text/plain, Size: 3824 bytes --]

On 2026-06-13 at 21:20:43, Jamison Phillips wrote:
> Hello Git Community,

Hey,

> THE PROBLEM:
> When a user clones a repository, Git safely excludes the '.git/hooks'
> directory. However, if a developer downloads a project as a ZIP
> archive from an untrusted third party and extracts it, the archive can
> contain a fully formed '.git/hooks' directory populated with
> malicious, executable scripts.
> 
> The moment the developer runs a standard command like 'git checkout'
> or 'git status' inside this unzipped folder, the hooks execute
> immediately without user consent or awareness. This is an active
> vector for supply-chain malware insertion on developer workstations.

Git's security model does not allow working with untrusted working
trees, period.  The only things we guarantee are safe to do with an
untrusted repository are clone and fetch from it.

I'll also note that there are a variety of other methods that one can
use to execute arbitrary code with an untrusted working tree due to
unsafe configuration options.  For example, one can set
`filter.<driver>.clean` and `filter.<driver>.smudge` and execute
arbitrary code with a crafted repository.  This is why we don't let
people include config (or hooks) as part of the repository.

My concern is that we'd be misleading people that this was a safe way to
work by adopting your proposal when that is not true.  We would then be
deluged by a whole host of invalid security reports.

Would you like to maybe share a little bit about why you (or others) are
distributing repositories as ZIP files instead of using the standard
protocol methods?  Perhaps we can offer some thoughtful comments about
how to achieve the intended goals with a better security posture.

> PROPOSED FEATURE:
> I suggest implementing a "Safe Hook Verification" mechanism with the
> following logic:
> 
> 1. First-Time Intercept: If Git detects executable scripts inside
> '.git/hooks' on a repository that does not have an explicit local
> clearance, it should halt execution and prompt the user: "Warning:
> This repository contains local hooks that have not been approved. Run
> them? (y/N)".

How would this work in a non-interactive situation?  If I install Git
LFS, it installs hooks when its filter process is installed for the
first time.  So if I then clone a repository using Git LFS in a CI job
or a container build process, the hooks won't work and my repository may
end up broken.

Note that the Unix philosophy does not have tools prompt users by
default.  If I say `rm -fr ~`, then my home directory gets blown away
because that is what I asked for, even if that may have been improvident
and imprudent; no prompt is expected.

> 2. Out-of-Directory Verification State: If the user approves ('y'),
> Git should log this approval by saving a unique cryptographic hash of
> the approved hooks to a global state directory outside of the
> repository's working tree (e.g., inside
> ~/.config/git/approved_hooks/).

This is almost certainly going to grow indefinitely.  I've been copying
my entire home directory from machine to machine as I get a new one for
19 years and I fully imagine that this would have grown quite a bit in
that time.

Another thing I think is worth noting is that just because I think a
hook is safe in one context does not mean I think it's safe in another.
A post-checkout hook that runs a particular command (say, `bin/setup`)
from the repository might be safe on my dotfiles (which I exclusively
control and maintain), but an identical hook on a repository from Bob's
Malware Emporium would probably not be a good idea.  Reusing safe code
to do unsafe things has long been a favourite approach of attackers.
-- 
brian m. carlson (they/them)
Toronto, Ontario, CA

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 325 bytes --]