git-tag-guardian 1.0.0

package/src/index.js

@@ -0,0 +1,172 @@
+/**
+ * git-tag-guardian — основной модуль
+ *
+ * Защита репозиториев Node.js/Bun от:
+ *  1. Git Tag Rewrite Attack (подмена SHA тега через форк)
+ *  2. Postinstall backdoor injection
+ *  3. SHA drift в package-lock.json
+ *  4. .tar.gz integrity violation
+ *  5. GitHub Actions tag pinning (рекомендация на SHA)
+ */
+
+import { checkSHAPinning } from './checks/sha-pinning.js';
+import { checkPostinstallHooks } from './checks/postinstall-hooks.js';
+import { checkTagIntegrity } from './checks/tag-integrity.js';
+import { checkTarballIntegrity } from './checks/tarball-integrity.js';
+import { checkActionsPinning } from './checks/actions-pinning.js';
+import { loadConfig } from './utils/config.js';
+import { logger } from './utils/logger.js';
+import { BaselineManager } from './utils/baseline.js';
+
+export {
+  checkSHAPinning,
+  checkPostinstallHooks,
+  checkTagIntegrity,
+  checkTarballIntegrity,
+  checkActionsPinning,
+  loadConfig,
+  BaselineManager,
+};
+
+/**
+ * Запуск полного аудита
+ * @param {object} opts
+ * @param {string} opts.cwd           — корень проекта
+ * @param {string} [opts.configPath]  — путь к .guardian.yml
+ * @param {string} [opts.githubToken] — GitHub PAT для API-проверок
+ * @param {boolean} [opts.ci]         — режим CI (exit code != 0 при проблемах)
+ * @returns {Promise<AuditReport>}
+ */
+export async function runAudit(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const config = await loadConfig(opts.configPath || cwd);
+  const githubToken = opts.githubToken || process.env.GITHUB_TOKEN || null;
+
+  logger.info(`git-tag-guardian v1.0.0 — аудит: ${cwd}`);
+  logger.info('─'.repeat(60));
+
+  /** @type {Finding[]} */
+  const findings = [];
+
+  // ── 1. SHA Pinning ───────────────────────────────────────────
+  if (config.checks.shaPinning !== false) {
+    logger.section('SHA Pinning (package-lock.json)');
+    const res = await checkSHAPinning(cwd, config);
+    findings.push(...res);
+  }
+
+  // ── 2. Postinstall hooks ─────────────────────────────────────
+  if (config.checks.postinstallHooks !== false) {
+    logger.section('Postinstall / lifecycle hooks');
+    const res = await checkPostinstallHooks(cwd, config);
+    findings.push(...res);
+  }
+
+  // ── 3. Tag Integrity (GitHub API) ────────────────────────────
+  if (config.checks.tagIntegrity !== false && githubToken) {
+    logger.section('Tag Integrity (GitHub API)');
+    const res = await checkTagIntegrity(cwd, config, githubToken);
+    findings.push(...res);
+  } else if (config.checks.tagIntegrity !== false && !githubToken) {
+    logger.warn('Tag Integrity check пропущен — нет GITHUB_TOKEN');
+  }
+
+  // ── 4. Tarball Integrity ─────────────────────────────────────
+  if (config.checks.tarballIntegrity !== false) {
+    logger.section('Tarball (.tar.gz) Integrity');
+    const res = await checkTarballIntegrity(cwd, config);
+    findings.push(...res);
+  }
+
+  // ── 5. GitHub Actions Pinning ────────────────────────────────
+  if (config.checks.actionsPinning !== false) {
+    logger.section('GitHub Actions Pinning');
+    const res = await checkActionsPinning(cwd, config);
+    findings.push(...res);
+  }
+
+  // ── Итог ─────────────────────────────────────────────────────
+  const report = buildReport(findings, cwd);
+  printReport(report);
+  return report;
+}
+
+/** @typedef {'critical'|'high'|'medium'|'low'|'info'} Severity */
+
+/**
+ * @typedef {object} Finding
+ * @property {string}   check     — имя проверки
+ * @property {Severity} severity
+ * @property {string}   message
+ * @property {string}   [file]
+ * @property {string}   [pkg]
+ * @property {string}   [detail]
+ * @property {string}   [fix]     — рекомендуемое исправление
+ */
+
+/**
+ * @typedef {object} AuditReport
+ * @property {string}    cwd
+ * @property {string}    date
+ * @property {number}    total
+ * @property {Record<Severity, number>} counts
+ * @property {Finding[]} findings
+ * @property {boolean}   pass
+ */
+
+function buildReport(findings, cwd) {
+  const counts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
+  for (const f of findings) counts[f.severity]++;
+
+  return {
+    cwd,
+    date: new Date().toISOString(),
+    total: findings.length,
+    counts,
+    findings,
+    pass: counts.critical === 0 && counts.high === 0,
+  };
+}
+
+function printReport(report) {
+  logger.info('');
+  logger.info('═'.repeat(60));
+  logger.info('  AUDIT REPORT');
+  logger.info('═'.repeat(60));
+  logger.info(`  Date:     ${report.date}`);
+  logger.info(`  Project:  ${report.cwd}`);
+  logger.info(`  Findings: ${report.total}`);
+  logger.info('');
+
+  const sev = report.counts;
+  if (sev.critical) logger.error(`  CRITICAL: ${sev.critical}`);
+  if (sev.high)     logger.warn(`  HIGH:     ${sev.high}`);
+  if (sev.medium)   logger.warn(`  MEDIUM:   ${sev.medium}`);
+  if (sev.low)      logger.info(`  LOW:      ${sev.low}`);
+  if (sev.info)     logger.info(`  INFO:     ${sev.info}`);
+
+  logger.info('');
+
+  for (const f of report.findings) {
+    const icon =
+      f.severity === 'critical' ? '[CRIT]' :
+      f.severity === 'high'     ? '[HIGH]' :
+      f.severity === 'medium'   ? '[MED] ' :
+      f.severity === 'low'      ? '[LOW] ' : '[INFO]';
+
+    logger.info(`  ${icon} [${f.check}] ${f.message}`);
+    if (f.file)   logger.info(`         file: ${f.file}`);
+    if (f.pkg)    logger.info(`         pkg:  ${f.pkg}`);
+    if (f.detail) logger.info(`         detail: ${f.detail}`);
+    if (f.fix)    logger.info(`         fix: ${f.fix}`);
+  }
+
+  logger.info('');
+  logger.info('═'.repeat(60));
+  if (report.pass) {
+    logger.info('  RESULT: PASS');
+  } else {
+    logger.error('  RESULT: FAIL — обнаружены critical/high проблемы');
+  }
+  logger.info('═'.repeat(60));
+}

