feat(hooks): use gitleaks for knowledge secret scanning when available

Author: skulidropek

scripts/pre-commit-secret-guard.sh

@@ -1,8 +1,8 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# CHANGE: Add bash-only pre-commit guard that redacts secret-like tokens in staged .knowledge/.knowlenge files.
-# WHY: Keep knowledge folders safe to commit even when users paste credentials by mistake.
+# CHANGE: Add staged knowledge secret guard with external scanner support.
+# WHY: Prefer proven scanners (gitleaks) when available, while keeping deterministic fallback redaction.
 
 ROOT_DIR="$(git rev-parse --show-toplevel)"
 cd "$ROOT_DIR"
@@ -11,18 +11,65 @@ command -v git >/dev/null || { echo "ERROR: git is required" >&2; exit 1; }
 command -v perl >/dev/null || { echo "ERROR: perl is required" >&2; exit 1; }
 
 SECRET_PATTERN='(\b(?:github_pat_|gho_|ghp_|ghu_|ghs_|ghr_|gha_)[A-Za-z0-9_]{20,255}\b|\bsk-(?!ant-)(?:proj-)?[A-Za-z0-9_-]{20,}\b|\bsk-ant-[A-Za-z0-9_-]{20,}\b|-----BEGIN(?: [A-Z0-9]+)* PRIVATE KEY-----)'
+HAS_GITLEAKS=0
+
+if command -v gitleaks >/dev/null 2>&1; then
+  HAS_GITLEAKS=1
+fi
 
 is_knowledge_path() {
   local path="$1"
   [[ "$path" =~ (^|/)\.(knowledge|knowlenge)(/|$) ]]
 }
 
+scan_with_gitleaks_file() {
+  local file_path="$1"
+  if [ "$HAS_GITLEAKS" -ne 1 ]; then
+    printf '%s\n' "skip"
+    return
+  fi
+
+  if gitleaks stdin --no-banner --redact --log-level error < "$file_path" >/dev/null 2>&1; then
+    printf '%s\n' "clean"
+    return
+  fi
+
+  local code=$?
+  if [ "$code" -eq 1 ]; then
+    printf '%s\n' "hit"
+    return
+  fi
+
+  printf '%s\n' "error"
+}
+
+staged_blob_to_file() {
+  local path="$1"
+  local out="$2"
+  git cat-file -p ":$path" > "$out"
+}
+
+has_secret_in_staged_blob() {
+  local staged_blob_path="$1"
+  local gitleaks_state
+  gitleaks_state="$(scan_with_gitleaks_file "$staged_blob_path")"
+
+  if [ "$gitleaks_state" = "hit" ]; then
+    return 0
+  fi
+  if grep -Pq "$SECRET_PATTERN" "$staged_blob_path"; then
+    return 0
+  fi
+  return 1
+}
+
 redacted_count=0
 manual_fix_files=()
 has_staged_files=0
 
 TMP_DIR=$(mktemp -d)
 trap 'rm -rf "$TMP_DIR"' EXIT
+index=0
 
 while IFS= read -r -d '' path; do
   if [ -z "$path" ]; then
@@ -37,23 +84,20 @@ while IFS= read -r -d '' path; do
   fi
 
   has_staged_files=1
-  tmp_path="${TMP_DIR}/entry"
-  has_unstaged=false
-
-  if ! git diff --quiet -- "$path"; then
-    has_unstaged=true
+  has_unstaged=true
+  if git diff --quiet -- "$path"; then
+    has_unstaged=false
   fi
 
-  if [ "$has_unstaged" = true ]; then
-    git cat-file -p ":$path" > "$tmp_path"
-    if grep -Pq "$SECRET_PATTERN" "$tmp_path"; then
-      manual_fix_files+=("$path")
-    fi
-
+  index=$((index + 1))
+  tmp_path="${TMP_DIR}/entry-${index}"
+  staged_blob_to_file "$path" "$tmp_path"
+  if ! has_secret_in_staged_blob "$tmp_path"; then
     continue
   fi
 
-  if ! grep -Pq "$SECRET_PATTERN" "$path"; then
+  if [ "$has_unstaged" = true ]; then
+    manual_fix_files+=("$path")
     continue
   fi
 
@@ -64,7 +108,14 @@ while IFS= read -r -d '' path; do
     s/-----BEGIN(?: [A-Z0-9]+)* PRIVATE KEY-----[\s\S]*?-----END(?: [A-Z0-9]+)* PRIVATE KEY-----/<REDACTED_PRIVATE_KEY>/g;
   ' "$path"
   git add -- "$path"
-  redacted_count=$((redacted_count + 1))
+
+  redacted_path="${TMP_DIR}/post-redacted-${index}"
+  staged_blob_to_file "$path" "$redacted_path"
+  if has_secret_in_staged_blob "$redacted_path"; then
+    manual_fix_files+=("$path")
+  else
+    redacted_count=$((redacted_count + 1))
+  fi
 done < <(git diff --cached --name-only --diff-filter=ACM -z)
 
 if [ "$has_staged_files" -eq 0 ]; then
