git-tag-guardian

Zero-dependency supply chain defense for Node.js and Bun projects.

Detects and blocks Git Tag Rewrite attacks, postinstall backdoors, SHA drift in lockfiles, tarball tampering, and unpinned GitHub Actions — before they compromise your CI/CD or production.

Built by CanisterWorm / TeamPCP as a practical countermeasure to real-world tag rewrite exploitation techniques.

The Problem

Git tags are mutable. Anyone with push access to a repository can silently repoint a tag to a completely different commit — including one from a fork that contains a backdoor. npm, GitHub Actions, and Dockerfiles that reference dependencies by tag will then pull the malicious code without any warning.

Attack chain:

1. Attacker forks your dependency
2. Adds malicious code in the fork (postinstall exfiltration, modified source, etc.)
3. Pushes to fork — commit lands in shared GitHub Object Store
4. Rewrites the tag in upstream: PATCH /git/refs/tags/v1.0.0 { sha: "malicious", force: true }
5. GitHub regenerates .tar.gz automatically
6. Next `npm install` pulls compromised code
7. postinstall runs silently — steals env vars, SSH keys, tokens

This tool detects every stage of that chain.

Install

# As a dev dependency
npm install --save-dev git-tag-guardian

# Or run directly
npx git-tag-guardian audit

No external dependencies. Works on Node.js >= 18 and Bun.

Quick Start

# 1. Full audit of current project
npx git-tag-guardian audit

# 2. Create a baseline (records current SHA hashes)
npx git-tag-guardian baseline

# 3. Install git hooks (pre-commit + post-merge)
npx git-tag-guardian hooks-install

# 4. Run in CI (exits 1 on critical/high findings)
npx git-tag-guardian audit --ci

5 Security Checks

1. SHA Pinning

Detects git dependencies in package.json that reference tags or branches instead of full 40-character SHA hashes. Tags can be rewritten; SHA hashes cannot.

[HIGH] Dependency "logger" references tag "v1.0.0" instead of SHA
       fix: Replace with full SHA commit hash

2. Postinstall Hook Detection

Scans every package in node_modules/ for lifecycle scripts (preinstall, install, postinstall, prepare, etc.) and analyzes their content for 15+ suspicious patterns:

Packages with 3+ suspicious patterns are flagged as CRITICAL.

3. Tag Integrity (GitHub API)

Queries the GitHub API to verify that tag SHA matches the baseline. Detects tag rewrite attacks in real-time. Also checks whether the commit belongs to the default branch or is a fork commit (strong indicator of attack).

[CRIT] TAG REWRITE DETECTED: owner/repo#v1.0.0 SHA changed!
       baseline SHA: 1fadba8...
       remote SHA:   16e4324... (from fork!)

Requires GITHUB_TOKEN environment variable.

4. Tarball Integrity

Downloads .tar.gz archives from GitHub for tag-based dependencies and compares SHA256 hashes against the baseline. GitHub regenerates tarballs dynamically after tag rewrite — same URL, different content.

[CRIT] TARBALL CHANGED: "logger" .tar.gz hash changed!
       baseline: 475308ac...
       current:  4204c3e4...

5. GitHub Actions Pinning

Scans .github/workflows/*.yml for uses: directives that reference actions by tag instead of SHA. An action tag rewrite gives attackers access to GITHUB_TOKEN, all secrets, and build artifacts.

[HIGH] Action "third-party/action@v2" uses tag instead of SHA!
       fix: uses: third-party/action@<40-char-sha> # v2

Baseline System

The baseline records known-good SHA hashes for dependencies, tags, and tarballs. Subsequent audits compare current state against the baseline to detect drift.

# Create initial baseline
npx git-tag-guardian baseline

# Commit it
git add .guardian-baseline.json
git commit -m "Add supply chain baseline"

The baseline file (.guardian-baseline.json) should be committed to your repository so every developer and CI runner uses the same reference.

GitHub Actions Workflow

A ready-to-use CI workflow is included at .github/workflows/supply-chain-guard.yml:

• Runs on every PR that touches package.json / package-lock.json
• Runs on push to main / master
• Scheduled daily cron for tag rewrite detection between commits
• Posts findings as PR comments on failure
• All actions in the workflow itself are SHA-pinned

# Key: install with --ignore-scripts to prevent postinstall execution
- run: npm ci --ignore-scripts
- run: npx git-tag-guardian audit --ci

Git Hooks

npx git-tag-guardian hooks-install

Installs two hooks:

• pre-commit — blocks commits that introduce SHA drift or new lifecycle hooks
• post-merge — automatically checks dependencies after git pull

Configuration

Create .guardian.yml in your project root (optional — sensible defaults are used otherwise):

checks:
  shaPinning: true
  postinstallHooks: true
  tagIntegrity: true        # requires GITHUB_TOKEN
  tarballIntegrity: true
  actionsPinning: true

# Packages allowed to have lifecycle scripts
allowedLifecyclePackages:
  - electron
  - sharp
  - better-sqlite3

# Actions owners trusted (severity: low instead of high)
trustedActions:
  - actions/*

# Baseline file name
baselineFile: .guardian-baseline.json

# Minimum severity to fail CI
failOnSeverity: high

CLI Reference

COMMANDS:
  audit           Full project audit (all 5 checks)
  baseline        Create/update SHA baseline
  verify          Quick check (SHA drift + postinstall only)
  hooks-install   Install git hooks (pre-commit, post-merge)
  help            Show help

FLAGS:
  --ci            CI mode (exit 1 on critical/high findings)
  --cwd <path>    Project root (default: cwd)
  --token <tok>   GitHub PAT for API checks (or GITHUB_TOKEN env)
  --output <file> Save report as JSON
  --no-color      Disable colors

Integration with AI Coding Agents

This project ships companion skills for Claude Code and OpenCode that automatically run supply chain checks when the agent installs npm packages:

• claude-supply-chain-skill — Claude Code / Anthropic CLI skill
• opencode-supply-chain-skill — OpenCode agent skill

These skills hook into the agent's npm install / bun install workflow and block installation if critical findings are detected.

How It Works (Technical)

Git Tag Rewrite Attack

Upstream repo:  owner/logger
  refs/tags/v1.0.0 → commit abc123 (clean)

Attacker fork:  attacker/logger
  branch: malicious → commit xyz789 (backdoor)

API call (with push access):
  PATCH /repos/owner/logger/git/refs/tags/v1.0.0
  { "sha": "xyz789", "force": true }

Result:
  refs/tags/v1.0.0 → commit xyz789 (backdoor!)
  .tar.gz regenerated with malicious content
  npm install pulls backdoor automatically

Why SHA Pinning Stops It

SHA-256 commit hashes are cryptographically unique. A rewritten tag points to a different SHA — but if your package-lock.json or baseline records the original SHA, the drift is immediately detectable.

Severity Levels

License

MIT

CanisterWorm / TeamPCP — Practical security tooling for the Node.js ecosystem.