My read-only Python scanner accidentally ran a Git helper

We were building a tool whose defining promise was simple: inspect unfamiliar repository configuration without executing its code. Then a test revealed that an ordinary-looking Git operation could launch a program defined by the repository itself.

A small assumption with big consequences

You're about to open a GitHub repository in your editor. You want to know which commands may run through package installation, trusted workspace tasks, devcontainer startup, MCP servers or an AI coding agent. A static auditor looks like a reasonable first line of review.

ClonePeek was designed for that job. Its scanner traverses recognized configuration files using bounded reads and reports trigger → command → source location → suggested review , without launching the project's npm scripts, shell hooks, or coding agents.

There is a useful optional flag: --changed-since filters findings to Git changes. Our first implementation called a local git diff command. It felt harmless. Diffing files isn't building the repository, right?

The catch is that Git's execution behavior can depend on checkout-local or inherited configuration, not just the arguments my code passes. In particular, a local core.fsmonitor setting can name a hook-like helper program. Depending on the command and Git version, Git may invoke that helper while refreshing file state. A subprocess invoked by the auditor was therefore enough to break our passive-scan invariant.

One important boundary: a normal git clone does not transfer the remote repo's .git/config. The issue is an existing checkout and its local configuration or inherited Git environment; don't confuse it with a malicious package.json remotely rewriting Git config simply by being cloned.

Making the regression observable

To test this safely, we created a disposable local fixture with a deliberately inert helper that merely wrote a marker file. We did not use a real suspicious repository, download an executable payload, or depend on a network request.

The test asked one specific question: can the audit complete without creating that marker? Before the fix, the marker appeared. After the fix, it did not. Reproducing the violation as a filesystem side effect made it much harder for later refactors to accidentally reintroduce it.

This is not a claim that every git diff invocation on every operating system will execute an fsmonitor helper. It's a concrete example of why "I only ran Git" doesn't establish that no repo-defined execution occurred.

The exact reproduction and safety constraints are in the Git configuration isolation notes; the patch and review trail are in PR #5.

The defense has to cover the helper process

Python's read-only filesystem operations were not the issue. The boundary changed when the scanner delegated work to Git, a separate executable capable of honoring configuration, helpers and extensions. Fixing it required controlling both process arguments and the environment.

# Excerpted structure, not a standalone security sandbox
argv = [
    "git",
    "-c", "core.fsmonitor=false",
    "-c", f"core.hooksPath={os.devnull}",
    "-c", "diff.external=",
    "-c", "protocol.ext.allow=never",
    "-c", "protocol.file.allow=never",
    "-C", str(repo_root),
    "diff", "--no-ext-diff", "--no-textconv",
    "--name-only", "-z", "--diff-filter=ACMR",
    reference, "--",
]

The scanner also strips inherited Git-specific variables and dangerous loader/Python environment overrides, disables system/global Git config for this invocation, rejects unexpected ref syntax, bounds subprocess runtime, and treats a failed diff as an error rather than silently reporting an empty result. These are defense-in-depth choices for an explicitly limited operation ; they are not equivalent to process isolation.

Important limit: This hardening is targeted to the Git invocation used by ClonePeek. Git and the host operating system have more behavior than one wrapper can model. Do not treat ClonePeek as a sandbox, a malware detector, or a reliable way to execute other tools against actively malicious content.

The next surprise was a script one file away

Another coverage gap turned out to be less dramatic but equally useful. A package.json file could contain a short lifecycle command such as sh ./scripts/setup.sh. A surface-only scanner recognized the install hook, but the interesting command might live inside scripts/setup.sh, outside the JSON.

We added bounded, first-hop, read-only inspection for statically identifiable local .sh references. It checks that paths stay inside the repository, rejects symlink escapes and unsafe file types, and limits references, file sizes and lines read. It doesn't shell-expand arbitrary expressions or chase unbounded nested scripts.

That sounds modest—and that's intentional. A scanner that executes the referenced script "to find out what it does" would solve one detection problem by discarding its own execution boundary. ClonePeek instead tells you what it can and can't see.

Testing a release from outside the repository

Internal tests can miss assumptions about packaging. The v0.5.0 GitHub Action therefore has separate integration CI on Linux, macOS and Windows, plus an actual consumer workflow in another repository. That consumer workflow read two pinned, public configuration snapshots (Cursor hooks and VS Code folder-open tasks), checked their Git blob hashes, and asserted paths and classifications. No upstream hooks were run.

These are narrow smoke tests, not independent outside-user adoption or an estimate of detection accuracy. The hand-authored synthetic evaluation deliberately includes false positives and false negatives; it is not representative of internet repositories.

A checklist for tools that inspect untrusted projects

• Map all execution paths, including your own helper commands. A safe-looking wrapper doesn't make delegated subprocesses inert.
• Write regression tests around side effects, not only output strings. A marker file can reveal unexpected execution even when the scanner report looks correct.
• Constrain filesystem reads and traversal. Symlinks, special files, large files and path escapes matter even when you never execute a script.
• Separate supported detection from safety claims. A command hook is a review prompt, not proof that an author is malicious.
• Make failure visible. Parse errors and unsupported references should not silently become "nothing found."

If you're auditing a repository you don't trust, the safest workflow begins before installing its dependencies or marking it trusted in an IDE. The five-minute pre-trust audit guide covers practical next steps.

Try it. Critique it. Improve it.

ClonePeek v0.5.1 is MIT licensed, has no runtime Python dependencies, and exposes its threat model publicly. We're looking for real, inert examples of execution hooks it misses or overclassifies—not drive-by stars or artificial PRs.

uvx --from git+https://github.com/harshitethic/clonepeek@v0.5.1 \
  clonepeek /path/to/repository

Browse source ↗ Contribute a real improvement ↗ Live demo ↗

Disclosure: I maintain ClonePeek. This case study was prepared with AI writing assistance and reviewed against the source, tests, and public docs. Maintainer-run tests are not independent security evaluation.