@@ -82,7 +133,11 @@ if [ "${#manual_fix_files[@]}" -gt 0 ]; then
 fi
 
 if [ "$redacted_count" -gt 0 ]; then
-  echo "pre-commit: auto-redacted secrets in $redacted_count staged .knowledge/.knowlenge file(s)."
+  if [ "$HAS_GITLEAKS" -eq 1 ]; then
+    echo "pre-commit: auto-redacted secrets in $redacted_count staged .knowledge/.knowlenge file(s) (scanner: gitleaks + fallback)."
+  else
+    echo "pre-commit: auto-redacted secrets in $redacted_count staged .knowledge/.knowlenge file(s) (scanner: fallback regex)."
+  fi
 fi
 
 exit 0

scripts/pre-push-knowledge-guard.js

@@ -7,7 +7,7 @@
 // SOURCE: n/a
 // FORMAT THEOREM: ∀b ∈ Blobs(pushedRange, knowledgePaths): size(b) ≤ MAX_BYTES ∧ noSecrets(b) → pushAllowed
 // PURITY: SHELL (git IO)
-// INVARIANT: No pushed blob in knowledge paths exceeds MAX_BYTES or matches secret patterns.
+// INVARIANT: No pushed blob in knowledge paths exceeds MAX_BYTES or matches secret patterns (regex + optional gitleaks).
 
 const { execFileSync } = require("node:child_process");
 const fs = require("node:fs");
@@ -45,13 +45,44 @@ const sh = (cmd, args, options = {}) =>
 const shBytes = (cmd, args, options = {}) =>
   execFileSync(cmd, args, { encoding: null, ...options });
 
+const hasGitleaks = (() => {
+  try {
+    execFileSync("gitleaks", ["version"], {
+      encoding: "utf8",
+      stdio: ["ignore", "ignore", "ignore"],
+    });
+    return true;
+  } catch {
+    return false;
+  }
+})();
+
 const toMb = (bytes) => (bytes / 1_000_000).toFixed(2);
 const classifySecret = (text) => {
   for (const pattern of SECRET_PATTERNS) {
     if (pattern.regex.test(text)) return pattern.name;
   }
   return null;
 };
+const scanWithGitleaks = (content) => {
+  if (!hasGitleaks) return "skip";
+  try {
+    execFileSync(
+      "gitleaks",
+      ["stdin", "--no-banner", "--redact", "--log-level", "error"],
+      {
+        encoding: null,
+        stdio: ["pipe", "ignore", "ignore"],
+        input: content,
+      }
+    );
+    return "clean";
+  } catch (error) {
+    const status = typeof error?.status === "number" ? error.status : null;
+    if (status === 1) return "hit";
+    return "error";
+  }
+};
 
 const stdin = fs.readFileSync(0, "utf8").trimEnd();
 if (stdin.length === 0) process.exit(0);
@@ -80,6 +111,7 @@ const oversize = [];
 const secretHits = [];
 const objectToPaths = new Map();
 const oversizeBlobOids = new Set();
+let gitleaksErrorCount = 0;
 
 for (const range of ranges) {
   let revList = "";
@@ -138,14 +170,29 @@ for (const oid of oids) {
   }
   if (content.includes(0)) continue;
 
-  const secretType = classifySecret(content.toString("utf8"));
-  if (secretType === null) continue;
+  const text = content.toString("utf8");
+  const secretType = classifySecret(text);
+  if (secretType !== null) {
+    secretHits.push({
+      oid,
+      paths: objectToPaths.get(oid) ?? new Set(),
+      type: secretType,
+    });
+    continue;
+  }
 
-  secretHits.push({
-    oid,
-    paths: objectToPaths.get(oid) ?? new Set(),
-    type: secretType,
-  });
+  const gitleaksState = scanWithGitleaks(content);
+  if (gitleaksState === "hit") {
+    secretHits.push({
+      oid,
+      paths: objectToPaths.get(oid) ?? new Set(),
+      type: "Gitleaks finding",
+    });
+    continue;
+  }
+  if (gitleaksState === "error") {
+    gitleaksErrorCount += 1;
+  }
 }
 
 if (oversize.length === 0 && secretHits.length === 0) process.exit(0);
@@ -170,6 +217,12 @@ if (secretHits.length > 0) {
   }
 }
 
+if (gitleaksErrorCount > 0) {
+  console.error(
+    `WARN: gitleaks scanner errored for ${gitleaksErrorCount} blob(s); fallback regex checks were used.`
+  );
+}
+
 console.error("");
 console.error("Fix options:");
 console.error(" - For new changes: commit again (pre-commit will split + redact knowledge files).");