@rafter-security/cli 0.10.5 → 0.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/dist/commands/agent/exec.js +26 -9
  2. package/dist/commands/agent/init.js +286 -225
  3. package/dist/commands/agent/install-hook.js +19 -8
  4. package/dist/commands/agent/scan.js +270 -70
  5. package/dist/commands/agent/status.js +2 -2
  6. package/dist/commands/agent/update-skill-scanner.js +1 -1
  7. package/dist/commands/agent/verify.js +39 -15
  8. package/dist/commands/backend/get.js +6 -2
  9. package/dist/commands/backend/run.js +25 -2
  10. package/dist/commands/backend/scan-status.js +34 -4
  11. package/dist/commands/hook/pretool.js +124 -36
  12. package/dist/commands/mcp/server.js +184 -129
  13. package/dist/commands/report.js +6 -2
  14. package/dist/core/audit-logger.js +47 -17
  15. package/dist/core/config-manager.js +46 -8
  16. package/dist/core/custom-patterns.js +28 -8
  17. package/dist/core/docs-loader.js +33 -3
  18. package/dist/core/pattern-engine.js +23 -5
  19. package/dist/core/policy-loader.js +15 -4
  20. package/dist/core/risk-rules.js +391 -9
  21. package/dist/index.js +7 -1
  22. package/dist/scanners/betterleaks.js +127 -14
  23. package/dist/scanners/git-history-scan.js +75 -0
  24. package/dist/scanners/regex-scanner.js +16 -2
  25. package/dist/scanners/secret-patterns.js +5 -1
  26. package/dist/scanners/union.js +31 -19
  27. package/dist/utils/api.js +35 -1
  28. package/dist/utils/env-guard.js +14 -14
  29. package/dist/utils/git-diff.js +36 -20
  30. package/dist/utils/git.js +164 -52
  31. package/dist/utils/skill-manager.js +4 -3
  32. package/package.json +16 -15
  33. package/resources/continue-rules/rafter.md +1 -1
  34. package/resources/cursor-rules/rafter.mdc +1 -1
  35. package/resources/rafter-security-skill.md +3 -1
  36. package/resources/skills/rafter/SKILL.md +1 -2
  37. package/resources/skills/rafter/docs/guardrails.md +1 -1
  38. package/resources/skills/rafter-code-review/SKILL.md +0 -1
  39. package/resources/skills/rafter-secure-design/SKILL.md +0 -1
  40. package/resources/skills/rafter-skill-review/SKILL.md +0 -1
  41. package/resources/windsurf-rules/rafter.md +1 -1
@@ -1,7 +1,8 @@
1
1
  import { Command } from "commander";
2
2
  import { RegexScanner } from "../../scanners/regex-scanner.js";
3
3
  import { scanAddedDiffLines } from "../../scanners/git-diff-scan.js";
4
- import { parseUnifiedDiffAddedLines } from "../../utils/git-diff.js";
4
+ import { gitRepoRoot, scanGitHistory } from "../../scanners/git-history-scan.js";
5
+ import { parseUnifiedDiffAddedLines, gitDiffMaxBuffer } from "../../utils/git-diff.js";
5
6
  import { BetterleaksScanner } from "../../scanners/betterleaks.js";
6
7
  import { unionScanResults } from "../../scanners/union.js";
7
8
  import { BinaryManager, BETTERLEAKS_VERSION } from "../../utils/binary-manager.js";
@@ -106,7 +107,9 @@ function applyBaseline(results, entries) {
106
107
  e.pattern === m.pattern.name &&
107
108
  (e.line == null || e.line === (m.line ?? null)))),
108
109
  }))
109
- .filter((r) => r.matches.length > 0);
110
+ // Keep a read-error entry even with no matches (sable-ilbx), so an
111
+ // unreadable file survives a baseline filter.
112
+ .filter((r) => r.matches.length > 0 || r.readError);
110
113
  }
