@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.
- package/README.md +127 -21
- package/dist/cli.d.ts +6 -0
- package/dist/cli.js +19 -4
- package/dist/gate-runner.d.ts +102 -10
- package/dist/gate-runner.js +282 -37
- package/dist/init-hook-detect.d.ts +1 -0
- package/dist/init-hook-detect.js +45 -0
- package/dist/init-policy.js +13 -0
- package/dist/init.d.ts +8 -0
- package/dist/init.js +166 -20
- package/dist/intent-prepare.d.ts +18 -1
- package/dist/intent-prepare.js +23 -2
- package/dist/normalize.d.ts +32 -2
- package/dist/normalize.js +117 -11
- package/dist/output-sarif.js +18 -0
- package/dist/output-text.d.ts +26 -1
- package/dist/output-text.js +206 -13
- package/dist/policy.d.ts +8 -0
- package/dist/policy.js +33 -6
- package/dist/products.d.ts +8 -1
- package/dist/products.js +14 -0
- package/dist/run.d.ts +4 -0
- package/dist/run.js +18 -2
- package/package.json +1 -1
- package/schema/guardrails.schema.json +6 -0
package/dist/output-text.d.ts
CHANGED
|
@@ -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
|
|
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;
|
package/dist/output-text.js
CHANGED
|
@@ -40,17 +40,127 @@ function subjectLabel(finding) {
|
|
|
40
40
|
return '';
|
|
41
41
|
}
|
|
42
42
|
}
|
|
43
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
168
|
-
|
|
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
|
-
|
|
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 {
|
package/dist/products.d.ts
CHANGED
|
@@ -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
|
-
|
|
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
|
@@ -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"]
|