git-tag-guardian 1.0.0

package/bin/guardian.js

@@ -0,0 +1,408 @@
+#!/usr/bin/env node
+
+/**
+ * git-tag-guardian CLI
+ *
+ * Команды:
+ *   audit            — полный аудит проекта
+ *   baseline         — создать/обновить baseline SHA
+ *   verify           — быстрая проверка (SHA drift + postinstall)
+ *   hooks-install    — установить git hooks (pre-commit, post-merge)
+ *   help             — справка
+ *
+ * Примеры:
+ *   npx git-tag-guardian audit
+ *   npx git-tag-guardian audit --ci
+ *   npx git-tag-guardian baseline
+ *   GITHUB_TOKEN=ghp_xxx npx git-tag-guardian audit
+ */
+
+import { runAudit, checkSHAPinning, checkPostinstallHooks, BaselineManager } from '../src/index.js';
+import { loadConfig } from '../src/utils/config.js';
+import { logger } from '../src/utils/logger.js';
+import { readFile, writeFile, mkdir, chmod } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+
+const args = process.argv.slice(2);
+const command = args[0] || 'help';
+const flags = parseFlags(args.slice(1));
+
+async function main() {
+  switch (command) {
+    case 'audit':
+      return await cmdAudit();
+    case 'baseline':
+      return await cmdBaseline();
+    case 'verify':
+      return await cmdVerify();
+    case 'hooks-install':
+      return await cmdHooksInstall();
+    case 'help':
+    case '--help':
+    case '-h':
+      return cmdHelp();
+    default:
+      logger.error(`Неизвестная команда: ${command}`);
+      cmdHelp();
+      process.exit(1);
+  }
+}
+
+// ── audit ──────────────────────────────────────────────────────
+
+async function cmdAudit() {
+  const cwd = flags.cwd || process.cwd();
+  const report = await runAudit({
+    cwd,
+    githubToken: flags.token || process.env.GITHUB_TOKEN,
+    ci: flags.ci || !!process.env.CI,
+  });
+
+  // В CI-режиме — exit code
+  if (flags.ci || process.env.CI) {
+    if (!report.pass) {
+      process.exit(1);
+    }
+  }
+
+  // Сохранение отчёта в JSON
+  if (flags.output) {
+    await writeFile(flags.output, JSON.stringify(report, null, 2), 'utf8');
+    logger.info(`Отчёт сохранён: ${flags.output}`);
+  }
+}
+
+// ── baseline ───────────────────────────────────────────────────
+
+async function cmdBaseline() {
+  const cwd = flags.cwd || process.cwd();
+  const config = await loadConfig(cwd);
+
+  logger.info('git-tag-guardian — создание baseline');
+  logger.info('─'.repeat(60));
+
+  const baseline = new BaselineManager(cwd, config.baselineFile);
+  await baseline.load();
+
+  // 1. Записываем SHA из package-lock.json
+  let lockfile;
+  try {
+    lockfile = JSON.parse(await readFile(join(cwd, 'package-lock.json'), 'utf8'));
+  } catch {
+    logger.warn('package-lock.json не найден');
+  }
+
+  if (lockfile?.packages) {
+    let count = 0;
+    for (const [pkgPath, meta] of Object.entries(lockfile.packages)) {
+      if (!meta.resolved || !meta.resolved.includes('git')) continue;
+      const sha = extractSHA(meta.resolved);
+      if (!sha) continue;
+
+      const pkgName = pkgPath.replace('node_modules/', '');
+      if (!pkgName) continue;
+
+      baseline.setDependency(pkgName, {
+        sha,
+        resolved: meta.resolved,
+        version: meta.version,
+      });
+      count++;
+      logger.info(`  dep: ${pkgName} → ${sha.slice(0, 12)}...`);
+    }
+    logger.info(`  Зависимостей записано: ${count}`);
+  }
+
+  // 2. Записываем SHA тегов через GitHub API (если есть токен)
+  const token = flags.token || process.env.GITHUB_TOKEN;
+  if (token) {
+    let pkgJson;
+    try {
+      pkgJson = JSON.parse(await readFile(join(cwd, 'package.json'), 'utf8'));
+    } catch { /* skip */ }
+
+    if (pkgJson) {
+      const allDeps = {
+        ...pkgJson.dependencies,
+        ...pkgJson.devDependencies,
+      };
+
+      for (const [name, spec] of Object.entries(allDeps)) {
+        const info = parseGitHubRef(spec);
+        if (!info || !info.tag) continue;
+
+        try {
+          const sha = await fetchTagSHA(info.owner, info.repo, info.tag, token);
+          if (sha) {
+            const repoTag = `${info.owner}/${info.repo}#${info.tag}`;
+            baseline.setTag(repoTag, { sha, tag: info.tag });
+            logger.info(`  tag: ${repoTag} → ${sha.slice(0, 12)}...`);
+          }
+        } catch (err) {
+          logger.warn(`  tag: ${info.owner}/${info.repo}#${info.tag} — ошибка: ${err.message}`);
+        }
+      }
+    }
+  }
+
+  // 3. Записываем хеши tarball
+  {
+    let pkgJson;
+    try {
+      pkgJson = JSON.parse(await readFile(join(cwd, 'package.json'), 'utf8'));
+    } catch { /* skip */ }
+
+    if (pkgJson) {
+      const allDeps = { ...pkgJson.dependencies, ...pkgJson.devDependencies };
+      for (const [name, spec] of Object.entries(allDeps)) {
+        const url = buildTarballUrl(spec);
+        if (!url) continue;
+
+        try {
+          const res = await fetch(url, {
+            headers: { 'User-Agent': 'git-tag-guardian/1.0' },
+            redirect: 'follow',
+          });
+          if (!res.ok) continue;
+
+          const buffer = Buffer.from(await res.arrayBuffer());
+          const sha256 = createHash('sha256').update(buffer).digest('hex');
+
+          baseline.setTarball(url, { sha256, size: buffer.length });
+          logger.info(`  tarball: ${name} → ${sha256.slice(0, 16)}... (${buffer.length} bytes)`);
+        } catch { /* skip */ }
+      }
+    }
+  }
+
+  await baseline.save();
+  logger.success('Baseline создан! Добавьте его в git:');
+  logger.info(`  git add ${config.baselineFile}`);
+}
+
+// ── verify ─────────────────────────────────────────────────────
+
+async function cmdVerify() {
+  const cwd = flags.cwd || process.cwd();
+  const config = await loadConfig(cwd);
+
+  logger.info('git-tag-guardian — быстрая проверка');
+  logger.info('─'.repeat(60));
+
+  const findings = [];
+
+  const sha = await checkSHAPinning(cwd, config);
+  findings.push(...sha);
+
+  const hooks = await checkPostinstallHooks(cwd, config);
+  findings.push(...hooks);
+
+  const critical = findings.filter(f => f.severity === 'critical');
+  const high = findings.filter(f => f.severity === 'high');
+
+  if (critical.length || high.length) {
+    logger.error(`\nОбнаружено проблем: ${critical.length} critical, ${high.length} high`);
+    for (const f of [...critical, ...high]) {
+      logger.error(`  [${f.severity.toUpperCase()}] ${f.message}`);
+    }
+    if (flags.ci || process.env.CI) process.exit(1);
+  } else {
+    logger.success('\nБыстрая проверка пройдена!');
+  }
+}
+
+// ── hooks-install ──────────────────────────────────────────────
+
+async function cmdHooksInstall() {
+  const cwd = flags.cwd || process.cwd();
+  const hooksDir = join(cwd, '.git', 'hooks');
+
+  try {
+    await mkdir(hooksDir, { recursive: true });
+  } catch { /* exists */ }
+
+  // pre-commit hook
+  const preCommit = `#!/bin/sh
+# git-tag-guardian: pre-commit hook
+# Проверяет SHA drift и postinstall hooks перед коммитом
+
+echo "[git-tag-guardian] Проверка безопасности зависимостей..."
+
+# Проверяем, изменились ли файлы зависимостей
+CHANGED_FILES=$(git diff --cached --name-only)
+NEEDS_CHECK=false
+
+for f in $CHANGED_FILES; do
+  case "$f" in
+    package.json|package-lock.json|bun.lockb|yarn.lock)
+      NEEDS_CHECK=true
+      ;;
+  esac
+done
+
+if [ "$NEEDS_CHECK" = "true" ]; then
+  npx git-tag-guardian verify 2>&1
+  if [ $? -ne 0 ]; then
+    echo ""
+    echo "[git-tag-guardian] BLOCKED: обнаружены проблемы безопасности!"
+    echo "[git-tag-guardian] Запустите 'npx git-tag-guardian audit' для деталей."
+    exit 1
+  fi
+fi
+
+echo "[git-tag-guardian] OK"
+`;
+
+  // post-merge hook (после git pull)
+  const postMerge = `#!/bin/sh
+# git-tag-guardian: post-merge hook
+# Автоматическая проверка после git pull / merge
+
+echo "[git-tag-guardian] Проверка после merge..."
+
+# Проверяем, изменились ли файлы зависимостей
+CHANGED=$(git diff-tree -r --name-only ORIG_HEAD HEAD 2>/dev/null)
+
+for f in $CHANGED; do
+  case "$f" in
+    package.json|package-lock.json)
+      echo "[git-tag-guardian] Зависимости изменились — запускаю проверку..."
+      npx git-tag-guardian verify 2>&1
+      exit 0
+      ;;
+  esac
+done
+`;
+
+  await writeFile(join(hooksDir, 'pre-commit'), preCommit, 'utf8');
+  await chmod(join(hooksDir, 'pre-commit'), 0o755);
+  logger.success('Установлен: .git/hooks/pre-commit');
+
+  await writeFile(join(hooksDir, 'post-merge'), postMerge, 'utf8');
+  await chmod(join(hooksDir, 'post-merge'), 0o755);
+  logger.success('Установлен: .git/hooks/post-merge');
+
+  logger.info('');
+  logger.info('Git hooks установлены! Теперь при каждом коммите и pull');
+  logger.info('будет автоматическая проверка безопасности зависимостей.');
+}
+
+// ── help ───────────────────────────────────────────────────────
+
+function cmdHelp() {
+  console.log(`
+git-tag-guardian v1.0.0 — защита от supply chain атак
+
+КОМАНДЫ:
+  audit           Полный аудит проекта (все 5 проверок)
+  baseline        Создать/обновить baseline SHA зависимостей
+  verify          Быстрая проверка (SHA drift + postinstall hooks)
+  hooks-install   Установить git hooks (pre-commit, post-merge)
+  help            Показать эту справку
+
+ФЛАГИ:
+  --ci            CI-режим (exit 1 при обнаружении проблем)
+  --cwd <path>    Корень проекта (по умолчанию: текущая директория)
+  --token <tok>   GitHub PAT для API-проверок (или GITHUB_TOKEN env)
+  --output <file> Сохранить отчёт в JSON файл
+  --no-color      Отключить цвета
+
+ПРОВЕРКИ:
+  1. SHA Pinning       — git-зависимости должны использовать SHA, не теги
+  2. Postinstall Hooks — обнаружение lifecycle-скриптов в зависимостях
+  3. Tag Integrity     — верификация SHA тегов через GitHub API
+  4. Tarball Integrity — проверка .tar.gz хешей
+  5. Actions Pinning   — GitHub Actions должны использовать SHA
+
+ПРИМЕРЫ:
+  npx git-tag-guardian audit
+  npx git-tag-guardian audit --ci --token ghp_xxx
+  npx git-tag-guardian baseline
+  npx git-tag-guardian verify
+  npx git-tag-guardian hooks-install
+
+КОНФИГУРАЦИЯ:
+  Создайте .guardian.yml в корне проекта (опционально):
+
+  checks:
+    shaPinning: true
+    postinstallHooks: true
+    tagIntegrity: true
+    tarballIntegrity: true
+    actionsPinning: true
+
+  allowedLifecyclePackages:
+    - electron
+    - sharp
+
+  trustedActions:
+    - actions/*
+`);
+}
+
+// ── Utils ──────────────────────────────────────────────────────
+
+function parseFlags(args) {
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--ci') flags.ci = true;
+    else if (arg === '--no-color') process.env.NO_COLOR = '1';
+    else if (arg === '--cwd' && args[i + 1]) flags.cwd = args[++i];
+    else if (arg === '--token' && args[i + 1]) flags.token = args[++i];
+    else if (arg === '--output' && args[i + 1]) flags.output = args[++i];
+  }
+  return flags;
+}
+
+function extractSHA(resolved) {
+  if (!resolved) return null;
+  const idx = resolved.lastIndexOf('#');
+  if (idx === -1) return null;
+  const sha = resolved.slice(idx + 1);
+  return /^[0-9a-f]{7,40}$/.test(sha) ? sha : null;
+}
+
+function parseGitHubRef(spec) {
+  if (!spec || typeof spec !== 'string') return null;
+  let rest = spec;
+  if (rest.startsWith('github:')) rest = rest.slice(7);
+  const match = rest.match(/^([^/]+)\/([^/#]+)(?:#(.+))?$/);
+  if (!match) return null;
+  const ref = match[3];
+  if (ref && /^[0-9a-f]{40}$/.test(ref)) return null; // SHA pinned
+  return { owner: match[1], repo: match[2], tag: ref };
+}
+
+async function fetchTagSHA(owner, repo, tag, token) {
+  const url = `https://api.github.com/repos/${owner}/${repo}/git/refs/tags/${tag}`;
+  const res = await fetch(url, {
+    headers: {
+      'Authorization': `token ${token}`,
+      'Accept': 'application/vnd.github+json',
+      'User-Agent': 'git-tag-guardian/1.0',
+    },
+  });
+  if (!res.ok) return null;
+  const data = await res.json();
+  return data.object?.sha || null;
+}
+
+function buildTarballUrl(spec) {
+  if (!spec || typeof spec !== 'string') return null;
+  let rest = spec;
+  if (rest.startsWith('github:')) rest = rest.slice(7);
+  else return null;
+  const hashIdx = rest.indexOf('#');
+  if (hashIdx === -1) return null;
+  const ownerRepo = rest.slice(0, hashIdx);
+  const ref = rest.slice(hashIdx + 1);
+  if (/^[0-9a-f]{40}$/.test(ref)) return null;
+  return `https://github.com/${ownerRepo}/archive/refs/tags/${ref}.tar.gz`;
+}
+
+main().catch(err => {
+  logger.error(`Ошибка: ${err.message}`);
+  process.exit(2);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "git-tag-guardian",
+  "version": "1.0.0",
+  "description": "Zero-dependency supply chain defense for Node.js/Bun — detects git tag rewrite attacks, postinstall backdoors, SHA drift, tarball tampering and unpinned GitHub Actions",
+  "type": "module",
+  "bin": {
+    "git-tag-guardian": "./bin/guardian.js"
+  },
+  "main": "./src/index.js",
+  "scripts": {
+    "audit": "node ./bin/guardian.js audit",
+    "baseline": "node ./bin/guardian.js baseline",
+    "verify": "node ./bin/guardian.js verify",
+    "hooks:install": "node ./bin/guardian.js hooks-install",
+    "test": "node --test ./tests/"
+  },
+  "keywords": [
+    "security",
+    "supply-chain",
+    "tag-rewrite",
+    "git-tags",
+    "npm-audit",
+    "postinstall",
+    "sha-pinning"
+  ],
+  "author": "CanisterWorm / TeamPCP",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/47-ron/git-tag-guardian.git"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    ".guardian.yml"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/checks/actions-pinning.js

@@ -0,0 +1,136 @@
+/**
+ * Проверка 5: GitHub Actions Pinning
+ *
+ * Сканирует .github/workflows/*.yml на использование
+ * actions с тегами вместо SHA.
+ *
+ * Вектор атаки: Tag rewrite на action-репозитории позволяет
+ * подменить код action'а. При следующем запуске CI/CD
+ * выполнится вредоносный код с доступом к GITHUB_TOKEN,
+ * secrets, артефактам.
+ *
+ * Пример:
+ *   ПЛОХО:  uses: actions/checkout@v3
+ *   ХОРОШО: uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744
+ */
+
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { logger } from '../utils/logger.js';
+
+const USES_RE = /uses:\s*["']?([^"'\s#]+)(?:#([^"'\s]+))?["']?/g;
+const SHA_RE = /^[0-9a-f]{40}$/;
+const ACTION_RE = /^([^/]+)\/([^/@]+)(?:\/([^@]+))?@(.+)$/;
+
+/**
+ * @param {string} cwd
+ * @param {object} config
+ * @returns {Promise<import('../index.js').Finding[]>}
+ */
+export async function checkActionsPinning(cwd, config) {
+  /** @type {import('../index.js').Finding[]} */
+  const findings = [];
+
+  const workflowsDir = join(cwd, '.github', 'workflows');
+  let files;
+  try {
+    files = await readdir(workflowsDir);
+  } catch {
+    logger.info('  .github/workflows/ не найден — пропускаем');
+    return findings;
+  }
+
+  const ymlFiles = files.filter(f => f.endsWith('.yml') || f.endsWith('.yaml'));
+  if (ymlFiles.length === 0) {
+    logger.info('  Workflow файлы не найдены');
+    return findings;
+  }
+
+  const trustedPatterns = (config.trustedActions || []).map(p => {
+    // Преобразуем "actions/*" → RegExp
+    const escaped = p.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp(`^${escaped}$`);
+  });
+
+  let totalActions = 0;
+  let unpinnedCount = 0;
+
+  for (const file of ymlFiles) {
+    const filePath = join(workflowsDir, file);
+    let content;
+    try {
+      content = await readFile(filePath, 'utf8');
+    } catch { continue; }
+
+    // Находим все "uses:" директивы
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const match = line.match(/uses:\s*["']?([^"'\s]+)["']?/);
+      if (!match) continue;
+
+      const fullRef = match[1];
+      const parsed = parseAction(fullRef);
+      if (!parsed) continue;
+
+      totalActions++;
+
+      // Проверяем, является ли ref полным SHA
+      if (SHA_RE.test(parsed.ref)) {
+        logger.debug(`  ${file}:${i + 1}: ${fullRef} — SHA-pinned (OK)`);
+        continue;
+      }
+
+      // Проверяем trusted list
+      const actionId = `${parsed.owner}/${parsed.repo}`;
+      const isTrusted = trustedPatterns.some(p => p.test(actionId));
+
+      if (isTrusted) {
+        // Даже для trusted — низкий severity
+        findings.push({
+          check: 'actions-pinning',
+          severity: 'low',
+          message: `Action "${fullRef}" использует тег вместо SHA (trusted)`,
+          file: `.github/workflows/${file}:${i + 1}`,
+          detail: `Тег "${parsed.ref}" может быть переписан. Даже для trusted actions рекомендуется SHA pinning.`,
+          fix: `Замените на: uses: ${parsed.owner}/${parsed.repo}${parsed.path ? '/' + parsed.path : ''}@<40-char-sha> # ${parsed.ref}`,
+        });
+      } else {
+        unpinnedCount++;
+        findings.push({
+          check: 'actions-pinning',
+          severity: 'high',
+          message: `Action "${fullRef}" использует тег "${parsed.ref}" вместо SHA!`,
+          file: `.github/workflows/${file}:${i + 1}`,
+          detail: `Тег "${parsed.ref}" может быть переписан через tag rewrite attack.\nВредоносный action получит доступ к:\n  - GITHUB_TOKEN\n  - Всем secrets\n  - Build артефактам\n  - Возможность push в репозиторий`,
+          fix: `1. Найдите SHA тега: git ls-remote https://github.com/${parsed.owner}/${parsed.repo} refs/tags/${parsed.ref}\n2. Замените на: uses: ${parsed.owner}/${parsed.repo}${parsed.path ? '/' + parsed.path : ''}@<sha> # ${parsed.ref}`,
+        });
+      }
+    }
+  }
+
+  logger.info(`  Workflow файлов: ${ymlFiles.length}`);
+  logger.info(`  Actions найдено: ${totalActions}`);
+  logger.info(`  Без SHA pinning: ${unpinnedCount}`);
+
+  return findings;
+}
+
+/**
+ * Парсит uses: reference.
+ * "owner/repo@ref" → { owner, repo, path, ref }
+ * "owner/repo/sub@ref" → { owner, repo, path: "sub", ref }
+ */
+function parseAction(fullRef) {
+  if (!fullRef || fullRef.startsWith('./') || fullRef.startsWith('docker://')) return null;
+
+  const match = fullRef.match(ACTION_RE);
+  if (!match) return null;
+
+  return {
+    owner: match[1],
+    repo: match[2],
+    path: match[3] || null,
+    ref: match[4],
+  };
+}