push-sentinel 0.1.0 → 0.1.2

package/README.md

@@ -1,88 +1,79 @@
 # push-sentinel
 
-Warns you if secrets are in your git commits before push.
+**Catches secrets in your git commits before they leave your machine.**
 
-## What it does
+You've seen the stories. Someone pushes an AWS key to a public repo. Bots scrape GitHub in seconds. The bill arrives the next morning: $8,000.
 
-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.
+push-sentinel sits in your `pre-push` hook and warns you before that happens.
 
-## Install
-
-```sh
-npx push-sentinel install
 ```
+$ git push
 
-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.
+  → 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
+## Install
 
 ```sh
-npx push-sentinel scan
+npx push-sentinel install
 ```
 
-### Block push on HIGH findings
+That's it. Runs automatically on every `git push` from now on.
 
-To treat HIGH severity findings as blocking errors, edit `.git/hooks/pre-push` and change the scan line to:
+## What it detects
 
-```sh
-npx push-sentinel scan --local-sha "$local_sha" --remote-sha "$remote_sha" --block-on-high
-```
+| 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 |
 
-## Suppressing false positives
+## False positive? Ignore it in one command
 
 ```sh
-# Ignore a specific line
-push-sentinel ignore src/config.ts:12
+push-sentinel ignore src/config.ts:12          # ignore a specific line
+push-sentinel ignore --pattern OPENAI_API_KEY  # ignore a pattern everywhere
+push-sentinel ignore --list                    # see all ignore rules
+```
 
-# Ignore all matches of a pattern name
-push-sentinel ignore --pattern OPENAI_API_KEY
+Rules are saved to `.push-sentinel-ignore` in your repo root.
 
-# List current ignore rules
-push-sentinel ignore --list
+## Why warning-only by default?
 
-# Remove a rule
-push-sentinel ignore --remove OPENAI_API_KEY
-```
+Blocking pushes creates friction. Friction leads to `--no-verify`. A warning at push time is early enough to catch real accidents — and you'll actually leave it installed.
 
-Rules are saved to `.push-sentinel-ignore` in the repo root. Add it to `.gitignore` or commit it — your choice.
+Want hard blocking for HIGH findings? Add `--block-on-high`:
 
-## Detected patterns
+```sh
+# edit .git/hooks/pre-push, change the scan line to:
+npx push-sentinel scan --local-sha "$local_sha" --remote-sha "$remote_sha" --block-on-high
+```
 
-| 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 |
+## Manual scan
 
-## Non-blocking design
+```sh
+npx push-sentinel scan
+```
 
-push-sentinel warns — it does not block — because:
+Manual scan checks, in order:
 
-- 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
+- commits not yet pushed to your upstream
+- staged changes
+- unstaged working tree changes
+- the last commit as a final fallback
 
 ## Uninstall
 
@@ -90,9 +81,11 @@ push-sentinel warns — it does not block — because:
 npx push-sentinel uninstall
 ```
 
-The original `pre-push` hook (if any) is automatically restored.
+Your original `pre-push` hook is restored automatically.
 
-## Requirements
+## Details
 
+- Scans only the commits being pushed — not your entire history
+- Zero dependencies (Node.js stdlib only)
 - Node.js >= 16
-- No additional dependencies
+- Existing `pre-push` hooks are preserved and still run

package/bin/cli.js

@@ -100,8 +100,9 @@ switch (command) {
     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)) {
+    const willBlock = blockOnHigh && hasHighFindings(findings);
+    report(findings, { willBlock });
+    if (willBlock) {
       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);
     }

package/hook-template.sh

@@ -6,10 +6,14 @@
 #
 # 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).
+# Stdin is saved and re-supplied to pre-push.local so existing hooks still work.
 
 EXIT_CODE=0
+STDIN_DATA=""
 
 while read local_ref local_sha remote_ref remote_sha; do
+  STDIN_DATA="${STDIN_DATA}${local_ref} ${local_sha} ${remote_ref} ${remote_sha}
+"
   npx push-sentinel scan --local-sha "$local_sha" --remote-sha "$remote_sha"
   RESULT=$?
   if [ $RESULT -ne 0 ]; then
@@ -22,5 +26,5 @@ if [ $EXIT_CODE -ne 0 ]; then
 fi
 
 if [ -f "$(git rev-parse --git-dir)/hooks/pre-push.local" ]; then
