@rafter-security/cli 0.5.1 → 0.5.3

package/dist/commands/completion.js

@@ -0,0 +1,170 @@
+import { Command } from "commander";
+const BASH_COMPLETION = `
+# rafter bash completion
+# Add to ~/.bashrc: eval "$(rafter completion bash)"
+_rafter_completion() {
+  local cur prev words
+  COMPREPLY=()
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  prev="\${COMP_WORDS[COMP_CWORD-1]}"
+  words="\${COMP_WORDS[*]}"
+
+  local top_cmds="run scan get usage agent ci hook mcp policy completion --help --version"
+  local agent_cmds="init scan exec config audit audit-skill install-hook verify status"
+  local ci_cmds="init"
+  local hook_cmds="pretool posttool"
+  local policy_cmds="export"
+
+  if [[ \${COMP_CWORD} -eq 1 ]]; then
+    COMPREPLY=( \$(compgen -W "\${top_cmds}" -- "\${cur}") )
+    return 0
+  fi
+
+  case "\${COMP_WORDS[1]}" in
+    agent)
+      if [[ \${COMP_CWORD} -eq 2 ]]; then
+        COMPREPLY=( \$(compgen -W "\${agent_cmds}" -- "\${cur}") )
+      fi
+      case "\${COMP_WORDS[2]}" in
+        scan)  COMPREPLY=( \$(compgen -W "--quiet --json --format --staged --diff --engine" -- "\${cur}") ) ;;
+        init)  COMPREPLY=( \$(compgen -W "--risk-level --skip-gitleaks --skip-openclaw --skip-claude-code --force" -- "\${cur}") ) ;;
+        verify) COMPREPLY=() ;;
+        status) COMPREPLY=() ;;
+        audit-skill) COMPREPLY=( \$(compgen -W "--skip-openclaw --json" -- "\${cur}") ) ;;
+        install-hook) COMPREPLY=( \$(compgen -W "--global" -- "\${cur}") ) ;;
+        config) COMPREPLY=( \$(compgen -W "show get set" -- "\${cur}") ) ;;
+        audit)  COMPREPLY=( \$(compgen -W "--last --event --agent --since" -- "\${cur}") ) ;;
+      esac
+      ;;
+    hook)
+      COMPREPLY=( \$(compgen -W "\${hook_cmds}" -- "\${cur}") )
+      ;;
+    ci)
+      if [[ \${COMP_CWORD} -eq 2 ]]; then
+        COMPREPLY=( \$(compgen -W "\${ci_cmds}" -- "\${cur}") )
+      fi
+      ;;
+    policy)
+      COMPREPLY=( \$(compgen -W "\${policy_cmds}" -- "\${cur}") )
+      ;;
+    run|scan)
+      COMPREPLY=( \$(compgen -W "--api-key --format --quiet" -- "\${cur}") )
+      ;;
+    completion)
+      COMPREPLY=( \$(compgen -W "bash zsh fish" -- "\${cur}") )
+      ;;
+  esac
+}
+complete -F _rafter_completion rafter
+`;
+const ZSH_COMPLETION = `
+# rafter zsh completion
+# Add to ~/.zshrc: eval "$(rafter completion zsh)"
+#compdef rafter
+
+_rafter() {
+  local state
+  typeset -A opt_args
+
+  _arguments \\
+    '1: :->cmd' \\
+    '*: :->args'
+
+  case \$state in
+    cmd)
+      _values 'command' \\
+        'run[Run a security scan via backend]' \\
+        'scan[Alias for run]' \\
+        'agent[Agent security features]' \\
+        'ci[CI/CD integration]' \\
+        'hook[Hook handlers]' \\
+        'mcp[MCP server]' \\
+        'policy[Policy management]' \\
+        'completion[Shell completion scripts]'
+      ;;
+    args)
+      case \$words[2] in
+        agent)
+          _values 'subcommand' \\
+            'init[Initialize agent security]' \\
+            'scan[Scan for secrets]' \\
+            'exec[Execute command with security validation]' \\
+            'config[Manage configuration]' \\
+            'audit[View audit logs]' \\
+            'audit-skill[Audit a skill file]' \\
+            'install-hook[Install git pre-commit hook]' \\
+            'verify[Health check]' \\
+            'status[Status dashboard]'
+          ;;
+        hook)
+          _values 'subcommand' 'pretool[PreToolUse handler]' 'posttool[PostToolUse handler]'
+          ;;
+        completion)
+          _values 'shell' 'bash' 'zsh' 'fish'
+          ;;
+      esac
+      ;;
+  esac
+}
+
+_rafter
+`;
+const FISH_COMPLETION = `
+# rafter fish completion
+# Save to ~/.config/fish/completions/rafter.fish
+# Or: rafter completion fish > ~/.config/fish/completions/rafter.fish
+
+complete -c rafter -f
+complete -c rafter -n '__fish_use_subcommand' -a 'run' -d 'Run a security scan via backend'
+complete -c rafter -n '__fish_use_subcommand' -a 'agent' -d 'Agent security features'
+complete -c rafter -n '__fish_use_subcommand' -a 'ci' -d 'CI/CD integration'
+complete -c rafter -n '__fish_use_subcommand' -a 'hook' -d 'Hook handlers'
+complete -c rafter -n '__fish_use_subcommand' -a 'mcp' -d 'MCP server'
+complete -c rafter -n '__fish_use_subcommand' -a 'completion' -d 'Shell completion scripts'
+
+# agent subcommands
+complete -c rafter -n '__fish_seen_subcommand_from agent' -a 'init scan exec config audit audit-skill install-hook verify status'
+complete -c rafter -n '__fish_seen_subcommand_from agent; and __fish_seen_subcommand_from scan' -l quiet -s q -d 'Only output if secrets found'
+complete -c rafter -n '__fish_seen_subcommand_from agent; and __fish_seen_subcommand_from scan' -l json -d 'JSON output'
+complete -c rafter -n '__fish_seen_subcommand_from agent; and __fish_seen_subcommand_from scan' -l format -d 'Output format: text, json, sarif'
+complete -c rafter -n '__fish_seen_subcommand_from agent; and __fish_seen_subcommand_from scan' -l staged -d 'Scan staged files'
+complete -c rafter -n '__fish_seen_subcommand_from agent; and __fish_seen_subcommand_from scan' -l engine -d 'Engine: gitleaks, patterns, auto'
+
+# hook subcommands
+complete -c rafter -n '__fish_seen_subcommand_from hook' -a 'pretool posttool'
+
+# completion subcommands
+complete -c rafter -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish'
+`;
+export function createCompletionCommand() {
+    return new Command("completion")
+        .description("Generate shell completion scripts")
+        .argument("<shell>", "Shell type: bash, zsh, or fish")
+        .addHelpText("after", `
+Examples:
+  # bash — add to ~/.bashrc
+  eval "$(rafter completion bash)"
+
+  # zsh — add to ~/.zshrc
+  eval "$(rafter completion zsh)"
+
+  # fish — save to completions dir
+  rafter completion fish > ~/.config/fish/completions/rafter.fish
+`)
+        .action((shell) => {
+        switch (shell.toLowerCase()) {
+            case "bash":
+                process.stdout.write(BASH_COMPLETION.trimStart());
+                break;
+            case "zsh":
+                process.stdout.write(ZSH_COMPLETION.trimStart());
+                break;
+            case "fish":
+                process.stdout.write(FISH_COMPLETION.trimStart());
+                break;
+            default:
+                console.error(`Unknown shell: ${shell}. Supported: bash, zsh, fish`);
+                process.exit(1);
+        }
+    });
+}

