@vaultcompass/conductor 0.9.0 → 0.10.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,4 +1,13 @@
1
1
  import type { RunResult } from './run.js';
2
+ /**
3
+ * How many entries a section prints before it rolls the rest up into one
4
+ * line, unless --verbose. A full-history gitleaks scan or an osv-scanner run
5
+ * over an old lockfile printed six hundred lines on one repository, which
6
+ * buries the verdict and every other gate. Findings past the cap are still
7
+ * findings: they are counted in every number on the report, they are in the
8
+ * SARIF log, --verbose prints them, and the exit code never reads this.
9
+ */
10
+ export declare const FINDINGS_SHOWN_PER_GATE = 20;
2
11
  /**
3
12
  * The one sentence the whole of pull-request mode has to fit into.
4
13
  *
@@ -61,7 +70,9 @@ export declare function jobLogSummary(result: RunResult): string;
61
70
  * Describes, decides nothing: every word is read off the outcomes the exit
62
71
  * code was already composed from. Same plain ASCII as the rest of this file.
63
72
  */
64
- export declare function gateLogLines(result: RunResult): string[];
73
+ export declare function gateLogLines(result: RunResult, options?: {
74
+ terminal?: boolean;
75
+ }): string[];
65
76
  /**
66
77
  * One warning per gate that was found on PATH at a version other than the one
67
78
  * this run expected (the Action's pin).
@@ -163,5 +174,19 @@ export interface TextOptions {
163
174
  * that did not block, never about a gate that did not run.
164
175
  */
165
176
  advisory?: boolean;
177
+ /**
178
+ * The report is going straight to a terminal (cli.ts: stdout is a TTY and
179
+ * no --output). Only one thing reads it: a refused trust base prints its
180
+ * refusal once at the top and one line per gate, rather than the refusal
181
+ * again in every gate's section and again in every gate's finding. A file,
182
+ * a pipe and a pull request comment never set it and are unchanged.
183
+ */
184
+ terminal?: boolean;
166
185
  }
186
+ /**
187
+ * dep-guard's own diagnostic code for an online budget that ran out before
188
+ * every lookup was made (dep-guard core, online/deadline.ts,
189
+ * ONLINE_DEADLINE_CODE). Read, never minted: the umbrella only repeats it.
190
+ */
191
+ export declare const DEP_GUARD_DEADLINE_CODE = "online-deadline-exceeded";
167
192
  export declare function renderText(result: RunResult, options?: TextOptions): string;
@@ -40,17 +40,127 @@ function subjectLabel(finding) {
40
40
  return '';
41
41
  }
42
42
  }