111
114
  export function createScanCommand() {
112
115
  return new Command("scan")
@@ -117,10 +120,11 @@ export function createScanCommand() {
117
120
  .option("--format <format>", "Output format: text, json, sarif", "text")
118
121
  .option("--staged", "Scan only git staged files")
119
122
  .option("--diff <ref>", "Scan files changed since a git ref")
123
+ .option("--range <range>", "Scan only files changed in a git commit range, e.g. main..HEAD")
120
124
  .option("--engine <engine>", "Scan engine: betterleaks or patterns", "auto")
121
125
  .option("--baseline", "Filter findings present in the saved baseline")
122
126
  .option("--watch", "Watch for file changes and re-scan on change")
123
- .option("--history", "Scan git history for secrets (requires betterleaks engine)")
127
+ .option("--history", "Scan every commit on every ref instead of the working tree")
124
128
  .option("--no-gitignore", "Scan files even if .gitignore would exclude them (default: respect .gitignore)")
125
129
  .option("--no-auto-update", "Do not auto-update a stale managed betterleaks binary; fall back to the patterns engine instead")
126
130
  .action(async (scanPath, opts) => {
@@ -144,17 +148,31 @@ export function createScanCommand() {
144
148
  if (isAgentScan) {
145
149
  process.stderr.write("Warning: rafter agent scan is deprecated and will be removed in a future major version. Use rafter secrets instead.\n");
146
150
  }
147
- // Load policy-merged config for excludePaths/customPatterns/ignore
151
+ // Load policy-merged config for excludePaths/customPatterns/ignore.
152
+ // Discover and anchor the policy from the scan TARGET, not the process
153
+ // cwd (sable-lu0j), so an ambient `.rafter.yml` in cwd cannot suppress
154
+ // real secrets in a scan of a different tree. For `--staged`/`--diff` the
155
+ // default target is "." (cwd), which is the repo the command runs in.
156
+ const scanBase = path.resolve(scanPath);
157
+ const rafterignoreDir = fs.existsSync(scanBase) && fs.statSync(scanBase).isDirectory()
158
+ ? scanBase
159
+ : path.dirname(scanBase);
148
160
  const manager = new ConfigManager();
149
- const cfg = manager.loadWithPolicy();
161
+ const cfg = manager.loadWithPolicy(scanBase);
150
162
  const scanCfg = cfg.agent?.scan;
151
- const suppressions = collectSuppressions(scanCfg?.ignore);
163
+ const suppressions = collectSuppressions(scanCfg?.ignore, scanCfg?.ignoreBaseDir, rafterignoreDir);
152
164
  const baselineEntries = opts.baseline ? loadBaselineEntries() : [];
153
165
  // Handle --diff flag
154
166
  if (opts.diff) {
155
167
  await scanDiffFiles(opts.diff, opts, scanCfg, baselineEntries, path.resolve(scanPath), suppressions);
156
168
  return;
157
169
  }
170
+ // Handle --range flag (a commit range a..b; reuses the diff plumbing so a
171
+ // user can scope the scan to the changed files on a huge repo).
172
+ if (opts.range) {
173
+ await scanRangeFiles(opts.range, opts, scanCfg, baselineEntries, path.resolve(scanPath), suppressions);
174
+ return;
175
+ }
158
176
  // Handle --staged flag
159
177
  if (opts.staged) {
160
178
  await scanStagedFiles(opts, scanCfg, baselineEntries, path.resolve(scanPath), suppressions);
@@ -172,23 +190,28 @@ export function createScanCommand() {
172
190
  return;
173
191
  }
174
192
  // Determine scan engine
175
- const engine = await selectEngine(opts.engine || "auto", opts.quiet || false, autoUpdateEnabled(opts, scanCfg));
193
+ const requestedEngine = opts.engine || "auto";
194
+ const selected = await selectEngine(requestedEngine, opts.quiet || false, autoUpdateEnabled(opts, scanCfg));
195
+ const engine = selected.engine;
196
+ // Threaded through the scan so a scan-time fall-back (e.g. a betterleaks
197
+ // timeout) updates it before the output reports the engine actually used.
198
+ const report = buildEngineReport(requestedEngine, engine, selected.reason);
176
199
  // Determine if path is file or directory
177
200
  const stats = fs.statSync(resolvedPath);
178
201
  let results;
179
202
  if (stats.isDirectory()) {
180
203
  if (!opts.quiet) {
181
- console.error(`Scanning directory: ${resolvedPath} (${engine})`);
204
+ console.error(`Scanning directory: ${resolvedPath} (${engineLabel(engine)})`);
182
205
  }
183
- results = await scanDirectory(resolvedPath, engine, scanCfg, opts.history, opts.gitignore);
206
+ results = await scanDirectory(resolvedPath, engine, scanCfg, opts.history, opts.gitignore, report);
184
207
  }
185
208
  else {
186
209
  if (!opts.quiet) {
187
- console.error(`Scanning file: ${resolvedPath} (${engine})`);
210
+ console.error(`Scanning file: ${resolvedPath} (${engineLabel(engine)})`);
188
211
  }
189
- results = await scanFile(resolvedPath, engine, scanCfg);
212
+ results = await scanFile(resolvedPath, engine, scanCfg, report);
190
213
  }
191
- outputScanResults(applyBaseline(results, baselineEntries), opts, undefined, true, suppressions);
214
+ outputScanResults(applyBaseline(results, baselineEntries), opts, undefined, true, suppressions, report);
192
215
  });
193
216
  }
194
217
  /**
@@ -207,13 +230,19 @@ export function createSecretsCommand() {
207
230
  * Order matters — first match wins, and policy rules are checked first so an
208
231
  * explicit reason wins over a bare .rafterignore line covering the same finding.
209
232
  */
210
- export function collectSuppressions(policyIgnore) {
211
- return [...policyIgnoreToSuppressions(policyIgnore), ...loadSuppressions()];
233
+ export function collectSuppressions(policyIgnore, policyBaseDir, rafterignoreDir = process.cwd()) {
234
+ // Anchor policy globs to the `.rafter.yml`'s directory and `.rafterignore`
235
+ // globs to the scanned tree (sable-lu0j), so neither can suppress findings in
236
+ // a different tree.
237
+ return [
238
+ ...policyIgnoreToSuppressions(policyIgnore, policyBaseDir),
239
+ ...loadSuppressions(rafterignoreDir),
240
+ ];
212
241
  }
213
242
  /**
214
243
  * Emit SARIF 2.1.0 JSON for GitHub/GitLab security tab integration
215
244
  */
216
- function outputSarif(results) {
245
+ function outputSarif(results, emptyExitCode = 0) {
217
246
  const rules = new Map();
218
247
  const sarifResults = [];
219
248
  for (const r of results) {
@@ -259,22 +288,46 @@ function outputSarif(results) {
259
288
  ],
260
289
  };
261
290
  console.log(JSON.stringify(sarif, null, 2));
262
- process.exit(results.length > 0 ? 1 : 0);
291
+ // A read error (sable-ilbx) makes an otherwise-empty scan non-clean; the
292
+ // caller passes that exit code in.
293
+ process.exit(results.length > 0 ? 1 : emptyExitCode);
263
294
  }
264
295
  /**
265
296
  * Shared output logic for scan results
266
297
  */
267
- function outputScanResults(results, opts, context, exitOnFindings = true, suppressions = []) {
298
+ function outputScanResults(results, opts, context, exitOnFindings = true, suppressions = [], report) {
268
299
  const format = opts.format ?? (opts.json ? "json" : "text");
269
300
  if (!["text", "json", "sarif"].includes(format)) {
270
301
  console.error(`Invalid format: ${format}. Valid values: text, json, sarif`);
271
302
  process.exit(2);
272
303
  }
304
+ // Partition off files that could not be read (sable-ilbx). A read failure is
305
+ // not a finding and not a clean pass — surface it so "no secrets detected"
306
+ // cannot stand in for "could not open". Warn on stderr (so stdout stays
307
+ // parseable), report it in the JSON/text body, and let it set the exit code.
308
+ const readErrors = results
309
+ .filter((r) => r.readError)
310
+ .map((r) => ({ file: r.file, error: r.readError }));
311
+ const scanResults = results.filter((r) => !r.readError);
312
+ if (readErrors.length > 0 && !opts.quiet) {
313
+ console.error(fmt.warning(`Could not read ${readErrors.length} file(s); results may be incomplete.`));
314
+ }
315
+ // No silent downgrade (sable-jiqb): when betterleaks was requested/auto but
316
+ // patterns ran instead, say so on stderr so it is visible in every format
317
+ // without corrupting a JSON/SARIF stdout payload. The JSON body below also
318
+ // carries it as structured fields.
319
+ if (report?.degraded && !opts.quiet) {
320
+ console.error(fmt.warning(`Engine: requested ${report.requested}, used ${engineLabel(report.used)}` +
321
+ (report.reason ? ` (${report.reason})` : "")));
322
+ }
273
323
  // Split suppressed findings off the main result list. Both engines feed
274
324
  // through here, so policy-driven suppression applies regardless of source.
275
- const { results: keptResults, suppressed } = applySuppressions(results, suppressions);
325
+ const { results: keptResults, suppressed } = applySuppressions(scanResults, suppressions);
326
+ // Exit code: findings dominate (1); otherwise an unreadable file is a scan
327
+ // that could not complete cleanly (2); a clean, complete scan is 0.
328
+ const scanExitCode = keptResults.length > 0 ? 1 : readErrors.length > 0 ? 2 : 0;
276
329
  if (format === "sarif") {
277
- outputSarif(keptResults);
330
+ outputSarif(keptResults, scanExitCode);
278
331
  return;
279
332
  }
280
333
  if (format === "json" || opts.json) {
@@ -299,12 +352,26 @@ function outputScanResults(results, opts, context, exitOnFindings = true, suppre
299
352
  triage_applied: false,
300
353
  results: filesOut,
301
354
  };
355
+ // sable-jiqb — report the engine actually used and any fall-back, so a
356
+ // json/MCP/CI consumer is never left thinking betterleaks ran when it did not.
357
+ if (report) {
358
+ out.engine_requested = report.requested;
359
+ out.engine_used = report.used;
360
+ out.degraded = report.degraded;
361
+ if (report.degraded && report.reason)
362
+ out.degraded_reason = report.reason;
363
+ }
302
364
  if (suppressed.length > 0) {
303
365
  out._suppressed = suppressed;
304
366
  }
367
+ // Files that could not be read (sable-ilbx) — a reader can tell an empty
368
+ // `results` from an incomplete scan.
369
+ if (readErrors.length > 0) {
370
+ out.unreadable = readErrors;
371
+ }
305
372
  console.log(JSON.stringify(out, null, 2));
306
373
  if (exitOnFindings)
307
- process.exit(keptResults.length > 0 ? 1 : 0);
374
+ process.exit(scanExitCode);
308
375
  return;
309
376
  }
310
377
  // Text output — note suppression on stderr so stdout remains parseable.
@@ -312,12 +379,21 @@ function outputScanResults(results, opts, context, exitOnFindings = true, suppre
312
379
  console.error(fmt.info(`(${suppressed.length} finding(s) hidden by .rafter.yml)`));
313
380
  }
314
381
  if (keptResults.length === 0) {
315
- if (!opts.quiet) {
382
+ if (readErrors.length > 0) {
383
+ // Not a clean pass — the scan could not read some files (sable-ilbx).
384
+ if (!opts.quiet) {
385
+ console.log(`\n${fmt.warning(`${readErrors.length} file(s) could not be read:`)}`);
386
+ for (const re of readErrors)
387
+ console.log(` ${re.file} (${re.error})`);
388
+ console.log();
389
+ }
390
+ }
391
+ else if (!opts.quiet) {
316
392
  const msg = context ? `No secrets detected in ${context}` : "No secrets detected";
317
393
  console.log(`\n${fmt.success(msg)}\n`);
318
394
  }
319
395
  if (exitOnFindings)
320
- process.exit(0);
396
+ process.exit(scanExitCode);
321
397
  return;
322
398
  }
323
399
  console.log(`\n${fmt.warning(`Found secrets in ${keptResults.length} file(s):`)}\n`);
@@ -336,6 +412,12 @@ function outputScanResults(results, opts, context, exitOnFindings = true, suppre
336
412
  }
337
413
  }
338
414
  console.log(`\n${fmt.warning(`Total: ${totalMatches} secret(s) detected in ${keptResults.length} file(s)`)}\n`);
415
+ if (readErrors.length > 0 && !opts.quiet) {
416
+ console.log(`${fmt.warning(`${readErrors.length} file(s) could not be read:`)}`);
417
+ for (const re of readErrors)
418
+ console.log(` ${re.file} (${re.error})`);
419
+ console.log();
420
+ }
339
421
  if (context === "staged files") {
340
422
  console.log(`${fmt.error("Commit blocked. Remove secrets before committing.")}\n`);
341
423
  }
@@ -343,14 +425,36 @@ function outputScanResults(results, opts, context, exitOnFindings = true, suppre
343
425
  console.log(`Run 'rafter agent audit' to see the security log.\n`);
344
426
  }
345
427
  if (exitOnFindings)
346
- process.exit(1);
428
+ process.exit(scanExitCode);
347
429
  }
348
430
  /**
349
431
  * Scan files changed since a git ref (+ lines only in the unified diff).
350
432
  */
351
433
  async function scanDiffFiles(ref, opts, scanCfg, baselineEntries = [], scanPath, suppressions = []) {
434
+ // git would parse a leading "-" as one of its own options, not a ref.
435
+ if (ref.startsWith("-")) {
436
+ console.error(`Error: invalid ref "${ref}" (a git ref cannot start with "-")`);
437
+ process.exit(2);
438
+ }
352
439
  await runGitAddedLineScan(["diff", "-U0", "--no-color", "--diff-filter=ACM", ref], opts, scanCfg, baselineEntries, scanPath, suppressions, `files changed since ${ref}`, `No files changed since ${ref}`);
353
440
  }
441
+ /**
442
+ * Scan only the files changed in a git commit range (e.g. `main..HEAD`).
443
+ *
444
+ * sable-jiqb — on a repo large enough that a full betterleaks scan is slow, a
445
+ * user can scope the scan to a range's changed files. Reuses the `--diff`
446
+ * added-line plumbing (patterns engine; git line scope is incompatible with
447
+ * betterleaks' whole-file `dir` scan), with the range passed to `git diff` as a
448
+ * single revision argument.
449
+ */
450
+ async function scanRangeFiles(range, opts, scanCfg, baselineEntries = [], scanPath, suppressions = []) {
451
+ // git would parse a leading "-" as one of its own options, not a revision range.
452
+ if (range.startsWith("-")) {
453
+ console.error(`Error: invalid range "${range}" (a git range cannot start with "-")`);
454
+ process.exit(2);
455
+ }
456
+ await runGitAddedLineScan(["diff", "-U0", "--no-color", "--diff-filter=ACM", range], opts, scanCfg, baselineEntries, scanPath, suppressions, `files changed in ${range}`, `No files changed in ${range}`);
457
+ }
354
458
  /**
355
459
  * Scan git staged files for secrets (+ lines only in the staged diff).
356
460
  */
@@ -363,11 +467,17 @@ async function scanStagedFiles(opts, scanCfg, baselineEntries = [], scanPath, su
363
467
  */
364
468
  async function runGitAddedLineScan(gitArgs, opts, scanCfg, baselineEntries, scanPath, suppressions, contextLabel, emptyMessage, errorOpts) {
365
469
  const cwd = scanPath && fs.existsSync(scanPath) && fs.statSync(scanPath).isDirectory() ? scanPath : undefined;
470
+ const diffReport = diffModeReport(opts);
366
471
  try {
367
472
  const patch = execFileSync("git", gitArgs, {
368
473
  encoding: "utf-8",
369
474
  cwd,
370
475
  stdio: ["pipe", "pipe", "ignore"],
476
+ // The default 1 MiB cap makes `git diff` throw ENOBUFS on ordinary large
477
+ // staged diffs (lockfiles, generated or vendored files). That crash used
478
+ // to exit 1 — indistinguishable from a real finding, so a commit gate
479
+ // reported a broken scan as a possible secret (#274). Read the whole diff.
480
+ maxBuffer: gitDiffMaxBuffer(),
371
481
  });
372
482
  if (!patch.trim()) {
373
483
  if (!opts.quiet) {
@@ -375,7 +485,7 @@ async function runGitAddedLineScan(gitArgs, opts, scanCfg, baselineEntries, scan
375
485
  // --json, and outputScanResults owns the single stdout success line.
376
486
  console.error(fmt.success(emptyMessage));
377
487
  }
378
- outputScanResults([], opts, contextLabel, true, suppressions);
488
+ outputScanResults([], opts, contextLabel, true, suppressions, diffReport);
379
489
  return;
380
490
  }
381
491
  const addedLines = parseUnifiedDiffAddedLines(patch);
@@ -385,7 +495,7 @@ async function runGitAddedLineScan(gitArgs, opts, scanCfg, baselineEntries, scan
385
495
  // --json, and outputScanResults owns the single stdout success line.
386
496
  console.error(fmt.success(emptyMessage));
387
497
  }
388
- outputScanResults([], opts, contextLabel, true, suppressions);
498
+ outputScanResults([], opts, contextLabel, true, suppressions, diffReport);
389
499
  return;
390
500
  }
391
501
  const repoRoot = execFileSync("git", ["rev-parse", "--show-toplevel"], {
@@ -399,16 +509,73 @@ async function runGitAddedLineScan(gitArgs, opts, scanCfg, baselineEntries, scan
399
509
  }
400
510
  const allResults = scanAddedDiffLines(addedLines, repoRoot, scanCfg?.customPatterns);
401
511
  const filtered = applyExcludePaths(allResults, scanCfg?.excludePaths, repoRoot);
402
- outputScanResults(applyBaseline(filtered, baselineEntries), opts, contextLabel, true, suppressions);
512
+ outputScanResults(applyBaseline(filtered, baselineEntries), opts, contextLabel, true, suppressions, diffReport);
403
513
  }
404
514
  catch (error) {
405
515
  if (error.status === 128) {
406
516
  console.error(errorOpts?.notRepoMessage ?? "Error: Not in a git repository or invalid ref");
407
517
  process.exit(2);
408
518
  }
409
- throw error;
519
+ // A scan that could not run is a scan ERROR, never a finding. Exit 2 (per
520
+ // CLI_SPEC: invalid input / scan error) so a commit gate keying on the exit
521
+ // code never mistakes a broken scan for a detected secret (#274). ENOBUFS is
522
+ // the known case (a diff past the buffer), but any failure to read/parse the
523
+ // diff belongs here rather than surfacing as exit 1.
524
+ const detail = error?.code === "ENOBUFS"
525
+ ? "staged diff too large for the scanner to read"
526
+ : (error?.message ?? String(error));
527
+ console.error(`Error: secret scan could not run (${detail}); no scan was performed`);
528
+ process.exit(2);
410
529
  }
411
530
  }
531
+ /** Self-explanatory display label for a resolved engine — "both" alone
532
+ * doesn't say which two engines ran (issue #231 item 6). */
533
+ export function engineLabel(engine) {
534
+ return engine === "both" ? "both: betterleaks + patterns" : engine;
535
+ }
536
+ /**
537
+ * Build the initial engine report from the requested engine and the engine
538
+ * `selectEngine` resolved to. A resolution of `patterns` when betterleaks was
539
+ * wanted (explicit or via `auto`) is a degradation; `selectReason` explains it.
540
+ * Scan-time failures (a timeout mid-scan) further mutate this report in the
541
+ * scanners below.
542
+ */
543
+ export function buildEngineReport(requested, resolved, selectReason = null) {
544
+ const wantedBetterleaks = requested === "auto" || requested === "betterleaks";
545
+ const degraded = wantedBetterleaks && resolved === "patterns";
546
+ return {
547
+ requested,
548
+ used: resolved,
549
+ degraded,
550
+ reason: degraded ? (selectReason ?? "betterleaks unavailable; used the patterns engine") : undefined,
551
+ };
552
+ }
553
+ /** Record a scan-time fall-back to the patterns engine on the report. */
554
+ function markDegraded(report, reason) {
555
+ if (!report)
556
+ return;
557
+ report.used = "patterns";
558
+ report.degraded = true;
559
+ report.reason = reason;
560
+ }
561
+ /**
562
+ * The engine report for the git-diff modes (`--diff` / `--range` / `--staged`),
563
+ * which scan added lines with the patterns engine by design (betterleaks'
564
+ * whole-file `dir` scan is incompatible with a line scope). Only an explicit
565
+ * `--engine betterleaks` is a degradation here; `auto` is satisfied by patterns.
566
+ */
567
+ function diffModeReport(opts) {
568
+ const requested = opts.engine || "auto";
569
+ const degraded = requested === "betterleaks";
570
+ return {
571
+ requested,
572
+ used: "patterns",
573
+ degraded,
574
+ reason: degraded
575
+ ? "diff/range/staged modes scan changed lines with the patterns engine"
576
+ : undefined,
577
+ };
578
+ }
412
579
  /**
413
580
  * Select scan engine based on availability and user preference.
414
581
  *
@@ -427,7 +594,7 @@ async function runGitAddedLineScan(gitArgs, opts, scanCfg, baselineEntries, scan
427
594
  */
428
595
  async function selectEngine(preference, quiet, autoUpdate = true) {
429
596
  if (preference === "patterns") {
430
- return "patterns";
597
+ return { engine: "patterns", reason: null };
431
598
  }
432
599
  if (preference === "betterleaks") {
433
600
  const bl = new BetterleaksScanner();
@@ -436,7 +603,7 @@ async function selectEngine(preference, quiet, autoUpdate = true) {
436
603
  if (!quiet) {
437
604
  console.error(fmt.warning("Betterleaks requested but not available, using patterns"));
438
605
  }
439
- return "patterns";
606
+ return { engine: "patterns", reason: "betterleaks requested but not available" };
440
607
  }
441
608
  return ensureBetterleaksUsable(quiet, autoUpdate);
442
609
  }
@@ -448,9 +615,11 @@ async function selectEngine(preference, quiet, autoUpdate = true) {
448
615
  const bl = new BetterleaksScanner();
449
616
  const available = await bl.isAvailable();
450
617
  if (!available)
451
- return "patterns";
618
+ return { engine: "patterns", reason: "betterleaks not available" };
452
619
  const usable = await ensureBetterleaksUsable(quiet, autoUpdate);
453
- return usable === "betterleaks" ? "both" : "patterns";
620
+ return usable.engine === "betterleaks"
621
+ ? { engine: "both", reason: null }
622
+ : { engine: "patterns", reason: usable.reason };
454
623
  }
455
624
  /**
456
625
  * sable-o4k — guard against a stale rafter-managed betterleaks binary silently
@@ -466,7 +635,7 @@ async function selectEngine(preference, quiet, autoUpdate = true) {
466
635
  async function ensureBetterleaksUsable(quiet, autoUpdate) {
467
636
  const bm = new BinaryManager();
468
637
  if (!(await bm.isManagedBetterleaksStale()))
469
- return "betterleaks";
638
+ return { engine: "betterleaks", reason: null };
470
639
  const current = await bm.getBetterleaksVersion();
471
640
  const cta = "Fix manually with: rafter agent update-betterleaks";
472
641
  const stale = `Stale betterleaks binary (${current}; expected v${BETTERLEAKS_VERSION})`;
@@ -474,7 +643,7 @@ async function ensureBetterleaksUsable(quiet, autoUpdate) {
474
643
  if (!quiet) {
475
644
  console.error(fmt.warning(`${stale}. Auto-update is off — using the patterns engine for this scan. ${cta}`));
476
645
  }
477
- return "patterns";
646
+ return { engine: "patterns", reason: `${stale}; auto-update off` };
478
647
  }
479
648
  // Only prompt when there's a human at a TTY; otherwise auto-update proceeds
480
649
  // (default on) so non-interactive runs aren't left with a broken engine.
@@ -482,7 +651,7 @@ async function ensureBetterleaksUsable(quiet, autoUpdate) {
482
651
  const ok = await askYesNo(`${stale}. Update it now?`, true);
483
652
  if (!ok) {
484
653
  console.error(fmt.warning(`Skipped — using the patterns engine for this scan. ${cta}`));
485
- return "patterns";
654
+ return { engine: "patterns", reason: `${stale}; update declined` };
486
655
  }
487
656
  }
488
657
  if (!quiet)
@@ -492,14 +661,14 @@ async function ensureBetterleaksUsable(quiet, autoUpdate) {
492
661
  console.error(` ${m}`); }, BETTERLEAKS_VERSION);
493
662
  if (!quiet)
494
663
  console.error(fmt.success(`Betterleaks updated to v${BETTERLEAKS_VERSION}.`));
495
- return "betterleaks";
664
+ return { engine: "betterleaks", reason: null };
496
665
  }
497
666
  catch (e) {
667
+ const msg = e instanceof Error ? e.message : String(e);
498
668
  if (!quiet) {
499
- const msg = e instanceof Error ? e.message : String(e);
500
669
  console.error(fmt.warning(`Betterleaks update failed (${msg}) — using the patterns engine for this scan. ${cta}`));
501
670
  }
502
- return "patterns";
671
+ return { engine: "patterns", reason: `betterleaks update failed (${msg})` };
503
672
  }
504
673
  }
505
674
  /**
@@ -513,11 +682,13 @@ export function autoUpdateEnabled(opts, scanCfg) {
513
682
  /**
514
683
  * Scan a file with selected engine
515
684
  */
516
- async function scanFile(filePath, engine, scanCfg) {
685
+ async function scanFile(filePath, engine, scanCfg, report) {
517
686
  const runPatterns = () => {
518
687
  const scanner = new RegexScanner(scanCfg?.customPatterns);
519
688
  const result = scanner.scanFile(filePath);
520
- return result.matches.length > 0 ? [result] : [];
689
+ // Keep the result when it has findings OR could not be read (sable-ilbx),
690
+ // so a permission-denied file is not reported as a clean scan.
691
+ return result.matches.length > 0 || result.readError ? [result] : [];
521
692
  };
522
693
  if (engine === "both") {
523
694
  // sable-j85 — kick off betterleaks (async subprocess) first, run the
@@ -528,8 +699,9 @@ async function scanFile(filePath, engine, scanCfg) {
528
699
  const result = await new BetterleaksScanner().scanFile(filePath);
529
700
  return result.matches.length > 0 ? [result] : [];
530
701
  }
531
- catch {
702
+ catch (e) {
532
703
  console.error(fmt.warning("Betterleaks scan failed, using patterns only for this run"));
704
+ markDegraded(report, errorText(e));
533
705
  return [];
534
706
  }
535
707
  })();
@@ -544,54 +716,82 @@ async function scanFile(filePath, engine, scanCfg) {
544
716
  }
545
717
  catch (e) {
546
718
  console.error(fmt.warning("Betterleaks scan failed, falling back to patterns"));
719
+ markDegraded(report, errorText(e));
547
720
  return runPatterns();
548
721
  }
549
722
  }
550
723
  return runPatterns();
551
724
  }
725
+ /** An engine failure's message, e.g. "Betterleaks scan failed (timed out after 60s)". */
726
+ function errorText(e) {
727
+ return e instanceof Error ? e.message : String(e);
728
+ }
552
729
  /**
553
730
  * Scan a directory with selected engine
554
731
  */
555
- async function scanDirectory(dirPath, engine, scanCfg, history, respectGitignore) {
556
- // respectGitignore default is true. The patterns engine honors it via
557
- // RegexScanner.scanDirectory; betterleaks honors it natively (gitleaks
558
- // ancestry — reads .gitignore unless --no-git is set).
559
- const runPatterns = () => {
560
- const scanner = new RegexScanner(scanCfg?.customPatterns);
561
- return scanner.scanDirectory(dirPath, {
562
- excludePaths: scanCfg?.excludePaths,
563
- respectGitignore,
564
- });
732
+ async function scanDirectory(dirPath, engine, scanCfg, history, respectGitignore, report) {
733
+ // respectGitignore default is true. Both engines honor it: the patterns
734
+ // engine via RegexScanner.scanDirectory, betterleaks by scanning only the
735
+ // files git does not ignore (BetterleaksScanner.scanDirectory, #262).
736
+ // sable-28lv — with --history BOTH engines read the commit history. The
737
+ // patterns engine used to scan the working tree instead, so without
738
+ // betterleaks `--history` reported a clean history it had never read.
739
+ let repoRoot = null;
740
+ if (history) {
741
+ try {
742
+ repoRoot = gitRepoRoot(dirPath);
743
+ }
744
+ catch (e) {
745
+ console.error(`Error: ${errorText(e)}`);
746
+ process.exit(2);
747
+ }
748
+ }
749
+ const runPatterns = async () => {
750
+ if (!history) {
751
+ return new RegexScanner(scanCfg?.customPatterns).scanDirectory(dirPath, {
752
+ excludePaths: scanCfg?.excludePaths,
753
+ respectGitignore,
754
+ });
755
+ }
756
+ try {
757
+ return await scanGitHistory(dirPath, scanCfg?.customPatterns);
758
+ }
759
+ catch (e) {
760
+ console.error(`Error: ${errorText(e)}`);
761
+ process.exit(2);
762
+ }
763
+ };
764
+ // `betterleaks git` reports paths relative to the repo root; make them
765
+ // absolute like every other scan, so the union merges the two engines.
766
+ const runBetterleaks = async () => {
767
+ const found = await new BetterleaksScanner().scanDirectory(dirPath, { useGit: history ?? false, respectGitignore });
768
+ return repoRoot ? found.map((r) => ({ ...r, file: path.resolve(repoRoot, r.file) })) : found;
565
769
  };
566
770
  let results;
567
771
  if (engine === "both") {
568
- // sable-j85 — start betterleaks (async subprocess) first, walk the tree
569
- // with the synchronous patterns engine while it runs, then union. The
570
- // exclude-paths post-filter below applies to the merged set.
571
- const blPromise = (async () => {
572
- try {
573
- return await new BetterleaksScanner().scanDirectory(dirPath, { useGit: history ?? false });
574
- }
575
- catch {
576
- console.error(fmt.warning("Betterleaks scan failed, using patterns only for this run"));
577
- return [];
578
- }
579
- })();
580
- const patternsResults = runPatterns();
772
+ // sable-j85 — start betterleaks (async subprocess) first, run the patterns
773
+ // engine while it runs, then union. The exclude-paths post-filter below
774
+ // applies to the merged set.
775
+ const blPromise = runBetterleaks().catch((e) => {
776
+ console.error(fmt.warning(`${errorText(e)}; using patterns only for this run`));
777
+ markDegraded(report, errorText(e));
778
+ return [];
779
+ });
780
+ const patternsResults = await runPatterns();
581
781
  results = unionScanResults(await blPromise, patternsResults);
582
782
  }
583
783
  else if (engine === "betterleaks") {
584
784
  try {
585
- const bl = new BetterleaksScanner();
586
- results = await bl.scanDirectory(dirPath, { useGit: history ?? false });
785
+ results = await runBetterleaks();
587
786
  }
588
787
  catch (e) {
589
- console.error(fmt.warning("Betterleaks scan failed, falling back to patterns"));
590
- results = runPatterns();
788
+ console.error(fmt.warning(`${errorText(e)}; falling back to patterns`));
789
+ markDegraded(report, errorText(e));
790
+ results = await runPatterns();
591
791
  }
592
792
  }
593
793
  else {
594
- results = runPatterns();
794
+ results = await runPatterns();
595
795
  }
596
796
  // sable-yz0 — post-filter by `.rafter.yml scan.exclude_paths`. Two bugs
597
797
  // motivated this chokepoint:
@@ -614,9 +814,9 @@ async function scanDirectory(dirPath, engine, scanCfg, history, respectGitignore
614
814
  async function watchAndScan(watchPath, opts, scanCfg, suppressions = []) {
615
815
  const { watch } = await import("chokidar");
616
816
  const logger = new AuditLogger();
617
- const engine = await selectEngine(opts.engine || "auto", opts.quiet || false, autoUpdateEnabled(opts, scanCfg));
817
+ const engine = (await selectEngine(opts.engine || "auto", opts.quiet || false, autoUpdateEnabled(opts, scanCfg))).engine;
618
818
  if (!opts.quiet) {
619
- console.error(fmt.info(`Watching ${watchPath} for changes (${engine}). Press Ctrl+C to exit.`));
819
+ console.error(fmt.info(`Watching ${watchPath} for changes (${engineLabel(engine)}). Press Ctrl+C to exit.`));
620
820
  }
621
821
  // Do an initial scan
622
822
  const stats = fs.statSync(watchPath);
@@ -2,7 +2,7 @@ import { Command } from "commander";
2
2
  import fs from "fs";
3
3
  import path from "path";
4
4
  import os from "os";
5
- import { execSync } from "child_process";
5
+ import { execFileSync, execSync } from "child_process";
6
6
  import { fileURLToPath } from "url";
7
7
  import { getRafterDir, getAuditLogPath, getBinDir } from "../../core/config-defaults.js";
8
8
  import { AuditLogger } from "../../core/audit-logger.js";
@@ -66,7 +66,7 @@ export function createStatusCommand() {
66
66
  catch {
67
67
  if (fs.existsSync(localBetterleaks)) {
68
68
  try {
69
- const ver = execSync(`"${localBetterleaks}" version`, { timeout: 5000, encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] }).trim();
69
+ const ver = execFileSync(localBetterleaks, ["version"], { timeout: 5000, encoding: "utf-8", stdio: ["pipe", "pipe", "ignore"] }).trim();
70
70
  betterleaksStatus = `${ver} (local)`;
71
71
  }
72
72
  catch {
@@ -4,7 +4,7 @@ import { SkillScannerInstaller, SKILL_SCANNER_VERSION, } from "../../scanners/sk
4
4
  import { fmt } from "../../utils/formatter.js";
5
5
  export function createUpdateSkillScannerCommand() {
6
6
  return new Command("update-skill-scanner")
7
- .description("Install or update the optional skill-scanner deep engine (audit-skill --deep)")
7
+ .description("Install or update the optional skill-scanner deep engine (skill review --deep)")
8
8
  .option("--version <version>", "skill-scanner version to install", SKILL_SCANNER_VERSION)
9
9
  .action(async (opts) => {
10
10
  const checkCmd = process.platform === "win32" ? "where skill-scanner" : "which skill-scanner";