@vaultcompass/conductor 0.8.0 → 0.9.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 +263 -77
- package/dist/cli.js +152 -30
- package/dist/envelope.d.ts +8 -0
- package/dist/exit-codes.d.ts +52 -2
- package/dist/exit-codes.js +64 -14
- package/dist/external-config.d.ts +2 -1
- package/dist/external-config.js +33 -18
- package/dist/gate-runner.d.ts +141 -17
- package/dist/gate-runner.js +537 -83
- package/dist/git.d.ts +95 -0
- package/dist/git.js +244 -0
- package/dist/init-policy.js +38 -2
- package/dist/init.js +40 -3
- package/dist/intent-base.d.ts +35 -1
- package/dist/intent-base.js +124 -64
- package/dist/intent-prepare.d.ts +33 -2
- package/dist/intent-prepare.js +443 -34
- package/dist/intent-spec.d.ts +28 -0
- package/dist/intent-spec.js +22 -5
- package/dist/normalize.d.ts +11 -0
- package/dist/normalize.js +60 -6
- 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 +55 -15
- package/dist/output-text.d.ts +53 -2
- package/dist/output-text.js +287 -27
- package/dist/policy.d.ts +10 -0
- package/dist/policy.js +21 -7
- package/dist/products.d.ts +32 -10
- package/dist/products.js +73 -9
- package/dist/requirements-pin.d.ts +47 -0
- package/dist/requirements-pin.js +256 -0
- package/dist/resolve.d.ts +1 -0
- package/dist/resolve.js +1 -1
- package/dist/run.d.ts +21 -0
- package/dist/run.js +74 -15
- package/dist/trust-base.d.ts +101 -20
- package/dist/trust-base.js +219 -73
- 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 +4 -0
package/dist/output-text.js
CHANGED
|
@@ -22,7 +22,8 @@
|
|
|
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
|
+
import { CONDUCTOR_OWN_REASONS, cleanOutputLine, conductorStatedReason, } from './gate-runner.js';
|
|
26
27
|
import { isLegacyContractPath } from './intent-prepare.js';
|
|
27
28
|
function subjectLabel(finding) {
|
|
28
29
|
const subject = finding.subject;
|
|
@@ -43,9 +44,42 @@ function findingLines(finding) {
|
|
|
43
44
|
const marker = finding.blocking ? 'BLOCKING' : ' report';
|
|
44
45
|
const severity = finding.severityIsDerived ? `${finding.severity}*` : finding.severity;
|
|
45
46
|
const subject = subjectLabel(finding);
|
|
46
|
-
|
|
47
|
+
// The vulnerabilities gate's base-comparison label, on a compared
|
|
48
|
+
// pull-request run only: the label is set nowhere else.
|
|
49
|
+
const baseline = finding.details.baseline;
|
|
50
|
+
const label = baseline === 'introduced' || baseline === 'present-on-base' ? ` ${baseline}` : '';
|
|
51
|
+
const head = ` ${marker} ${severity.padEnd(9)} ${finding.ruleId}${subject === '' ? '' : ` ${subject}`}${label}`;
|
|
47
52
|
return [head, ` ${finding.message}`];
|
|
48
53
|
}
|
|
54
|
+
/**
|
|
55
|
+
* The base comparison under the vulnerabilities gate's threshold line: the
|
|
56
|
+
* ref, the two counts, the base policy and what it means here, then one line
|
|
57
|
+
* per lockfile the comparison was unavailable for. Nothing on a run with no
|
|
58
|
+
* comparison.
|
|
59
|
+
*/
|
|
60
|
+
function baseComparisonLines(gate) {
|
|
61
|
+
const comparison = gate.baseComparison;
|
|
62
|
+
if (comparison === undefined) {
|
|
63
|
+
return [];
|
|
64
|
+
}
|
|
65
|
+
const meaning = comparison.policy === 'report' ? 'report (not blocking)' : 'block (blocking)';
|
|
66
|
+
return [
|
|
67
|
+
` base comparison ${comparison.ref} introduced ${comparison.introduced} ` +
|
|
68
|
+
`present-on-base ${comparison.presentOnBase} present-on-base: ${meaning}`,
|
|
69
|
+
...comparison.unavailable.map((entry) => ` base comparison unavailable for ${entry.path}: ${entry.reason}; counted as introduced`),
|
|
70
|
+
];
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* How many present-on-base findings were reported and NOT blocking, across
|
|
74
|
+
* the gates: the vulnerabilities gate under present-on-base: report. The
|
|
75
|
+
* number on the report's third line and in the exit-0 verdict clause.
|
|
76
|
+
*/
|
|
77
|
+
function presentOnBaseReported(result) {
|
|
78
|
+
return result.gates
|
|
79
|
+
.filter((gate) => gate.baseComparison?.policy === 'report')
|
|
80
|
+
.flatMap((gate) => gate.findings)
|
|
81
|
+
.filter((finding) => finding.details.baseline === 'present-on-base' && !finding.blocking).length;
|
|
82
|
+
}
|
|
49
83
|
function header(gate) {
|
|
50
84
|
const version = gate.productVersion === null ? '(version unknown)' : gate.productVersion;
|
|
51
85
|
// On the header line rather than only at the bottom of the section: a
|
|
@@ -74,7 +108,7 @@ function enforcementNote(gate) {
|
|
|
74
108
|
'so it is a note here rather than a failed run. Nothing was checked by it.');
|
|
75
109
|
}
|
|
76
110
|
const blocking = gate.findings.filter((finding) => finding.blocking).length;
|
|
77
|
-
if (blocking > 0 || (gate
|
|
111
|
+
if (blocking > 0 || gateExitBlocks(gate)) {
|
|
78
112
|
return (` not enforced: this gate reported ${blocking} blocking finding(s) and exited ` +
|
|
79
113
|
`${gate.exitCode ?? '?'}, and enforce is false for it in .guardrails.yaml, so the commit ` +
|
|
80
114
|
'proceeds. Set enforce: true there to make it block.');
|
|
@@ -112,12 +146,18 @@ function gateSection(gate) {
|
|
|
112
146
|
const contract = contractLine(gate);
|
|
113
147
|
if (contract !== null) {
|
|
114
148
|
lines.push(contract);
|
|
149
|
+
if (gate.intent?.note !== undefined) {
|
|
150
|
+
lines.push(` note: ${gate.intent.note}`);
|
|
151
|
+
}
|
|
115
152
|
}
|
|
116
153
|
if (gate.couldNotRun !== null) {
|
|
117
154
|
lines.push(` ${gate.couldNotRun.detail}`);
|
|
155
|
+
if (gate.couldNotRun.gateSaid !== undefined) {
|
|
156
|
+
lines.push(` gate said: "${gate.couldNotRun.gateSaid}"`);
|
|
157
|
+
}
|
|
118
158
|
if (gate.stderr.trim().length > 0) {
|
|
119
159
|
for (const line of gate.stderr.trim().split('\n')) {
|
|
120
|
-
lines.push(` | ${line}`);
|
|
160
|
+
lines.push(` | ${cleanOutputLine(line)}`);
|
|
121
161
|
}
|
|
122
162
|
}
|
|
123
163
|
}
|
|
@@ -136,6 +176,7 @@ function gateSection(gate) {
|
|
|
136
176
|
? 'ignored not reported'
|
|
137
177
|
: `ignored ${gate.run.ignored}`;
|
|
138
178
|
lines.push(` ${threshold} suppressed ${gate.run.suppressed} ${ignored}`);
|
|
179
|
+
lines.push(...baseComparisonLines(gate));
|
|
139
180
|
// The gate's own run facts: what it scanned, with what, against what.
|
|
140
181
|
// These were being collected and then dropped.
|
|
141
182
|
//
|
|
@@ -218,6 +259,13 @@ function skipWording(reason) {
|
|
|
218
259
|
function excludedLines(result) {
|
|
219
260
|
return result.excluded.map((gate) => ` excluded ${gate.role} ${gate.product} did not run here; --gate did not name it`);
|
|
220
261
|
}
|
|
262
|
+
/**
|
|
263
|
+
* One line per gate the policy file switches off with enabled: false, so an
|
|
264
|
+
* adopter sees what is not running at all. Absent when none is.
|
|
265
|
+
*/
|
|
266
|
+
function disabledLines(result) {
|
|
267
|
+
return (result.disabled ?? []).map((gate) => ` disabled ${gate.role} ${gate.product} enabled: false in .guardrails.yaml; it did not run`);
|
|
268
|
+
}
|
|
221
269
|
/**
|
|
222
270
|
* One line per gate skipped because the head tree equals the trust base's
|
|
223
271
|
* (issue #69).
|
|
@@ -237,19 +285,39 @@ function treeUnchangedLines(result) {
|
|
|
237
285
|
* answer to "did this pull request also try to change the rules", and leaving
|
|
238
286
|
* it out when the answer is none makes a run in pull-request mode
|
|
239
287
|
* indistinguishable from a run that was never in it.
|
|
288
|
+
*
|
|
289
|
+
* NEVER A COUNT THAT TREATS A GATE THAT COULD NOT RUN AS ZERO. A gate that
|
|
290
|
+
* was put into pull-request mode and could not run reported no summary the
|
|
291
|
+
* umbrella reads, so its proposals are not known rather than none. The
|
|
292
|
+
* sentence then names those gates and counts only what the others proposed.
|
|
293
|
+
* On a run with a trust base that includes a gate that stopped before its
|
|
294
|
+
* pull-request mode was even decided (it carries no trustBase: a preparation
|
|
295
|
+
* that failed, a git older than the floor, a missing binary), because it was
|
|
296
|
+
* meant to run in that mode and reported nothing either.
|
|
240
297
|
*/
|
|
241
|
-
function proposalCount(result) {
|
|
242
|
-
|
|
298
|
+
export function proposalCount(result) {
|
|
299
|
+
const unknown = result.gates.filter((gate) => gate.couldNotRun !== null &&
|
|
300
|
+
(gate.trustBase === undefined
|
|
301
|
+
? result.trustBase !== null
|
|
302
|
+
: gate.trustBase.withheld === null && gate.trustBase.refused === null));
|
|
303
|
+
if (unknown.length === 0) {
|
|
304
|
+
return `${result.proposals.length} control change(s) proposed in this pull request`;
|
|
305
|
+
}
|
|
306
|
+
const names = unknown.map((gate) => `${gate.role} (${gate.product})`).join(', ');
|
|
307
|
+
return (`${result.proposals.length} control change(s) proposed by the gates that ran; ` +
|
|
308
|
+
`${names} could not run, so the proposals of ${unknown.length === 1 ? 'that gate are' : 'those gates are'} not known`);
|
|
243
309
|
}
|
|
244
310
|
/**
|
|
245
|
-
* The gates the umbrella
|
|
311
|
+
* The gates the umbrella did not hand the trust base to.
|
|
246
312
|
*
|
|
247
|
-
* This is the loud half and it must never be silent
|
|
248
|
-
*
|
|
249
|
-
*
|
|
250
|
-
*
|
|
251
|
-
*
|
|
252
|
-
*
|
|
313
|
+
* This is the loud half and it must never be silent: a run where one gate was
|
|
314
|
+
* not handed the base ref must not read like a run where every gate was. A
|
|
315
|
+
* gate below its pull-request-mode minimum is never here (it is
|
|
316
|
+
* could-not-run); what is left is an intent gate judging a contract imported
|
|
317
|
+
* from the base for this run, and a product with no pull-request mode at all.
|
|
318
|
+
* It is a statement about coverage rather than about anybody's code, so it is
|
|
319
|
+
* a line and a notification rather than a finding, and it never reaches the
|
|
320
|
+
* exit code.
|
|
253
321
|
*/
|
|
254
322
|
function withheldTrustBase(result) {
|
|
255
323
|
return result.gates.flatMap((gate) => {
|
|
@@ -291,6 +359,9 @@ function trustBaseLines(result) {
|
|
|
291
359
|
if (result.trustBase === null) {
|
|
292
360
|
return [];
|
|
293
361
|
}
|
|
362
|
+
if (result.trustBase.notGiven === true) {
|
|
363
|
+
return [' pull-request mode: no trust base was given, so no rules were read.'];
|
|
364
|
+
}
|
|
294
365
|
const lines = [
|
|
295
366
|
` pull-request mode: rules from ${result.trustBase.ref}. ${proposalCount(result)}.`,
|
|
296
367
|
];
|
|
@@ -318,7 +389,7 @@ function unenforcedClauses(result) {
|
|
|
318
389
|
// blocking finding" reports the same gate as having blocked AND as having
|
|
319
390
|
// failed to run, which are opposite claims.
|
|
320
391
|
const blocked = unenforced.filter((gate) => gate.couldNotRun === null &&
|
|
321
|
-
((gate
|
|
392
|
+
(gateExitBlocks(gate) || gate.findings.some((finding) => finding.blocking)));
|
|
322
393
|
const broken = unenforced.filter((gate) => gate.couldNotRun !== null);
|
|
323
394
|
const clauses = [];
|
|
324
395
|
if (blocked.length > 0) {
|
|
@@ -346,7 +417,9 @@ function refusalLines(result) {
|
|
|
346
417
|
return [];
|
|
347
418
|
}
|
|
348
419
|
return [
|
|
349
|
-
|
|
420
|
+
result.trustBase?.notGiven === true
|
|
421
|
+
? 'conductor: this is a pull-request job and no trust base was given, so no rules were read. Nothing was checked.'
|
|
422
|
+
: `conductor: refused the trust base "${result.trustBase?.ref ?? ''}". Nothing was checked.`,
|
|
350
423
|
` ${refusal}`,
|
|
351
424
|
];
|
|
352
425
|
}
|
|
@@ -378,10 +451,97 @@ function refusalLines(result) {
|
|
|
378
451
|
export function jobLogSummary(result) {
|
|
379
452
|
const refusal = result.trustBase?.refusal;
|
|
380
453
|
if (refusal !== undefined && refusal !== null) {
|
|
381
|
-
return
|
|
454
|
+
return result.trustBase?.notGiven === true
|
|
455
|
+
? `pull-request job with no trust base, no rules read: ${refusal.replace(/\.+\s*$/, '')}`
|
|
456
|
+
: `refused the trust base "${result.trustBase?.ref ?? ''}": ${refusal.replace(/\.+\s*$/, '')}`;
|
|
382
457
|
}
|
|
383
458
|
return `${result.gates.length} gate(s), ${result.findings.length} finding(s)`;
|
|
384
459
|
}
|
|
460
|
+
/**
|
|
461
|
+
* One plain line per gate, for the job log: which gate, which version, what
|
|
462
|
+
* happened, and the exit code. Written to stderr by cli.ts on EVERY run, so
|
|
463
|
+
* an adopter reading the log learns which gate did what without opening a
|
|
464
|
+
* report (the SARIF log, the text report file or the pull request comment).
|
|
465
|
+
*
|
|
466
|
+
* Outcomes, in the words the lines use: `ok`, `findings (N, M blocking)`,
|
|
467
|
+
* `could-not-run (reason)` with the gate's own stated reason when it gave
|
|
468
|
+
* one, or conductor's own reason when the refusal was conductor's (both
|
|
469
|
+
* cleaned, one line, capped and quoted), `missing (reason)` for a gate that
|
|
470
|
+
* was not found, and `skipped (why)`
|
|
471
|
+
* for a gate that was enabled and never spawned (deferred by stage, left out
|
|
472
|
+
* by --gate, no contract, tree unchanged). A gate with no process behind it
|
|
473
|
+
* says `no exit code`, never a made-up one.
|
|
474
|
+
*
|
|
475
|
+
* Describes, decides nothing: every word is read off the outcomes the exit
|
|
476
|
+
* code was already composed from. Same plain ASCII as the rest of this file.
|
|
477
|
+
*/
|
|
478
|
+
export function gateLogLines(result) {
|
|
479
|
+
const lines = [];
|
|
480
|
+
for (const gate of result.gates) {
|
|
481
|
+
const version = gate.productVersion === null ? 'version unknown' : gate.productVersion;
|
|
482
|
+
const exit = gate.exitCode === null ? 'no exit code' : `exit ${gate.exitCode}`;
|
|
483
|
+
let outcome;
|
|
484
|
+
if (gate.couldNotRun !== null) {
|
|
485
|
+
const reason = gate.couldNotRun.reason;
|
|
486
|
+
outcome =
|
|
487
|
+
reason === 'binary-missing' || reason === 'configured-command-missing'
|
|
488
|
+
? `missing (${reason})`
|
|
489
|
+
: `could-not-run (${reason})`;
|
|
490
|
+
}
|
|
491
|
+
else {
|
|
492
|
+
const total = gate.findings.length;
|
|
493
|
+
const blocking = gate.findings.filter((finding) => finding.blocking).length;
|
|
494
|
+
outcome =
|
|
495
|
+
total === 0 && (gate.exitCode ?? 0) === 0 ? 'ok' : `findings (${total}, ${blocking} blocking)`;
|
|
496
|
+
}
|
|
497
|
+
// conductor's own refusals (a git below the floor, a path list it cannot
|
|
498
|
+
// pass, a PATH or git-directory failure, a gate below its minimum) carry
|
|
499
|
+
// their reason the same way, since no gate said anything for them.
|
|
500
|
+
const conductorSaid = gate.couldNotRun !== null &&
|
|
501
|
+
gate.couldNotRun.gateSaid === undefined &&
|
|
502
|
+
CONDUCTOR_OWN_REASONS.has(gate.couldNotRun.reason)
|
|
503
|
+
? conductorStatedReason(gate.couldNotRun.detail)
|
|
504
|
+
: null;
|
|
505
|
+
lines.push(`conductor: gate ${gate.role} (${gate.product} ${version}): ${outcome}, ${exit}` +
|
|
506
|
+
(gate.enforce ? '' : ', not enforced') +
|
|
507
|
+
(gate.couldNotRun?.gateSaid === undefined ? '' : `, gate said: "${gate.couldNotRun.gateSaid}"`) +
|
|
508
|
+
(conductorSaid === null ? '' : `, conductor said: "${conductorSaid}"`));
|
|
509
|
+
}
|
|
510
|
+
const notRun = (role, product, why) => `conductor: gate ${role} (${product}): skipped (${why}), no exit code`;
|
|
511
|
+
for (const gate of result.deferred) {
|
|
512
|
+
lines.push(notRun(gate.role, gate.product, `deferred to stage ${gate.stage}`));
|
|
513
|
+
}
|
|
514
|
+
for (const gate of result.skipped) {
|
|
515
|
+
lines.push(notRun(gate.role, gate.product, skipWording(gate.reason).line));
|
|
516
|
+
}
|
|
517
|
+
for (const gate of result.excluded) {
|
|
518
|
+
lines.push(notRun(gate.role, gate.product, '--gate did not name it'));
|
|
519
|
+
}
|
|
520
|
+
for (const gate of result.treeUnchanged) {
|
|
521
|
+
lines.push(notRun(gate.role, gate.product, 'head tree equals the base tree'));
|
|
522
|
+
}
|
|
523
|
+
return lines;
|
|
524
|
+
}
|
|
525
|
+
/**
|
|
526
|
+
* One warning per gate that was found on PATH at a version other than the one
|
|
527
|
+
* this run expected (the Action's pin).
|
|
528
|
+
*
|
|
529
|
+
* For the job log only: it names where the binary was found, and an absolute
|
|
530
|
+
* path has no business in a published SARIF log or a pull request comment, so
|
|
531
|
+
* this is never part of either report. A warning and nothing more. Resolution
|
|
532
|
+
* is unchanged and the gate ran (or was refused) exactly as it would have
|
|
533
|
+
* without it.
|
|
534
|
+
*/
|
|
535
|
+
export function versionSkewWarnings(result) {
|
|
536
|
+
return result.gates.flatMap((gate) => gate.versionSkew === undefined
|
|
537
|
+
? []
|
|
538
|
+
: [
|
|
539
|
+
`conductor: warning: ${gate.product} resolved from PATH reports version ${gate.versionSkew.found}, ` +
|
|
540
|
+
`but this run expects ${gate.versionSkew.expected} (the version the action pinned). ` +
|
|
541
|
+
`It was found at ${gate.versionSkew.path}. Resolution is unchanged and that binary was used. ` +
|
|
542
|
+
`Fix: remove the other ${gate.product} from PATH, or install ${gate.versionSkew.expected}.`,
|
|
543
|
+
]);
|
|
544
|
+
}
|
|
385
545
|
/**
|
|
386
546
|
* How many blocking findings one gate that RAN is carrying, for the token.
|
|
387
547
|
*
|
|
@@ -397,7 +557,7 @@ function blockingCount(gate) {
|
|
|
397
557
|
return 0;
|
|
398
558
|
}
|
|
399
559
|
const blocking = gate.findings.filter((finding) => finding.blocking).length;
|
|
400
|
-
return blocking === 0 && (gate
|
|
560
|
+
return blocking === 0 && gateExitBlocks(gate) ? 1 : blocking;
|
|
401
561
|
}
|
|
402
562
|
/**
|
|
403
563
|
* The verdict token: a label for the umbrella's OWN exit decision, in a
|
|
@@ -405,8 +565,11 @@ function blockingCount(gate) {
|
|
|
405
565
|
* the state without parsing the verdict sentence.
|
|
406
566
|
*
|
|
407
567
|
* pass exit 0 and nothing was hidden by it
|
|
408
|
-
* nothing-checked exit 0, but no gate ran at
|
|
409
|
-
* or every one deferred,
|
|
568
|
+
* nothing-checked exit 0, but nothing was checked: no gate ran at
|
|
569
|
+
* all (none enabled, or every one deferred,
|
|
570
|
+
* tree-unchanged or skipped), or every gate that
|
|
571
|
+
* ran checked nothing (nothing to scan, or no
|
|
572
|
+
* contract; audit finding F4)
|
|
410
573
|
* advisory-blocked (N) exit 1 that --advisory turned into exit 0
|
|
411
574
|
* unenforced-findings (N) exit 0, but enforce: false gates blocked or
|
|
412
575
|
* could not run
|
|
@@ -455,7 +618,49 @@ export function verdictToken(result, advisory) {
|
|
|
455
618
|
const unenforced = result.gates
|
|
456
619
|
.filter((gate) => !gate.enforce)
|
|
457
620
|
.reduce((total, gate) => total + (gate.couldNotRun !== null ? 1 : blockingCount(gate)), 0);
|
|
458
|
-
|
|
621
|
+
if (unenforced > 0) {
|
|
622
|
+
return `unenforced-findings (${unenforced})`;
|
|
623
|
+
}
|
|
624
|
+
// Exit 0 where every gate that RAN checked nothing (audit finding F4): the
|
|
625
|
+
// vulnerabilities gate with no lockfile it reads, an intent gate with no
|
|
626
|
+
// contract. Gates ran, so the rule above does not fire, but nothing was
|
|
627
|
+
// examined, and a pass here is the same false statement as a pass with no
|
|
628
|
+
// gate at all. Same token, same exit code (0), same predicate the verdict
|
|
629
|
+
// sentence uses, so the two cannot disagree.
|
|
630
|
+
return result.gates.every(gateCheckedNothing) ? 'nothing-checked' : 'pass';
|
|
631
|
+
}
|
|
632
|
+
/**
|
|
633
|
+
* A gate that ran and examined nothing: osv-scanner with nothing to scan,
|
|
634
|
+
* osv-scanner whose every handed lockfile parsed to no packages (exit 128,
|
|
635
|
+
* marked `packages-read 0`; a sole lockfile rewritten to {} is exactly the
|
|
636
|
+
* same news as no lockfile), or an intent gate that found no contract to
|
|
637
|
+
* check against. The one predicate behind both the verdict token and the
|
|
638
|
+
* verdict sentence's list of what was not checked.
|
|
639
|
+
*
|
|
640
|
+
* NOT the partial-empty case: `conductor/lockfiles-empty` is also raised
|
|
641
|
+
* when osv-scanner read packages from other lockfiles (audit finding F2),
|
|
642
|
+
* and that gate checked something. Only the `packages-read` marker, which
|
|
643
|
+
* the exit-128 branch alone writes, tells the two apart.
|
|
644
|
+
*/
|
|
645
|
+
function readNoPackages(gate) {
|
|
646
|
+
return gate.run.details['packages-read'] === 0;
|
|
647
|
+
}
|
|
648
|
+
function gateCheckedNothing(gate) {
|
|
649
|
+
if (gate.couldNotRun !== null) {
|
|
650
|
+
return false;
|
|
651
|
+
}
|
|
652
|
+
return (gate.diagnostics.some((d) => d.code === 'conductor/nothing-to-scan') ||
|
|
653
|
+
readNoPackages(gate) ||
|
|
654
|
+
(gate.role === 'intent' && gate.run.details.contractFound === false));
|
|
655
|
+
}
|
|
656
|
+
/** How the verdict sentence names a gate that ran and checked nothing. */
|
|
657
|
+
function checkedNothingWording(gate) {
|
|
658
|
+
if (gate.role === 'intent') {
|
|
659
|
+
return `${gate.role} ran but found no contract to check against`;
|
|
660
|
+
}
|
|
661
|
+
return readNoPackages(gate)
|
|
662
|
+
? `${gate.role} read no packages from its lockfiles`
|
|
663
|
+
: `${gate.role} had nothing to scan`;
|
|
459
664
|
}
|
|
460
665
|
function verdict(result, advisory) {
|
|
461
666
|
const refusal = result.trustBase?.refusal;
|
|
@@ -465,8 +670,11 @@ function verdict(result, advisory) {
|
|
|
465
670
|
// them would describe a different run from the one that happened. A
|
|
466
671
|
// refusal is a could-not-run outcome (exit 2), which --advisory never
|
|
467
672
|
// touches, so this branch reads advisory or not exactly the same.
|
|
468
|
-
return
|
|
469
|
-
'
|
|
673
|
+
return result.trustBase?.notGiven === true
|
|
674
|
+
? 'verdict: exit 2, this is a pull-request job and no trust base was given, so no rules ' +
|
|
675
|
+
'were read, no gate ran and nothing here is a result of any kind.'
|
|
676
|
+
: `verdict: exit 2, the trust base "${result.trustBase?.ref ?? ''}" could not be used, ` +
|
|
677
|
+
'so no gate ran and nothing here is a result of any kind.';
|
|
470
678
|
}
|
|
471
679
|
return verdictForRun(result, advisory);
|
|
472
680
|
}
|
|
@@ -563,7 +771,7 @@ function verdictForRun(result, advisory) {
|
|
|
563
771
|
// explicitly says there is none of, so it gets its own, narrower
|
|
564
772
|
// wording that is true here and says nothing about findings at all.
|
|
565
773
|
const names = enforcedGates
|
|
566
|
-
.filter((gate) => (gate
|
|
774
|
+
.filter((gate) => gateExitBlocks(gate))
|
|
567
775
|
.map((gate) => `${gate.role} (exit ${gate.exitCode ?? '?'})`)
|
|
568
776
|
.join(', ');
|
|
569
777
|
const base = `and no finding here is marked blocking. Enforced gate(s) that exited ` +
|
|
@@ -573,19 +781,52 @@ function verdictForRun(result, advisory) {
|
|
|
573
781
|
? `verdict: exit 0, ${base} This run was advisory, so exit 1 became exit 0.`
|
|
574
782
|
: `verdict: exit 1, ${base}`;
|
|
575
783
|
}
|
|
576
|
-
|
|
784
|
+
// Gates that blocked out of gates that could have, not a bare count of
|
|
785
|
+
// the enforced ones, which read as if every one of them had blocked.
|
|
786
|
+
const blockedGates = enforcedGates.filter((gate) => blockingCount(gate) > 0).length;
|
|
787
|
+
const base = `${blocking} blocking finding(s) in ${blockedGates} of ${enforcedGates.length} ` +
|
|
788
|
+
`enforced gate(s).${aside}`;
|
|
577
789
|
return advisory
|
|
578
790
|
? `verdict: exit 0, ${base} Findings were advisory and did not block, so this run exits 0 rather than 1.`
|
|
579
791
|
: `verdict: exit 1, ${base}`;
|
|
580
792
|
}
|
|
793
|
+
// Known advisories already on the base branch, reported and not blocking
|
|
794
|
+
// (the vulnerabilities gate under present-on-base: report). Said on the
|
|
795
|
+
// exit-0 verdict, so a pass that carries them never reads as spotless.
|
|
796
|
+
const reported = presentOnBaseReported(result);
|
|
797
|
+
const presentClause = reported === 0
|
|
798
|
+
? ''
|
|
799
|
+
: `; ${reported} known ${reported === 1 ? 'vulnerability' : 'vulnerabilities'} already on the ` +
|
|
800
|
+
`base ${reported === 1 ? 'was' : 'were'} reported, not blocking (vulnerabilities: present-on-base: report)`;
|
|
581
801
|
// Exit 0 with red on the screen above it. The verdict is the one line
|
|
582
802
|
// somebody reads when they read nothing else, so it is the line that has
|
|
583
803
|
// to carry the reason rather than leaving it to the sections.
|
|
584
804
|
if (clauses.length > 0) {
|
|
585
|
-
return (`verdict: exit 0, but ${clauses.join(' and ')}. ` +
|
|
805
|
+
return (`verdict: exit 0, but ${clauses.join(' and ')}${presentClause}. ` +
|
|
586
806
|
'Those gates have enforce: false in .guardrails.yaml, so nothing here failed the run.');
|
|
587
807
|
}
|
|
588
|
-
|
|
808
|
+
// "Every enabled gate ran" is only true when each one actually checked
|
|
809
|
+
// something. A gate that was held back, left out, skipped, or found nothing
|
|
810
|
+
// to scan did not, and the sentence a reader reads alone must say so.
|
|
811
|
+
const unchecked = [
|
|
812
|
+
...result.deferred.map((gate) => `${gate.role} deferred to stage ${gate.stage}`),
|
|
813
|
+
...result.excluded.map((gate) => `${gate.role} left out by --gate`),
|
|
814
|
+
...result.treeUnchanged.map((gate) => `${gate.role} skipped, head tree equals the base tree`),
|
|
815
|
+
...result.skipped.map((gate) => `${gate.role} ${skipWording(gate.reason).verdict}`),
|
|
816
|
+
// A gate with nothing to scan, or the intent gate with require-frozen:
|
|
817
|
+
// false running with no contract: it ran and checked nothing.
|
|
818
|
+
...result.gates.filter(gateCheckedNothing).map(checkedNothingWording),
|
|
819
|
+
];
|
|
820
|
+
// Every gate that ran checked nothing: the token is nothing-checked (audit
|
|
821
|
+
// finding F4), and the sentence says what the token says.
|
|
822
|
+
if (result.gates.every(gateCheckedNothing)) {
|
|
823
|
+
return `verdict: exit 0, nothing was checked: ${unchecked.join('; ')}.`;
|
|
824
|
+
}
|
|
825
|
+
if (unchecked.length > 0) {
|
|
826
|
+
return ('verdict: exit 0, no gate blocked, but not every enabled gate checked something: ' +
|
|
827
|
+
`${unchecked.join('; ')}${presentClause}.`);
|
|
828
|
+
}
|
|
829
|
+
return `verdict: exit 0, every enabled gate ran and none blocked${presentClause}.`;
|
|
589
830
|
}
|
|
590
831
|
/**
|
|
591
832
|
* Whether this run has nothing at all to report.
|
|
@@ -617,12 +858,17 @@ function verdictForRun(result, advisory) {
|
|
|
617
858
|
* confusion this family exists to prevent.
|
|
618
859
|
*/
|
|
619
860
|
function isFullyClean(result) {
|
|
620
|
-
|
|
861
|
+
// Every gate that ran checked nothing is the nothing-checked token's state
|
|
862
|
+
// (audit finding F4), and a line opening "clean" would contradict it.
|
|
863
|
+
if (result.exitCode !== 0 || result.gates.length === 0 || result.gates.every(gateCheckedNothing)) {
|
|
621
864
|
return false;
|
|
622
865
|
}
|
|
623
866
|
return result.gates.every((gate) => gate.couldNotRun === null &&
|
|
624
867
|
(gate.exitCode ?? 0) === 0 &&
|
|
625
868
|
gate.diagnostics.length === 0 &&
|
|
869
|
+
// A note about an input this run did not use is never folded into the
|
|
870
|
+
// one-line summary, where nobody would see it.
|
|
871
|
+
gate.intent?.note === undefined &&
|
|
626
872
|
!gate.findings.some((finding) => finding.blocking));
|
|
627
873
|
}
|
|
628
874
|
/**
|
|
@@ -717,6 +963,13 @@ function summaryLine(result) {
|
|
|
717
963
|
else {
|
|
718
964
|
parts.push('0 gate(s) not enforced.');
|
|
719
965
|
}
|
|
966
|
+
// Gates the policy file switches off. Only when there are some: a count of
|
|
967
|
+
// zero here would be noise on the line a hook prints on every commit.
|
|
968
|
+
const disabled = result.disabled ?? [];
|
|
969
|
+
if (disabled.length > 0) {
|
|
970
|
+
const names = disabled.map((gate) => `${gate.role} (${gate.product})`).join(', ');
|
|
971
|
+
parts.push(`Disabled (enabled: false in .guardrails.yaml): ${names}.`);
|
|
972
|
+
}
|
|
720
973
|
// Non-blocking findings are counted rather than hidden, for the same reason
|
|
721
974
|
// the full report prints the suppressed and ignored counts at zero: they
|
|
722
975
|
// are things the gates actually said, and a summary that omitted them would
|
|
@@ -812,8 +1065,14 @@ export function renderText(result, options = {}) {
|
|
|
812
1065
|
// question, what failed the run, and that one is enforced gates only. Two
|
|
813
1066
|
// different questions, so two numbers, and the section headers and the
|
|
814
1067
|
// "not enforced" lines are what connect them.
|
|
1068
|
+
// The fixed third line (osv design, section 4.4), printed only when known
|
|
1069
|
+
// advisories were reported and not blocking. The Action copies it to the
|
|
1070
|
+
// job summary when, and only when, line 3 is exactly this shape, so a pass
|
|
1071
|
+
// that carries them does not read as spotless there either.
|
|
1072
|
+
const reported = presentOnBaseReported(result);
|
|
815
1073
|
const lines = [
|
|
816
1074
|
...headerLines(result, options),
|
|
1075
|
+
...(reported === 0 ? [] : [`present-on-base: ${reported} reported, not blocking`]),
|
|
817
1076
|
...refusal,
|
|
818
1077
|
...(refusal.length === 0 ? [] : ['']),
|
|
819
1078
|
`conductor run: ${result.gates.length} gate(s), ${result.findings.length} finding(s)`,
|
|
@@ -826,6 +1085,7 @@ export function renderText(result, options = {}) {
|
|
|
826
1085
|
...skippedLines(result),
|
|
827
1086
|
...excludedLines(result),
|
|
828
1087
|
...treeUnchangedLines(result),
|
|
1088
|
+
...disabledLines(result),
|
|
829
1089
|
];
|
|
830
1090
|
if (aside.length > 0) {
|
|
831
1091
|
lines.push('', ...aside);
|
package/dist/policy.d.ts
CHANGED
|
@@ -83,7 +83,17 @@ 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;
|
|
86
94
|
}
|
|
95
|
+
/** The two values of the vulnerabilities gate's present-on-base key. */
|
|
96
|
+
export type PresentOnBase = 'block' | 'report';
|
|
87
97
|
export interface Policy {
|
|
88
98
|
version: 1;
|
|
89
99
|
gates: Partial<Record<GateRole, GatePolicy>>;
|
package/dist/policy.js
CHANGED
|
@@ -195,13 +195,15 @@ function describeErrors(errors, source) {
|
|
|
195
195
|
* Why one reserved key is reserved.
|
|
196
196
|
*
|
|
197
197
|
* The general sentence, at the bottom, is that the umbrella writes that exact
|
|
198
|
-
* flag itself, and it is true of most of these keys.
|
|
199
|
-
*
|
|
200
|
-
*
|
|
201
|
-
* the
|
|
202
|
-
*
|
|
203
|
-
*
|
|
204
|
-
*
|
|
198
|
+
* flag itself, and it is true of most of these keys. Two keys are reserved
|
|
199
|
+
* although the umbrella writes no such flag, and that is what
|
|
200
|
+
* policy.test.ts pins: format on vault-guard, and base on intent-guard. The
|
|
201
|
+
* test derives the flags gateArgs actually writes and holds that
|
|
202
|
+
* reserved-without-writing list to exactly those two, so another one cannot
|
|
203
|
+
* be added without saying why. trust-base, and base on dep-guard, get their
|
|
204
|
+
* own messages as well, because the umbrella writes those flags only on some
|
|
205
|
+
* runs and the general sentence would send somebody looking for a flag that
|
|
206
|
+
* is not on the command line of the run they are debugging.
|
|
205
207
|
*/
|
|
206
208
|
function reservedReason(product, key) {
|
|
207
209
|
if (key === 'trust-base') {
|
|
@@ -313,6 +315,15 @@ export function parsePolicy(text, source) {
|
|
|
313
315
|
reservedReason(product, key));
|
|
314
316
|
}
|
|
315
317
|
}
|
|
318
|
+
// Only the vulnerabilities gate has a base comparison to apply the key to.
|
|
319
|
+
// On another gate it would read as a promise nothing keeps, so it is
|
|
320
|
+
// refused rather than ignored.
|
|
321
|
+
const presentOnBase = entry['present-on-base'];
|
|
322
|
+
if (presentOnBase !== undefined && role !== 'vulnerabilities') {
|
|
323
|
+
throw new PolicyError(`${source}: gates.${role}.present-on-base is set, but only the vulnerabilities gate ` +
|
|
324
|
+
'(osv-scanner) compares a pull request with its base, so the key has nothing to decide ' +
|
|
325
|
+
`on the ${role} gate. Remove it there.`);
|
|
326
|
+
}
|
|
316
327
|
const command = entry.command;
|
|
317
328
|
if (command !== undefined && !path.isAbsolute(command)) {
|
|
318
329
|
throw new PolicyError(`${source}: gates.${role}.command must be an absolute path, got "${command}". ` +
|
|
@@ -336,6 +347,9 @@ export function parsePolicy(text, source) {
|
|
|
336
347
|
...(command === undefined ? {} : { command }),
|
|
337
348
|
...(entry.args === undefined ? {} : { args: entry.args }),
|
|
338
349
|
options,
|
|
350
|
+
// Absent means block: a policy written before the key existed blocks
|
|
351
|
+
// on every known vulnerability, so no policy is loosened by an upgrade.
|
|
352
|
+
...(role === 'vulnerabilities' ? { presentOnBase: presentOnBase ?? 'block' } : {}),
|
|
339
353
|
};
|
|
340
354
|
}
|
|
341
355
|
return {
|
package/dist/products.d.ts
CHANGED
|
@@ -56,11 +56,13 @@ export interface ProductProfile {
|
|
|
56
56
|
*/
|
|
57
57
|
stderrError: RegExp | null;
|
|
58
58
|
/**
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
* that
|
|
59
|
+
* Which tracked files the tool is handed one by one, by base name, instead
|
|
60
|
+
* of being pointed at a directory to walk, and how: `bare` as the path
|
|
61
|
+
* itself, `requirements` as a pip requirements file that must first pass
|
|
62
|
+
* the pin check (src/requirements-pin.ts). Null for a tool that is not
|
|
63
|
+
* handed files.
|
|
62
64
|
*/
|
|
63
|
-
|
|
65
|
+
lockfileMatcher: ((file: string) => LockfileKind | null) | null;
|
|
64
66
|
/**
|
|
65
67
|
* The config can name another file (`[extend] path`) that the tool reads
|
|
66
68
|
* relative to its working directory. On a pull request every such file is
|
|
@@ -84,20 +86,40 @@ export interface ProductProfile {
|
|
|
84
86
|
*/
|
|
85
87
|
readsHistory: boolean;
|
|
86
88
|
}
|
|
89
|
+
/** How a matched file is handed over: as its own path, or as a requirements file. */
|
|
90
|
+
export type LockfileKind = 'bare' | 'requirements';
|
|
87
91
|
/**
|
|
88
|
-
* The lockfiles osv-scanner is handed, matched by base name at
|
|
89
|
-
* among the repository's TRACKED files (`git ls-files`).
|
|
92
|
+
* The lockfiles osv-scanner is handed as a bare path, matched by base name at
|
|
93
|
+
* any depth among the repository's TRACKED files (`git ls-files`).
|
|
90
94
|
*
|
|
91
95
|
* By name, not by walking the tree, for three reasons: osv-scanner's own walk
|
|
92
96
|
* skips anything .gitignore matches, tracked or not, so a pull request could
|
|
93
97
|
* hide a committed lockfile from it with one ignore line; the walk can reach
|
|
94
98
|
* into node_modules; and an untracked lockfile is not part of what is being
|
|
95
|
-
* judged.
|
|
96
|
-
*
|
|
97
|
-
*
|
|
98
|
-
*
|
|
99
|
+
* judged.
|
|
100
|
+
*
|
|
101
|
+
* Every name here was handed to osv-scanner 2.4.0 with --lockfile and read
|
|
102
|
+
* (the 2026-10-11 osv design under docs/superpowers/specs, section 2.1). go.sum is deliberately absent: 2.4.0
|
|
103
|
+
* rejects it ("could not determine extractor", exit 127), which would make
|
|
104
|
+
* every Go pull request could-not-run, and go.mod is what it reads for Go.
|
|
105
|
+
*
|
|
106
|
+
* The second group was added on 2026-10-13 (audit finding F3: a tracked
|
|
107
|
+
* mix.lock was neither scanned nor named), each measured the same way
|
|
108
|
+
* against 2.4.0 and read with one or more packages. Measured and NOT added,
|
|
109
|
+
* because 2.4.0 exits 127 on them: Podfile.lock and deno.lock (both are
|
|
110
|
+
* named by the unread-manifests note instead). gradle's
|
|
111
|
+
* verification-metadata.xml is read only inside a `gradle` directory and is
|
|
112
|
+
* matched by `osvLockfileKind` rather than listed here.
|
|
99
113
|
*/
|
|
100
114
|
export declare const OSV_LOCKFILE_NAMES: readonly string[];
|
|
115
|
+
/**
|
|
116
|
+
* What osv-scanner is handed for a tracked file, or null. Takes the
|
|
117
|
+
* repository-relative path (a bare base name works for every name but one):
|
|
118
|
+
* gradle's verification-metadata.xml is read by osv-scanner 2.4.0 only when
|
|
119
|
+
* its parent directory is `gradle`, and anywhere else it exits 127, so the
|
|
120
|
+
* parent is part of the match for that one file.
|
|
121
|
+
*/
|
|
122
|
+
export declare function osvLockfileKind(file: string): LockfileKind | null;
|
|
101
123
|
/**
|
|
102
124
|
* The npm gates print a bare version. No capture group on purpose: the runner
|
|
103
125
|
* has always reported the whole first line minus a leading v, prerelease
|