DEV Community: Harshit Sharma

Repository hooks to inspect before trusting a GitHub project

Harshit Sharma — Sun, 18 Oct 2026 03:59:03 +0000

Opening a folder, installing dependencies, attaching a coding agent, or launching a devcontainer can activate configuration-defined commands. Here is a short checklist for finding the known entry points before you decide what to trust.

Start with the scope, not a security score

Repository configuration can describe what a development tool may run later. Seeing a command in a file is not proof that it executed, that the author is malicious, or that the project is compromised. Triggers depend on individual package-manager, editor, trust and agent settings.

Review an unfamiliar checkout from a separate trusted terminal before installing its packages, opening it as a trusted editor workspace, or starting a coding agent. Even cloning is not a sandbox: your local Git configuration and environment may affect Git operations.

1. Package-manager lifecycle scripts

Look in package.json, especially the scripts keys preinstall, install, postinstall, prepare and prepack. Some package-manager operations can invoke these automatically. A normal lifecycle command is not inherently suspicious; check the script and the programs it calls.

{
  "scripts": {
    "postinstall": "node scripts/verify-setup.js"
  }
}

This is an inert illustration. Do not execute it to inspect it. ClonePeek models these npm surfaces and follows one statically identifiable hop into literal local .sh references, but it does not analyze arbitrary JavaScript imports or recursive script execution.

2. VS Code automatic folder-open tasks

Inspect .vscode/tasks.json for tasks that declare runOptions.runOn: folderOpen. Whether a task runs when the folder is opened depends on workspace trust and automatic-task settings. Read the command, task arguments and referenced files before accepting the workspace.

{
  "version": "2.0.0",
  "tasks": [{
    "label": "Example setup task",
    "type": "shell",
    "command": "echo review-me",
    "runOptions": {"runOn": "folderOpen"}
  }]
}

The echo value is deliberately harmless; this snippet exists to demonstrate the configuration shape, not to perform a setup.

3. Devcontainer lifecycle

Review .devcontainer/devcontainer.json for initializeCommand, onCreateCommand, postCreateCommand, postStartCommand and postAttachCommand. Those correspond to different phases of creating, starting and attaching to a development environment. Devcontainer features can also introduce build-time setup. An isolated container is not a blanket guarantee of safety when it has mounts, credentials or network access.

4. Claude Code command hooks

Look at project files such as .claude/settings.json and .claude/settings.local.json. Command hooks can be attached to events such as SessionStart or PostToolUse. Activation depends on the agent and its configuration. Treat instructions, tools and automatic commands from a new project as untrusted until reviewed.

5. Cursor workspace and agent hooks

Look for .cursor/hooks.json, including event definitions such as workspaceOpen and afterFileEdit. Read what will be invoked, when, and by which process. A passive review tool should never trigger the hook merely to discover its output.

6. Local MCP process launch configuration

Review the local MCP configuration your agent or editor may consume, particularly each mcpServers entry with a command, args, environment variables and filesystem references. These are process-launch instructions, not necessarily running servers. They may take effect only when the client enables or approves them.

Run a passive review in a trusted terminal

I maintain ClonePeek, a small MIT-licensed Python CLI and GitHub Action for enumerating the modeled entry points above. The scan reads bounded configuration files and does not run the target repository's scripts. Downloading/installing the scanner itself uses a network connection; the scan itself operates offline.

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

For an inert demonstration, use the bundled agent-hooks fixture. Review the trigger , source path and line , example evidence , and suggested review advice for each finding. None of the example commands needs to run.

You can also start with this non-blocking PR workflow:

name: Review execution hooks
on: [pull_request]
permissions:
  contents: read
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: harshitethic/clonepeek@v0.5.1
        with:
          path: .
          fail-on: none

The Action integration guide explains thresholds, baselines, JSON/SARIF and changed-file mode.

What a clean result does not mean

No scanner can promise a safe repository. ClonePeek deliberately omits dynamic references, many language/build execution paths and other unsupported tools.
Severity means review urgency. Common, benign setup tasks can still receive high heuristic severity, while obfuscated or unsupported paths can be missed.
Baseline does not equal approval. A finding marked known is still an execution-capable surface; it merely matched your stored fingerprint.
Scan reports can contain sensitive content. Redaction is best effort. Review and sanitize source excerpts before posting an artifact or CI comment publicly.
Git operations deserve a boundary review too. ClonePeek's Git fsmonitor case study documents a prior bug where a passive-looking diff invoked a configured helper. This was fixed with regression tests; it is not a sandbox guarantee.

Help improve the checklist

Have a harmless repository hook that is missing or misclassified? A tiny inert reproduction and clear expected trigger help more than generic praise. The public threat model lists blind spots, and the labeled synthetic evaluation is explicitly not independent real-world accuracy evidence.

Contribute an inert field test ↗ Get the stable release ↗ Explore ClonePeek ↗

Disclosure: I maintain ClonePeek. This DEV cross-post was prepared with AI assistance from my original, publicly available technical guide and is not an independent endorsement. See the repository threat model for the exact scan boundaries.

My read-only Python scanner accidentally ran a Git helper

Harshit Sharma — Sat, 17 Oct 2026 04:21:42 +0000

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.