@vaultcompass/conductor 0.4.6 → 0.5.0

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.
@@ -1,10 +1,12 @@
1
1
  // Running one gate as a child process.
2
2
  //
3
3
  // Wrapper, not library: nothing here imports any gate's own package. That
4
- // is what keeps the umbrella from taking three exact version pins and
5
- // needing a release of its own every time one of the three ships, and it is
4
+ // is what keeps the umbrella from taking exact version pins on five tools
5
+ // and needing a release of its own every time one of them ships, and it is
6
6
  // what makes "this gate ran and exited N, output unparsed" an available
7
- // outcome instead of a build error.
7
+ // outcome instead of a build error. What differs per tool (how the version
8
+ // is asked, where the JSON comes from, what each exit means, the timeout)
9
+ // is data in src/products.ts, not branches here.
8
10
  //
9
11
  // The one non-obvious constraint, and it came from running the tools rather
10
12
  // than from reading them: the CHILD'S WORKING DIRECTORY MUST BE THE
@@ -16,15 +18,20 @@
16
18
  // --project, so setting cwd correctly is the single approach that is right
17
19
  // for all three.
18
20
  import { spawnSync } from 'node:child_process';
21
+ import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs';
22
+ import { tmpdir } from 'node:os';
23
+ import path from 'node:path';
19
24
  import { NormalizeError } from './envelope.js';
