secure-push-check 1.0.0

package/README.md

@@ -0,0 +1,218 @@
+# secure-push-check
+
+`secure-push-check` is a production-ready Node.js CLI that scans a local Git repository for common security risks before you push to GitHub.
+
+It detects:
+- Hardcoded secrets in text files (regex-based, configurable)
+- Sensitive files accidentally tracked by Git
+- Missing sensitive patterns in `.gitignore`
+- Dependency vulnerabilities from `npm audit --json`
+- Hardcoded credentials in JS/TS via Babel AST parsing
+
+## Features
+
+- Fully async ESM implementation (`Node.js >= 18`)
+- Modular scanner architecture under `src/scanners`
+- Configurable behavior via `.securepushrc.json`
+- Colored terminal output with file paths and line numbers
+- JSON report mode for CI systems
+- Git `pre-push` hook installation command
+
+## Project Structure
+
+```text
+.
+├── bin
+│   └── secure-push-check.js
+├── src
+│   ├── scanners
+│   │   ├── credentials.js
+│   │   ├── deps.js
+│   │   ├── files.js
+│   │   ├── gitignore.js
+│   │   └── secrets.js
+│   ├── cli.js
+│   └── index.js
+├── package.json
+└── README.md
+```
+
+## Installation
+
+### Local project install
+
+```bash
+npm install --save-dev secure-push-check
+```
+
+### Run from source
+
+```bash
+npm install
+npm run scan
+```
+
+## CLI Commands
+
+```bash
+secure-push-check scan
+secure-push-check install
+secure-push-check report --json
+```
+
+### `scan`
+
+Runs all checks and prints colorized output.
+
+```bash
+secure-push-check scan
+secure-push-check scan --json
+secure-push-check scan --cwd /path/to/repo
+```
+
+### `report`
+
+Runs all checks and prints report output (recommended with `--json` for automation).
+
+```bash
+secure-push-check report --json
+```
+
+### `install`
+
+Installs or updates a `pre-push` hook at `.git/hooks/pre-push`.
+
+```bash
+secure-push-check install
+```
+
+## Configuration
+
+Create `.securepushrc.json` in repository root:
+
+```json
+{
+  "ignore": ["tests/**", "fixtures/**"],
+  "allowPatterns": ["TEST_KEY_", "/^fake_/i"],
+  "severity": "high",
+  "secretPatterns": [
+    {
+      "name": "Internal Token",
+      "regex": "int_[A-Za-z0-9]{24,}",
+      "flags": "g",
+      "severity": "critical"
+    }
+  ]
+}
+```
+
+### Config Fields
+
+- `ignore`: glob patterns excluded from file scanning.
+- `allowPatterns`: strings or regex-like strings (`/pattern/flags`) to suppress known-safe matches.
+- `severity`: push-block threshold (`low`, `moderate`, `high`, `critical`).
+- `secretPatterns`: additional custom secret regex rules.
+
+## Output and Exit Codes
+
+Report sections:
+- `❌ Critical Issues`
+- `⚠️ Warnings`
+- `✅ Passed Checks`
+
+Exit code semantics:
+- `0`: safe to push
+- `1`: push blocked
+
+## Example Output
+
+```text
+🔍 Secure Push Check v1.0.0
+
+❌ Critical Issues
+  - [CRITICAL] Potential OpenAI Key detected (src/config.js:18:16)
+  - [CRITICAL] Sensitive file exists and is not ignored by Git (.env)
+
+⚠️ Warnings
+  - [HIGH] Missing sensitive ignore pattern: .env.local (.gitignore)
+  - [MODERATE] npm audit found 2 moderate vulnerabilities. (package-lock.json)
+
+✅ Passed Checks
+  - Hardcoded Credentials Scan
+
+Summary: critical=2, high=1, moderate=1, total=4
+Result: BLOCKED (threshold: high)
+```
+
+## Git Hook Workflow
+
+Install once:
+
+```bash
+secure-push-check install
+```
+
+During `git push`, the generated hook runs:
+
+```bash
+secure-push-check scan
+```
+
+If scan exits non-zero, push is blocked.
+
+## CI Usage
+
+GitHub Actions example:
+
+```yaml
+name: security-push-check
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - run: npm ci
+      - run: npx secure-push-check report --json
+```
+
+## Publish Instructions
+
+1. Authenticate with npm:
+```bash
+npm login
+```
+2. Verify package:
+```bash
+npm pack --dry-run
+```
+3. Publish:
+```bash
+npm publish --access public
+```
+4. Tag release:
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+## Contributing
+
+1. Fork and create a feature branch.
+2. Keep scanner modules focused and unit-testable.
+3. Add tests for parser/regex edge cases and hook installation flows.
+4. Open a PR with:
+- problem statement
+- change summary
+- sample output
+
+## License
+
+MIT