package/dist/commands/hook/index.js

@@ -1,8 +1,10 @@
 import { Command } from "commander";
 import { createHookPretoolCommand } from "./pretool.js";
+import { createHookPosttoolCommand } from "./posttool.js";
 export function createHookCommand() {
     const hook = new Command("hook")
         .description("Hook handlers for agent platform integration");
     hook.addCommand(createHookPretoolCommand());
+    hook.addCommand(createHookPosttoolCommand());
     return hook;
 }

package/dist/commands/hook/posttool.js

@@ -0,0 +1,73 @@
+import { Command } from "commander";
+import { RegexScanner } from "../../scanners/regex-scanner.js";
+import { AuditLogger } from "../../core/audit-logger.js";
+export function createHookPosttoolCommand() {
+    return new Command("posttool")
+        .description("PostToolUse hook handler (reads stdin, redacts secrets in output, writes JSON to stdout)")
+        .action(async () => {
+        const input = await readStdin();
+        let payload;
+        try {
+            payload = JSON.parse(input);
+        }
+        catch {
+            writeOutput({ action: "continue" });
+            return;
+        }
+        const output = evaluateToolResponse(payload);
+        writeOutput(output);
+    });
+}
+function evaluateToolResponse(payload) {
+    const { tool_response } = payload;
+    // No response body — pass through
+    if (!tool_response) {
+        return { action: "continue" };
+    }
+    const scanner = new RegexScanner();
+    let modified = false;
+    const redacted = { ...tool_response };
+    // Scan and redact output
+    if (typeof tool_response.output === "string" && tool_response.output) {
+        if (scanner.hasSecrets(tool_response.output)) {
+            redacted.output = scanner.redact(tool_response.output);
+            modified = true;
+        }
+    }
+    // Scan and redact content (used by some tools)
+    if (typeof tool_response.content === "string" && tool_response.content) {
+        if (scanner.hasSecrets(tool_response.content)) {
+            redacted.content = scanner.redact(tool_response.content);
+            modified = true;
+        }
+    }
+    if (modified) {
+        const audit = new AuditLogger();
+        const matchCount = countMatches(scanner, tool_response);
+        audit.logContentSanitized(`${payload.tool_name} tool response`, matchCount);
+        return { action: "modify", tool_response: redacted };
+    }
+    return { action: "continue" };
+}
+function countMatches(scanner, tool_response) {
+    let count = 0;
+    if (typeof tool_response?.output === "string" && tool_response.output) {
+        count += scanner.scanText(tool_response.output).length;
+    }
+    if (typeof tool_response?.content === "string" && tool_response.content) {
+        count += scanner.scanText(tool_response.content).length;
+    }
+    return count;
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        process.stdin.setEncoding("utf-8");
+        process.stdin.on("data", (chunk) => { data += chunk; });
+        process.stdin.on("end", () => { resolve(data); });
+        process.stdin.resume();
+    });
+}
+function writeOutput(output) {
+    process.stdout.write(JSON.stringify(output) + "\n");
+}

