push-sentinel 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pmaind
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# push-sentinel
+
+Warns you if secrets are in your git commits before push.
+
+## What it does
+
+Scans the commits you are about to push for potential secrets (API keys, private keys, tokens) and prints a warning. **It does not block the push by default** — it is a safety net, not a gatekeeper.
+
+## Install
+
+```sh
+npx push-sentinel install
+```
+
+This writes a `pre-push` hook to `.git/hooks/`. Any existing hook is preserved as `pre-push.local` and called automatically after the scan.
+
+## Usage
+
+### Automatic (after install)
+
+The hook runs on every `git push`. No action required.
+
+```
+[push-sentinel] ⚠ Potential secrets found:
+
+  [HIGH] src/config.ts:12
+  AKIAIO...
+  → Risk: Full access to AWS resources. Attacker can create/delete instances, incur charges, or exfiltrate data.
+  → To ignore this line: push-sentinel ignore src/config.ts:12
+
+  Push continues. Double-check before sharing.
+```
+
+### Manual scan
+
+```sh
+npx push-sentinel scan
+```
+
+### Block push on HIGH findings
+
+To treat HIGH severity findings as blocking errors, edit `.git/hooks/pre-push` and change the scan line to:
+
+```sh
+npx push-sentinel scan --local-sha "$local_sha" --remote-sha "$remote_sha" --block-on-high
+```
+
+## Suppressing false positives
+
+```sh
+# Ignore a specific line
+push-sentinel ignore src/config.ts:12
+
+# Ignore all matches of a pattern name
+push-sentinel ignore --pattern OPENAI_API_KEY
+
+# List current ignore rules
+push-sentinel ignore --list
+
+# Remove a rule
+push-sentinel ignore --remove OPENAI_API_KEY
+```
+
+Rules are saved to `.push-sentinel-ignore` in the repo root. Add it to `.gitignore` or commit it — your choice.
+
+## Detected patterns
+
+| Pattern | Severity |
+|---------|----------|
+| Private Key (RSA, EC, OPENSSH, DSA, PKCS#8) | HIGH |
+| AWS Access Key (`AKIA...`) | HIGH |
+| AWS Secret Key (entropy-based) | HIGH |
+| GitHub Token (`ghp_`, `github_pat_`) | HIGH |
+| Anthropic API Key (`sk-ant-...`) | MEDIUM |
+| OpenAI API Key (`sk-...`) | MEDIUM |
+| Generic API Key (variable name + high entropy) | LOW |
+| `.env` file committed | MEDIUM |
+
+## Non-blocking design
+
+push-sentinel warns — it does not block — because:
+
+- Blocking creates friction that causes developers to skip or uninstall the hook
+- A warning seen at push time is still early enough to catch accidental leaks
+- Use `--block-on-high` if you want stricter enforcement for HIGH-severity findings
+
+## Uninstall
+
+```sh
+npx push-sentinel uninstall
+```
+
+The original `pre-push` hook (if any) is automatically restored.
+
+## Requirements
+
+- Node.js >= 16
+- No additional dependencies

package/bin/cli.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+'use strict';
+
+const { install, uninstall } = require('../src/install');
+const { scan } = require('../src/scan');
+const { report, hasHighFindings } = require('../src/reporter');
+const { getRepoRoot } = require('../src/utils');
+const fs = require('fs');
+const path = require('path');
+
+const [, , command, ...args] = process.argv;
+
+function getIgnoreFilePath() {
+  return path.join(getRepoRoot(), '.push-sentinel-ignore');
+}
+
+function readIgnoreFile() {
+  const p = getIgnoreFilePath();
+  return fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '';
+}
+
+function writeIgnoreFile(content) {
+  fs.writeFileSync(getIgnoreFilePath(), content, 'utf8');
+}
+
+function handleIgnore(args) {
+  if (args.includes('--list')) {
+    const content = readIgnoreFile();
+    if (!content.trim()) {
+      console.log('[push-sentinel] No ignore rules set.');
+    } else {
+      console.log('[push-sentinel] Ignore rules:');
+      console.log(content);
+    }
+    return;
+  }
+
+  if (args.includes('--remove')) {
+    const idx = args.indexOf('--remove');
+    const target = args[idx + 1];
+    if (!target) {
+      console.error('[push-sentinel] Usage: push-sentinel ignore --remove <pattern>');
+      process.exit(1);
+    }
+    const lines = readIgnoreFile().split('\n').filter((l) => l.trim() !== target);
+    writeIgnoreFile(lines.join('\n'));
+    console.log(`[push-sentinel] Removed ignore rule: ${target}`);
+    return;
+  }
+
+  if (args.includes('--pattern')) {
+    const idx = args.indexOf('--pattern');
+    const pattern = args[idx + 1];
+    if (!pattern) {
+      console.error('[push-sentinel] Usage: push-sentinel ignore --pattern <PATTERN_NAME>');
+      process.exit(1);
+    }
+    const content = readIgnoreFile();
+    if (content.split('\n').some((l) => l.trim() === pattern)) {
+      console.log(`[push-sentinel] Pattern already ignored: ${pattern}`);
+      return;
+    }
+    writeIgnoreFile(content + (content.endsWith('\n') || !content ? '' : '\n') + pattern + '\n');
+    console.log(`[push-sentinel] Added ignore pattern: ${pattern}`);
+    return;
+  }
+
+  const target = args[0];
+  if (!target) {
+    console.error('[push-sentinel] Usage: push-sentinel ignore <file>:<line>');
+    console.error('               push-sentinel ignore --pattern <PATTERN_NAME>');
+    console.error('               push-sentinel ignore --list');
+    console.error('               push-sentinel ignore --remove <entry>');
+    process.exit(1);
+  }
+  const content = readIgnoreFile();
+  if (content.split('\n').some((l) => l.trim() === target)) {
+    console.log(`[push-sentinel] Already ignored: ${target}`);
+    return;
+  }
+  writeIgnoreFile(content + (content.endsWith('\n') || !content ? '' : '\n') + target + '\n');
+  console.log(`[push-sentinel] Added ignore rule: ${target}`);
+}
+
+switch (command) {
+  case 'install':
+    install();
+    break;
+
+  case 'uninstall':
+    uninstall();
+    break;
+
+  case 'scan': {
+    // --block-on-high: exit 1 if any HIGH severity findings are detected, blocking the push
+    const blockOnHigh = args.includes('--block-on-high');
+    // --local-sha / --remote-sha: passed by the pre-push hook from git's stdin
+    const localShaIdx = args.indexOf('--local-sha');
+    const remoteShaIdx = args.indexOf('--remote-sha');
+    const localSha = localShaIdx !== -1 ? args[localShaIdx + 1] : undefined;
+    const remoteSha = remoteShaIdx !== -1 ? args[remoteShaIdx + 1] : undefined;
+    const findings = scan(localSha, remoteSha);
+    report(findings);
+    if (blockOnHigh && hasHighFindings(findings)) {
+      process.stderr.write('\n[push-sentinel] Push blocked: HIGH severity secret(s) detected. Remove the secret or run `push-sentinel ignore` to suppress.\n');
+      process.exit(1);
+    }
+    process.exit(0);
+    break;
+  }
+
+  case 'ignore':
+    handleIgnore(args);
+    break;
+
+  default:
+    console.log('push-sentinel: Warns you if secrets are in your git diff before push.\n');
+    console.log('Usage:');
+    console.log('  push-sentinel install                 Install pre-push hook');
+    console.log('  push-sentinel uninstall               Remove pre-push hook');
+    console.log('  push-sentinel scan                    Manually run secret scan (warn only)');
+    console.log('  push-sentinel scan --block-on-high    Block push if HIGH findings detected');
+    console.log('  push-sentinel ignore <file:line>      Ignore a specific finding');
+    console.log('  push-sentinel ignore --pattern <NAME> Ignore a pattern');
+    console.log('  push-sentinel ignore --list           Show all ignore rules');
+    console.log('  push-sentinel ignore --remove <entry> Remove an ignore rule');
+    break;
+}

package/hook-template.sh

@@ -0,0 +1,26 @@
+#!/bin/sh
+# push-sentinel
+#
+# Git passes pushed ref information via stdin, one line per ref being pushed:
+#   <local-ref> <local-sha1> <remote-ref> <remote-sha1>
+#
+# We read each line and pass the SHAs explicitly so push-sentinel can compute
+# the exact range of commits being pushed (including new branch / first push).
+
+EXIT_CODE=0
+
+while read local_ref local_sha remote_ref remote_sha; do
+  npx push-sentinel scan --local-sha "$local_sha" --remote-sha "$remote_sha"
+  RESULT=$?
+  if [ $RESULT -ne 0 ]; then
+    EXIT_CODE=$RESULT
+  fi
+done
+
+if [ $EXIT_CODE -ne 0 ]; then
+  exit $EXIT_CODE
+fi
+
+if [ -f "$(git rev-parse --git-dir)/hooks/pre-push.local" ]; then
+  "$(git rev-parse --git-dir)/hooks/pre-push.local" "$@"
+fi

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "push-sentinel",
+  "version": "0.1.0",
+  "description": "Warns you if secrets are in your git diff before push.",
+  "bin": {
+    "push-sentinel": "bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "hook-template.sh"
+  ],
+  "keywords": [
+    "git",
+    "pre-push",
+    "secrets",
+    "security",
+    "hook"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pmaind/pre-push-secrets.git"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "dependencies": {}
+}

package/src/install.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const SENTINEL_MARKER = '# push-sentinel';
+
+function getGitDir() {
+  try {
+    return execSync('git rev-parse --git-dir', { encoding: 'utf8' }).trim();
+  } catch {
+    throw new Error('Not inside a git repository.');
+  }
+}
+
+function getHookPath(gitDir) {
+  return path.join(gitDir, 'hooks', 'pre-push');
+}
+
+function getLocalHookPath(gitDir) {
+  return path.join(gitDir, 'hooks', 'pre-push.local');
+}
+
+// Wrapper hook content (spec 4.2)
+// Reads git's stdin (one line per ref being pushed) and passes each SHA pair
+// to push-sentinel so it can compute the exact commit range being pushed.
+function hookContent() {
+  return `#!/bin/sh
+${SENTINEL_MARKER}
+#
+# Git passes pushed ref information via stdin, one line per ref:
+#   <local-ref> <local-sha1> <remote-ref> <remote-sha1>
+# We forward the SHAs so push-sentinel can determine exactly which commits
+# are being pushed, including new branches (remote-sha = 0000...0000).
+
+EXIT_CODE=0
+
+while read local_ref local_sha remote_ref remote_sha; do
+  npx push-sentinel scan --local-sha "$local_sha" --remote-sha "$remote_sha"
+  RESULT=$?
+  if [ $RESULT -ne 0 ]; then
+    EXIT_CODE=$RESULT
+  fi
+done
+
+if [ $EXIT_CODE -ne 0 ]; then
+  exit $EXIT_CODE
+fi
+
+if [ -f "$(git rev-parse --git-dir)/hooks/pre-push.local" ]; then
+  "$(git rev-parse --git-dir)/hooks/pre-push.local" "$@"
+fi
+`;
+}
+
+function install() {
+  const gitDir = getGitDir();
+  const hookPath = getHookPath(gitDir);
+  const localPath = getLocalHookPath(gitDir);
+
+  // Idempotency: already installed
+  if (fs.existsSync(hookPath)) {
+    const existing = fs.readFileSync(hookPath, 'utf8');
+    if (existing.includes(SENTINEL_MARKER)) {
+      console.log('[push-sentinel] Already installed.');
+      return;
+    }
+    // Preserve existing hook as pre-push.local (spec 4.2)
+    fs.renameSync(hookPath, localPath);
+    fs.chmodSync(localPath, 0o755);
+    console.log('[push-sentinel] Existing pre-push hook preserved as pre-push.local.');
+  }
+
+  fs.writeFileSync(hookPath, hookContent(), 'utf8');
+  fs.chmodSync(hookPath, 0o755);
+  console.log('[push-sentinel] Installed pre-push hook.');
+  console.log('[push-sentinel] Tip: to block pushes on HIGH findings, edit the hook to use: npx push-sentinel scan --block-on-high');
+}
+
+function uninstall() {
+  const gitDir = getGitDir();
+  const hookPath = getHookPath(gitDir);
+  const localPath = getLocalHookPath(gitDir);
+
+  if (!fs.existsSync(hookPath)) {
+    console.log('[push-sentinel] No pre-push hook found.');
+    return;
+  }
+
+  const content = fs.readFileSync(hookPath, 'utf8');
+  if (!content.includes(SENTINEL_MARKER)) {
+    console.log('[push-sentinel] push-sentinel hook not found. Nothing to remove.');
+    return;
+  }
+
+  fs.unlinkSync(hookPath);
+
+  // Restore pre-push.local if it exists (spec 4.2)
+  if (fs.existsSync(localPath)) {
+    fs.renameSync(localPath, hookPath);
+    console.log('[push-sentinel] Uninstalled. Original pre-push hook restored.');
+  } else {
+    console.log('[push-sentinel] Uninstalled.');
+  }
+}
+
+module.exports = { install, uninstall };

package/src/patterns.js

@@ -0,0 +1,51 @@
+'use strict';
+
+// Detection patterns per design spec section 2.2
+const PATTERNS = [
+  {
+    name: 'Private Key',
+    severity: 'HIGH',
+    // Covers RSA, EC, OPENSSH, DSA, ECDSA, and PKCS#8 (PRIVATE KEY)
+    regex: /-----BEGIN (RSA |EC |OPENSSH |DSA |ECDSA )?PRIVATE KEY-----/,
+    risk: 'Full server/certificate takeover. Attacker can impersonate your server or decrypt all traffic.',
+  },
+  {
+    name: 'AWS Access Key',
+    severity: 'HIGH',
+    regex: /AKIA[0-9A-Z]{16}/,
+    risk: 'Full access to AWS resources. Attacker can create/delete instances, incur charges, or exfiltrate data.',
+  },
+  {
+    name: 'GitHub Token',
+    severity: 'HIGH',
+    // ghp_ tokens are 36 chars; github_pat_ tokens are longer — require at least 36 chars after prefix
+    regex: /ghp_[a-zA-Z0-9]{36}|github_pat_[a-zA-Z0-9_]{36,}/,
+    risk: 'Full read/write access to your GitHub repositories, including deletion.',
+  },
+  {
+    // Must appear before OpenAI: sk-ant-... also matches the broader sk- pattern
+    name: 'Anthropic API Key',
+    severity: 'MEDIUM',
+    regex: /sk-ant-[a-zA-Z0-9\-]{32,}/,
+    risk: 'Unauthorized API usage billed to your account. Possible data access.',
+  },
+  {
+    name: 'OpenAI API Key',
+    severity: 'MEDIUM',
+    // Matches sk-proj-..., sk-...-..., and legacy sk-... formats (dash included in character class)
+    regex: /sk-[a-zA-Z0-9\-]{32,}/,
+    risk: 'Unauthorized API usage billed to your account. Possible data access.',
+  },
+  {
+    name: 'Generic API Key',
+    severity: 'LOW',
+    regex: /[Aa][Pp][Ii]_?[Kk][Ee][Yy]\s*=\s*["']?([^\s"']{16,})/,
+    risk: 'Depends on the service. May allow unauthorized access or actions.',
+    captureGroup: 1,
+  },
+];
+
+// AWS Secret Key is detected by variable name filter + high entropy (no fixed prefix pattern)
+// handled in scan.js via variable name filter + entropy check
+
+module.exports = { PATTERNS };

package/src/reporter.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const MAX_FINDINGS = 10;
+
+// Show only the first 6 characters and mask the rest to minimise log exposure
+function maskValue(value) {
+  if (!value) return '(staged file)';
+  const show = Math.min(6, value.length);
+  return value.slice(0, show) + 'x'.repeat(Math.max(0, value.length - show)) + '...';
+}
+
+function severityLabel(severity) {
+  return `[${severity}]`;
+}
+
+function report(findings) {
+  if (findings.length === 0) {
+    process.stderr.write('[push-sentinel] \u2713 No secrets detected.\n');
+    return;
+  }
+
+  const shown = findings.slice(0, MAX_FINDINGS);
+  const extra = findings.length - shown.length;
+
+  process.stderr.write('[push-sentinel] \u26a0 Potential secrets found:\n\n');
+
+  for (const f of shown) {
+    const location = f.lineNum ? `${f.file}:${f.lineNum}` : f.file;
+    process.stderr.write(`  ${severityLabel(f.severity)} ${location}\n`);
+    process.stderr.write(`  ${maskValue(f.matchedValue)}\n`);
+    process.stderr.write(`  \u2192 Risk: ${f.risk}\n`);
+    if (f.lineNum) {
+      process.stderr.write(`  \u2192 To ignore this line: push-sentinel ignore ${location}\n`);
+    }
+    process.stderr.write('\n');
+  }
+
+  if (extra > 0) {
+    process.stderr.write(`  + ${extra} more finding(s) not shown.\n\n`);
+  }
+
+  process.stderr.write('  Push continues. Double-check before sharing.\n');
+}
+
+function hasHighFindings(findings) {
+  return findings.some((f) => f.severity === 'HIGH');
+}
+
+module.exports = { report, hasHighFindings };

package/src/scan.js

@@ -0,0 +1,266 @@
+'use strict';
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { PATTERNS } = require('./patterns');
+const { getRepoRoot } = require('./utils');
+
+// Zero SHA: indicates a new branch with no history on the remote
+const ZERO_SHA = '0000000000000000000000000000000000000000';
+
+// Variable name keywords that must appear on the line (false positive filter, spec 2.3 rule ①)
+const VAR_NAME_KEYWORDS = /API|SECRET|TOKEN|KEY|PASSWORD/i;
+
+// Shannon entropy calculation (spec 2.3 rule ②)
+function shannonEntropy(str) {
+  const freq = {};
+  for (const c of str) {
+    freq[c] = (freq[c] || 0) + 1;
+  }
+  let h = 0;
+  const len = str.length;
+  for (const count of Object.values(freq)) {
+    const p = count / len;
+    h -= p * Math.log2(p);
+  }
+  return h;
+}
+
+// Check if a candidate string is high-entropy (spec 2.3 rule ②)
+function isHighEntropy(candidate) {
+  if (candidate.length < 16) return false;
+  if (/^(.)\1+$/.test(candidate)) return false;
+  return shannonEntropy(candidate) >= 3.5;
+}
+
+// Load .push-sentinel-ignore (spec 2.3 / 2.4)
+function loadIgnoreRules(repoRoot) {
+  const ignoreFile = path.join(repoRoot, '.push-sentinel-ignore');
+  if (!fs.existsSync(ignoreFile)) return { lines: [], patterns: [] };
+
+  const content = fs.readFileSync(ignoreFile, 'utf8');
+  const lines = [];
+  const patterns = [];
+
+  for (const raw of content.split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    if (/[:\/\\*?]/.test(line) || line.includes('.')) {
+      lines.push(line);
+    } else {
+      patterns.push(line.toUpperCase());
+    }
+  }
+  return { lines, patterns };
+}
+
+// Check if a file (regardless of line) matches any ignore rule
+function matchesIgnoreFile(filePath, ignoreLines) {
+  for (const rule of ignoreLines) {
+    if (rule === filePath) return true;
+    if (rule.endsWith('/**')) {
+      const dir = rule.slice(0, -3);
+      if (filePath.startsWith(dir + '/') || filePath === dir) return true;
+    }
+    if (rule.endsWith('*')) {
+      if (filePath.startsWith(rule.slice(0, -1))) return true;
+    }
+  }
+  return false;
+}
+
+// Check if a file:line matches any ignore rule (simple glob support)
+function matchesIgnoreLine(filePath, lineNum, ignoreLines) {
+  const target = `${filePath}:${lineNum}`;
+  for (const rule of ignoreLines) {
+    if (rule === target) return true;
+    if (rule.endsWith('/**')) {
+      const dir = rule.slice(0, -3);
+      if (filePath.startsWith(dir + '/') || filePath === dir) return true;
+    }
+    if (rule.endsWith('*')) {
+      if (filePath.startsWith(rule.slice(0, -1))) return true;
+    }
+  }
+  return false;
+}
+
+// Check if the line content is a test/fake/example dummy (spec 2.3)
+function isDummyValue(line) {
+  return /\b(test_|fake_|example_|dummy_|placeholder)/i.test(line);
+}
+
+// Build the git log command args for the range of commits being pushed.
+// localSha/remoteSha come from the pre-push hook stdin (see hook-template.sh).
+// When called manually (no SHAs), falls back to @{u}..HEAD then last commit.
+function getDiffArgs(localSha, remoteSha) {
+  if (localSha && remoteSha) {
+    if (remoteSha === ZERO_SHA) {
+      // New branch: scan commits not yet reachable from any remote
+      return ['log', '--not', '--remotes', '-p', localSha];
+    }
+    return ['log', `${remoteSha}..${localSha}`, '-p'];
+  }
+  // Manual scan: use upstream range, or fall back to last commit
+  return null;
+}
+
+function getFileListArgs(localSha, remoteSha) {
+  if (localSha && remoteSha) {
+    if (remoteSha === ZERO_SHA) {
+      return ['log', '--not', '--remotes', '--name-only', '--format=', localSha];
+    }
+    return ['diff', '--name-only', `${remoteSha}..${localSha}`];
+  }
+  return null;
+}
+
+function runGit(args) {
+  const result = spawnSync('git', args, { encoding: 'utf8', stdio: 'pipe' });
+  return result.status === 0 ? (result.stdout || '') : null;
+}
+
+function getPushDiff(localSha, remoteSha) {
+  const args = getDiffArgs(localSha, remoteSha);
+  if (args) {
+    const out = runGit(args);
+    if (out !== null) return out;
+  }
+  // Fallback for manual scan
+  return runGit(['log', '@{u}..HEAD', '-p']) ?? runGit(['log', '-1', '-p', 'HEAD']) ?? '';
+}
+
+function getPushedFileList(localSha, remoteSha) {
+  const args = getFileListArgs(localSha, remoteSha);
+  if (args) {
+    const out = runGit(args);
+    if (out !== null) return out.split('\n').map((f) => f.trim()).filter(Boolean);
+  }
+  // Fallback for manual scan
+  const out = runGit(['diff', '--name-only', '@{u}..HEAD'])
+    ?? runGit(['diff', '--name-only', 'HEAD~1..HEAD'])
+    ?? '';
+  return out.split('\n').map((f) => f.trim()).filter(Boolean);
+}
+
+// Parse diff output into added lines: { file, lineNum, content }
+function parseDiffAddedLines(diff) {
+  const results = [];
+  let currentFile = null;
+  let lineNum = 0;
+
+  for (const line of diff.split('\n')) {
+    const fileMatch = line.match(/^\+\+\+ b\/(.+)$/);
+    if (fileMatch) {
+      currentFile = fileMatch[1];
+      lineNum = 0;
+      continue;
+    }
+    const hunkMatch = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+    if (hunkMatch) {
+      lineNum = parseInt(hunkMatch[1], 10) - 1;
+      continue;
+    }
+    if (!currentFile) continue;
+
+    if (line.startsWith('+') && !line.startsWith('+++')) {
+      lineNum++;
+      results.push({ file: currentFile, lineNum, content: line.slice(1) });
+    } else if (!line.startsWith('-')) {
+      lineNum++;
+    }
+  }
+  return results;
+}
+
+// localSha / remoteSha: passed from the pre-push hook via --local-sha / --remote-sha flags.
+// When omitted (manual scan), falls back to upstream-based diff.
+function scan(localSha, remoteSha) {
+  // Ref deletion (git push origin :branch): local_sha is all zeros.
+  // There are no commits to scan — return immediately to avoid falling back
+  // to @{u}..HEAD and producing spurious warnings.
+  if (localSha === ZERO_SHA) return [];
+  const repoRoot = getRepoRoot();
+  const ignore = loadIgnoreRules(repoRoot);
+  const findings = [];
+
+  // .env file check (spec 2.2 / 2.3 rule ③)
+  // Note: files appearing in the push diff are tracked by git.
+  // We do NOT skip based on .gitignore — a tracked file in .gitignore can still leak secrets.
+  const pushedFiles = getPushedFileList(localSha, remoteSha);
+  for (const f of pushedFiles) {
+    if (f === '.env' || f.endsWith('/.env') || /^\.env(\.|$)/.test(path.basename(f))) {
+      if (!matchesIgnoreFile(f, ignore.lines)) {
+        findings.push({
+          file: f,
+          lineNum: null,
+          matchedValue: null,
+          severity: 'MEDIUM',
+          patternName: '.env file',
+          risk: 'Committing a .env file may expose multiple secrets at once.',
+        });
+      }
+    }
+  }
+
+  const diff = getPushDiff(localSha, remoteSha);
+  if (!diff) return findings;
+
+  const addedLines = parseDiffAddedLines(diff);
+
+  for (const { file, lineNum, content } of addedLines) {
+    // Files appearing in a push diff are tracked; we do NOT skip based on .gitignore.
+    if (matchesIgnoreLine(file, lineNum, ignore.lines)) continue;
+    if (isDummyValue(content)) continue;
+
+    let matched = false;
+    for (const pattern of PATTERNS) {
+      const skipVarFilter = ['Private Key', 'AWS Access Key', 'GitHub Token', 'OpenAI API Key', 'Anthropic API Key'];
+      if (!skipVarFilter.includes(pattern.name) && !VAR_NAME_KEYWORDS.test(content)) continue;
+
+      if (ignore.patterns.includes(pattern.name.toUpperCase().replace(/\s+/g, '_'))) continue;
+      const lineUpper = content.toUpperCase();
+      if (ignore.patterns.some((p) => lineUpper.includes(p))) continue;
+
+      const match = content.match(pattern.regex);
+      if (!match) continue;
+
+      const candidate = pattern.captureGroup ? match[pattern.captureGroup] : match[0];
+      if (pattern.name === 'Generic API Key' && !isHighEntropy(candidate)) continue;
+
+      findings.push({
+        file,
+        lineNum,
+        matchedValue: candidate,
+        severity: pattern.severity,
+        patternName: pattern.name,
+        risk: pattern.risk,
+      });
+      matched = true;
+      break;
+    }
+
+    if (matched) continue;
+
+    // AWS Secret Key: variable name + high entropy (no fixed prefix)
+    // isDummyValue and matchesIgnoreLine are already checked above
+    if (VAR_NAME_KEYWORDS.test(content) && /AWS.*SECRET|SECRET.*AWS/i.test(content)) {
+      const valueMatch = content.match(/[a-zA-Z0-9/+=]{40}/);
+      if (valueMatch && isHighEntropy(valueMatch[0])) {
+        findings.push({
+          file,
+          lineNum,
+          matchedValue: valueMatch[0],
+          severity: 'HIGH',
+          patternName: 'AWS Secret Key',
+          risk: 'Full access to AWS resources. Attacker can create/delete instances, incur charges, or exfiltrate data.',
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+module.exports = { scan };

package/src/utils.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const { execSync } = require('child_process');
+
+function getRepoRoot() {
+  try {
+    return execSync('git rev-parse --show-toplevel', { encoding: 'utf8' }).trim();
+  } catch {
+    return process.cwd();
+  }
+}
+
+module.exports = { getRepoRoot };