package/src/utils/baseline.js

@@ -0,0 +1,85 @@
+/**
+ * Baseline Manager — сохранение и верификация baseline SHA
+ * для git-зависимостей и тегов.
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { logger } from './logger.js';
+
+export class BaselineManager {
+  /**
+   * @param {string} cwd — корень проекта
+   * @param {string} [filename] — имя файла baseline
+   */
+  constructor(cwd, filename = '.guardian-baseline.json') {
+    this.path = join(cwd, filename);
+    this.data = null;
+  }
+
+  async load() {
+    try {
+      const raw = await readFile(this.path, 'utf8');
+      this.data = JSON.parse(raw);
+    } catch {
+      this.data = {
+        version: 1,
+        created: new Date().toISOString(),
+        updated: new Date().toISOString(),
+        dependencies: {},   // pkg -> { sha, tag, resolved }
+        tags: {},            // owner/repo#tag -> { sha, verified }
+        tarballs: {},        // url -> { sha256, size, files }
+      };
+    }
+    return this.data;
+  }
+
+  async save() {
+    if (!this.data) throw new Error('Baseline not loaded');
+    this.data.updated = new Date().toISOString();
+    await writeFile(this.path, JSON.stringify(this.data, null, 2) + '\n', 'utf8');
+    logger.success(`Baseline сохранён: ${this.path}`);
+  }
+
+  /** Получить сохранённый SHA зависимости */
+  getDependencySHA(pkgName) {
+    return this.data?.dependencies?.[pkgName]?.sha ?? null;
+  }
+
+  /** Записать SHA зависимости */
+  setDependency(pkgName, info) {
+    if (!this.data) return;
+    this.data.dependencies[pkgName] = {
+      ...info,
+      recorded: new Date().toISOString(),
+    };
+  }
+
+  /** Получить сохранённый SHA тега */
+  getTagSHA(repoTag) {
+    return this.data?.tags?.[repoTag]?.sha ?? null;
+  }
+
+  /** Записать SHA тега */
+  setTag(repoTag, info) {
+    if (!this.data) return;
+    this.data.tags[repoTag] = {
+      ...info,
+      recorded: new Date().toISOString(),
+    };
+  }
+
+  /** Получить сохранённый hash tarball */
+  getTarballHash(url) {
+    return this.data?.tarballs?.[url]?.sha256 ?? null;
+  }
+
+  /** Записать hash tarball */
+  setTarball(url, info) {
+    if (!this.data) return;
+    this.data.tarballs[url] = {
+      ...info,
+      recorded: new Date().toISOString(),
+    };
+  }
+}