20
- import { normalizeDepGuard, normalizeFailedGate, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
25
+ import { normalizeDepGuard, normalizeFailedGate, normalizeGitleaks, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeOsvScanner, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
21
26
  import { renderOptionFlags } from './policy.js';
27
+ import { ExternalConfigError, materializeExternalConfig, nestedConfigProposals, } from './external-config.js';
28
+ import { profileFor } from './products.js';
22
29
  import { atLeastVersion, refuseHeadControlledProgram } from './trust-base.js';
23
30
  import { ResolveError, candidateNames, nodeModulesCandidate, resolveGateBinary, } from './resolve.js';
24
31
  /**
25
32
  * The first version of each gate that understands `--trust-base`.
26
33
  *
27
- * A TABLE rather than a boolean, because the three gates get pull-request
34
+ * A TABLE rather than a boolean, because the three family gates got pull-request
28
35
  * mode in three separate releases and the umbrella has to keep working
29
36
  * against every combination in the meantime. A product missing from this
30
37
  * table has no pull-request mode yet and is never handed the flag; a product
@@ -43,10 +50,19 @@ export const TRUST_BASE_MIN_VERSION = {
43
50
  'intent-guard': '1.4.0',
44
51
  'vault-guard': '1.7.0',
45
52
  'dep-guard': '0.6.0',
46
- // All three products are in. The table stays a table rather than becoming
47
- // a boolean: a fourth role can arrive without one, and the "no
48
- // pull-request mode yet" branch below is what keeps that gate from being
49
- // handed a flag it would reject.
53
+ // The two external tools have no --trust-base and are never handed one.
54
+ // For them the umbrella itself provides pull-request mode: it scopes the
55
+ // history to base..HEAD and hands over the config (and gitleaks' ignore
56
+ // file) read from the base ref (src/external-config.ts). So the entry here
57
+ // is their command-line floor, the same value as `minVersion` in
58
+ // src/products.ts, and being in the table is what makes an unreadable
59
+ // version a refusal on a pull request rather than a quiet withholding.
60
+ gitleaks: '8.19.0',
61
+ 'osv-scanner': '2.0.0',
62
+ // The table stays a table rather than becoming a boolean: a new role can
63
+ // arrive without pull-request mode, and the "no pull-request mode yet"
64
+ // branch below is what keeps that gate from being handed a flag it would
65
+ // reject.
50
66
  };
51
67
  /**
52
68
  * Whether this gate can be handed `--trust-base`, and why not when it cannot.
@@ -223,16 +239,36 @@ export function gateArgs(gate, staged, intent,
223
239
  * `decideTrustBase`; nothing here re-decides it, so a gate that cannot take
224
240
  * the flag is never handed one by a second opinion written in this switch.
225
241
  */
226
- trustBase) {
242
+ trustBase,
243
+ /** Paths the runner owns for an external tool; the npm gates ignore them. */
244
+ external = {}) {
227
245
  const passthrough = renderOptionFlags(gate.options);
228
246
  const trust = trustBase === undefined ? [] : ['--trust-base', trustBase];
247
+ const config = external.configPath === undefined ? [] : ['--config', external.configPath];
229
248
  switch (gate.product) {
230
- case 'dep-guard':
249
+ case 'dep-guard': {
231
250
  // `scan` takes --trust-base from 0.6.0. It sits beside whatever the
232
251
  // umbrella already passes rather than replacing it: --trust-base says
233
252
  // where the RULES come from and the mode flags say what is scanned,
234
253
  // and a pull-request run passes both.
235
- return [...(staged ? ['--staged'] : []), '--format', 'json', ...trust, ...passthrough];
254
+ //
255
+ // --base is a different flag answering a different question:
256
+ // --trust-base says whose config is trusted, --base says what the
257
+ // change is compared against. On a pull-request run (trustBase
258
+ // decided) they end up pointing at the same ref, because the base
259
+ // branch is both the state the pull request diverged from and the
260
+ // state whose rules were approved -- but dep-guard's own CLI treats
261
+ // them as unrelated flags, so both are passed rather than one
262
+ // implying the other.
263
+ //
264
+ // Never added when staged: dep-guard's CLI refuses --staged together
265
+ // with --base (packages/cli/src/cli.ts, resolveMode), because the two
266
+ // name incompatible comparisons -- the git index versus an arbitrary
267
+ // ref. A staged run already has its own comparison and --trust-base
268
+ // is unaffected, since it answers a different question.
269
+ const base = trustBase !== undefined && !staged ? ['--base', trustBase] : [];
270
+ return [...(staged ? ['--staged'] : []), '--format', 'json', ...trust, ...base, ...passthrough];
271
+ }
236
272
  case 'vault-guard':
237
273
  // No path argument: the CLI defaults it to "." and the umbrella runs
238
274
  // with cwd at the repository root anyway. Passing one would also risk
@@ -277,6 +313,67 @@ trustBase) {
277
313
  ...passthrough,
278
314
  ];
279
315
  }
316
+ case 'gitleaks': {
317
+ if (external.reportPath === undefined) {
318
+ throw new Error('gitleaks needs a report path: it cannot write its report to stdout');
319
+ }
320
+ // --exit-code 3 moves the leak code off 1, which gitleaks also uses for
321
+ // errors, so a crash and a leak stop sharing a number. --log-opts is
322
+ // always set: gitleaks' default is git log --all, which on a checkout
323
+ // with fetch-depth 0 scans every branch, so one branch's secret would
324
+ // redden every other pull request. --staged has no meaning here, and
325
+ // --trust-base is never handed to an external tool: the trust base
326
+ // scopes the history and selects the config, and that is all.
327
+ //
328
+ // --diff-merges=first-parent because `git log -p` shows no diff for a
329
+ // merge commit, so a secret added inside a merge's own changes (an
330
+ // evil merge, a key pasted while resolving a conflict) was never
331
+ // scanned. The price is that a pull request's change shows twice under
332
+ // an Actions-style merge, once in its commit and once in the merge's
333
+ // first-parent diff; normalizeGitleaks collapses those.
334
+ //
335
+ // --log-level info, pinned: the umbrella reads ERR lines to tell a
336
+ // failed scan from a clean one, so a lower level (or a future lower
337
+ // default) would turn a failed scan into a pass. It is reserved too.
338
+ const scope = trustBase === undefined ? 'HEAD' : `${trustBase}..HEAD`;
339
+ return [
340
+ '--report-format',
341
+ 'json',
342
+ '--report-path',
343
+ external.reportPath,
344
+ '--exit-code',
345
+ '3',
346
+ '--redact',
347
+ '--no-banner',
348
+ '--log-level',
349
+ 'info',
350
+ '--log-opts',
351
+ `--diff-merges=first-parent ${scope}`,
352
+ // On a pull request, inline gitleaks:allow comments are ignored: an
353
+ // inline allow lives in the tree being judged, so the pull request
354
+ // controls it. A legitimate allow belongs in the base ref's
355
+ // .gitleaks.toml allowlist or .gitleaksignore, both of which the
356
+ // umbrella already reads from the base. Local runs keep them.
357
+ ...(trustBase === undefined ? [] : ['--ignore-gitleaks-allow']),
358
+ ...config,
359
+ ...(external.ignorePath === undefined ? [] : ['--gitleaks-ignore-path', external.ignorePath]),
360
+ ...passthrough,
361
+ external.scanRoot ?? '.',
362
+ ];
363
+ }
364
+ case 'osv-scanner': {
365
+ // JSON goes to stdout and everything else to stderr, so no report
366
+ // file. No directory walk: each tracked lockfile is named with
367
+ // --lockfile (the runner lists them, src/products.ts
368
+ // OSV_LOCKFILE_NAMES), because osv-scanner's own walk skips anything
369
+ // .gitignore matches, tracked or not. With none there is nothing to
370
+ // hand over, and the runner reports that without spawning the tool.
371
+ if (external.lockfiles === undefined || external.lockfiles.length === 0) {
372
+ throw new Error('osv-scanner needs at least one lockfile: with none, nothing is spawned');
373
+ }
374
+ const lockfiles = external.lockfiles.flatMap((file) => ['--lockfile', file]);
375
+ return ['--format', 'json', ...config, ...lockfiles, ...passthrough];
376
+ }
280
377
  }
