@vaultcompass/conductor 0.8.1 → 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 +261 -46
- package/dist/cli.d.ts +6 -0
- package/dist/cli.js +20 -5
- package/dist/envelope.d.ts +8 -0
- package/dist/exit-codes.d.ts +52 -2
- package/dist/exit-codes.js +64 -14
- package/dist/gate-runner.d.ts +124 -11
- package/dist/gate-runner.js +491 -60
- package/dist/git.d.ts +15 -0
- package/dist/git.js +20 -0
- package/dist/init-hook-detect.d.ts +1 -0
- package/dist/init-hook-detect.js +45 -0
- package/dist/init-policy.js +51 -2
- 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 +43 -2
- package/dist/normalize.js +168 -10
- package/dist/osv-baseline.d.ts +84 -0
- package/dist/osv-baseline.js +325 -0
- package/dist/osv-coverage.d.ts +80 -0
- package/dist/osv-coverage.js +223 -0
- package/dist/output-sarif.js +61 -2
- package/dist/output-text.d.ts +31 -3
- package/dist/output-text.js +354 -26
- package/dist/policy.d.ts +18 -0
- package/dist/policy.js +45 -6
- package/dist/products.d.ts +40 -11
- package/dist/products.js +87 -9
- package/dist/requirements-pin.d.ts +47 -0
- package/dist/requirements-pin.js +256 -0
- package/dist/run.d.ts +17 -0
- package/dist/run.js +29 -4
- package/dist/trust-base.d.ts +19 -0
- package/dist/trust-base.js +30 -1
- package/dist/unread-manifests.d.ts +14 -0
- package/dist/unread-manifests.js +69 -0
- package/package.json +1 -1
- package/schema/guardrails.schema.json +10 -0
package/dist/output-text.js
CHANGED
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
// CI logs, and in pasted issue reports, and the plainest thing that works
|
|
23
23
|
// everywhere is worth more here than a nicer-looking terminal.
|
|
24
24
|
import { compareFindings } from './envelope.js';
|
|
25
|
-
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN } from './exit-codes.js';
|
|
25
|
+
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, gateExitBlocks } from './exit-codes.js';
|
|
26
26
|
import { CONDUCTOR_OWN_REASONS, cleanOutputLine, conductorStatedReason, } from './gate-runner.js';
|
|
27
27
|
import { isLegacyContractPath } from './intent-prepare.js';
|
|
28
28
|
function subjectLabel(finding) {
|
|
@@ -40,14 +40,157 @@ 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);
|
|
47
|
-
|
|
48
|
-
|
|
128
|
+
const subject = finding.product === 'osv-scanner' && finding.subject.kind === 'package' ? osvSubject(entry) : subjectLabel(finding);
|
|
129
|
+
// The vulnerabilities gate's base-comparison label, on a compared
|
|
130
|
+
// pull-request run only: the label is set nowhere else.
|
|
131
|
+
const baseline = finding.details.baseline;
|
|
132
|
+
const label = baseline === 'introduced' || baseline === 'present-on-base' ? ` ${baseline}` : '';
|
|
133
|
+
const head = ` ${marker} ${severity.padEnd(9)} ${finding.ruleId}${subject === '' ? '' : ` ${subject}`}${label}`;
|
|
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;
|
|
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;
|
|
164
|
+
/**
|
|
165
|
+
* The base comparison under the vulnerabilities gate's threshold line: the
|
|
166
|
+
* ref, the two counts, the base policy and what it means here, then one line
|
|
167
|
+
* per lockfile the comparison was unavailable for. Nothing on a run with no
|
|
168
|
+
* comparison.
|
|
169
|
+
*/
|
|
170
|
+
function baseComparisonLines(gate) {
|
|
171
|
+
const comparison = gate.baseComparison;
|
|
172
|
+
if (comparison === undefined) {
|
|
173
|
+
return [];
|
|
174
|
+
}
|
|
175
|
+
const meaning = comparison.policy === 'report' ? 'report (not blocking)' : 'block (blocking)';
|
|
176
|
+
return [
|
|
177
|
+
` base comparison ${comparison.ref} introduced ${comparison.introduced} ` +
|
|
178
|
+
`present-on-base ${comparison.presentOnBase} present-on-base: ${meaning}`,
|
|
179
|
+
...comparison.unavailable.map((entry) => ` base comparison unavailable for ${entry.path}: ${entry.reason}; counted as introduced`),
|
|
180
|
+
];
|
|
49
181
|
}
|
|
50
|
-
|
|
182
|
+
/**
|
|
183
|
+
* How many present-on-base findings were reported and NOT blocking, across
|
|
184
|
+
* the gates: the vulnerabilities gate under present-on-base: report. The
|
|
185
|
+
* number on the report's third line and in the exit-0 verdict clause.
|
|
186
|
+
*/
|
|
187
|
+
function presentOnBaseReported(result) {
|
|
188
|
+
return result.gates
|
|
189
|
+
.filter((gate) => gate.baseComparison?.policy === 'report')
|
|
190
|
+
.flatMap((gate) => gate.findings)
|
|
191
|
+
.filter((finding) => finding.details.baseline === 'present-on-base' && !finding.blocking).length;
|
|
192
|
+
}
|
|
193
|
+
function header(gate, verbose) {
|
|
51
194
|
const version = gate.productVersion === null ? '(version unknown)' : gate.productVersion;
|
|
52
195
|
// On the header line rather than only at the bottom of the section: a
|
|
53
196
|
// reader scanning headers for the gate that refused their commit has to
|
|
@@ -57,7 +200,10 @@ function header(gate) {
|
|
|
57
200
|
return `${gate.role} ${gate.product} ${version} DID NOT RUN (${gate.couldNotRun.reason})${enforcement}`;
|
|
58
201
|
}
|
|
59
202
|
const source = gate.binary === null ? '' : ` via ${gate.binary.candidate} on ${gate.binary.source}`;
|
|
60
|
-
|
|
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}`;
|
|
61
207
|
}
|
|
62
208
|
/**
|
|
63
209
|
* The line that keeps a green exit from being a surprise.
|
|
@@ -75,7 +221,7 @@ function enforcementNote(gate) {
|
|
|
75
221
|
'so it is a note here rather than a failed run. Nothing was checked by it.');
|
|
76
222
|
}
|
|
77
223
|
const blocking = gate.findings.filter((finding) => finding.blocking).length;
|
|
78
|
-
if (blocking > 0 || (gate
|
|
224
|
+
if (blocking > 0 || gateExitBlocks(gate)) {
|
|
79
225
|
return (` not enforced: this gate reported ${blocking} blocking finding(s) and exited ` +
|
|
80
226
|
`${gate.exitCode ?? '?'}, and enforce is false for it in .guardrails.yaml, so the commit ` +
|
|
81
227
|
'proceeds. Set enforce: true there to make it block.');
|
|
@@ -108,8 +254,21 @@ function contractLine(gate) {
|
|
|
108
254
|
const base = gate.intent.baseRef === null ? 'base: none, the git index' : `base: ${gate.intent.baseRef}`;
|
|
109
255
|
return ` contract: ${where} ${base}`;
|
|
110
256
|
}
|
|
111
|
-
function gateSection(gate) {
|
|
112
|
-
|
|
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
|
+
}
|
|
113
272
|
const contract = contractLine(gate);
|
|
114
273
|
if (contract !== null) {
|
|
115
274
|
lines.push(contract);
|
|
@@ -123,6 +282,11 @@ function gateSection(gate) {
|
|
|
123
282
|
lines.push(` gate said: "${gate.couldNotRun.gateSaid}"`);
|
|
124
283
|
}
|
|
125
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
|
+
}
|
|
126
290
|
for (const line of gate.stderr.trim().split('\n')) {
|
|
127
291
|
lines.push(` | ${cleanOutputLine(line)}`);
|
|
128
292
|
}
|
|
@@ -130,9 +294,17 @@ function gateSection(gate) {
|
|
|
130
294
|
}
|
|
131
295
|
// Sorted here rather than relying on the order the gate happened to emit:
|
|
132
296
|
// blocking first, then by severity. A section whose first line is a low
|
|
133
|
-
// finding buries the one that just refused a commit.
|
|
134
|
-
|
|
135
|
-
|
|
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.');
|
|
136
308
|
}
|
|
137
309
|
if (gate.couldNotRun === null) {
|
|
138
310
|
const threshold = gate.run.failOn === null ? 'threshold not reported' : `threshold ${gate.run.failOn}`;
|
|
@@ -143,6 +315,7 @@ function gateSection(gate) {
|
|
|
143
315
|
? 'ignored not reported'
|
|
144
316
|
: `ignored ${gate.run.ignored}`;
|
|
145
317
|
lines.push(` ${threshold} suppressed ${gate.run.suppressed} ${ignored}`);
|
|
318
|
+
lines.push(...baseComparisonLines(gate));
|
|
146
319
|
// The gate's own run facts: what it scanned, with what, against what.
|
|
147
320
|
// These were being collected and then dropped.
|
|
148
321
|
//
|
|
@@ -225,6 +398,13 @@ function skipWording(reason) {
|
|
|
225
398
|
function excludedLines(result) {
|
|
226
399
|
return result.excluded.map((gate) => ` excluded ${gate.role} ${gate.product} did not run here; --gate did not name it`);
|
|
227
400
|
}
|
|
401
|
+
/**
|
|
402
|
+
* One line per gate the policy file switches off with enabled: false, so an
|
|
403
|
+
* adopter sees what is not running at all. Absent when none is.
|
|
404
|
+
*/
|
|
405
|
+
function disabledLines(result) {
|
|
406
|
+
return (result.disabled ?? []).map((gate) => ` disabled ${gate.role} ${gate.product} enabled: false in .guardrails.yaml; it did not run`);
|
|
407
|
+
}
|
|
228
408
|
/**
|
|
229
409
|
* One line per gate skipped because the head tree equals the trust base's
|
|
230
410
|
* (issue #69).
|
|
@@ -348,7 +528,7 @@ function unenforcedClauses(result) {
|
|
|
348
528
|
// blocking finding" reports the same gate as having blocked AND as having
|
|
349
529
|
// failed to run, which are opposite claims.
|
|
350
530
|
const blocked = unenforced.filter((gate) => gate.couldNotRun === null &&
|
|
351
|
-
((gate
|
|
531
|
+
(gateExitBlocks(gate) || gate.findings.some((finding) => finding.blocking)));
|
|
352
532
|
const broken = unenforced.filter((gate) => gate.couldNotRun !== null);
|
|
353
533
|
const clauses = [];
|
|
354
534
|
if (blocked.length > 0) {
|
|
@@ -434,7 +614,17 @@ export function jobLogSummary(result) {
|
|
|
434
614
|
* Describes, decides nothing: every word is read off the outcomes the exit
|
|
435
615
|
* code was already composed from. Same plain ASCII as the rest of this file.
|
|
436
616
|
*/
|
|
437
|
-
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
|
+
}
|
|
438
628
|
const lines = [];
|
|
439
629
|
for (const gate of result.gates) {
|
|
440
630
|
const version = gate.productVersion === null ? 'version unknown' : gate.productVersion;
|
|
@@ -452,6 +642,11 @@ export function gateLogLines(result) {
|
|
|
452
642
|
const blocking = gate.findings.filter((finding) => finding.blocking).length;
|
|
453
643
|
outcome =
|
|
454
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
|
+
}
|
|
455
650
|
}
|
|
456
651
|
// conductor's own refusals (a git below the floor, a path list it cannot
|
|
457
652
|
// pass, a PATH or git-directory failure, a gate below its minimum) carry
|
|
@@ -516,7 +711,7 @@ function blockingCount(gate) {
|
|
|
516
711
|
return 0;
|
|
517
712
|
}
|
|
518
713
|
const blocking = gate.findings.filter((finding) => finding.blocking).length;
|
|
519
|
-
return blocking === 0 && (gate
|
|
714
|
+
return blocking === 0 && gateExitBlocks(gate) ? 1 : blocking;
|
|
520
715
|
}
|
|
521
716
|
/**
|
|
522
717
|
* The verdict token: a label for the umbrella's OWN exit decision, in a
|
|
@@ -524,8 +719,11 @@ function blockingCount(gate) {
|
|
|
524
719
|
* the state without parsing the verdict sentence.
|
|
525
720
|
*
|
|
526
721
|
* pass exit 0 and nothing was hidden by it
|
|
527
|
-
* nothing-checked exit 0, but no gate ran at
|
|
528
|
-
* or every one deferred,
|
|
722
|
+
* nothing-checked exit 0, but nothing was checked: no gate ran at
|
|
723
|
+
* all (none enabled, or every one deferred,
|
|
724
|
+
* tree-unchanged or skipped), or every gate that
|
|
725
|
+
* ran checked nothing (nothing to scan, or no
|
|
726
|
+
* contract; audit finding F4)
|
|
529
727
|
* advisory-blocked (N) exit 1 that --advisory turned into exit 0
|
|
530
728
|
* unenforced-findings (N) exit 0, but enforce: false gates blocked or
|
|
531
729
|
* could not run
|
|
@@ -574,7 +772,49 @@ export function verdictToken(result, advisory) {
|
|
|
574
772
|
const unenforced = result.gates
|
|
575
773
|
.filter((gate) => !gate.enforce)
|
|
576
774
|
.reduce((total, gate) => total + (gate.couldNotRun !== null ? 1 : blockingCount(gate)), 0);
|
|
577
|
-
|
|
775
|
+
if (unenforced > 0) {
|
|
776
|
+
return `unenforced-findings (${unenforced})`;
|
|
777
|
+
}
|
|
778
|
+
// Exit 0 where every gate that RAN checked nothing (audit finding F4): the
|
|
779
|
+
// vulnerabilities gate with no lockfile it reads, an intent gate with no
|
|
780
|
+
// contract. Gates ran, so the rule above does not fire, but nothing was
|
|
781
|
+
// examined, and a pass here is the same false statement as a pass with no
|
|
782
|
+
// gate at all. Same token, same exit code (0), same predicate the verdict
|
|
783
|
+
// sentence uses, so the two cannot disagree.
|
|
784
|
+
return result.gates.every(gateCheckedNothing) ? 'nothing-checked' : 'pass';
|
|
785
|
+
}
|
|
786
|
+
/**
|
|
787
|
+
* A gate that ran and examined nothing: osv-scanner with nothing to scan,
|
|
788
|
+
* osv-scanner whose every handed lockfile parsed to no packages (exit 128,
|
|
789
|
+
* marked `packages-read 0`; a sole lockfile rewritten to {} is exactly the
|
|
790
|
+
* same news as no lockfile), or an intent gate that found no contract to
|
|
791
|
+
* check against. The one predicate behind both the verdict token and the
|
|
792
|
+
* verdict sentence's list of what was not checked.
|
|
793
|
+
*
|
|
794
|
+
* NOT the partial-empty case: `conductor/lockfiles-empty` is also raised
|
|
795
|
+
* when osv-scanner read packages from other lockfiles (audit finding F2),
|
|
796
|
+
* and that gate checked something. Only the `packages-read` marker, which
|
|
797
|
+
* the exit-128 branch alone writes, tells the two apart.
|
|
798
|
+
*/
|
|
799
|
+
function readNoPackages(gate) {
|
|
800
|
+
return gate.run.details['packages-read'] === 0;
|
|
801
|
+
}
|
|
802
|
+
function gateCheckedNothing(gate) {
|
|
803
|
+
if (gate.couldNotRun !== null) {
|
|
804
|
+
return false;
|
|
805
|
+
}
|
|
806
|
+
return (gate.diagnostics.some((d) => d.code === 'conductor/nothing-to-scan') ||
|
|
807
|
+
readNoPackages(gate) ||
|
|
808
|
+
(gate.role === 'intent' && gate.run.details.contractFound === false));
|
|
809
|
+
}
|
|
810
|
+
/** How the verdict sentence names a gate that ran and checked nothing. */
|
|
811
|
+
function checkedNothingWording(gate) {
|
|
812
|
+
if (gate.role === 'intent') {
|
|
813
|
+
return `${gate.role} ran but found no contract to check against`;
|
|
814
|
+
}
|
|
815
|
+
return readNoPackages(gate)
|
|
816
|
+
? `${gate.role} read no packages from its lockfiles`
|
|
817
|
+
: `${gate.role} had nothing to scan`;
|
|
578
818
|
}
|
|
579
819
|
function verdict(result, advisory) {
|
|
580
820
|
const refusal = result.trustBase?.refusal;
|
|
@@ -685,7 +925,7 @@ function verdictForRun(result, advisory) {
|
|
|
685
925
|
// explicitly says there is none of, so it gets its own, narrower
|
|
686
926
|
// wording that is true here and says nothing about findings at all.
|
|
687
927
|
const names = enforcedGates
|
|
688
|
-
.filter((gate) => (gate
|
|
928
|
+
.filter((gate) => gateExitBlocks(gate))
|
|
689
929
|
.map((gate) => `${gate.role} (exit ${gate.exitCode ?? '?'})`)
|
|
690
930
|
.join(', ');
|
|
691
931
|
const base = `and no finding here is marked blocking. Enforced gate(s) that exited ` +
|
|
@@ -695,19 +935,52 @@ function verdictForRun(result, advisory) {
|
|
|
695
935
|
? `verdict: exit 0, ${base} This run was advisory, so exit 1 became exit 0.`
|
|
696
936
|
: `verdict: exit 1, ${base}`;
|
|
697
937
|
}
|
|
698
|
-
|
|
938
|
+
// Gates that blocked out of gates that could have, not a bare count of
|
|
939
|
+
// the enforced ones, which read as if every one of them had blocked.
|
|
940
|
+
const blockedGates = enforcedGates.filter((gate) => blockingCount(gate) > 0).length;
|
|
941
|
+
const base = `${blocking} blocking finding(s) in ${blockedGates} of ${enforcedGates.length} ` +
|
|
942
|
+
`enforced gate(s).${aside}`;
|
|
699
943
|
return advisory
|
|
700
944
|
? `verdict: exit 0, ${base} Findings were advisory and did not block, so this run exits 0 rather than 1.`
|
|
701
945
|
: `verdict: exit 1, ${base}`;
|
|
702
946
|
}
|
|
947
|
+
// Known advisories already on the base branch, reported and not blocking
|
|
948
|
+
// (the vulnerabilities gate under present-on-base: report). Said on the
|
|
949
|
+
// exit-0 verdict, so a pass that carries them never reads as spotless.
|
|
950
|
+
const reported = presentOnBaseReported(result);
|
|
951
|
+
const presentClause = reported === 0
|
|
952
|
+
? ''
|
|
953
|
+
: `; ${reported} known ${reported === 1 ? 'vulnerability' : 'vulnerabilities'} already on the ` +
|
|
954
|
+
`base ${reported === 1 ? 'was' : 'were'} reported, not blocking (vulnerabilities: present-on-base: report)`;
|
|
703
955
|
// Exit 0 with red on the screen above it. The verdict is the one line
|
|
704
956
|
// somebody reads when they read nothing else, so it is the line that has
|
|
705
957
|
// to carry the reason rather than leaving it to the sections.
|
|
706
958
|
if (clauses.length > 0) {
|
|
707
|
-
return (`verdict: exit 0, but ${clauses.join(' and ')}. ` +
|
|
959
|
+
return (`verdict: exit 0, but ${clauses.join(' and ')}${presentClause}. ` +
|
|
708
960
|
'Those gates have enforce: false in .guardrails.yaml, so nothing here failed the run.');
|
|
709
961
|
}
|
|
710
|
-
|
|
962
|
+
// "Every enabled gate ran" is only true when each one actually checked
|
|
963
|
+
// something. A gate that was held back, left out, skipped, or found nothing
|
|
964
|
+
// to scan did not, and the sentence a reader reads alone must say so.
|
|
965
|
+
const unchecked = [
|
|
966
|
+
...result.deferred.map((gate) => `${gate.role} deferred to stage ${gate.stage}`),
|
|
967
|
+
...result.excluded.map((gate) => `${gate.role} left out by --gate`),
|
|
968
|
+
...result.treeUnchanged.map((gate) => `${gate.role} skipped, head tree equals the base tree`),
|
|
969
|
+
...result.skipped.map((gate) => `${gate.role} ${skipWording(gate.reason).verdict}`),
|
|
970
|
+
// A gate with nothing to scan, or the intent gate with require-frozen:
|
|
971
|
+
// false running with no contract: it ran and checked nothing.
|
|
972
|
+
...result.gates.filter(gateCheckedNothing).map(checkedNothingWording),
|
|
973
|
+
];
|
|
974
|
+
// Every gate that ran checked nothing: the token is nothing-checked (audit
|
|
975
|
+
// finding F4), and the sentence says what the token says.
|
|
976
|
+
if (result.gates.every(gateCheckedNothing)) {
|
|
977
|
+
return `verdict: exit 0, nothing was checked: ${unchecked.join('; ')}.`;
|
|
978
|
+
}
|
|
979
|
+
if (unchecked.length > 0) {
|
|
980
|
+
return ('verdict: exit 0, no gate blocked, but not every enabled gate checked something: ' +
|
|
981
|
+
`${unchecked.join('; ')}${presentClause}.`);
|
|
982
|
+
}
|
|
983
|
+
return `verdict: exit 0, every enabled gate ran and none blocked${presentClause}.`;
|
|
711
984
|
}
|
|
712
985
|
/**
|
|
713
986
|
* Whether this run has nothing at all to report.
|
|
@@ -739,7 +1012,9 @@ function verdictForRun(result, advisory) {
|
|
|
739
1012
|
* confusion this family exists to prevent.
|
|
740
1013
|
*/
|
|
741
1014
|
function isFullyClean(result) {
|
|
742
|
-
|
|
1015
|
+
// Every gate that ran checked nothing is the nothing-checked token's state
|
|
1016
|
+
// (audit finding F4), and a line opening "clean" would contradict it.
|
|
1017
|
+
if (result.exitCode !== 0 || result.gates.length === 0 || result.gates.every(gateCheckedNothing)) {
|
|
743
1018
|
return false;
|
|
744
1019
|
}
|
|
745
1020
|
return result.gates.every((gate) => gate.couldNotRun === null &&
|
|
@@ -750,6 +1025,32 @@ function isFullyClean(result) {
|
|
|
750
1025
|
gate.intent?.note === undefined &&
|
|
751
1026
|
!gate.findings.some((finding) => finding.blocking));
|
|
752
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
|
+
}
|
|
753
1054
|
/**
|
|
754
1055
|
* The gates' own notes, and only those.
|
|
755
1056
|
*
|
|
@@ -842,6 +1143,13 @@ function summaryLine(result) {
|
|
|
842
1143
|
else {
|
|
843
1144
|
parts.push('0 gate(s) not enforced.');
|
|
844
1145
|
}
|
|
1146
|
+
// Gates the policy file switches off. Only when there are some: a count of
|
|
1147
|
+
// zero here would be noise on the line a hook prints on every commit.
|
|
1148
|
+
const disabled = result.disabled ?? [];
|
|
1149
|
+
if (disabled.length > 0) {
|
|
1150
|
+
const names = disabled.map((gate) => `${gate.role} (${gate.product})`).join(', ');
|
|
1151
|
+
parts.push(`Disabled (enabled: false in .guardrails.yaml): ${names}.`);
|
|
1152
|
+
}
|
|
845
1153
|
// Non-blocking findings are counted rather than hidden, for the same reason
|
|
846
1154
|
// the full report prints the suppressed and ignored counts at zero: they
|
|
847
1155
|
// are things the gates actually said, and a summary that omitted them would
|
|
@@ -857,6 +1165,14 @@ function summaryLine(result) {
|
|
|
857
1165
|
if (counts.length > 0) {
|
|
858
1166
|
parts.push(`${counts.join(', ')}.`);
|
|
859
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
|
+
}
|
|
860
1176
|
// The suppressed and ignored counts the gates reported, summed across them
|
|
861
1177
|
// and printed even at zero. The full report prints these per gate for the
|
|
862
1178
|
// same reason, so a quiet report is not mistaken for a clean one; the clean
|
|
@@ -937,20 +1253,31 @@ export function renderText(result, options = {}) {
|
|
|
937
1253
|
// question, what failed the run, and that one is enforced gates only. Two
|
|
938
1254
|
// different questions, so two numbers, and the section headers and the
|
|
939
1255
|
// "not enforced" lines are what connect them.
|
|
1256
|
+
// The fixed third line (osv design, section 4.4), printed only when known
|
|
1257
|
+
// advisories were reported and not blocking. The Action copies it to the
|
|
1258
|
+
// job summary when, and only when, line 3 is exactly this shape, so a pass
|
|
1259
|
+
// that carries them does not read as spotless there either.
|
|
1260
|
+
const reported = presentOnBaseReported(result);
|
|
940
1261
|
const lines = [
|
|
941
1262
|
...headerLines(result, options),
|
|
1263
|
+
...(reported === 0 ? [] : [`present-on-base: ${reported} reported, not blocking`]),
|
|
942
1264
|
...refusal,
|
|
943
1265
|
...(refusal.length === 0 ? [] : ['']),
|
|
944
1266
|
`conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
|
|
945
1267
|
];
|
|
1268
|
+
const refusedOnTerminal = options.terminal === true && refusal.length > 0;
|
|
1269
|
+
if (refusedOnTerminal && result.gates.length > 0) {
|
|
1270
|
+
lines.push('');
|
|
1271
|
+
}
|
|
946
1272
|
for (const gate of result.gates) {
|
|
947
|
-
lines.push(...gateSection(gate));
|
|
1273
|
+
lines.push(...gateSection(gate, Boolean(options.verbose), refusedOnTerminal));
|
|
948
1274
|
}
|
|
949
1275
|
const aside = [
|
|
950
1276
|
...deferredLines(result),
|
|
951
1277
|
...skippedLines(result),
|
|
952
1278
|
...excludedLines(result),
|
|
953
1279
|
...treeUnchangedLines(result),
|
|
1280
|
+
...disabledLines(result),
|
|
954
1281
|
];
|
|
955
1282
|
if (aside.length > 0) {
|
|
956
1283
|
lines.push('', ...aside);
|
|
@@ -962,7 +1289,8 @@ export function renderText(result, options = {}) {
|
|
|
962
1289
|
// A derived severity is marked with a trailing asterisk above; say what
|
|
963
1290
|
// that means rather than leaving a reader to guess, and only when one is
|
|
964
1291
|
// actually on screen.
|
|
965
|
-
|
|
1292
|
+
// A compact terminal refusal prints no finding line at all, so no asterisk.
|
|
1293
|
+
if (!refusedOnTerminal && result.findings.some((finding) => finding.severityIsDerived)) {
|
|
966
1294
|
lines.push('', '* severity assigned by the umbrella; that gate reports no per-finding severity.');
|
|
967
1295
|
}
|
|
968
1296
|
lines.push('', verdict(result, Boolean(options.advisory)));
|
package/dist/policy.d.ts
CHANGED
|
@@ -83,7 +83,25 @@ export interface GatePolicy {
|
|
|
83
83
|
args?: string[];
|
|
84
84
|
/** Handed to the gate unchanged. */
|
|
85
85
|
options: Record<string, OptionValue>;
|
|
86
|
+
/**
|
|
87
|
+
* The vulnerabilities gate only, and always set there: whether a finding
|
|
88
|
+
* that is also on the base branch blocks (`block`, the default when the key
|
|
89
|
+
* is absent) or is reported without blocking (`report`). Gate-level beside
|
|
90
|
+
* `enforce`, never under `options`, which are a pure passthrough. Absent on
|
|
91
|
+
* every other gate; a reader of an absent value treats it as `block`.
|
|
92
|
+
*/
|
|
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;
|
|
86
102
|
}
|
|
103
|
+
/** The two values of the vulnerabilities gate's present-on-base key. */
|
|
104
|
+
export type PresentOnBase = 'block' | 'report';
|
|
87
105
|
export interface Policy {
|
|
88
106
|
version: 1;
|
|
89
107
|
gates: Partial<Record<GateRole, GatePolicy>>;
|