package/dist/core/config-manager.js

@@ -96,6 +96,22 @@ export class ConfigManager {
                 fs.mkdirSync(dir, { recursive: true });
             }
         }
+        // Write patterns/ README if missing
+        const patternsReadme = path.join(rafterDir, "patterns", "README.md");
+        if (!fs.existsSync(patternsReadme)) {
+            fs.writeFileSync(patternsReadme, [
+                "# Custom Secret Patterns",
+                "",
+                "Place custom secret-detection pattern files here.",
+                "Each file should contain one regex pattern per line.",
+                "",
+                "Rafter ships 21 built-in patterns (AWS, GitHub, Stripe, etc.).",
+                "Files in this directory extend that set for your environment.",
+                "",
+                "Support for loading custom patterns from this directory is planned",
+                "for a future release.",
+            ].join("\n"), "utf-8");
+        }
         // Create default config if it doesn't exist
         if (!fs.existsSync(this.configPath)) {
             const config = getDefaultConfig();

package/dist/core/custom-patterns.js

@@ -0,0 +1,157 @@
+/**
+ * Load custom secret patterns from ~/.rafter/patterns/
+ * and suppression rules from .rafterignore.
+ */
+import fs from "fs";
+import path from "path";
+import { getRafterDir } from "./config-defaults.js";
+// ---------------------------------------------------------------------------
+// Custom pattern loading
+// ---------------------------------------------------------------------------
+/**
+ * Load user-defined patterns from ~/.rafter/patterns/*.txt and *.json.
+ *
+ * .txt  — one regex per line (comments with # ignored)
+ * .json — array of {name, pattern, severity?} objects
+ *
+ * Returns Pattern[] merged with DEFAULT_SECRET_PATTERNS by callers.
+ */
+export function loadCustomPatterns() {
+    const patternsDir = path.join(getRafterDir(), "patterns");
+    if (!fs.existsSync(patternsDir))
+        return [];
+    const results = [];
+    let entries;
+    try {
+        entries = fs.readdirSync(patternsDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const file = path.join(patternsDir, entry.name);
+        const ext = path.extname(entry.name).toLowerCase();
+        if (ext === ".txt") {
+            results.push(...loadTxtPatterns(file));
+        }
+        else if (ext === ".json") {
+            results.push(...loadJsonPatterns(file));
+        }
+    }
+    return results;
+}
+function loadTxtPatterns(file) {
+    try {
+        const lines = fs.readFileSync(file, "utf-8").split("\n");
+        const patterns = [];
+        for (const raw of lines) {
+            const line = raw.trim();
+            if (!line || line.startsWith("#"))
+                continue;
+            patterns.push({
+                name: `Custom (${path.basename(file, ".txt")})`,
+                regex: line,
+                severity: "high",
+            });
+        }
+        return patterns;
+    }
+    catch {
+        return [];
+    }
+}
+function loadJsonPatterns(file) {
+    try {
+        const data = JSON.parse(fs.readFileSync(file, "utf-8"));
+        if (!Array.isArray(data))
+            return [];
+        const patterns = [];
+        for (const entry of data) {
+            if (typeof entry.pattern !== "string")
+                continue;
+            patterns.push({
+                name: entry.name ?? `Custom (${path.basename(file, ".json")})`,
+                regex: entry.pattern,
+                severity: entry.severity ?? "high",
+                description: entry.description,
+            });
+        }
+        return patterns;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Parse .rafterignore from the given directory (project root).
+ *
+ * Format — one entry per line:
+ *   path/glob                     → suppress all findings in matching files
+ *   path/glob:pattern-name        → suppress specific pattern in matching files
+ *
+ * Lines starting with # are comments.
+ */
+export function loadSuppressions(projectRoot = process.cwd()) {
+    const file = path.join(projectRoot, ".rafterignore");
+    if (!fs.existsSync(file))
+        return [];
+    const suppressions = [];
+    try {
+        const lines = fs.readFileSync(file, "utf-8").split("\n");
+        for (const raw of lines) {
+            const line = raw.trim();
+            if (!line || line.startsWith("#"))
+                continue;
+            const colonIdx = line.indexOf(":");
+            if (colonIdx === -1) {
+                suppressions.push({ pathGlob: line });
+            }
+            else {
+                suppressions.push({
+                    pathGlob: line.slice(0, colonIdx).trim(),
+                    patternName: line.slice(colonIdx + 1).trim() || undefined,
+                });
+            }
+        }
+    }
+    catch {
+        // ignore unreadable .rafterignore
+    }
+    return suppressions;
+}
+/**
+ * Returns true if a finding should be suppressed.
+ */
+export function isSuppressed(filePath, patternName, suppressions) {
+    for (const s of suppressions) {
+        if (matchGlob(s.pathGlob, filePath)) {
+            if (!s.patternName || s.patternName.toLowerCase() === patternName.toLowerCase()) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Minimal glob matcher: supports * (within segment) and ** (cross-segment).
+ * Not full micromatch — covers the 90% case for .rafterignore.
+ */
+function matchGlob(glob, filePath) {
+    // Normalise separators
+    const g = glob.replace(/\\/g, "/");
+    const f = filePath.replace(/\\/g, "/");
+    // Escape regex special chars except * which we handle specially
+    const escaped = g
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, "\x00") // placeholder for **
+        .replace(/\*/g, "[^/]*") // * = anything within one segment
+        .replace(/\x00/g, ".*"); // ** = anything including /
+    try {
+        return new RegExp(`(^|/)${escaped}(/|$)`).test(f);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/risk-rules.js

@@ -17,7 +17,9 @@ export const HIGH_PATTERNS = [
     /chmod\s+777/,
     /curl.*\|\s*(bash|sh|zsh|dash)\b/,
     /wget.*\|\s*(bash|sh|zsh|dash)\b/,
-    /git\s+push\s+--force/,
+    /git\s+push\s+(--force|-f)\b/,
+    /git\s+push\s+--force-(with-lease|if-includes)\b/,
+    /git\s+push\s+\S*\s+\+\S+/, // refspec force: git push origin +main
     /docker\s+system\s+prune/,
     /npm\s+publish/,
     /pypi.*upload/,
@@ -45,6 +47,9 @@ export const DEFAULT_REQUIRE_APPROVAL = [
     "wget.*\\|\\s*(bash|sh|zsh|dash)\\b",
     "chmod 777",
     "git push --force",
+    "git push -f",
+    "git push --force-with-lease",
+    "git push --force-if-includes",
 ];
 /**
  * Assess risk level of a command string.

package/dist/index.js

@@ -9,10 +9,11 @@ import { createCiCommand } from "./commands/ci/index.js";
 import { createHookCommand } from "./commands/hook/index.js";
 import { createMcpCommand } from "./commands/mcp/index.js";
 import { createPolicyCommand } from "./commands/policy/index.js";
+import { createCompletionCommand } from "./commands/completion.js";
 import { checkForUpdate } from "./utils/update-checker.js";
 import { setAgentMode } from "./utils/formatter.js";
 dotenv.config();
-const VERSION = "0.5.0";
+const VERSION = "0.5.3";
 const program = new Command()
     .name("rafter")
     .description("Rafter CLI")
@@ -39,6 +40,8 @@ program.addCommand(createHookCommand());
 program.addCommand(createMcpCommand());
 // Policy commands
 program.addCommand(createPolicyCommand());
+// Shell completions
+program.addCommand(createCompletionCommand());
 // Non-blocking update check — runs after command, prints to stderr
 checkForUpdate(VERSION).then((notice) => {
     if (notice)

package/dist/scanners/regex-scanner.js

@@ -2,9 +2,10 @@ import fs from "fs";
 import path from "path";
 import { PatternEngine } from "../core/pattern-engine.js";
 import { DEFAULT_SECRET_PATTERNS } from "./secret-patterns.js";
+import { loadCustomPatterns, loadSuppressions, isSuppressed } from "../core/custom-patterns.js";
 export class RegexScanner {
     constructor(customPatterns) {
-        const patterns = [...DEFAULT_SECRET_PATTERNS];
+        const patterns = [...DEFAULT_SECRET_PATTERNS, ...loadCustomPatterns()];
         if (customPatterns) {
             for (const cp of customPatterns) {
                 patterns.push({
@@ -15,6 +16,7 @@ export class RegexScanner {
             }
         }
         this.engine = new PatternEngine(patterns);
+        this.suppressions = loadSuppressions();
     }
     /**
      * Scan a single file for secrets
@@ -22,18 +24,12 @@ export class RegexScanner {
     scanFile(filePath) {
         try {
             const content = fs.readFileSync(filePath, "utf-8");
-            const matches = this.engine.scanWithPosition(content);
-            return {
-                file: filePath,
-                matches
-            };
+            const raw = this.engine.scanWithPosition(content);
+            const matches = raw.filter((m) => !isSuppressed(filePath, m.pattern.name, this.suppressions));
+            return { file: filePath, matches };
         }
         catch (e) {
-            // If file can't be read (binary, permissions, etc.), return empty matches
-            return {
-                file: filePath,
-                matches: []
-            };
+            return { file: filePath, matches: [] };
         }
     }
     /**

package/dist/utils/binary-manager.js

@@ -1,7 +1,7 @@
 import fs from "fs";
 import path from "path";
 import https from "https";
-import { exec } from "child_process";
+import { exec, execSync } from "child_process";
 import { promisify } from "util";
 import { getBinDir } from "../core/config-defaults.js";
 import * as tar from "tar";
@@ -52,6 +52,20 @@ export class BinaryManager {
         const gitleaksPath = this.getGitleaksPath();
         return fs.existsSync(gitleaksPath);
     }
+    /**
+     * Find gitleaks on system PATH (like Python's shutil.which)
+     */
+    findGitleaksOnPath() {
+        const cmd = process.platform === "win32" ? "where gitleaks" : "which gitleaks";
+        try {
+            const result = execSync(cmd, { timeout: 5000, encoding: "utf-8" });
+            const found = result.trim().split("\n")[0].trim();
+            return found || null;
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * Verify Gitleaks binary works
      */
@@ -69,6 +83,67 @@ export class BinaryManager {
             return false;
         }
     }
+    /**
+     * Run gitleaks version and return {ok, stdout, stderr}
+     */
+    async verifyGitleaksVerbose(binaryPath) {
+        const gitleaksPath = binaryPath ?? this.getGitleaksPath();
+        try {
+            const { stdout, stderr } = await execAsync(`"${gitleaksPath}" version`, { timeout: 5000 });
+            const ok = stdout.includes("gitleaks version");
+            return { ok, stdout: stdout.trim(), stderr: stderr.trim() };
+        }
+        catch (e) {
+            const err = e;
+            return {
+                ok: false,
+                stdout: (err.stdout ?? "").trim(),
+                stderr: (err.stderr ?? String(e)).trim(),
+            };
+        }
+    }
+    /**
+     * Collect diagnostic context for a failed binary (file type, uname, glibc/musl)
+     */
+    async collectBinaryDiagnostics(binaryPath) {
+        const gitleaksPath = binaryPath ?? this.getGitleaksPath();
+        const lines = [];
+        try {
+            const { stdout: fileOut } = await execAsync(`file "${gitleaksPath}"`, { timeout: 5000 });
+            lines.push(`  file: ${fileOut.trim()}`);
+        }
+        catch {
+            lines.push(`  file: (unavailable)`);
+        }
+        try {
+            const { stdout: uname } = await execAsync("uname -a", { timeout: 5000 });
+            lines.push(`  uname: ${uname.trim()}`);
+        }
+        catch {
+            lines.push(`  uname: (unavailable)`);
+        }
+        lines.push(`  node arch: ${process.arch}, platform: ${process.platform}`);
+        // Detect glibc vs musl on Linux
+        if (process.platform === "linux") {
+            try {
+                const { stdout: ldd } = await execAsync("ldd --version 2>&1 || true", { timeout: 5000 });
+                if (ldd.includes("musl")) {
+                    lines.push("  libc: musl (gitleaks linux builds target glibc; musl systems need a musl build or static binary)");
+                }
+                else if (ldd.includes("GLIBC") || ldd.includes("GNU")) {
+                    const match = ldd.match(/(\d+\.\d+)/);
+                    lines.push(`  libc: glibc ${match ? match[1] : "(version unknown)"}`);
+                }
+                else {
+                    lines.push("  libc: unknown");
+                }
+            }
+            catch {
+                lines.push("  libc: (detection failed)");
+            }
+        }
+        return lines.join("\n");
+    }
     /**
      * Download and install Gitleaks
      */
@@ -86,10 +161,14 @@ export class BinaryManager {
         const arch = this.getArchString();
         const url = this.getDownloadUrl(platform, arch);
         log(`Downloading Gitleaks v${GITLEAKS_VERSION} for ${platform}/${arch}...`);
+        log(`  URL: ${url}`);
         const archivePath = path.join(this.binDir, platform === "windows" ? "gitleaks.zip" : "gitleaks.tar.gz");
         try {
             // Download archive
             await this.downloadFile(url, archivePath, log);
+            // Log downloaded file size as basic integrity signal
+            const stats = fs.statSync(archivePath);
+            log(`  Downloaded: ${(stats.size / 1024).toFixed(1)} KB`);
             // Extract binary
             log("Extracting binary...");
             if (platform === "windows") {
@@ -102,12 +181,22 @@ export class BinaryManager {
             // Make executable (Unix systems)
             if (process.platform !== "win32") {
                 await execAsync(`chmod +x "${this.getGitleaksPath()}"`);
+                log("  chmod +x applied");
             }
-            // Verify it works
-            const works = await this.verifyGitleaks();
-            if (!works) {
-                throw new Error("Downloaded binary doesn't execute correctly");
+            // Verify it works — capture output for diagnostics
+            const { ok, stdout: verOut, stderr: verErr } = await this.verifyGitleaksVerbose();
+            if (!ok) {
+                const diag = await this.collectBinaryDiagnostics();
+                const binaryPath = this.getGitleaksPath();
+                throw new Error(`Gitleaks binary failed to execute.\n` +
+                    `  Binary: ${binaryPath}\n` +
+                    `  URL: ${url}\n` +
+                    (verOut ? `  gitleaks version stdout: ${verOut}\n` : "") +
+                    (verErr ? `  gitleaks version stderr: ${verErr}\n` : "") +
+                    `Diagnostics:\n${diag}\n` +
+                    `Fix: ensure the binary matches your OS/arch, or install gitleaks manually and ensure it is on PATH.`);
             }
+            log(`  Verified: ${verOut}`);
             // Clean up archive
             if (fs.existsSync(archivePath)) {
                 fs.unlinkSync(archivePath);
@@ -231,13 +320,17 @@ export class BinaryManager {
         });
     }
     /**
-     * Extract tarball
+     * Extract tarball — binary only, strip packaging extras (LICENSE, README.md)
      */
     async extractTarball(tarballPath) {
         await tar.extract({
             file: tarballPath,
             cwd: this.binDir,
-            strip: 0
+            strip: 1,
+            filter: (p) => {
+                const base = path.basename(p);
+                return base === "gitleaks" || base === "gitleaks.exe";
+            },
         });
     }
 }