281
378
  }
282
379
  /**
@@ -286,8 +383,9 @@ trustBase) {
286
383
  * per-command binaries ignore --version and run the gate instead, so a
287
384
  * probe there would have side effects on the user's repository.
288
385
  */
289
- function probeVersion(binary, repoRoot, timeoutMs) {
290
- if (binary.versionProbe === null) {
386
+ function probeVersion(binary, product, repoRoot, timeoutMs) {
387
+ const spec = profileFor(product).versionProbe;
388
+ if (binary.versionProbe === null || spec === null) {
291
389
  return null;
292
390
  }
293
391
  const probe = spawnSync(binary.versionProbe.command, binary.versionProbe.argv, {
@@ -298,13 +396,21 @@ function probeVersion(binary, repoRoot, timeoutMs) {
298
396
  if (probe.status !== 0 || typeof probe.stdout !== 'string') {
299
397
  return null;
300
398
  }
301
- // All three print a bare version string. Take the first line and accept
302
- // it only if it looks like one, so a future help banner does not end up
303
- // in a SARIF driver's version field.
399
+ // Take the first line and accept it only if the product's pattern matches,
400
+ // so a future help banner does not end up in a SARIF driver's version
401
+ // field. The npm gates print a bare version and their pattern keeps the
402
+ // whole line; an external tool that prefixes its version with its name has
403
+ // a capture group that takes the number alone.
304
404
  const first = probe.stdout.trim().split('\n')[0]?.trim() ?? '';
305
- return /^v?\d+\.\d+\.\d+/.test(first) ? first.replace(/^v/, '') : null;
405
+ const match = spec.pattern.exec(first);
406
+ return match === null ? null : (match[1] ?? match[0]).replace(/^v/, '');
306
407
  }
307
- function normalizeFor(product, parsed, version) {
408
+ /**
409
+ * `context.blocked` is whether the gate's exit said it blocked. The npm gates
410
+ * carry that in their own JSON and ignore it; the external tools' reports do
411
+ * not, so their normalizers take it from here.
412
+ */
413
+ function normalizeFor(product, parsed, version, context) {
308
414
  switch (product) {
309
415
  case 'dep-guard':
310
416
  return normalizeDepGuard(parsed, version);
@@ -312,8 +418,30 @@ function normalizeFor(product, parsed, version) {
312
418
  return normalizeVaultGuard(parsed, version);
313
419
  case 'intent-guard':
314
420
  return normalizeIntentGuard(parsed, version);
421
+ case 'gitleaks':
422
+ return normalizeGitleaks(parsed, version, context.blocked);
423
+ case 'osv-scanner':
424
+ return normalizeOsvScanner(parsed, version, context.blocked, context.roots);
315
425
  }
316
426
  }
427
+ /**
428
+ * The repository root in every spelling a child could print it in: as given,
429
+ * and with symbolic links resolved (a macOS temporary directory is the
430
+ * everyday case: /var is a link to /private/var).
431
+ */
432
+ function rootSpellings(repoRoot) {
433
+ const spellings = [path.resolve(repoRoot)];
434
+ try {
435
+ const real = realpathSync(repoRoot);
436
+ if (!spellings.includes(real)) {
437
+ spellings.push(real);
438
+ }
439
+ }
440
+ catch {
441
+ // A root that cannot be resolved has one spelling.
442
+ }
443
+ return spellings;
444
+ }
317
445
  /**
318
446
  * An error's message, never its stack.
319
447
  *
@@ -342,15 +470,20 @@ function messageOf(err) {
342
470
  * lives on the base branch, which is the protected side.
343
471
  */
344
472
  function missingGateRemedy(product, skipNodeModules, skipped) {
473
+ const profile = profileFor(product);
474
+ if (!profile.managed) {
475
+ // An external tool is never in node_modules and never installed by the
476
+ // Action, so the pull-request sentence below would send a reader to the
477
+ // wrong place. Its own install instruction applies on every run.
478
+ return ` ${profile.remedy(skipNodeModules)}`;
479
+ }
345
480
  if (!skipNodeModules) {
346
481
  return '';
347
482
  }
348
483
  return (' On a pull-request run node_modules/.bin is not consulted at all: what is installed there ' +
349
484
  'is chosen by the head own manifest and lockfile, so no ref approves it.' +
350
485
  (skipped === null ? '' : ` There is a ${skipped}, and it was skipped for that reason.`) +
351
- ` Install the gate outside the tree with npm install -g @vaultcompass/${product}. The ` +
352
- `conductor Action does exactly that, at the version its ${product}-version input pins, and ` +
353
- 'that pin lives in the workflow file on the base branch.');
486
+ ` ${profile.remedy(true)}`);
354
487
  }
355
488
  /**
356
489
  * Runs one gate. TOTAL: this never throws.
@@ -421,7 +554,7 @@ export function runGate(gate, options) {
421
554
  }
422
555
  }
423
556
  function runGateInner(gate, options, started, progress) {
424
- const timeoutMs = options.timeoutMs ?? 120_000;
557
+ const timeoutMs = options.timeoutMs ?? profileFor(gate.product).timeoutMs;
425
558
  // ONE PLACE DECIDES WHAT PULL-REQUEST MODE IS, and it is the presence of a
426
559
  // trust base. resolve.ts knows nothing about refs, so it is told rather than
427
560
  // asked.
@@ -503,7 +636,30 @@ function runGateInner(gate, options, started, progress) {
503
636
  };
504
637
  }
505
638
  }
506
- const version = probeVersion(binary, options.repoRoot, timeoutMs);
639
+ const version = probeVersion(binary, gate.product, options.repoRoot, timeoutMs);
640
+ // The command-line floor. Only the external tools have one: the umbrella
641
+ // writes flags they grew at a known release (gitleaks' git subcommand,
642
+ // osv-scanner's scan source), and an older build would reject the command
643
+ // line with an exit the umbrella could misread. An UNREADABLE version falls
644
+ // through to the trust-base decision below, which refuses it on a pull
645
+ // request and runs it unverified locally, the same as the npm gates.
646
+ const profile = profileFor(gate.product);
647
+ if (profile.minVersion !== null &&
648
+ version !== null &&
649
+ !atLeastVersion(version, profile.minVersion)) {
650
+ const detail = `${gate.product} ${version} is older than ${profile.minVersion}, the oldest version whose ` +
651
+ `command line this umbrella speaks. Upgrade it to ${profile.minVersion} or later.`;
652
+ return {
653
+ ...base,
654
+ productVersion: version,
655
+ binary,
656
+ durationMs: Date.now() - started,
657
+ couldNotRun: { reason: 'gate-version-unsupported', detail },
658
+ findings: [normalizeFailedGate(gate.role, gate.product, detail)],
659
+ run: EMPTY_RUN,
660
+ diagnostics: [],
661
+ };
662
+ }
507
663
  // AFTER the version probe and BEFORE the command line is built, because the
508
664
  // decision reads the version. That ordering is the whole capability gate:
509
665
  // an intent-guard older than 1.4.0 must not be handed a flag it would
@@ -538,12 +694,198 @@ function runGateInner(gate, options, started, progress) {
538
694
  diagnostics: [],
539
695
  };
540
696
  }
697
+ // A directory of the runner's own for an external tool's working files: the
698
+ // report gitleaks writes. Made under the caller's temporary root when there
699
+ // is one, and removed whatever happens, so a run leaves nothing behind. The
700
+ // npm gates need none, and get none.
701
+ const decidedRef = trustBase === undefined || trustBase.withheld !== null ? undefined : trustBase.ref;
702
+ const needsConfig = decidedRef !== undefined && profile.configFile !== null;
703
+ const workDir = profile.output.kind === 'report-file' || needsConfig
704
+ ? mkdtempSync(path.join(options.tempRoot ?? tmpdir(), 'conductor-gate-'))
705
+ : null;
706
+ try {
707
+ return spawnAndRead({
708
+ gate,
709
+ options,
710
+ started,
711
+ progress,
712
+ base,
713
+ binary,
714
+ version,
715
+ trustBase,
716
+ profile,
717
+ timeoutMs,
718
+ workDir,
719
+ });
720
+ }
721
+ finally {
722
+ if (workDir !== null) {
723
+ rmSync(workDir, { recursive: true, force: true });
724
+ }
725
+ }
726
+ }
727
+ /** Strips ANSI colour codes: gitleaks colours its log even off a terminal. */
728
+ function stripAnsi(text) {
729
+ return text.replace(/\u001b\[[0-9;]*m/g, '');
730
+ }
731
+ /** Builds the command line, runs the gate, and reads what it said. */
732
+ function spawnAndRead(ctx) {
733
+ const { gate, options, started, progress, base, binary, version, trustBase, profile, timeoutMs, workDir } = ctx;
734
+ const external = {};
735
+ if (profile.output.kind === 'report-file' && workDir !== null) {
736
+ external.reportPath = path.join(workDir, `${gate.product}-report${profile.output.extension}`);
737
+ }
738
+ const decidedRef = trustBase === undefined || trustBase.withheld !== null ? undefined : trustBase.ref;
739
+ // The lockfiles a file-fed tool is handed, from the repository's tracked
740
+ // files. On a pull request this is the head's index, read directly and not
741
+ // from the base ref: the lockfiles ARE the tree being judged, and adding,
742
+ // removing or renaming one is visible in the diff, so there is nothing for
743
+ // a base-ref read to protect. A listing that fails is not "no lockfiles".
744
+ const nestedProposals = [];
745
+ if (profile.lockfileNames !== null) {
746
+ const names = new Set(profile.lockfileNames);
747
+ const listing = spawnSync('git', ['ls-files', '-z'], {
748
+ cwd: options.repoRoot,
749
+ encoding: 'utf8',
750
+ maxBuffer: 64 * 1024 * 1024,
751
+ });
752
+ if (listing.status !== 0 || typeof listing.stdout !== 'string') {
753
+ const detail = `the repository's tracked files could not be listed, so ${gate.product} had no ` +
754
+ 'lockfiles to be handed.';
755
+ return {
756
+ ...base,
757
+ productVersion: version,
758
+ binary,
759
+ durationMs: Date.now() - started,
760
+ ...(trustBase === undefined ? {} : { trustBase }),
761
+ couldNotRun: { reason: 'preparation-failed', detail },
762
+ findings: [normalizeFailedGate(gate.role, gate.product, detail)],
763
+ run: EMPTY_RUN,
764
+ diagnostics: [],
765
+ };
766
+ }
767
+ const tracked = listing.stdout.split('\0').filter((file) => file !== '');
768
+ if (decidedRef !== undefined && profile.configFile !== null) {
769
+ nestedProposals.push(...nestedConfigProposals(options.repoRoot, decidedRef, tracked, profile.configFile));
770
+ }
771
+ external.lockfiles = tracked
772
+ // Never a vendored copy under node_modules: that is a dependency's own
773
+ // lockfile, not a statement about what this repository resolves.
774
+ .filter((file) => !file.split('/').includes('node_modules'))
775
+ .filter((file) => names.has(path.posix.basename(file)))
776
+ .sort();
777
+ if (external.lockfiles.length === 0) {
778
+ // Nothing to scan, reported the same way as osv-scanner's own 128 below,
779
+ // without spawning it.
780
+ return {
781
+ ...base,
782
+ productVersion: version,
783
+ binary,
784
+ durationMs: Date.now() - started,
785
+ ...(trustBase === undefined ? {} : { trustBase }),
786
+ exitCode: 0,
787
+ couldNotRun: null,
788
+ findings: [],
789
+ run: EMPTY_RUN,
790
+ diagnostics: [
791
+ {
792
+ code: 'conductor/nothing-to-scan',
793
+ message: `${gate.product} found nothing to scan (no tracked lockfile); treated as clean.`,
794
+ },
795
+ ],
796
+ };
797
+ }
798
+ }
799
+ // On a pull request, the tool's config and ignore file come from the base
800
+ // ref (or a neutral stand-in), never from the head it would otherwise
801
+ // auto-load them from. A head-side change is a proposal, carried the same
802
+ // way an npm gate's own proposals are.
803
+ const configProposals = [...nestedProposals];
804
+ // Where the child runs. The repository root, except for a tool whose base
805
+ // config can name further files relative to its working directory: on a
806
+ // pull request that tool runs from a directory holding the base ref's
807
+ // copies, so no relative path it reads can land in the head tree. Every
808
+ // path the umbrella hands it is absolute, so nothing else depends on it.
809
+ let spawnCwd = options.repoRoot;
810
+ if (decidedRef !== undefined && workDir !== null) {
811
+ const baseline = gate.options['baseline-path'];
812
+ let materialized;
813
+ try {
814
+ materialized = materializeExternalConfig({
815
+ repoRoot: options.repoRoot,
816
+ trustBase: decidedRef,
817
+ profile,
818
+ tempRoot: workDir,
819
+ ...(typeof baseline === 'string' && !path.isAbsolute(baseline) ? { extraFiles: [baseline] } : {}),
820
+ });
821
+ }
822
+ catch (err) {
823
+ if (!(err instanceof ExternalConfigError)) {
824
+ throw err;
825
+ }
826
+ return {
827
+ ...base,
828
+ productVersion: version,
829
+ binary,
830
+ durationMs: Date.now() - started,
831
+ ...(trustBase === undefined ? {} : { trustBase }),
832
+ couldNotRun: { reason: 'preparation-failed', detail: err.message },
833
+ findings: [normalizeFailedGate(gate.role, gate.product, err.message)],
834
+ run: EMPTY_RUN,
835
+ diagnostics: [],
836
+ };
837
+ }
838
+ if (materialized !== null) {
839
+ external.configPath = materialized.path;
840
+ if (materialized.proposal !== null) {
841
+ configProposals.push(materialized.proposal);
842
+ }
843
+ configProposals.push(...materialized.extendProposals);
844
+ if (profile.followsConfigExtend) {
845
+ spawnCwd = materialized.cwd;
846
+ }
847
+ if (materialized.ignore !== null) {
848
+ external.ignorePath = materialized.ignore.dir;
849
+ if (materialized.ignore.proposal !== null) {
850
+ configProposals.push(materialized.ignore.proposal);
851
+ }
852
+ }
853
+ }
854
+ if (profile.ignoreFile?.alsoLoadedFromScanRoot === true) {
855
+ const gitDir = spawnSync('git', ['rev-parse', '--absolute-git-dir'], {
856
+ cwd: options.repoRoot,
857
+ encoding: 'utf8',
858
+ });
859
+ const resolved = typeof gitDir.stdout === 'string' ? gitDir.stdout.trim() : '';
860
+ if (gitDir.status !== 0 || resolved === '') {
861
+ // No git directory means no history to scan and nowhere safe to scan
862
+ // it from. Not a clean result.
863
+ const detail = `the repository's git directory could not be found, so ${gate.product} could not be ` +
864
+ 'pointed away from the head tree on this pull request.';
865
+ return {
866
+ ...base,
867
+ productVersion: version,
868
+ binary,
869
+ durationMs: Date.now() - started,
870
+ ...(trustBase === undefined ? {} : { trustBase }),
871
+ couldNotRun: { reason: 'preparation-failed', detail },
872
+ findings: [normalizeFailedGate(gate.role, gate.product, detail)],
873
+ run: EMPTY_RUN,
874
+ diagnostics: [],
875
+ };
876
+ }
877
+ external.scanRoot = resolved;
878
+ }
879
+ }
880
+ const trustBaseOut = trustBase === undefined || configProposals.length === 0
881
+ ? trustBase
882
+ : { ...trustBase, proposals: [...trustBase.proposals, ...configProposals] };
541
883
  const argv = [
542
884
  ...binary.argvPrefix,
543
- ...gateArgs(gate, options.staged, options.intent, trustBase === undefined || trustBase.withheld !== null ? undefined : trustBase.ref),
885
+ ...gateArgs(gate, options.staged, options.intent, decidedRef, external),
544
886
  ];
545
887
  const child = spawnSync(binary.command, argv, {
546
- cwd: options.repoRoot,
888
+ cwd: spawnCwd,
547
889
  encoding: 'utf8',
548
890
  timeout: timeoutMs,
549
891
  maxBuffer: 64 * 1024 * 1024,
@@ -554,13 +896,17 @@ function runGateInner(gate, options, started, progress) {
554
896
  argv,
555
897
  binary,
556
898
  durationMs: Date.now() - started,
557
- stderr: child.stderr ?? '',
899
+ // Colour codes stripped here, once, so neither the text report nor the
900
+ // gate-failed finding (which carries a summary of this into SARIF and a
901
+ // pull-request comment) shows escape sequences: gitleaks colours its log
902
+ // even when stderr is not a terminal.
903
+ stderr: stripAnsi(child.stderr ?? ''),
558
904
  // Carried on every return path below, the failures included: WHETHER
559
905
  // this gate was in pull-request mode is exactly as interesting when it
560
906
  // could not run as when it could, and the withheld reason is the only
561
907
  // place a report can say a gate read its own rules out of the tree under
562
908
  // judgment.
563
- ...(trustBase === undefined ? {} : { trustBase }),
909
+ ...(trustBaseOut === undefined ? {} : { trustBase: trustBaseOut }),
564
910
  };
565
911
  // Keep the backstop's view current, so an unexpected throw below still
566
912
  // reports which binary ran and what it printed.
@@ -578,11 +924,41 @@ function runGateInner(gate, options, started, progress) {
578
924
  };
579
925
  }
580
926
  const exitCode = child.status;
581
- const stdout = child.stdout ?? '';
582
- // dep-guard's 2 means "could not run the checks at all" and it prints no
583
- // JSON. The other two have no such code, but a signal-killed child or a
584
- // timeout lands here too, and none of those are a clean result.
585
- if (exitCode === null || exitCode > 1) {
927
+ // "Nothing here to scan" is its own exit for osv-scanner (128, a
928
+ // repository with no lockfile). Read as an error it would redden every pull
929
+ // request in a docs-only repository; read as a verdict it would claim a
930
+ // scan that did not happen. So it is clean, and the report says why.
931
+ if (exitCode !== null && profile.exit.nothingToScan.includes(exitCode)) {
932
+ return {
933
+ ...withRun,
934
+ exitCode: 0,
935
+ couldNotRun: null,
936
+ findings: [],
937
+ run: EMPTY_RUN,
938
+ diagnostics: [
939
+ // When lockfiles WERE handed over, this exit means they parsed to no
940
+ // packages at all, which is different news from "no lockfile": a
941
+ // lockfile the tool could not read anything from deserves a look.
942
+ external.lockfiles !== undefined && external.lockfiles.length > 0
943
+ ? {
944
+ code: 'conductor/lockfiles-empty',
945
+ message: `${gate.product} read no packages from ${external.lockfiles.join(', ')} ` +
946
+ `(exit ${exitCode}); treated as clean.`,
947
+ }
948
+ : {
949
+ code: 'conductor/nothing-to-scan',
950
+ message: `${gate.product} found nothing to scan (exit ${exitCode}); treated as clean.`,
951
+ },
952
+ ],
953
+ };
954
+ }
955
+ // The profile says which exits are verdicts. For the npm gates that is 0
956
+ // and 1, exactly as before profiles existed: dep-guard's 2 means "could not
957
+ // run the checks at all" and it prints no JSON. gitleaks is handed
958
+ // --exit-code 3, so its 1 is left meaning an error. A signal-killed child
959
+ // or a timeout lands here too, and none of those are a clean result.
960
+ const blocked = exitCode !== null && profile.exit.blocked.includes(exitCode);
961
+ if (exitCode === null || (!blocked && !profile.exit.clean.includes(exitCode))) {
586
962
  const detail = exitCode === null
587
963
  ? 'the gate did not exit normally (killed, or timed out).'
588
964
  : `the gate exited ${exitCode}, which it uses for "could not run".`;
@@ -599,17 +975,64 @@ function runGateInner(gate, options, started, progress) {
599
975
  diagnostics: [],
600
976
  };
601
977
  }
978
+ // A clean exit that logged an error is not a clean scan. gitleaks 8.30.1
979
+ // swallows a git failure (a base ref the checkout never fetched, a path
980
+ // that is not a repository): it logs the git error at ERR, scans 0
981
+ // commits, writes a report of [], and exits 0. Read by exit code alone
982
+ // that is a pass over nothing on exactly the pull requests where the
983
+ // history was never there to read.
984
+ if (!blocked && profile.stderrError !== null) {
985
+ const pattern = profile.stderrError;
986
+ const errorLine = stripAnsi(withRun.stderr)
987
+ .split('\n')
988
+ .find((line) => pattern.test(line));
989
+ if (errorLine !== undefined) {
990
+ const detail = `${gate.product} exited ${exitCode} but logged an error, so its clean result cannot be ` +
991
+ `trusted: ${errorLine.trim()}`;
992
+ return {
993
+ ...withRun,
994
+ exitCode,
995
+ couldNotRun: { reason: 'gate-error', detail },
996
+ findings: [normalizeFailedGate(gate.role, gate.product, detail, withRun.stderr)],
997
+ run: EMPTY_RUN,
998
+ diagnostics: [],
999
+ };
1000
+ }
1001
+ }
1002
+ let text;
1003
+ if (profile.output.kind === 'report-file') {
1004
+ // The report is where the verdict is. An exit that says clean or blocked
1005
+ // with no report behind it is not either of those.
1006
+ const reportPath = external.reportPath;
1007
+ if (!existsSync(reportPath)) {
1008
+ const detail = `${gate.product} exited ${exitCode} but wrote no report, so there is no verdict to read.`;
1009
+ return {
1010
+ ...withRun,
1011
+ exitCode,
1012
+ couldNotRun: { reason: 'report-missing', detail },
1013
+ findings: [normalizeFailedGate(gate.role, gate.product, detail, withRun.stderr)],
1014
+ run: EMPTY_RUN,
1015
+ diagnostics: [],
1016
+ };
1017
+ }
1018
+ text = readFileSync(reportPath, 'utf8');
1019
+ }
1020
+ else {
1021
+ text = child.stdout ?? '';
1022
+ }
602
1023
  let parsed;
603
1024
  try {
604
- parsed = JSON.parse(stdout);
1025
+ parsed = JSON.parse(text);
605
1026
  }
606
1027
  catch {
607
1028
  // Exit 1 with unparseable stdout is what a rejected config looks like
608
1029
  // from two of the three products, and it is could-not-run rather than
609
1030
  // clean. Reporting it as a policy violation would tell the user their
610
1031
  // code is at fault when their config is.
611
- const detail = `the gate exited ${exitCode} without valid JSON on stdout. ` +
612
- 'A rejected config file looks exactly like this, and it is not a clean result.';
1032
+ const detail = profile.output.kind === 'report-file'
1033
+ ? `the gate exited ${exitCode} and its report is not valid JSON, which is not a clean result.`
1034
+ : `the gate exited ${exitCode} without valid JSON on stdout. ` +
1035
+ 'A rejected config file looks exactly like this, and it is not a clean result.';
613
1036
  return {
614
1037
  ...withRun,
615
1038
  exitCode,
@@ -620,7 +1043,10 @@ function runGateInner(gate, options, started, progress) {
620
1043
  };
621
1044
  }
622
1045
  try {
623
- const normalized = normalizeFor(gate.product, parsed, version);
1046
+ const normalized = normalizeFor(gate.product, parsed, version, {
1047
+ blocked,
1048
+ roots: rootSpellings(options.repoRoot),
1049
+ });
624
1050
  return {
625
1051
  ...withRun,
626
1052
  exitCode,