-  "$(git rev-parse --git-dir)/hooks/pre-push.local" "$@"
+  echo "$STDIN_DATA" | "$(git rev-parse --git-dir)/hooks/pre-push.local" "$@"
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "push-sentinel",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Warns you if secrets are in your git diff before push.",
   "bin": {
     "push-sentinel": "bin/cli.js"

package/src/install.js

@@ -33,10 +33,14 @@ ${SENTINEL_MARKER}
 #   <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).
+# Stdin is saved and re-supplied to pre-push.local so existing hooks still work.
 
 EXIT_CODE=0
+STDIN_DATA=""
 
 while read local_ref local_sha remote_ref remote_sha; do
+  STDIN_DATA="${'$'}{STDIN_DATA}${'$'}{local_ref} ${'$'}{local_sha} ${'$'}{remote_ref} ${'$'}{remote_sha}
+"
   npx push-sentinel scan --local-sha "$local_sha" --remote-sha "$remote_sha"
   RESULT=$?
   if [ $RESULT -ne 0 ]; then
@@ -49,7 +53,7 @@ if [ $EXIT_CODE -ne 0 ]; then
 fi
 
 if [ -f "$(git rev-parse --git-dir)/hooks/pre-push.local" ]; then
-  "$(git rev-parse --git-dir)/hooks/pre-push.local" "$@"
+  echo "$STDIN_DATA" | "$(git rev-parse --git-dir)/hooks/pre-push.local" "$@"
 fi
 `;
 }

package/src/reporter.js

@@ -13,7 +13,7 @@ function severityLabel(severity) {
   return `[${severity}]`;
 }
 
-function report(findings) {
+function report(findings, { willBlock = false } = {}) {
   if (findings.length === 0) {
     process.stderr.write('[push-sentinel] \u2713 No secrets detected.\n');
     return;
@@ -39,7 +39,11 @@ function report(findings) {
     process.stderr.write(`  + ${extra} more finding(s) not shown.\n\n`);
   }
 
-  process.stderr.write('  Push continues. Double-check before sharing.\n');
+  if (willBlock) {
+    process.stderr.write('  Push will be blocked.\n');
+  } else {
+    process.stderr.write('  Push continues. Double-check before sharing.\n');
+  }
 }
 
 function hasHighFindings(findings) {

package/src/scan.js

@@ -55,33 +55,31 @@ function loadIgnoreRules(repoRoot) {
   return { lines, patterns };
 }
 
+// Check if a file path matches a single glob-style ignore rule
+function matchesGlob(filePath, rule) {
+  if (rule.endsWith('/**')) {
+    const dir = rule.slice(0, -3);
+    return filePath.startsWith(dir + '/') || filePath === dir;
+  }
+  if (rule.endsWith('*')) {
+    return filePath.startsWith(rule.slice(0, -1));
+  }
+  return false;
+}
+
 // 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;
-    }
+    if (rule === filePath || matchesGlob(filePath, rule)) return true;
   }
   return false;
 }
 
-// Check if a file:line matches any ignore rule (simple glob support)
+// Check if a file:line matches any ignore rule
 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;
-    }
+    if (rule === target || matchesGlob(filePath, rule)) return true;
   }
   return false;
 }
@@ -121,14 +119,24 @@ function runGit(args) {
   return result.status === 0 ? (result.stdout || '') : null;
 }
 
+function runGitNonEmpty(args) {
+  const out = runGit(args);
+  return out && out.trim() ? out : 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']) ?? '';
+  // Manual scan: inspect unpushed commits first, then staged changes, then working tree,
+  // and finally fall back to the last commit if none of those produce a diff.
+  return runGitNonEmpty(['log', '@{u}..HEAD', '-p'])
+    ?? runGitNonEmpty(['diff', '--cached'])
+    ?? runGitNonEmpty(['diff'])
+    ?? runGit(['log', '-1', '-p', 'HEAD'])
+    ?? '';
 }
 
 function getPushedFileList(localSha, remoteSha) {
@@ -137,8 +145,10 @@ function getPushedFileList(localSha, remoteSha) {
     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'])
+  // Manual scan: include files from unpushed commits, staged changes, and working tree.
+  const out = runGitNonEmpty(['diff', '--name-only', '@{u}..HEAD'])
+    ?? runGitNonEmpty(['diff', '--name-only', '--cached'])
+    ?? runGitNonEmpty(['diff', '--name-only'])
     ?? runGit(['diff', '--name-only', 'HEAD~1..HEAD'])
     ?? '';
   return out.split('\n').map((f) => f.trim()).filter(Boolean);