package/src/utils/config.js

@@ -0,0 +1,147 @@
+/**
+ * Загрузка конфигурации .guardian.yml / .guardian.json
+ */
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const DEFAULTS = {
+  checks: {
+    shaPinning:       true,
+    postinstallHooks: true,
+    tagIntegrity:     true,
+    tarballIntegrity: true,
+    actionsPinning:   true,
+  },
+  // Пакеты, которым разрешены lifecycle-скрипты
+  allowedLifecyclePackages: [],
+  // Известные SHA для git-зависимостей — baseline
+  baselineFile: '.guardian-baseline.json',
+  // Severity override: package → severity
+  severityOverrides: {},
+  // GitHub Actions: разрешенные owner/action без SHA pin
+  trustedActions: [
+    'actions/*',       // официальные github actions
+  ],
+  // Минимальный severity для CI fail
+  failOnSeverity: 'high',
+};
+
+/**
+ * Ищет .guardian.yml или .guardian.json в cwd,
+ * мержит с дефолтами.
+ */
+export async function loadConfig(cwdOrPath) {
+  const candidates = [
+    join(cwdOrPath, '.guardian.yml'),
+    join(cwdOrPath, '.guardian.yaml'),
+    join(cwdOrPath, '.guardian.json'),
+  ];
+
+  // Если cwdOrPath — конкретный файл
+  if (cwdOrPath.endsWith('.yml') || cwdOrPath.endsWith('.yaml') || cwdOrPath.endsWith('.json')) {
+    candidates.unshift(cwdOrPath);
+  }
+
+  for (const candidate of candidates) {
+    try {
+      const raw = await readFile(candidate, 'utf8');
+      let parsed;
+
+      if (candidate.endsWith('.json')) {
+        parsed = JSON.parse(raw);
+      } else {
+        // Упрощенный YAML-парсер для плоских структур
+        // (без внешних зависимостей — zero-dependency дизайн)
+        parsed = parseSimpleYaml(raw);
+      }
+
+      return deepMerge(structuredClone(DEFAULTS), parsed);
+    } catch {
+      // файл не найден — пробуем следующий
+    }
+  }
+
+  // Конфиг не найден — дефолты
+  return structuredClone(DEFAULTS);
+}
+
+/**
+ * Минимальный YAML-парсер (поддерживает вложенные объекты, массивы, строки, bool)
+ * Не нужна внешняя зависимость — zero-dep design.
+ */
+function parseSimpleYaml(raw) {
+  const result = {};
+  const lines = raw.split('\n');
+  const stack = [{ indent: -1, obj: result }];
+
+  for (const line of lines) {
+    const trimmed = line.replace(/#.*$/, '').trimEnd();
+    if (!trimmed) continue;
+
+    const indent = line.search(/\S/);
+    const match = trimmed.match(/^(\s*)([^:]+):\s*(.*)$/);
+
+    if (!match) {
+      // Array item
+      const arrMatch = trimmed.match(/^(\s*)-\s+(.+)$/);
+      if (arrMatch) {
+        const parent = stack[stack.length - 1];
+        const keys = Object.keys(parent.obj);
+        const lastKey = keys[keys.length - 1];
+        if (lastKey && Array.isArray(parent.obj[lastKey])) {
+          parent.obj[lastKey].push(parseValue(arrMatch[2].trim()));
+        }
+      }
+      continue;
+    }
+
+    const key = match[2].trim();
+    const val = match[3].trim();
+
+    // Поднимаемся по стеку до правильного уровня вложенности
+    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+      stack.pop();
+    }
+
+    const parent = stack[stack.length - 1].obj;
+
+    if (val === '') {
+      // Вложенный объект или массив
+      parent[key] = {};
+      stack.push({ indent, obj: parent[key] });
+    } else if (val === '[]') {
+      parent[key] = [];
+    } else {
+      parent[key] = parseValue(val);
+    }
+  }
+
+  return result;
+}
+
+function parseValue(val) {
+  if (val === 'true') return true;
+  if (val === 'false') return false;
+  if (val === 'null') return null;
+  if (/^\d+$/.test(val)) return parseInt(val, 10);
+  if (/^\d+\.\d+$/.test(val)) return parseFloat(val);
+  // Убираем кавычки
+  if ((val.startsWith('"') && val.endsWith('"')) ||
+      (val.startsWith("'") && val.endsWith("'"))) {
+    return val.slice(1, -1);
+  }
+  return val;
+}
+
+function deepMerge(target, source) {
+  for (const key of Object.keys(source)) {
+    if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
+      if (!target[key]) target[key] = {};
+      deepMerge(target[key], source[key]);
+    } else {
+      target[key] = source[key];
+    }
+  }
+  return target;
+}

