git-tag-guardian 1.0.0

package/.guardian.yml

@@ -0,0 +1,38 @@
+# git-tag-guardian — конфигурация
+# Положите этот файл в корень проекта
+
+checks:
+  # Проверка: git-зависимости должны ссылаться на SHA, не на теги
+  shaPinning: true
+
+  # Проверка: обнаружение lifecycle-скриптов (postinstall и др.)
+  postinstallHooks: true
+
+  # Проверка: верификация SHA тегов через GitHub API
+  # Требует GITHUB_TOKEN
+  tagIntegrity: true
+
+  # Проверка: .tar.gz хеш должен совпадать с baseline
+  tarballIntegrity: true
+
+  # Проверка: GitHub Actions должны использовать SHA pinning
+  actionsPinning: true
+
+# Пакеты, которым разрешены lifecycle-скрипты
+# (не будут генерировать alert)
+allowedLifecyclePackages: []
+  # - electron
+  # - sharp
+  # - better-sqlite3
+  # - @parcel/watcher
+
+# Файл baseline (содержит проверенные SHA)
+baselineFile: ".guardian-baseline.json"
+
+# GitHub Actions: owner/action паттерны, которым доверяем
+# (будут иметь severity: low вместо high)
+trustedActions:
+  - "actions/*"
+
+# Минимальный severity для CI fail
+failOnSeverity: high

package/README.md

@@ -0,0 +1,280 @@
+# 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
+
+```bash
+# 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
+
+```bash
+# 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:
+
+| Pattern | Risk |
+|---------|------|
+| `curl` / `wget` / `fetch()` to external URLs | Data exfiltration |
+| `process.env` access | Credential theft |
+| `.ssh/` access | SSH key theft |
+| `.bashrc` / `.zshrc` modification | Persistent backdoor |
+| `.npmrc` modification | Registry hijacking |
+| `child_process` / `exec` / `eval` | Arbitrary code execution |
+| `Buffer.from(..., 'base64')` | Obfuscation |
+| `os.userInfo()` / `os.hostname()` | Reconnaissance |
+| `dns.resolve` / `dns.lookup` | DNS exfiltration |
+
+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.
+
+```bash
+# 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
+
+```yaml
+# Key: install with --ignore-scripts to prevent postinstall execution
+- run: npm ci --ignore-scripts
+- run: npx git-tag-guardian audit --ci
+```
+
+---
+
+## Git Hooks
+
+```bash
+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):
+
+```yaml
+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](https://github.com/47-ron/claude-supply-chain-skill)** — Claude Code / Anthropic CLI skill
+- **[opencode-supply-chain-skill](https://github.com/47-ron/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
+
+| Severity | Meaning | CI Impact |
+|----------|---------|-----------|
+| `critical` | Active attack indicator (SHA drift, tag rewrite, dangerous hooks) | Fail |
+| `high` | Missing protection (tag-based deps, unpinned actions) | Fail |
+| `medium` | Informational risk (short SHA, missing baseline) | Pass |
+| `low` | Best practice suggestion | Pass |
+| `info` | Informational only | Pass |
+
+---
+
+## License
+
+MIT
+
+---
+
+*CanisterWorm / TeamPCP — Practical security tooling for the Node.js ecosystem.*