package/bin/secure-push-check.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "../src/cli.js";

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "secure-push-check",
+  "version": "1.0.0",
+  "description": "Production-ready CLI that scans local Git repositories for security risks before push.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "secure-push-check": "bin/secure-push-check.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "scan": "node ./bin/secure-push-check.js scan",
+    "report:json": "node ./bin/secure-push-check.js report --json",
+    "install:hook": "node ./bin/secure-push-check.js install"
+  },
+  "keywords": [
+    "security",
+    "git",
+    "cli",
+    "secrets",
+    "audit",
+    "pre-push"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@babel/parser": "^7.27.7",
+    "chalk": "^5.4.1",
+    "commander": "^12.1.0",
+    "fast-glob": "^3.3.3"
+  }
+}

package/src/cli.js

@@ -0,0 +1,185 @@
+import chalk from "chalk";
+import { Command } from "commander";
+import {
+  TOOL_VERSION,
+  installPrePushHook,
+  normalizeSeverity,
+  runScan
+} from "./index.js";
+
+/**
+ * @param {string} severity
+ * @returns {(text: string) => string}
+ */
+function severityColor(severity) {
+  switch (normalizeSeverity(severity)) {
+    case "critical":
+      return chalk.red.bold;
+    case "high":
+      return chalk.yellow.bold;
+    case "moderate":
+      return chalk.hex("#f59e0b");
+    case "low":
+      return chalk.blue;
+    default:
+      return chalk.white;
+  }
+}
+
+/**
+ * @param {object} finding
+ * @returns {string}
+ */
+function formatFindingLocation(finding) {
+  const base = finding.file || "unknown";
+  if (typeof finding.line === "number" && typeof finding.column === "number") {
+    return `${base}:${finding.line}:${finding.column}`;
+  }
+  if (typeof finding.line === "number") {
+    return `${base}:${finding.line}`;
+  }
+  return base;
+}
+
+/**
+ * @param {object} result
+ * @returns {void}
+ */
+function renderHumanReport(result) {
+  const critical = [];
+  const warnings = [];
+
+  for (const check of result.checks) {
+    for (const finding of check.findings || []) {
+      const enriched = { ...finding, checkName: check.name };
+      if (normalizeSeverity(finding.severity) === "critical") {
+        critical.push(enriched);
+      } else {
+        warnings.push(enriched);
+      }
+    }
+  }
+
+  const passedChecks = result.checks.filter((check) => check.status === "passed");
+  const skippedChecks = result.checks.filter((check) => check.status === "skipped");
+
+  console.log(chalk.cyan.bold(`\n🔍 Secure Push Check v${result.version}\n`));
+
+  console.log(chalk.red.bold("❌ Critical Issues"));
+  if (critical.length === 0) {
+    console.log(chalk.green("  ✅ None"));
+  } else {
+    for (const finding of critical) {
+      const color = severityColor(finding.severity);
+      const severityTag = color(`[${String(finding.severity).toUpperCase()}]`);
+      console.log(
+        `  - ${severityTag} ${finding.message} (${formatFindingLocation(finding)})`
+      );
+    }
+  }
+
+  console.log(chalk.yellow.bold("\n⚠️ Warnings"));
+  if (warnings.length === 0) {
+    console.log(chalk.green("  ✅ None"));
+  } else {
+    for (const finding of warnings) {
+      const color = severityColor(finding.severity);
+      const severityTag = color(`[${String(finding.severity).toUpperCase()}]`);
+      console.log(
+        `  - ${severityTag} ${finding.message} (${formatFindingLocation(finding)})`
+      );
+    }
+  }
+
+  console.log(chalk.green.bold("\n✅ Passed Checks"));
+  if (passedChecks.length === 0) {
+    console.log(chalk.yellow("  - None"));
+  } else {
+    for (const check of passedChecks) {
+      console.log(chalk.green(`  - ${check.name}`));
+    }
+  }
+
+  if (skippedChecks.length > 0) {
+    console.log(chalk.gray.bold("\nℹ️ Skipped Checks"));
+    for (const check of skippedChecks) {
+      console.log(chalk.gray(`  - ${check.name}`));
+    }
+  }
+
+  console.log(
+    chalk.bold(
+      `\nSummary: critical=${result.summary.critical}, high=${result.summary.high}, moderate=${result.summary.moderate}, total=${result.summary.totalFindings}`
+    )
+  );
+  console.log(
+    result.summary.blocked
+      ? chalk.red(`Result: BLOCKED (threshold: ${result.summary.severityThreshold})`)
+      : chalk.green(`Result: SAFE (threshold: ${result.summary.severityThreshold})`)
+  );
+}
+
+/**
+ * @param {object} options
+ * @param {boolean} options.json
+ * @param {string} options.cwd
+ * @returns {Promise<void>}
+ */
+async function executeScan(options) {
+  const result = await runScan({ cwd: options.cwd });
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    renderHumanReport(result);
+  }
+
+  process.exitCode = result.summary.blocked ? 1 : 0;
+}
+
+const program = new Command();
+program
+  .name("secure-push-check")
+  .description("Scan local Git repositories for security risks before pushing.")
+  .version(TOOL_VERSION)
+  .showHelpAfterError();
+
+program
+  .command("scan")
+  .description("Run all checks and print a colorized report.")
+  .option("--json", "Output report as JSON.")
+  .option("--cwd <path>", "Working directory to scan.", process.cwd())
+  .action(async (options) => {
+    await executeScan({
+      json: Boolean(options.json),
+      cwd: options.cwd
+    });
+  });
+
+program
+  .command("report")
+  .description("Run all checks and generate a report.")
+  .option("--json", "Output report as JSON.")
+  .option("--cwd <path>", "Working directory to scan.", process.cwd())
+  .action(async (options) => {
+    await executeScan({
+      json: Boolean(options.json),
+      cwd: options.cwd
+    });
+  });
+
+program
+  .command("install")
+  .description("Install secure-push-check as a pre-push Git hook.")
+  .option("--cwd <path>", "Repository path where hook should be installed.", process.cwd())
+  .action(async (options) => {
+    const result = await installPrePushHook({ cwd: options.cwd });
+    console.log(chalk.green(`Pre-push hook ${result.operation} at ${result.hookPath}`));
+  });
+
+try {
+  await program.parseAsync(process.argv);
+} catch (error) {
+  console.error(chalk.red(`Error: ${error.message}`));
+  process.exitCode = 1;
+}