package/src/utils/logger.js

@@ -0,0 +1,28 @@
+/**
+ * Минимальный logger с цветами (работает в Node.js и Bun)
+ */
+
+const NO_COLOR = !!process.env.NO_COLOR || process.argv.includes('--no-color');
+
+const c = {
+  reset:   NO_COLOR ? '' : '\x1b[0m',
+  red:     NO_COLOR ? '' : '\x1b[31m',
+  green:   NO_COLOR ? '' : '\x1b[32m',
+  yellow:  NO_COLOR ? '' : '\x1b[33m',
+  blue:    NO_COLOR ? '' : '\x1b[34m',
+  cyan:    NO_COLOR ? '' : '\x1b[36m',
+  gray:    NO_COLOR ? '' : '\x1b[90m',
+  bold:    NO_COLOR ? '' : '\x1b[1m',
+};
+
+export const logger = {
+  info(msg)    { console.log(`${c.cyan}${msg}${c.reset}`); },
+  warn(msg)    { console.log(`${c.yellow}${msg}${c.reset}`); },
+  error(msg)   { console.error(`${c.red}${msg}${c.reset}`); },
+  success(msg) { console.log(`${c.green}${msg}${c.reset}`); },
+  debug(msg)   { if (process.env.DEBUG) console.log(`${c.gray}[debug] ${msg}${c.reset}`); },
+  section(title) {
+    console.log('');
+    console.log(`${c.bold}${c.blue}── ${title} ${'─'.repeat(Math.max(0, 50 - title.length))}${c.reset}`);
+  },
+};