@vaultcompass/conductor 0.4.7 → 0.6.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.
@@ -218,6 +218,18 @@ function skipWording(reason) {
218
218
  function excludedLines(result) {
219
219
  return result.excluded.map((gate) => ` excluded ${gate.role} ${gate.product} did not run here; --gate did not name it`);
220
220
  }
221
+ /**
222
+ * One line per gate skipped because the head tree equals the trust base's
223
+ * (issue #69).
224
+ *
225
+ * Modeled on deferredLines and excludedLines just above: nothing ran for
226
+ * these gates either, so there is no header, no exit code and no duration to
227
+ * put in a section, and the reason has to be on screen or a run in this shape
228
+ * reads exactly like a run that judged every enabled gate's tree.
229
+ */
230
+ function treeUnchangedLines(result) {
231
+ return result.treeUnchanged.map((gate) => ` tree-unchanged ${gate.role} ${gate.product} did not run: the head tree is identical to the base tree, so there is no change for this gate to judge`);
232
+ }
221
233
  /**
222
234
  * The one sentence the whole of pull-request mode has to fit into.
223
235
  *
@@ -338,6 +350,38 @@ function refusalLines(result) {
338
350
  ` ${refusal}`,
339
351
  ];
340
352
  }
353
+ /**
354
+ * The one-line summary a `--output` run prints to the job log after writing
355
+ * its report to a file (see cli.ts). Refused first, exactly like every other
356
+ * renderer in this file, and for the same reason: `refusedTrustBase` fills
357
+ * `result.gates` and `result.findings` with a could-not-run outcome PER
358
+ * ENABLED GATE, so counting them the ordinary way reports "N gate(s), N
359
+ * finding(s)" on a run where nothing ran and nothing was found -- issue #46.
360
+ * A reader with only this line, no --verbose and no pull-request comment
361
+ * (a fork's read-only token, or pr-comment left off) deserves the same words
362
+ * the comment's own compact body gives them, not a count that implies gates
363
+ * ran.
364
+ *
365
+ * `refusal` (from refuseTrustBaseRef in trust-base.ts) already says "Nothing
366
+ * was checked" itself as part of its own sentence, so this does not repeat
367
+ * that lead-in: doing so used to print the phrase twice on one line. Nor
368
+ * does it append its own closing sentence: cli.ts joins this return value
369
+ * with "; " before the rest of the job-log line, and a trailing period here
370
+ * left every refused run's log line reading "...; sarif report written",
371
+ * with a period sitting directly before that semicolon. A trailing period
372
+ * on `refusal` itself is trimmed for the same reason.
373
+ *
374
+ * A normal run is untouched: the exact same
375
+ * "N gate(s), N finding(s)" text as before, so a working adopter's log does
376
+ * not change.
377
+ */
378
+ export function jobLogSummary(result) {
379
+ const refusal = result.trustBase?.refusal;
380
+ if (refusal !== undefined && refusal !== null) {
381
+ return `refused the trust base "${result.trustBase?.ref ?? ''}": ${refusal.replace(/\.+\s*$/, '')}`;
382
+ }
383
+ return `${result.gates.length} gate(s), ${result.findings.length} finding(s)`;
384
+ }
341
385
  function verdict(result, advisory) {
342
386
  const refusal = result.trustBase?.refusal;
343
387
  if (refusal !== undefined && refusal !== null) {
@@ -360,25 +404,40 @@ function verdictForRun(result, advisory) {
360
404
  const blocking = enforcedGates
361
405
  .flatMap((gate) => gate.findings)
362
406
  .filter((finding) => finding.blocking).length;
363
- if (result.gates.length === 0 && result.deferred.length > 0) {
364
- // Distinct from "none is enabled" below. A policy file with everything
365
- // switched off and a stage with nothing to do at it are two different
366
- // states, and telling somebody to set enabled: true is the wrong advice
367
- // for the second one.
368
- const names = result.deferred.map((gate) => `${gate.role} at stage ${gate.stage}`).join(', ');
369
- return `verdict: exit 0, nothing ran at this stage: every enabled gate is deferred (${names}).`;
370
- }
371
- if (result.gates.length === 0 && result.skipped.length > 0) {
372
- // A third distinct state, and telling somebody to switch a gate on is
373
- // wrong advice here too: the gate IS on, it ran, and it had nothing to
374
- // check. What to do about that is NOT the same in both cases, which is
375
- // why the clause comes from the skip reason rather than being written
376
- // here: for a missing spec the fix is to write one, and for a waiver
377
- // there is nothing to fix, because a person decided it.
378
- const clauses = result.skipped
379
- .map((gate) => `${gate.role} ${skipWording(gate.reason).verdict}`)
380
- .join(', ');
381
- return `verdict: exit 0, nothing was checked: ${clauses}.`;
407
+ if (result.gates.length === 0 &&
408
+ (result.deferred.length > 0 || result.treeUnchanged.length > 0 || result.skipped.length > 0)) {
409
+ // Three distinct states can each leave result.gates empty, and a run can
410
+ // land in more than one of them at once: a stage that deferred one gate
411
+ // while another was tree-unchanged (issue #69) is a real shape, not a
412
+ // hypothetical, so this names EVERY one that applies rather than the
413
+ // first one found. Naming only "every enabled gate is deferred" when a
414
+ // tree-unchanged gate was also in the mix would be false: not every gate
415
+ // was deferred, some had nothing to judge for a different reason. All
416
+ // three are also distinct from "none is enabled" below, and each needs
417
+ // its own fix: set enabled: true is wrong for all three of them, since
418
+ // every gate named here IS enabled.
419
+ const clauses = [];
420
+ if (result.deferred.length > 0) {
421
+ // Never "every enabled gate is deferred" here: that claim is only true
422
+ // when nothing else in this branch fired, and a mix with a
423
+ // tree-unchanged or skipped gate makes it false.
424
+ const names = result.deferred.map((gate) => `${gate.role} at stage ${gate.stage}`).join(', ');
425
+ clauses.push(`deferred to a later stage (${names})`);
426
+ }
427
+ if (result.treeUnchanged.length > 0) {
428
+ // The head tree is identical to the trust base's, so there is nothing
429
+ // for these gates to judge (issue #69).
430
+ const names = result.treeUnchanged.map((gate) => gate.role).join(', ');
431
+ clauses.push(`the head tree is identical to the base tree, so there is no change for these gates to judge (${names})`);
432
+ }
433
+ if (result.skipped.length > 0) {
434
+ // What to do about this is NOT the same for every reason, which is why
435
+ // the clause comes from the skip reason rather than being written
436
+ // here: for a missing spec the fix is to write one, and for a waiver
437
+ // there is nothing to fix, because a person decided it.
438
+ clauses.push(result.skipped.map((gate) => `${gate.role} ${skipWording(gate.reason).verdict}`).join(', '));
439
+ }
440
+ return `verdict: exit 0, nothing was checked: ${clauses.join('; ')}.`;
382
441
  }
383
442
  if (result.gates.length === 0) {
384
443
  // Exit 0 with an empty report is indistinguishable from a clean run at a
@@ -520,6 +579,13 @@ function summaryLine(result) {
520
579
  .join(', ');
521
580
  parts.push(`Deferred to a later stage: ${names}.`);
522
581
  }
582
+ // Same reasoning as the deferred clause, for the equal-tree shape
583
+ // (issue #69): these gates are enabled and did not run, so a clean run in
584
+ // this shape must not read like a run that judged their tree too.
585
+ if (result.treeUnchanged.length > 0) {
586
+ const names = result.treeUnchanged.map((gate) => `${gate.role} (${gate.product})`).join(', ');
587
+ parts.push(`Tree unchanged from the trust base, skipped: ${names}.`);
588
+ }
523
589
  // Same reasoning as the deferred clause. A gate that ran and had nothing to
524
590
  // check covered none of this commit, and silence there makes a branch with
525
591
  // no spec read as a branch that passed the intent gate.
@@ -668,7 +734,12 @@ export function renderText(result, options = {}) {
668
734
  for (const gate of result.gates) {
669
735
  lines.push(...gateSection(gate));
670
736
  }
671
- const aside = [...deferredLines(result), ...skippedLines(result), ...excludedLines(result)];
737
+ const aside = [
738
+ ...deferredLines(result),
739
+ ...skippedLines(result),
740
+ ...excludedLines(result),
741
+ ...treeUnchangedLines(result),
742
+ ];
672
743
  if (aside.length > 0) {
673
744
  lines.push('', ...aside);
674
745
  }
package/dist/policy.d.ts CHANGED
@@ -1,7 +1,13 @@
1
1
  export declare const POLICY_FILE_NAME = ".guardrails.yaml";
2
- export declare const GATE_ROLES: readonly ["dependencies", "secrets", "intent"];
2
+ export declare const GATE_ROLES: readonly ["dependencies", "secrets", "intent", "secrets-history", "vulnerabilities"];
3
3
  export type GateRole = (typeof GATE_ROLES)[number];
4
- export declare const PRODUCTS: readonly ["dep-guard", "vault-guard", "intent-guard"];
4
+ /**
5
+ * Five products. The first three are this family's own npm packages, which
6
+ * the Action installs. The last two are external tools the adopter installs
7
+ * on their own machine or runner; conductor finds them on PATH and downloads
8
+ * nothing (src/products.ts, `managed: false`).
9
+ */
10
+ export declare const PRODUCTS: readonly ["dep-guard", "vault-guard", "intent-guard", "gitleaks", "osv-scanner"];
5
11
  export type Product = (typeof PRODUCTS)[number];
6
12
  /**
7
13
  * When a gate runs, in order, earliest first.
@@ -17,8 +23,8 @@ export type GateStage = (typeof GATE_STAGES)[number];
17
23
  /**
18
24
  * Where each gate sits when the policy file does not say.
19
25
  *
20
- * Runtime is not what decides this. All three gates together take under a
21
- * second on a staged commit; the cost is CEREMONY, and only the intent gate
26
+ * Runtime is not what decides this for the three family gates: together they
27
+ * take under a second on a staged commit; the cost is CEREMONY, and only the intent gate
22
28
  * has any, because it wants a contract approved before the work starts.
23
29
  * The other two are silent until they find something, and a secret that
24
30
  * reaches a pull request is already on a remote, so the earliest stage is
package/dist/policy.js CHANGED
@@ -1,6 +1,7 @@
1
1
  // The one policy file.
2
2
  //
3
- // Gates are keyed by the ROLE they fill (dependencies, secrets, intent) and
3
+ // Gates are keyed by the ROLE they fill (dependencies, secrets, intent,
4
+ // secrets-history, vulnerabilities) and
4
5
  // name the product filling it in a `product` field. That indirection is
5
6
  // worth the extra line: a product rename, or swapping one gate for another,
6
7
  // becomes a one-line edit instead of a rename of the key a repository wrote
@@ -9,18 +10,19 @@
9
10
  // Two rules this file exists to enforce, both of them decisions rather than
10
11
  // mechanics:
11
12
  //
12
- // 1. THERE IS NO SHARED SEVERITY THRESHOLD. Two of the three products
13
- // happen to share a four-level scale; the third scores a weighted
14
- // rubric from 0 to 100 and has no per-finding severity at all. A single
15
- // `failOn` at the top of the file would read as one decision and mean
16
- // three different things, so a top-level `failOn` is rejected outright
13
+ // 1. THERE IS NO SHARED SEVERITY THRESHOLD. Five products, two of them
14
+ // external tools. Two of the family's three share a four-level scale; the
15
+ // third scores a weighted rubric from 0 to 100, gitleaks reports match
16
+ // or no match, and osv-scanner carries CVSS scores. A single `failOn` at
17
+ // the top of the file would read as one decision and mean five
18
+ // different things, so a top-level `failOn` is rejected outright
17
19
  // rather than silently ignored. Each gate keeps its own threshold in
18
20
  // its own passthrough block, spelled the way that gate spells it.
19
21
  //
20
22
  // 2. THE PASSTHROUGH IS ACTUALLY A PASSTHROUGH. `options` keys are the
21
23
  // gate's own long-flag names with the dashes stripped, and this file
22
24
  // never maps, renames, or interprets one. That is what keeps the
23
- // umbrella from growing a second, drifting copy of three CLIs, and it
25
+ // umbrella from growing a second, drifting copy of five CLIs, and it
24
26
  // is why a gate gains a flag without this package needing a release.
25
27
  // The only keys rejected are the handful the umbrella itself passes,
26
28
  // because two writers of the same flag is a fight the user would have
@@ -34,8 +36,20 @@ import path from 'node:path';
34
36
  import { fileURLToPath } from 'node:url';
35
37
  import { parse as parseYaml } from 'yaml';
36
38
  export const POLICY_FILE_NAME = '.guardrails.yaml';
37
- export const GATE_ROLES = ['dependencies', 'secrets', 'intent'];
38
- export const PRODUCTS = ['dep-guard', 'vault-guard', 'intent-guard'];
39
+ export const GATE_ROLES = [
40
+ 'dependencies',
41
+ 'secrets',
42
+ 'intent',
43
+ 'secrets-history',
44
+ 'vulnerabilities',
45
+ ];
46
+ /**
47
+ * Five products. The first three are this family's own npm packages, which
48
+ * the Action installs. The last two are external tools the adopter installs
49
+ * on their own machine or runner; conductor finds them on PATH and downloads
50
+ * nothing (src/products.ts, `managed: false`).
51
+ */
52
+ export const PRODUCTS = ['dep-guard', 'vault-guard', 'intent-guard', 'gitleaks', 'osv-scanner'];
39
53
  /**
40
54
  * When a gate runs, in order, earliest first.
41
55
  *
@@ -49,8 +63,8 @@ export const GATE_STAGES = ['commit', 'push', 'ci'];
49
63
  /**
50
64
  * Where each gate sits when the policy file does not say.
51
65
  *
52
- * Runtime is not what decides this. All three gates together take under a
53
- * second on a staged commit; the cost is CEREMONY, and only the intent gate
66
+ * Runtime is not what decides this for the three family gates: together they
67
+ * take under a second on a staged commit; the cost is CEREMONY, and only the intent gate
54
68
  * has any, because it wants a contract approved before the work starts.
55
69
  * The other two are silent until they find something, and a secret that
56
70
  * reaches a pull request is already on a remote, so the earliest stage is
@@ -60,6 +74,11 @@ export const DEFAULT_STAGE_FOR_ROLE = {
60
74
  dependencies: 'commit',
61
75
  secrets: 'commit',
62
76
  intent: 'ci',
77
+ // A history scan and a registry lookup are pull-request work, not
78
+ // commit-time work: one reads every commit, the other asks a network
79
+ // service, and neither says anything about the files being staged.
80
+ 'secrets-history': 'ci',
81
+ vulnerabilities: 'ci',
63
82
  };
64
83
  /** Whether a gate at `gateStage` runs during a run asked for at `requested`. */
65
84
  export function runsAtStage(gateStage, requested) {
@@ -79,6 +98,8 @@ export const PRODUCT_FOR_ROLE = {
79
98
  dependencies: 'dep-guard',
80
99
  secrets: 'vault-guard',
81
100
  intent: 'intent-guard',
101
+ 'secrets-history': 'gitleaks',
102
+ vulnerabilities: 'osv-scanner',
82
103
  };
83
104
  /**
84
105
  * Flags the umbrella supplies itself, per product. A policy that also sets
@@ -112,6 +133,27 @@ export const RESERVED_OPTIONS = {
112
133
  // problem rather than a confusion, since the loser decides where the gate
113
134
  // reads its rules from.
114
135
  'intent-guard': ['json', 'staged', 'project', 'paths', 'base', 'trust-base'],
136
+ // The umbrella writes every one of these for gitleaks: the report goes to a
137
+ // file it owns, the exit code for a leak is moved off 1 so an error and a
138
+ // leak stop sharing a number, history is scoped by --log-opts so one
139
+ // branch's secret cannot redden every other pull request, and the config
140
+ // is read from the base ref on a pull request, as is the ignore file.
141
+ gitleaks: [
142
+ 'report-format',
143
+ 'report-path',
144
+ 'exit-code',
145
+ 'log-opts',
146
+ 'config',
147
+ 'gitleaks-ignore-path',
148
+ 'ignore-gitleaks-allow',
149
+ 'redact',
150
+ 'no-banner',
151
+ 'log-level',
152
+ ],
153
+ // osv-scanner: the umbrella owns the format (json to stdout), the config on
154
+ // a pull-request run, and which lockfiles are scanned (every tracked one,
155
+ // by name; there is no directory walk and so no --recursive).
156
+ 'osv-scanner': ['format', 'config', 'lockfile'],
115
157
  };
116
158
  export class PolicyError extends Error {
117
159
  constructor(message) {
@@ -175,18 +217,62 @@ function reservedReason(product, key) {
175
217
  "Use the umbrella's own --base instead.");
176
218
  }
177
219
  if (product === 'dep-guard' && key === 'base') {
178
- return ('The umbrella never passes --base to this gate; it passes --staged, and a base here ' +
179
- 'would fight it over which change set is being scanned. Use the umbrella own --staged, ' +
180
- 'or leave it off to scan the working tree.');
220
+ return ('On a pull-request run the umbrella writes --base to this gate itself, pointing at the ' +
221
+ 'same ref as --trust-base, so a value here would be a second writer of the flag that ' +
222
+ 'decides what changed. Otherwise the umbrella passes --staged on a staged run, and a ' +
223
+ "base here would fight it: dep-guard's own CLI refuses --staged and --base together. On " +
224
+ 'a plain run the umbrella passes neither flag, and a base here would silently decide ' +
225
+ 'what that run compares dependencies against, without going through the trust base the ' +
226
+ 'umbrella itself decided. Leave it off; the umbrella decides it either way.');
181
227
  }
182
228
  if (product === 'vault-guard' && key === 'format') {
183
229
  return ('The umbrella writes this option itself under its short name, -f json. A --format here ' +
184
230
  'is a second writer of the same option, and which one wins depends on that CLI argument ' +
185
231
  'parser. The report format is chosen with the umbrella own --format.');
186
232
  }
233
+ const external = EXTERNAL_RESERVED_REASONS[product]?.[key];
234
+ if (external !== undefined) {
235
+ return `The umbrella passes --${key} to ${product} itself. ${external}`;
236
+ }
187
237
  return (`The umbrella passes that flag to ${product} itself, and two writers of one flag ` +
188
238
  'would resolve differently depending on that CLI argument parser.');
189
239
  }
240
+ /**
241
+ * Why each flag the umbrella writes for an external tool is the umbrella's.
242
+ * Every one of them is written; the sentence says what a second writer would
243
+ * break, which for these tools is a verdict rather than a formatting detail.
244
+ */
245
+ const EXTERNAL_RESERVED_REASONS = {
246
+ gitleaks: {
247
+ 'report-format': 'The report is parsed as JSON; another format would make every run unparseable.',
248
+ 'report-path': 'The report goes to a file the umbrella owns and reads back; pointing it elsewhere would ' +
249
+ 'leave the umbrella nothing to read.',
250
+ 'exit-code': 'The umbrella moves the leak exit code to 3 because gitleaks also exits 1 on an error; ' +
251
+ 'another value would make a crash read as a leak, or a leak read as clean.',
252
+ 'log-opts': 'The umbrella scopes history to HEAD, or to base..HEAD on a pull request, so a secret on ' +
253
+ 'another branch cannot redden this one. Narrow the scan in .gitleaks.toml instead.',
254
+ config: 'On a pull request the config is read from the base ref, so the pull request cannot ' +
255
+ 'allowlist what it adds. Commit .gitleaks.toml instead.',
256
+ 'gitleaks-ignore-path': 'On a pull request the ignore file is read from the base ref, so the pull request cannot ' +
257
+ 'ignore the fingerprint of the leak it adds. Commit .gitleaksignore instead.',
258
+ 'ignore-gitleaks-allow': 'On a pull request inline gitleaks:allow comments are ignored, because an inline allow ' +
259
+ 'lives in the tree being judged and the pull request controls it. A legitimate allow ' +
260
+ 'belongs in the base ref .gitleaks.toml allowlist or .gitleaksignore.',
261
+ redact: 'Findings reach a pull-request comment and a SARIF upload; the umbrella keeps secrets ' +
262
+ 'redacted in the report it reads.',
263
+ 'no-banner': 'The banner is noise on stderr, which the report shows when a gate fails.',
264
+ 'log-level': 'The umbrella depends on gitleaks ERR lines to tell a failed scan from a clean one: gitleaks ' +
265
+ 'reports a git failure as exit 0 with an empty report. A lower level would silence them and ' +
266
+ 'turn a scan that never happened into a pass, so the umbrella pins it at info.',
267
+ },
268
+ 'osv-scanner': {
269
+ format: 'The output is parsed as JSON from stdout; another format would make every run unparseable.',
270
+ config: 'On a pull request the config is read from the base ref, so the pull request cannot ' +
271
+ 'ignore the advisory it introduces. Commit osv-scanner.toml instead.',
272
+ lockfile: 'The umbrella hands osv-scanner every tracked lockfile by name, so no lockfile is left ' +
273
+ 'out by a policy line or by a .gitignore entry.',
274
+ },
275
+ };
190
276
  /**
191
277
  * Parses and validates policy YAML.
192
278
  *
@@ -0,0 +1,107 @@
1
+ import type { Product } from './policy.js';
2
+ export type OutputSource = {
3
+ kind: 'stdout';
4
+ } | {
5
+ kind: 'report-file';
6
+ flag: string;
7
+ extension: string;
8
+ };
9
+ export interface ExitSemantics {
10
+ clean: readonly number[];
11
+ blocked: readonly number[];
12
+ /** Exits that mean "there was nothing here to scan": clean, with a diagnostic. */
13
+ nothingToScan: readonly number[];
14
+ }
15
+ export interface VersionProbeSpec {
16
+ argv: readonly string[];
17
+ /**
18
+ * Applied to the trimmed first line of the probe's stdout. Capture group 1
19
+ * is the version when the pattern has one; otherwise the whole match is.
20
+ */
21
+ pattern: RegExp;
22
+ }
23
+ export interface ProductProfile {
24
+ product: Product;
25
+ /** Installed by the Action from npm and covered by npm audit signatures. */
26
+ managed: boolean;
27
+ versionProbe: VersionProbeSpec | null;
28
+ output: OutputSource;
29
+ exit: ExitSemantics;
30
+ timeoutMs: number;
31
+ /** Oldest version whose command line this runner speaks; null means any. */
32
+ minVersion: string | null;
33
+ /** Config file the tool auto-loads from the scanned tree; read from the base ref on a pull request. */
34
+ configFile: string | null;
35
+ /** What to pass as the config when the base ref has none, so the head's cannot be auto-loaded. */
36
+ neutralConfig: string | null;
37
+ /**
38
+ * A second file the tool auto-loads from the scanned tree that suppresses
39
+ * findings, and the flag that points it elsewhere. Read from the base ref
40
+ * on a pull request, like the config.
41
+ */
42
+ ignoreFile: {
43
+ name: string;
44
+ flag: string;
45
+ /**
46
+ * The tool ALSO loads `<scan root>/<name>` whatever the flag says, so on
47
+ * a pull request the scan root must be somewhere the head cannot write.
48
+ */
49
+ alsoLoadedFromScanRoot: boolean;
50
+ } | null;
51
+ /** How to install the tool, for a missing-binary finding. */
52
+ remedy: (skipNodeModules: boolean) => string;
53
+ /**
54
+ * A stderr line (ANSI colour stripped) that turns a clean exit into an
55
+ * error. Null for a tool whose exit code can be taken at its word.
56
+ */
57
+ stderrError: RegExp | null;
58
+ /**
59
+ * File names the tool is handed one by one, from the repository's tracked
60
+ * files, instead of being pointed at a directory to walk. Null for a tool
61
+ * that is not handed files.
62
+ */
63
+ lockfileNames: readonly string[] | null;
64
+ /**
65
+ * The config can name another file (`[extend] path`) that the tool reads
66
+ * relative to its working directory. On a pull request every such file is
67
+ * materialised from the base ref and the tool is run from that directory.
68
+ */
69
+ followsConfigExtend: boolean;
70
+ /**
71
+ * Whether this gate's INPUT is git history rather than the tree being
72
+ * judged.
73
+ *
74
+ * True only for gitleaks. Every other gate here reads the tree (vault-guard
75
+ * and dep-guard scan files, intent-guard reads a diff of paths) or a
76
+ * lockfile in it (osv-scanner), so when the head tree is byte-identical to
77
+ * the trust base's -- issue #69's shape, a value committed and then backed
78
+ * out inside one pull request -- those gates have nothing to judge that the
79
+ * base ref did not already judge, and the umbrella skips them rather than
80
+ * reporting a clean scan of a change that is not there. gitleaks' report is
81
+ * about commits between the base and HEAD, not about either tree, so it is
82
+ * the one gate an equal tree does not blind: see `decideTrustBase` and the
83
+ * equal-tree branch in `runAll` (src/run.ts).
84
+ */
85
+ readsHistory: boolean;
86
+ }
87
+ /**
88
+ * The lockfiles osv-scanner is handed, matched by base name at any depth
89
+ * among the repository's TRACKED files (`git ls-files`).
90
+ *
91
+ * By name, not by walking the tree, for three reasons: osv-scanner's own walk
92
+ * skips anything .gitignore matches, tracked or not, so a pull request could
93
+ * hide a committed lockfile from it with one ignore line; the walk can reach
94
+ * into node_modules; and an untracked lockfile is not part of what is being
95
+ * judged. Only the npm family is listed, because that is the ecosystem this
96
+ * family's own dependency gate knows (npm, pnpm, yarn, bun); osv-scanner
97
+ * supports more, and a repository whose only lockfile is another ecosystem's
98
+ * gets nothing-to-scan until a name is added here.
99
+ */
100
+ export declare const OSV_LOCKFILE_NAMES: readonly string[];
101
+ /**
102
+ * The npm gates print a bare version. No capture group on purpose: the runner
103
+ * has always reported the whole first line minus a leading v, prerelease
104
+ * suffix included, and the trust-base floor compares that value.
105
+ */
106
+ export declare const NPM_VERSION_PATTERN: RegExp;
107
+ export declare function profileFor(product: Product): ProductProfile;
@@ -0,0 +1,132 @@
1
+ // What the runner needs to know about each product, as data.
2
+ //
3
+ // The runner used to hardcode one behaviour for every gate: ask --version,
4
+ // read JSON from stdout, read exit 0 as clean and 1 as blocked, give up after
5
+ // two minutes. That was true of the three npm gates and it is not true of the
6
+ // external tools, so the behaviour lives here per product and the runner
7
+ // consults it. The three npm profiles below restate exactly what the runner
8
+ // did before profiles existed; changing one of them changes a gate that
9
+ // adopters already run.
10
+ /**
11
+ * The lockfiles osv-scanner is handed, matched by base name at any depth
12
+ * among the repository's TRACKED files (`git ls-files`).
13
+ *
14
+ * By name, not by walking the tree, for three reasons: osv-scanner's own walk
15
+ * skips anything .gitignore matches, tracked or not, so a pull request could
16
+ * hide a committed lockfile from it with one ignore line; the walk can reach
17
+ * into node_modules; and an untracked lockfile is not part of what is being
18
+ * judged. Only the npm family is listed, because that is the ecosystem this
19
+ * family's own dependency gate knows (npm, pnpm, yarn, bun); osv-scanner
20
+ * supports more, and a repository whose only lockfile is another ecosystem's
21
+ * gets nothing-to-scan until a name is added here.
22
+ */
23
+ export const OSV_LOCKFILE_NAMES = [
24
+ 'package-lock.json',
25
+ 'npm-shrinkwrap.json',
26
+ 'pnpm-lock.yaml',
27
+ 'yarn.lock',
28
+ 'bun.lock',
29
+ ];
30
+ /**
31
+ * The npm gates print a bare version. No capture group on purpose: the runner
32
+ * has always reported the whole first line minus a leading v, prerelease
33
+ * suffix included, and the trust-base floor compares that value.
34
+ */
35
+ export const NPM_VERSION_PATTERN = /^v?\d+\.\d+\.\d+.*/;
36
+ const NPM_EXIT = { clean: [0], blocked: [1], nothingToScan: [] };
37
+ function managedRemedy(product) {
38
+ return (skipNodeModules) => skipNodeModules
39
+ ? `Install the gate outside the tree with npm install -g @vaultcompass/${product}. The ` +
40
+ `conductor Action does exactly that, at the version its ${product}-version input pins, and ` +
41
+ 'that pin lives in the workflow file on the base branch.'
42
+ : `Install it with npm install -g @vaultcompass/${product}, or add it to the repository's devDependencies.`;
43
+ }
44
+ function managedProfile(product) {
45
+ return {
46
+ product,
47
+ managed: true,
48
+ versionProbe: { argv: ['--version'], pattern: NPM_VERSION_PATTERN },
49
+ output: { kind: 'stdout' },
50
+ exit: NPM_EXIT,
51
+ timeoutMs: 120_000,
52
+ minVersion: null,
53
+ configFile: null,
54
+ neutralConfig: null,
55
+ ignoreFile: null,
56
+ remedy: managedRemedy(product),
57
+ stderrError: null,
58
+ lockfileNames: null,
59
+ followsConfigExtend: false,
60
+ readsHistory: false,
61
+ };
62
+ }
63
+ const PROFILES = {
64
+ 'dep-guard': managedProfile('dep-guard'),
65
+ 'vault-guard': managedProfile('vault-guard'),
66
+ 'intent-guard': managedProfile('intent-guard'),
67
+ gitleaks: {
68
+ product: 'gitleaks',
69
+ managed: false,
70
+ versionProbe: { argv: ['version'], pattern: /(\d+\.\d+\.\d+)/ },
71
+ // gitleaks writes its JSON report to a file, never to stdout.
72
+ output: { kind: 'report-file', flag: '--report-path', extension: '.json' },
73
+ // gitleaks exits 1 for a leak AND for an error by default. The umbrella
74
+ // passes --exit-code 3 (src/gate-runner.ts, gateArgs), so 3 is a leak and
75
+ // 1 is left meaning an error.
76
+ exit: { clean: [0], blocked: [3], nothingToScan: [] },
77
+ // A full-history scan on a large repository outlives the npm gates' two
78
+ // minutes; could-not-run on every pull request is the failure to avoid.
79
+ timeoutMs: 600_000,
80
+ minVersion: '8.19.0',
81
+ configFile: '.gitleaks.toml',
82
+ neutralConfig: '[extend]\nuseDefault = true\n',
83
+ // .gitleaksignore lists fingerprints the scan skips: a pull request
84
+ // adding its own leak's fingerprint there is the config hole through a
85
+ // second file. gitleaks 8.30.1 loads the one at --gitleaks-ignore-path
86
+ // AND the one at the root of the scanned source, whatever the flag says
87
+ // (observed against the real binary, tests/fixtures/README.md), so the
88
+ // flag alone does not close it.
89
+ ignoreFile: { name: '.gitleaksignore', flag: '--gitleaks-ignore-path', alsoLoadedFromScanRoot: true },
90
+ remedy: () => 'Install gitleaks 8.19 or later on the machine or runner before conductor runs (a pinned ' +
91
+ 'release download with a checksum is the usual step), or disable the secrets-history gate ' +
92
+ 'in .guardrails.yaml. conductor does not download it.',
93
+ // gitleaks 8.30.1 swallows a git failure: it logs "<time> ERR [git]
94
+ // fatal: ..." and exits 0 with an empty report (tests/fixtures/README.md).
95
+ stderrError: /^\S+\s+ERR\s/,
96
+ lockfileNames: null,
97
+ followsConfigExtend: true,
98
+ // gitleaks reads git history (--log-opts), never the tree, which is
99
+ // exactly what makes it the one gate an equal-tree pull request does not
100
+ // blind (issue #69): the history between the base and HEAD still holds
101
+ // whatever was committed and backed out, even when the two trees match.
102
+ readsHistory: true,
103
+ },
104
+ 'osv-scanner': {
105
+ product: 'osv-scanner',
106
+ managed: false,
107
+ versionProbe: { argv: ['--version'], pattern: /(\d+\.\d+\.\d+)/ },
108
+ // JSON goes to stdout and everything else to stderr.
109
+ output: { kind: 'stdout' },
110
+ // 128 is osv-scanner's "no package sources found": a repository with no
111
+ // lockfile has nothing to scan, which is clean, not an error.
112
+ exit: { clean: [0], blocked: [1], nothingToScan: [128] },
113
+ timeoutMs: 300_000,
114
+ minVersion: '2.0.0',
115
+ configFile: 'osv-scanner.toml',
116
+ neutralConfig: '',
117
+ ignoreFile: null,
118
+ remedy: () => 'Install osv-scanner 2.x on the machine or runner before conductor runs, or disable the ' +
119
+ 'vulnerabilities gate in .guardrails.yaml. conductor does not download it.',
120
+ // osv-scanner's exit codes separate an error (127) from a verdict, and
121
+ // its stderr is progress chatter, so the exit is taken at its word.
122
+ stderrError: null,
123
+ lockfileNames: OSV_LOCKFILE_NAMES,
124
+ followsConfigExtend: false,
125
+ // osv-scanner reads the tracked lockfiles it is handed, which are the
126
+ // tree being judged, not history.
127
+ readsHistory: false,
128
+ },
129
+ };
130
+ export function profileFor(product) {
131
+ return PROFILES[product];
132
+ }