package/src/index.js

@@ -0,0 +1,266 @@
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import { createRequire } from "node:module";
+import { promisify } from "node:util";
+import { scanSecrets } from "./scanners/secrets.js";
+import { scanSensitiveFiles } from "./scanners/files.js";
+import { validateGitignore } from "./scanners/gitignore.js";
+import { scanDependencies } from "./scanners/deps.js";
+import { scanHardcodedCredentials } from "./scanners/credentials.js";
+
+const execFileAsync = promisify(execFile);
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+
+const HOOK_MARKER_START = "# secure-push-check hook start";
+const HOOK_MARKER_END = "# secure-push-check hook end";
+
+const SEVERITY_RANK = {
+  low: 1,
+  moderate: 2,
+  high: 3,
+  critical: 4
+};
+
+export const TOOL_NAME = "secure-push-check";
+export const TOOL_VERSION = pkg.version;
+export const DEFAULT_CONFIG = Object.freeze({
+  ignore: [],
+  allowPatterns: [],
+  severity: "high",
+  secretPatterns: []
+});
+
+/**
+ * @param {unknown} severity
+ * @returns {"low" | "moderate" | "high" | "critical"}
+ */
+export function normalizeSeverity(severity) {
+  const value = String(severity || "").trim().toLowerCase();
+  if (value in SEVERITY_RANK) {
+    return /** @type {"low" | "moderate" | "high" | "critical"} */ (value);
+  }
+  return "high";
+}
+
+/**
+ * @param {unknown} values
+ * @returns {string[]}
+ */
+function uniqueStringList(values) {
+  if (!Array.isArray(values)) {
+    return [];
+  }
+
+  return [...new Set(values.filter((item) => typeof item === "string" && item.trim() !== "").map((item) => item.trim()))];
+}
+
+/**
+ * @param {string} repoRoot
+ * @returns {Promise<object>}
+ */
+export async function loadConfig(repoRoot) {
+  const configPath = path.join(repoRoot, ".securepushrc.json");
+  let parsed = {};
+
+  try {
+    const content = await fs.readFile(configPath, "utf8");
+    parsed = JSON.parse(content);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw new Error(`Failed to parse .securepushrc.json: ${error.message}`);
+    }
+  }
+
+  return {
+    ignore: uniqueStringList(parsed.ignore),
+    allowPatterns: uniqueStringList(parsed.allowPatterns),
+    severity: normalizeSeverity(parsed.severity || DEFAULT_CONFIG.severity),
+    secretPatterns: Array.isArray(parsed.secretPatterns) ? parsed.secretPatterns : [],
+    configPath
+  };
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<string>}
+ */
+export async function findGitRepositoryRoot(cwd = process.cwd()) {
+  try {
+    const { stdout } = await execFileAsync("git", ["rev-parse", "--show-toplevel"], { cwd });
+    const repoRoot = stdout.trim();
+    if (!repoRoot) {
+      throw new Error("Git returned an empty repository path.");
+    }
+    return repoRoot;
+  } catch (error) {
+    throw new Error(`Unable to resolve Git repository root from '${cwd}': ${error.message}`);
+  }
+}
+
+/**
+ * @param {Array<object>} checks
+ * @param {string} severityThreshold
+ * @returns {object}
+ */
+export function createSummary(checks, severityThreshold) {
+  const findings = checks.flatMap((check) => (Array.isArray(check.findings) ? check.findings : []));
+  const severityCounts = {
+    critical: 0,
+    high: 0,
+    moderate: 0,
+    low: 0
+  };
+
+  for (const finding of findings) {
+    const severity = normalizeSeverity(finding.severity);
+    severityCounts[severity] += 1;
+  }
+
+  const threshold = normalizeSeverity(severityThreshold);
+  const blocked = findings.some((finding) => SEVERITY_RANK[normalizeSeverity(finding.severity)] >= SEVERITY_RANK[threshold]);
+
+  return {
+    ...severityCounts,
+    totalFindings: findings.length,
+    passedChecks: checks.filter((check) => check.status === "passed").length,
+    failedChecks: checks.filter((check) => check.status === "failed").length,
+    skippedChecks: checks.filter((check) => check.status === "skipped").length,
+    severityThreshold: threshold,
+    blocked
+  };
+}
+
+/**
+ * @param {object} options
+ * @param {string} [options.cwd]
+ * @returns {Promise<object>}
+ */
+export async function runScan(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const repoRoot = await findGitRepositoryRoot(cwd);
+  const config = await loadConfig(repoRoot);
+
+  const scannerOptions = {
+    repoRoot,
+    ignoreGlobs: config.ignore,
+    allowPatterns: config.allowPatterns,
+    secretPatterns: config.secretPatterns
+  };
+
+  const checks = await Promise.all([
+    scanSecrets(scannerOptions),
+    scanSensitiveFiles(scannerOptions),
+    validateGitignore(scannerOptions),
+    scanDependencies(scannerOptions),
+    scanHardcodedCredentials(scannerOptions)
+  ]);
+
+  const summary = createSummary(checks, config.severity);
+
+  return {
+    tool: TOOL_NAME,
+    version: TOOL_VERSION,
+    scannedAt: new Date().toISOString(),
+    repository: repoRoot,
+    config: {
+      ignore: config.ignore,
+      allowPatterns: config.allowPatterns,
+      severity: config.severity,
+      customSecretPatterns: config.secretPatterns.length
+    },
+    checks,
+    summary
+  };
+}
+
+/**
+ * @returns {string}
+ */
+function createHookSnippet() {
+  return [
+    HOOK_MARKER_START,
+    "if command -v secure-push-check >/dev/null 2>&1; then",
+    "  secure-push-check scan",
+    "  SECURE_PUSH_CHECK_STATUS=$?",
+    "else",
+    "  npx --no-install secure-push-check scan",
+    "  SECURE_PUSH_CHECK_STATUS=$?",
+    "fi",
+    "if [ $SECURE_PUSH_CHECK_STATUS -ne 0 ]; then",
+    "  echo \"secure-push-check blocked this push.\"",
+    "  exit $SECURE_PUSH_CHECK_STATUS",
+    "fi",
+    HOOK_MARKER_END
+  ].join("\n");
+}
+
+/**
+ * @param {string} existingContent
+ * @returns {string}
+ */
+function upsertHookContent(existingContent) {
+  const snippet = createHookSnippet();
+  const content = existingContent || "";
+
+  if (content.trim() === "") {
+    return `#!/bin/sh\n\n${snippet}\n`;
+  }
+
+  if (content.includes(HOOK_MARKER_START) && content.includes(HOOK_MARKER_END)) {
+    const escapedStart = HOOK_MARKER_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const escapedEnd = HOOK_MARKER_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const blockRegex = new RegExp(`${escapedStart}[\\s\\S]*?${escapedEnd}\\n?`, "g");
+    return content.replace(blockRegex, `${snippet}\n`);
+  }
+
+  const separator = content.endsWith("\n") ? "\n" : "\n\n";
+  return `${content}${separator}${snippet}\n`;
+}
+
+/**
+ * Install or update a pre-push Git hook.
+ *
+ * @param {object} options
+ * @param {string} [options.cwd]
+ * @returns {Promise<object>}
+ */
+export async function installPrePushHook(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const repoRoot = await findGitRepositoryRoot(cwd);
+  const hooksDir = path.join(repoRoot, ".git", "hooks");
+  const hookPath = path.join(hooksDir, "pre-push");
+
+  await fs.mkdir(hooksDir, { recursive: true });
+
+  let existingContent = "";
+  try {
+    existingContent = await fs.readFile(hookPath, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  const nextContent = upsertHookContent(existingContent);
+  const operation = existingContent
+    ? existingContent.includes(HOOK_MARKER_START)
+      ? "updated"
+      : "appended"
+    : "created";
+
+  await fs.writeFile(hookPath, nextContent, "utf8");
+
+  try {
+    await fs.chmod(hookPath, 0o755);
+  } catch {
+    // Windows filesystems may ignore chmod, which is safe for this workflow.
+  }
+
+  return {
+    repository: repoRoot,
+    hookPath,
+    operation
+  };
+}