43
- function findingLines(finding) {
43
+ /**
44
+ * The findings of one section, as the entries a reader sees.
45
+ *
46
+ * For osv-scanner one entry per ADVISORY ON ONE INSTALLED PACKAGE, however
47
+ * many lockfiles carry it: a repository with a dozen lockfiles pinning the
48
+ * same lodash printed the same advisory a dozen times, and the one fact that
49
+ * differed between those lines, the lockfile, is what --verbose lists. Every
50
+ * other gate keeps one entry per finding. Presentation only: the findings
51
+ * themselves, their count, SARIF and the exit decision are all untouched.
52
+ */
53
+ function findingEntries(gate) {
54
+ const sorted = [...gate.findings].sort(compareFindings);
55
+ if (gate.product !== 'osv-scanner') {
56
+ return sorted.map((finding) => [finding]);
57
+ }
58
+ const groups = new Map();
59
+ for (const finding of sorted) {
60
+ const name = finding.subject.kind === 'package' ? finding.subject.name : '';
61
+ const key = JSON.stringify([
62
+ finding.ruleId,
63
+ name,
64
+ finding.details.version ?? null,
65
+ finding.blocking,
66
+ finding.severity,
67
+ finding.details.baseline ?? null,
68
+ ]);
69
+ groups.set(key, [...(groups.get(key) ?? []), finding]);
70
+ }
71
+ return [...groups.values()];
72
+ }
73
+ function isDev(finding) {
74
+ const groups = finding.details.dependencyGroups;
75
+ return Array.isArray(groups) && groups.includes('dev');
76
+ }
77
+ /** The osv-scanner head-line subject: package@installed, the lockfile or the count, the fix, dev. */
78
+ function osvSubject(entry) {
79
+ const first = entry[0];
80
+ const name = first.subject.kind === 'package' ? first.subject.name : '';
81
+ const installed = typeof first.details.version === 'string' ? first.details.version : '';
82
+ const where = entry.length === 1 && first.subject.kind === 'package'
83
+ ? `(${first.subject.manifest})`
84
+ : `${entry.length} lockfiles`;
85
+ const fixed = typeof first.details.fixedVersion === 'string' ? `fix ${first.details.fixedVersion}` : 'no fix listed';
86
+ const dev = entry.filter(isDev).length;
87
+ const devLabel = dev === 0 ? '' : dev === entry.length ? ' dev' : ` dev in ${dev} of ${entry.length}`;
88
+ return `${name}@${installed} ${where} ${fixed}${devLabel}`;
89
+ }
90
+ function shortCommit(value) {
91
+ return typeof value === 'string' && value.length > 0 ? value.slice(0, 7) : null;
92
+ }
93
+ /** gitleaks' own identity for a finding: the commit it was seen in and its fingerprint. */
94
+ function gitleaksLines(finding) {
95
+ const commit = shortCommit(finding.details.commit);
96
+ const parts = [
97
+ ...(commit === null ? [] : [`commit ${commit}`]),
98
+ ...(finding.fingerprint === null ? [] : [`fingerprint ${finding.fingerprint.value}`]),
99
+ ];
100
+ const alsoIn = Array.isArray(finding.details.alsoIn)
101
+ ? finding.details.alsoIn.map(shortCommit).filter((value) => value !== null)
102
+ : [];
103
+ if (alsoIn.length > 0) {
104
+ parts.push(`also in ${alsoIn.join(', ')}`);
105
+ }
106
+ const lines = parts.length === 0 ? [] : [` ${parts.join(' ')}`];
107
+ const twins = finding.details.possiblySameSecretAs;
108
+ if (Array.isArray(twins) && twins.length > 0) {
109
+ lines.push(` possibly the same secret as ${twins.join(', ')} (same rule, file, columns and entropy; ` +
110
+ 'a merge reports a moved line again)');
111
+ }
112
+ return lines;
113
+ }
114
+ /**
115
+ * The umbrella's own finding for a gate that did not complete, whose message
116
+ * is that gate's detail plus its stderr: both already printed in the section
117
+ * just above it. gate-missing is not one, its message carries the install
118
+ * remedy, which the section does not print anywhere else.
119
+ */
120
+ function isRepeatedProblem(finding) {
121
+ return (finding.product === 'conductor' &&
122
+ (finding.ruleId === 'conductor/gate-failed' || finding.ruleId === 'conductor/gate-output-unparseable'));
123
+ }
124
+ function findingLines(entry, verbose, shortProblem) {
125
+ const finding = entry[0];
44
126
  const marker = finding.blocking ? 'BLOCKING' : ' report';
45
127
  const severity = finding.severityIsDerived ? `${finding.severity}*` : finding.severity;
46
- const subject = subjectLabel(finding);
128
+ const subject = finding.product === 'osv-scanner' && finding.subject.kind === 'package' ? osvSubject(entry) : subjectLabel(finding);
47
129
  // The vulnerabilities gate's base-comparison label, on a compared
48
130
  // pull-request run only: the label is set nowhere else.
49
131
  const baseline = finding.details.baseline;
50
132
  const label = baseline === 'introduced' || baseline === 'present-on-base' ? ` ${baseline}` : '';
51
133
  const head = ` ${marker} ${severity.padEnd(9)} ${finding.ruleId}${subject === '' ? '' : ` ${subject}`}${label}`;
52
- return [head, ` ${finding.message}`];
134
+ // A gate that could not run already printed its reason, and the gate's own
135
+ // output, in the lines above this one. The umbrella's finding carries the
136
+ // same two again for SARIF, where they are the only record; here they were
137
+ // the second and third copy of one failure.
138
+ // The unparseable finding keeps the one sentence the section above does not
139
+ // say: whose side the problem is on.
140
+ const message = !shortProblem
141
+ ? finding.message
142
+ : finding.ruleId === 'conductor/gate-output-unparseable'
143
+ ? 'Nothing was verified by this gate; the reason is above. This is the umbrella being out of date with that gate, not a problem in your code.'
144
+ : 'Nothing was verified by this gate; the reason is above.';
145
+ const lines = [head, ` ${message}`];
146
+ if (finding.product === 'gitleaks') {
147
+ lines.push(...gitleaksLines(finding));
148
+ }
149
+ if (verbose && entry.length > 1) {
150
+ const manifests = entry.map((each) => (each.subject.kind === 'package' ? each.subject.manifest : ''));
151
+ lines.push(` lockfiles: ${manifests.join(', ')}`);
152
+ }
153
+ return lines;
53
154
  }
155
+ /**
156
+ * How many entries a section prints before it rolls the rest up into one
157
+ * line, unless --verbose. A full-history gitleaks scan or an osv-scanner run
158
+ * over an old lockfile printed six hundred lines on one repository, which
159
+ * buries the verdict and every other gate. Findings past the cap are still
160
+ * findings: they are counted in every number on the report, they are in the
161
+ * SARIF log, --verbose prints them, and the exit code never reads this.
162
+ */
163
+ export const FINDINGS_SHOWN_PER_GATE = 20;
54
164
  /**
55
165
  * The base comparison under the vulnerabilities gate's threshold line: the
56
166
  * ref, the two counts, the base policy and what it means here, then one line
@@ -80,7 +190,7 @@ function presentOnBaseReported(result) {
80
190
  .flatMap((gate) => gate.findings)
81
191
  .filter((finding) => finding.details.baseline === 'present-on-base' && !finding.blocking).length;
82
192
  }
83
- function header(gate) {
193
+ function header(gate, verbose) {
84
194
  const version = gate.productVersion === null ? '(version unknown)' : gate.productVersion;
85
195
  // On the header line rather than only at the bottom of the section: a
86
196
  // reader scanning headers for the gate that refused their commit has to
@@ -90,7 +200,10 @@ function header(gate) {
90
200
  return `${gate.role} ${gate.product} ${version} DID NOT RUN (${gate.couldNotRun.reason})${enforcement}`;
91
201
  }
92
202
  const source = gate.binary === null ? '' : ` via ${gate.binary.candidate} on ${gate.binary.source}`;
93
- return `${gate.role} ${gate.product} ${version} exit ${gate.exitCode ?? '?'} ${gate.durationMs}ms${source}${enforcement}`;
203
+ // Only with --verbose, and only a limit the policy set: a default is the
204
+ // same on every run and says nothing about this repository.
205
+ const limit = verbose && gate.timeLimit?.source === 'policy' ? ` limit ${Math.round(gate.timeLimit.ms / 1000)}s (policy)` : '';
206
+ return `${gate.role} ${gate.product} ${version} exit ${gate.exitCode ?? '?'} ${gate.durationMs}ms${limit}${source}${enforcement}`;
94
207
  }
95
208
  /**
96
209
  * The line that keeps a green exit from being a surprise.
@@ -141,8 +254,21 @@ function contractLine(gate) {
141
254
  const base = gate.intent.baseRef === null ? 'base: none, the git index' : `base: ${gate.intent.baseRef}`;
142
255
  return ` contract: ${where} ${base}`;
143
256
  }
144
- function gateSection(gate) {
145
- const lines = ['', header(gate)];
257
+ function gateSection(gate, verbose, refusedOnTerminal = false) {
258
+ // A gate the refused trust base stopped, on a terminal: the refusal is at
259
+ // the top of the report once, so the section is one line and no more.
260
+ // Every other caller (a file, a pipe, a pull request comment) keeps the full
261
+ // section, byte for byte.
262
+ if (refusedOnTerminal) {
263
+ return [` ${gate.role} ${gate.product} did not run: the trust base was refused (above)`];
264
+ }
265
+ const lines = ['', header(gate, verbose)];
266
+ // Under the header, on every outcome that carries it: gitleaks' own
267
+ // --timeout is not conductor's limit, and the gate-error it produces is the
268
+ // outcome a reader most needs this on.
269
+ if (gate.gateOwnOption !== undefined) {
270
+ lines.push(` note conductor/option-is-gate-own: ${gate.gateOwnOption}`);
271
+ }
146
272
  const contract = contractLine(gate);
147
273
  if (contract !== null) {
148
274
  lines.push(contract);
@@ -156,6 +282,11 @@ function gateSection(gate) {
156
282
  lines.push(` gate said: "${gate.couldNotRun.gateSaid}"`);
157
283
  }
158
284
  if (gate.stderr.trim().length > 0) {
285
+ if (gate.couldNotRun.reason === 'timed-out') {
286
+ // What a stopped gate printed is often a warning that has nothing to
287
+ // do with the stop; the line above is the reason.
288
+ lines.push(' (printed by the gate before it was stopped; not the reason it stopped)');
289
+ }
159
290
  for (const line of gate.stderr.trim().split('\n')) {
160
291
  lines.push(` | ${cleanOutputLine(line)}`);
161
292
  }
@@ -163,9 +294,17 @@ function gateSection(gate) {
163
294
  }
164
295
  // Sorted here rather than relying on the order the gate happened to emit:
165
296
  // blocking first, then by severity. A section whose first line is a low
166
- // finding buries the one that just refused a commit.
167
- for (const finding of [...gate.findings].sort(compareFindings)) {
168
- lines.push(...findingLines(finding));
297
+ // finding buries the one that just refused a commit. The cap keeps that
298
+ // order, so what it rolls up is always the least severe.
299
+ const entries = findingEntries(gate);
300
+ const shown = verbose ? entries : entries.slice(0, FINDINGS_SHOWN_PER_GATE);
301
+ for (const entry of shown) {
302
+ lines.push(...findingLines(entry, verbose, gate.couldNotRun !== null && isRepeatedProblem(entry[0])));
303
+ }
304
+ const hidden = entries.slice(shown.length).reduce((total, entry) => total + entry.length, 0);
305
+ if (hidden > 0) {
306
+ lines.push(` ${hidden} more finding(s) in this gate, not shown here: re-run with --verbose, or read the ` +
307
+ 'SARIF report (--format sarif). They count toward everything on this report.');
169
308
  }
170
309
  if (gate.couldNotRun === null) {
171
310
  const threshold = gate.run.failOn === null ? 'threshold not reported' : `threshold ${gate.run.failOn}`;
@@ -475,7 +614,17 @@ export function jobLogSummary(result) {
475
614
  * Describes, decides nothing: every word is read off the outcomes the exit
476
615
  * code was already composed from. Same plain ASCII as the rest of this file.
477
616
  */
478
- export function gateLogLines(result) {
617
+ export function gateLogLines(result, options = {}) {
618
+ // On a terminal a refused run's per-gate lines are the refusal sentence once
619
+ // per gate, under a report that already led with it. One line instead; a
620
+ // job log (never a terminal) keeps one line per gate.
621
+ const refusal = result.trustBase?.refusal;
622
+ if (options.terminal === true && refusal !== undefined && refusal !== null && result.gates.length > 0) {
623
+ return [
624
+ `conductor: the trust base was refused, so no gate ran: ` +
625
+ `${result.gates.map((gate) => `${gate.role} (${gate.product})`).join(', ')}; could-not-run, no exit code`,
626
+ ];
627
+ }
479
628
  const lines = [];
480
629
  for (const gate of result.gates) {
481
630
  const version = gate.productVersion === null ? 'version unknown' : gate.productVersion;
@@ -493,6 +642,11 @@ export function gateLogLines(result) {
493
642
  const blocking = gate.findings.filter((finding) => finding.blocking).length;
494
643
  outcome =
495
644
  total === 0 && (gate.exitCode ?? 0) === 0 ? 'ok' : `findings (${total}, ${blocking} blocking)`;
645
+ // Only when the gate said so; the outcome word above is unchanged.
646
+ const coverage = deadlineCoverage(gate);
647
+ if (coverage !== null) {
648
+ outcome += `, ${coverage}`;
649
+ }
496
650
  }
497
651
  // conductor's own refusals (a git below the floor, a path list it cannot
498
652
  // pass, a PATH or git-directory failure, a gate below its minimum) carry
@@ -871,6 +1025,32 @@ function isFullyClean(result) {
871
1025
  gate.intent?.note === undefined &&
872
1026
  !gate.findings.some((finding) => finding.blocking));
873
1027
  }
1028
+ /**
1029
+ * dep-guard's own diagnostic code for an online budget that ran out before
1030
+ * every lookup was made (dep-guard core, online/deadline.ts,
1031
+ * ONLINE_DEADLINE_CODE). Read, never minted: the umbrella only repeats it.
1032
+ */
1033
+ export const DEP_GUARD_DEADLINE_CODE = 'online-deadline-exceeded';
1034
+ /**
1035
+ * The coverage clause for a dep-guard run whose online lookups were cut short
1036
+ * by its own deadline, or null. Not a verdict: dep-guard still exits 0 for
1037
+ * this and so does the run; the clause exists because a summary that read
1038
+ * "ok" while some names were never looked up overstated what was checked.
1039
+ */
1040
+ function deadlineCoverage(gate) {
1041
+ if (gate.product !== 'dep-guard' || gate.couldNotRun !== null) {
1042
+ return null;
1043
+ }
1044
+ const said = gate.run.diagnostics.some((diagnostic) => diagnostic.code === DEP_GUARD_DEADLINE_CODE);
1045
+ const skipped = gate.run.details['skipped-by-deadline'];
1046
+ const count = typeof skipped === 'number' ? skipped : null;
1047
+ if (!said && (count === null || count === 0)) {
1048
+ return null;
1049
+ }
1050
+ return count === null || count === 0
1051
+ ? `online lookups incomplete (${DEP_GUARD_DEADLINE_CODE})`
1052
+ : `online lookups incomplete, ${count} skipped by the deadline (${DEP_GUARD_DEADLINE_CODE})`;
1053
+ }
874
1054
  /**
875
1055
  * The gates' own notes, and only those.
876
1056
  *
@@ -985,6 +1165,14 @@ function summaryLine(result) {
985
1165
  if (counts.length > 0) {
986
1166
  parts.push(`${counts.join(', ')}.`);
987
1167
  }
1168
+ // A clean run whose dependency gate did not finish its online lookups is
1169
+ // still exit 0, and still this line, but it says so in words.
1170
+ for (const gate of result.gates) {
1171
+ const coverage = deadlineCoverage(gate);
1172
+ if (coverage !== null) {
1173
+ parts.push(`${gate.role} (${gate.product}): ${coverage}.`);
1174
+ }
1175
+ }
988
1176
  // The suppressed and ignored counts the gates reported, summed across them
989
1177
  // and printed even at zero. The full report prints these per gate for the
990
1178
  // same reason, so a quiet report is not mistaken for a clean one; the clean
@@ -1077,8 +1265,12 @@ export function renderText(result, options = {}) {
1077
1265
  ...(refusal.length === 0 ? [] : ['']),
1078
1266
  `conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
1079
1267
  ];
1268
+ const refusedOnTerminal = options.terminal === true && refusal.length > 0;
1269
+ if (refusedOnTerminal && result.gates.length > 0) {
1270
+ lines.push('');
1271
+ }
1080
1272
  for (const gate of result.gates) {
1081
- lines.push(...gateSection(gate));
1273
+ lines.push(...gateSection(gate, Boolean(options.verbose), refusedOnTerminal));
1082
1274
  }
1083
1275
  const aside = [
1084
1276
  ...deferredLines(result),
@@ -1097,7 +1289,8 @@ export function renderText(result, options = {}) {
1097
1289
  // A derived severity is marked with a trailing asterisk above; say what
1098
1290
  // that means rather than leaving a reader to guess, and only when one is
1099
1291
  // actually on screen.
1100
- if (result.findings.some((finding) => finding.severityIsDerived)) {
1292
+ // A compact terminal refusal prints no finding line at all, so no asterisk.
1293
+ if (!refusedOnTerminal && result.findings.some((finding) => finding.severityIsDerived)) {
1101
1294
  lines.push('', '* severity assigned by the umbrella; that gate reports no per-finding severity.');
1102
1295
  }
1103
1296
  lines.push('', verdict(result, Boolean(options.advisory)));
package/dist/policy.d.ts CHANGED
@@ -91,6 +91,14 @@ export interface GatePolicy {
91
91
  * every other gate; a reader of an absent value treats it as `block`.
92
92
  */
93
93
  presentOnBase?: PresentOnBase;
94
+ /**
95
+ * conductor's own time limit for this gate, in whole seconds (10 to 21600,
96
+ * the schema's bounds). Set only when the policy names the key; absent
97
+ * means the product's profile default (src/products.ts). Gate-level beside
98
+ * `enforce`, never under `options`. Resolved, with the test hook, by
99
+ * `resolveTimeLimit` in src/gate-runner.ts and nowhere else.
100
+ */
101
+ timeoutSeconds?: number;
94
102
  }
95
103
  /** The two values of the vulnerabilities gate's present-on-base key. */
96
104
  export type PresentOnBase = 'block' | 'report';
package/dist/policy.js CHANGED
@@ -107,6 +107,17 @@ export const PRODUCT_FOR_ROLE = {
107
107
  * depend on that CLI's argument parser rather than on anything the user
108
108
  * could read in their own policy file.
109
109
  */
110
+ //
111
+ // Two keys are reserved for a different reason: they name conductor's OWN
112
+ // setting, written in the wrong place. `timeout-seconds` is the gate-level
113
+ // time limit, beside `enforce`; no tool has a --timeout-seconds flag, so the
114
+ // only way to write it under options is to mean conductor's key. `timeout`
115
+ // is reserved on the four tools that have no --timeout flag (each rejects
116
+ // it, so no working policy can contain it), and NOT on gitleaks, whose
117
+ // --timeout is its own deadline and works: reserving it there would refuse
118
+ // policies that pass it today. Neither reservation is a trust control: they
119
+ // match exact option keys only, and on a pull request only the base policy is
120
+ // read anyway.
110
121
  export const RESERVED_OPTIONS = {
111
122
  // `trust-base` is reserved for all three products, and the umbrella now
112
123
  // writes it for all three. It was reserved here before dep-guard's own
@@ -115,8 +126,8 @@ export const RESERVED_OPTIONS = {
115
126
  // have broken repositories on an upgrade nobody asked for. The flag it
116
127
  // names is the one that decides where a gate reads its rules from, which
117
128
  // is the last place to leave a window open.
118
- 'dep-guard': ['format', 'staged', 'base', 'trust-base'],
119
- 'vault-guard': ['format', 'f', 'staged', 'trust-base'],
129
+ 'dep-guard': ['format', 'staged', 'base', 'trust-base', 'timeout-seconds', 'timeout'],
130
+ 'vault-guard': ['format', 'f', 'staged', 'trust-base', 'timeout-seconds', 'timeout'],
120
131
  // `base` is reserved even though the umbrella never passes it to this gate,
121
132
  // and that is the point. The umbrella works the changed-path set out itself
122
133
  // and hands over `--paths`, because `--project` may be a temporary
@@ -132,7 +143,7 @@ export const RESERVED_OPTIONS = {
132
143
  // out. It is also the one flag where two writers would be a security
133
144
  // problem rather than a confusion, since the loser decides where the gate
134
145
  // reads its rules from.
135
- 'intent-guard': ['json', 'staged', 'project', 'paths', 'base', 'trust-base'],
146
+ 'intent-guard': ['json', 'staged', 'project', 'paths', 'base', 'trust-base', 'timeout-seconds', 'timeout'],
136
147
  // The umbrella writes every one of these for gitleaks: the report goes to a
137
148
  // file it owns, the exit code for a leak is moved off 1 so an error and a
138
149
  // leak stop sharing a number, history is scoped by --log-opts so one
@@ -149,12 +160,16 @@ export const RESERVED_OPTIONS = {
149
160
  'redact',
150
161
  'no-banner',
151
162
  'log-level',
163
+ // Conductor's own setting; `timeout` stays a passthrough here (see above).
164
+ 'timeout-seconds',
152
165
  ],
153
166
  // osv-scanner: the umbrella owns the format (json to stdout), the config on
154
167
  // a pull-request run, and which lockfiles are scanned (every tracked one,
155
168
  // by name; there is no directory walk and so no --recursive).
156
- 'osv-scanner': ['format', 'config', 'lockfile'],
169
+ 'osv-scanner': ['format', 'config', 'lockfile', 'timeout-seconds', 'timeout'],
157
170
  };
171
+ /** The keys reserved under options because they name conductor's own time limit. */
172
+ const CONDUCTOR_SETTING_KEYS = new Set(['timeout-seconds', 'timeout']);
158
173
  export class PolicyError extends Error {
159
174
  constructor(message) {
160
175
  super(message);
@@ -205,7 +220,14 @@ function describeErrors(errors, source) {
205
220
  * runs and the general sentence would send somebody looking for a flag that
206
221
  * is not on the command line of the run they are debugging.
207
222
  */
208
- function reservedReason(product, key) {
223
+ function reservedReason(product, role, key) {
224
+ if (CONDUCTOR_SETTING_KEYS.has(key)) {
225
+ return key === 'timeout-seconds'
226
+ ? "timeout-seconds is conductor's own limit for this gate. Set it beside enforce, as " +
227
+ `gates.${role}.timeout-seconds, not under options.`
228
+ : "This gate has no --timeout flag; conductor's own limit is " +
229
+ `gates.${role}.timeout-seconds, beside enforce.`;
230
+ }
209
231
  if (key === 'trust-base') {
210
232
  return ('That flag says where a gate reads its rules from, and on a pull-request run the umbrella ' +
211
233
  'writes it itself, pointing at the base ref it read its own policy from. A value here ' +
@@ -312,7 +334,7 @@ export function parsePolicy(text, source) {
312
334
  for (const key of Object.keys(options)) {
313
335
  if (RESERVED_OPTIONS[product].includes(key)) {
314
336
  throw new PolicyError(`${source}: "${key}" under gates.${role}.options is reserved. ` +
315
- reservedReason(product, key));
337
+ reservedReason(product, role, key));
316
338
  }
317
339
  }
318
340
  // Only the vulnerabilities gate has a base comparison to apply the key to.
@@ -350,6 +372,11 @@ export function parsePolicy(text, source) {
350
372
  // Absent means block: a policy written before the key existed blocks
351
373
  // on every known vulnerability, so no policy is loosened by an upgrade.
352
374
  ...(role === 'vulnerabilities' ? { presentOnBase: presentOnBase ?? 'block' } : {}),
375
+ // Only when the key is present: an absent key is the profile default,
376
+ // decided in resolveTimeLimit, never a value frozen in here.
377
+ ...(entry['timeout-seconds'] === undefined
378
+ ? {}
379
+ : { timeoutSeconds: entry['timeout-seconds'] }),
353
380
  };
354
381
  }
355
382
  return {
@@ -1,4 +1,4 @@
1
- import type { Product } from './policy.js';
1
+ import type { GateRole, Product } from './policy.js';
2
2
  export type OutputSource = {
3
3
  kind: 'stdout';
4
4
  } | {
@@ -27,7 +27,14 @@ export interface ProductProfile {
27
27
  versionProbe: VersionProbeSpec | null;
28
28
  output: OutputSource;
29
29
  exit: ExitSemantics;
30
+ /** The time limit when the policy sets no timeout-seconds for this gate. */
30
31
  timeoutMs: number;
32
+ /**
33
+ * What to do about a gate stopped at its limit: the sentence the timed-out
34
+ * detail carries. Never a bounded history window or a default size cap,
35
+ * which would narrow coverage without anybody deciding to.
36
+ */
37
+ timeoutRemedies: (role: GateRole) => string;
31
38
  /** Oldest version whose command line this runner speaks; null means any. */
32
39
  minVersion: string | null;
33
40
  /** Config file the tool auto-loads from the scanned tree; read from the base ref on a pull request. */
package/dist/products.js CHANGED
@@ -7,6 +7,11 @@
7
7
  // consults it. The three npm profiles below restate exactly what the runner
8
8
  // did before profiles existed; changing one of them changes a gate that
9
9
  // adopters already run.
10
+ /** The first half of every timed-out remedy: where the limit is raised. */
11
+ function raiseTheLimit(role) {
12
+ return (`Raise the limit with gates.${role}.timeout-seconds in .guardrails.yaml (on a pull request, on ` +
13
+ 'the base branch).');
14
+ }
10
15
  /**
11
16
  * The lockfiles osv-scanner is handed as a bare path, matched by base name at
12
17
  * any depth among the repository's TRACKED files (`git ls-files`).
@@ -113,6 +118,8 @@ function managedProfile(product) {
113
118
  output: { kind: 'stdout' },
114
119
  exit: NPM_EXIT,
115
120
  timeoutMs: 120_000,
121
+ timeoutRemedies: (role) => `${raiseTheLimit(role)} A family gate that needs more than two minutes is unusual, so the ` +
122
+ "gate's own output below is worth reading first.",
116
123
  minVersion: null,
117
124
  configFile: null,
118
125
  neutralConfig: null,
@@ -140,7 +147,12 @@ const PROFILES = {
140
147
  exit: { clean: [0], blocked: [3], nothingToScan: [] },
141
148
  // A full-history scan on a large repository outlives the npm gates' two
142
149
  // minutes; could-not-run on every pull request is the failure to avoid.
150
+ // This is the default when the policy sets no timeout-seconds.
143
151
  timeoutMs: 600_000,
152
+ timeoutRemedies: (role) => `${raiseTheLimit(role)} A history scan grows with the repository's history and the size of ` +
153
+ 'what was committed: scan full history on a schedule and let pull requests scan only their ' +
154
+ 'own range, or pass max-target-megabytes under options, which skips every file larger than ' +
155
+ 'the cap without saying which, so a secret in such a file is not found.',
144
156
  minVersion: '8.19.0',
145
157
  configFile: '.gitleaks.toml',
146
158
  neutralConfig: '[extend]\nuseDefault = true\n',
@@ -175,6 +187,8 @@ const PROFILES = {
175
187
  // lockfile has nothing to scan, which is clean, not an error.
176
188
  exit: { clean: [0], blocked: [1], nothingToScan: [128] },
177
189
  timeoutMs: 300_000,
190
+ timeoutRemedies: (role) => `${raiseTheLimit(role)} osv-scanner queries osv.dev over the network, so a slow or ` +
191
+ 'unreachable service shows up as a timeout too.',
178
192
  minVersion: '2.0.0',
179
193
  configFile: 'osv-scanner.toml',
180
194
  neutralConfig: '',
package/dist/run.d.ts CHANGED
@@ -198,6 +198,10 @@ export interface RunOptions {
198
198
  repoRoot: string;
199
199
  staged: boolean;
200
200
  pathValue: string;
201
+ /**
202
+ * A test hook: every gate's time limit, outranking the policy. No CLI path
203
+ * sets it; `resolveTimeLimit` (src/gate-runner.ts) decides the limit.
204
+ */
201
205
  timeoutMs?: number;
202
206
  /**
203
207
  * Which stopping point this run is. Absent means every enabled gate runs,
package/dist/run.js CHANGED
@@ -1,7 +1,7 @@
1
1
  // One run across every enabled gate.
2
2
  import { compareFindings } from './envelope.js';
3
3
  import { EXIT_COULD_NOT_RUN, composeExitCode, gateExitBlocks } from './exit-codes.js';
4
- import { gateProgramRefused, preparationFailed, refuseHeadControlledBinary, runGate, } from './gate-runner.js';
4
+ import { gateProgramRefused, preparationFailed, preparationTimedOut, refuseHeadControlledBinary, resolveTimeLimit, runGate, } from './gate-runner.js';
5
5
  import { resolveBaseRef } from './intent-base.js';
6
6
  import { frozenNativeContractPath, prepareIntent, } from './intent-prepare.js';
7
7
  import { GATE_ROLES, enabledGates, runsAtStage } from './policy.js';
@@ -281,13 +281,17 @@ export function runAll(policy, options) {
281
281
  continue;
282
282
  }
283
283
  }
284
+ const intentLimit = resolveTimeLimit(gate, options.timeoutMs);
284
285
  const prepared = prepareIntent({
285
286
  repoRoot: options.repoRoot,
286
287
  binary,
287
288
  env,
288
289
  ...(options.base === undefined ? {} : { base: options.base }),
289
290
  ...(options.spec === undefined ? {} : { spec: options.spec }),
290
- ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
291
+ // The same resolver runGate uses, so the preparation spawns and
292
+ // the gate's own spawns cannot disagree about its limit; each
293
+ // preparation spawn gets the full limit.
294
+ timeoutMs: intentLimit.ms,
291
295
  ...(options.tempRoot === undefined ? {} : { tempRoot: options.tempRoot }),
292
296
  ...(trustBaseRef === undefined ? {} : { trustBase: trustBaseRef }),
293
297
  });
@@ -308,6 +312,18 @@ export function runAll(policy, options) {
308
312
  });
309
313
  continue;
310
314
  }
315
+ if (prepared.kind === 'timed-out') {
316
+ outcomes.push(preparationTimedOut(
317
+ // The same enforce rule as a failed preparation, below.
318
+ trustBaseRef === undefined ? gate : { ...gate, enforce: true }, {
319
+ step: prepared.step,
320
+ elapsedMs: prepared.elapsedMs,
321
+ signal: prepared.signal,
322
+ limit: intentLimit,
323
+ ...(trustBaseRef === undefined ? {} : { trustBase: trustBaseRef }),
324
+ }));
325
+ continue;
326
+ }
311
327
  if (prepared.kind === 'failed') {
312
328
  outcomes.push(preparationFailed(
313
329
  // ENFORCED under a trust base, by the same argument as
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.9.0",
3
+ "version": "0.10.0",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [
@@ -58,6 +58,12 @@
58
58
  "description": "Only on the vulnerabilities gate. On a pull-request run osv-scanner also scans the base branch copies of the lockfiles that carry findings, and labels each finding introduced or present-on-base. block (the default when the key is absent) blocks on every finding; report reports present-on-base findings without blocking and blocks only on introduced ones. Read from the base branch policy on a pull request, so a pull request cannot set it for itself. Has no effect on a run without a base, where every finding blocks.",
59
59
  "enum": ["block", "report"]
60
60
  },
61
+ "timeout-seconds": {
62
+ "description": "How long conductor lets this gate run before stopping it, in whole seconds, from 10 to 21600 (six hours, the GitHub-hosted job limit). Every spawn of the gate gets the full limit: the version probe, the scan, the intent gate's preparation steps and osv-scanner's base run. Absent means the default for the product: 120 for dep-guard, vault-guard and intent-guard, 600 for gitleaks, 300 for osv-scanner. A gate stopped at its limit could not run (timed-out). Read from the base branch policy on a pull request, so a pull request cannot change its own limit. Not the same as a gate's own timeout flag under options.",
63
+ "type": "integer",
64
+ "minimum": 10,
65
+ "maximum": 21600
66
+ },
61
67
  "stage": {
62
68
  "description": "When this gate runs. Stages are cumulative in the order commit, push, ci: a gate runs at its own stage and at every later one, so a run at ci runs everything enabled. Defaults to commit for dependencies and secrets, and to ci for intent, secrets-history and vulnerabilities: the intent gate carries per-task ceremony, and a history scan or a registry lookup is pull-request work. A run with no --stage runs every enabled gate whatever its stage.",
63
69
  "enum": ["commit", "push", "ci"]