@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/cli.js
CHANGED
|
@@ -6,17 +6,18 @@
|
|
|
6
6
|
// parses arguments and prints. That split is what lets every one of those
|
|
7
7
|
// decisions be tested without a subprocess.
|
|
8
8
|
import { Command, CommanderError } from 'commander';
|
|
9
|
-
import { execFileSync } from 'node:child_process';
|
|
10
9
|
import { closeSync, constants as fsConstants, lstatSync, openSync, readFileSync, realpathSync, statSync, unlinkSync, writeSync, } from 'node:fs';
|
|
10
|
+
import os from 'node:os';
|
|
11
11
|
import path from 'node:path';
|
|
12
12
|
import { fileURLToPath } from 'node:url';
|
|
13
13
|
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, EXIT_OK } from './exit-codes.js';
|
|
14
|
+
import { absolutePathEntries, createGitShim, pinGitOutside, pinnedGitInside, realPathInside, removeGitShim, runGit, tempInsideTreeMessage, workTreeAbove, } from './git.js';
|
|
14
15
|
import { applyInit, planInit, renderInitHuman, renderRevertHuman, revertInit, } from './init.js';
|
|
15
16
|
import { renderSarif } from './output-sarif.js';
|
|
16
|
-
import { jobLogSummary, renderText, verdictToken } from './output-text.js';
|
|
17
|
+
import { gateLogLines, jobLogSummary, renderText, verdictToken, versionSkewWarnings, } from './output-text.js';
|
|
17
18
|
import { GATE_ROLES, GATE_STAGES, POLICY_FILE_NAME, PolicyError, applyCliOverrides, loadPolicy, parsePolicy, } from './policy.js';
|
|
18
19
|
import { refusedTrustBase, runAll } from './run.js';
|
|
19
|
-
import { headTreeEqualsBase, policyDiffers,
|
|
20
|
+
import { headTreeEqualsBase, policyDiffers, readFileAtRef, refuseTrustBaseForPullRequest, unreadableBaseRemedy, refuseTrustBaseRef, } from './trust-base.js';
|
|
20
21
|
const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
|
|
21
22
|
const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
|
|
22
23
|
/**
|
|
@@ -94,31 +95,21 @@ function writeReportFile(target, what, body) {
|
|
|
94
95
|
* the path's spelling.
|
|
95
96
|
*/
|
|
96
97
|
function isGitDirectory(cwd) {
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
cwd,
|
|
100
|
-
encoding: 'utf8',
|
|
101
|
-
stdio: ['ignore', 'pipe', 'ignore'],
|
|
102
|
-
}).trim() === 'true');
|
|
103
|
-
}
|
|
104
|
-
catch {
|
|
105
|
-
return false;
|
|
106
|
-
}
|
|
98
|
+
const result = runGit(cwd, ['rev-parse', '--is-inside-git-dir']);
|
|
99
|
+
return result.error === undefined && result.status === 0 && result.stdout.trim() === 'true';
|
|
107
100
|
}
|
|
108
101
|
function repoRoot(cwd) {
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
encoding: 'utf8',
|
|
113
|
-
stdio: ['ignore', 'pipe', 'ignore'],
|
|
114
|
-
}).trim();
|
|
102
|
+
const result = runGit(cwd, ['rev-parse', '--show-toplevel']);
|
|
103
|
+
if (result.error === undefined && result.status === 0) {
|
|
104
|
+
return result.stdout.trim();
|
|
115
105
|
}
|
|
116
|
-
|
|
117
|
-
|
|
106
|
+
{
|
|
107
|
+
const err = result.error;
|
|
108
|
+
if (err?.code === 'ENOENT') {
|
|
118
109
|
throw new Error('git is not on PATH, so the repository root could not be found. Install git, or ' +
|
|
119
110
|
'run conductor from a shell that has it.');
|
|
120
111
|
}
|
|
121
|
-
if (typeof
|
|
112
|
+
if (err === undefined && typeof result.status === 'number') {
|
|
122
113
|
// git ran and refused. The directory is named because it is the one
|
|
123
114
|
// thing the reader has to check, and it is the directory they typed
|
|
124
115
|
// the command in rather than anything internal to this tool.
|
|
@@ -132,7 +123,7 @@ function repoRoot(cwd) {
|
|
|
132
123
|
// git is there and never got as far as an exit code: a permissions
|
|
133
124
|
// problem, or a machine out of processes. Neither of the two sentences
|
|
134
125
|
// above would be true, so this says what actually happened.
|
|
135
|
-
throw new Error(`git could not be run to find the repository root: ${err
|
|
126
|
+
throw new Error(`git could not be run to find the repository root: ${err?.message ?? 'it did not exit normally'}`);
|
|
136
127
|
}
|
|
137
128
|
}
|
|
138
129
|
/**
|
|
@@ -245,8 +236,31 @@ function inventoryFromHead(root, overrides) {
|
|
|
245
236
|
return { version: 1, gates: {}, report: { format: 'text' } };
|
|
246
237
|
}
|
|
247
238
|
}
|
|
248
|
-
function policyForRun(root, trustBase, overrides, githubBaseRef) {
|
|
239
|
+
function policyForRun(root, trustBase, overrides, githubBaseRef, githubActions) {
|
|
249
240
|
if (trustBase === undefined) {
|
|
241
|
+
// A PULL-REQUEST JOB WITH NO TRUST BASE would take its rules from the
|
|
242
|
+
// tree being judged. In Actions (GITHUB_ACTIONS and GITHUB_BASE_REF both
|
|
243
|
+
// set) that is refused, could-not-run, naming the two ways to clear it.
|
|
244
|
+
// Outside Actions one notice line, and the run goes on as before: a local
|
|
245
|
+
// shell that happens to export GITHUB_BASE_REF is the user's own tree.
|
|
246
|
+
if (githubBaseRef !== undefined && githubBaseRef !== '') {
|
|
247
|
+
const why = `GITHUB_BASE_REF is set to "${githubBaseRef}", so this is a pull-request job, and no ` +
|
|
248
|
+
'--trust-base was given: the policy would come from the tree being judged.';
|
|
249
|
+
if (githubActions === 'true') {
|
|
250
|
+
return {
|
|
251
|
+
kind: 'refused',
|
|
252
|
+
ref: '',
|
|
253
|
+
notGiven: true,
|
|
254
|
+
detail: `${why} Pass --trust-base refs/remotes/origin/${githubBaseRef} (check out with ` +
|
|
255
|
+
'fetch-depth: 0), or use the Action, which passes it. A pre-commit hook run inside ' +
|
|
256
|
+
'a pull-request job (conductor run --staged) hits this too: skip the hook in CI, ' +
|
|
257
|
+
'or pass --trust-base to it. Nothing was checked.',
|
|
258
|
+
inventory: inventoryFromHead(root, overrides),
|
|
259
|
+
};
|
|
260
|
+
}
|
|
261
|
+
process.stderr.write(`conductor: ${why} Outside GitHub Actions the run goes on with the working tree policy; ` +
|
|
262
|
+
'in Actions it is refused. Pass --trust-base for pull-request mode.\n');
|
|
263
|
+
}
|
|
250
264
|
return { kind: 'policy', policy: applyCliOverrides(loadPolicy(root), overrides) };
|
|
251
265
|
}
|
|
252
266
|
// DEFENCE IN DEPTH, ISSUE #58. action.yml's validate step already refuses
|
|
@@ -269,8 +283,24 @@ function policyForRun(root, trustBase, overrides, githubBaseRef) {
|
|
|
269
283
|
inventory: inventoryFromHead(root, overrides),
|
|
270
284
|
};
|
|
271
285
|
}
|
|
272
|
-
const
|
|
273
|
-
const
|
|
286
|
+
const baseRead = readFileAtRef(root, trustBase, POLICY_FILE_NAME);
|
|
287
|
+
const headRead = readFileAtRef(root, 'HEAD', POLICY_FILE_NAME);
|
|
288
|
+
if (baseRead.kind === 'error') {
|
|
289
|
+
// UNREADABLE IS NOT ABSENT. The base may carry a policy, and nothing was
|
|
290
|
+
// judged against it, so this is the could-not-run refusal with git's own
|
|
291
|
+
// reason, never the "run conductor init" sentence below and never a run
|
|
292
|
+
// under any other policy.
|
|
293
|
+
return {
|
|
294
|
+
kind: 'refused',
|
|
295
|
+
ref: trustBase,
|
|
296
|
+
detail: `cannot read ${POLICY_FILE_NAME} at "${trustBase}": ${baseRead.detail}. On a pull-request ` +
|
|
297
|
+
`run every rule comes from the base ref, so nothing was checked. ` +
|
|
298
|
+
unreadableBaseRemedy(POLICY_FILE_NAME),
|
|
299
|
+
inventory: inventoryFromHead(root, overrides),
|
|
300
|
+
};
|
|
301
|
+
}
|
|
302
|
+
const baseText = baseRead.kind === 'file' ? baseRead.text : null;
|
|
303
|
+
const headText = headRead.kind === 'file' ? headRead.text : null;
|
|
274
304
|
if (baseText === null) {
|
|
275
305
|
// CONFIG ABSENT ON THE BASE, not a policy error thrown from here. The old
|
|
276
306
|
// shape threw a PolicyError, which the run command's catch prints as one
|
|
@@ -318,7 +348,9 @@ function policyForRun(root, trustBase, overrides, githubBaseRef) {
|
|
|
318
348
|
policy: applyCliOverrides(parsePolicy(baseText, `${trustBase}:${POLICY_FILE_NAME}`), overrides),
|
|
319
349
|
trustBase: {
|
|
320
350
|
ref: trustBase,
|
|
321
|
-
|
|
351
|
+
// A head file git could not read is reported as a change, the
|
|
352
|
+
// fail-closed direction: it is never taken to match the base.
|
|
353
|
+
policyChanged: headRead.kind === 'error' ? true : policyDiffers(baseText, headText),
|
|
322
354
|
refusal: null,
|
|
323
355
|
// Computed AFTER refuseTrustBaseRef has already returned null, on the
|
|
324
356
|
// one shape that check accepts despite an identical tree: a merge
|
|
@@ -329,6 +361,63 @@ function policyForRun(root, trustBase, overrides, githubBaseRef) {
|
|
|
329
361
|
},
|
|
330
362
|
};
|
|
331
363
|
}
|
|
364
|
+
/**
|
|
365
|
+
* On a run with a trust base: removes every PATH entry that resolves against
|
|
366
|
+
* the working directory, for this process and for every child it starts,
|
|
367
|
+
* says what it removed, and pins git to the first git on PATH whose real path
|
|
368
|
+
* is outside the repository's work tree.
|
|
369
|
+
*
|
|
370
|
+
* Nearly every child runs with the repository root as its working directory,
|
|
371
|
+
* and that tree is the one under judgment, so every PATH lookup resolves
|
|
372
|
+
* against an absolute directory, and conductor's own git is never a program
|
|
373
|
+
* inside that tree. An absolute PATH entry inside the tree is kept: a gate
|
|
374
|
+
* installed as a dependency is reached that way, and the program check
|
|
375
|
+
* (refuseHeadControlledProgram) governs it. Runs without a trust base keep
|
|
376
|
+
* PATH exactly as given: a local hook commonly relies on a relative entry,
|
|
377
|
+
* and the tree there is the user's own. A gate that can no longer be found
|
|
378
|
+
* is the ordinary gate-missing outcome, cleared with an absolute PATH entry
|
|
379
|
+
* or an absolute command:.
|
|
380
|
+
*
|
|
381
|
+
* The work tree is found without running git (`workTreeAbove`), from the
|
|
382
|
+
* directory the run starts in; the caller checks the pinned git again
|
|
383
|
+
* against the root git then reports.
|
|
384
|
+
*
|
|
385
|
+
* Then puts a private directory first on PATH for this process and every
|
|
386
|
+
* child (`createGitShim`): a directory outside the tree holding only a link
|
|
387
|
+
* named git to the pinned program, so a gate, or anything a gate starts, that
|
|
388
|
+
* looks git up by name runs the pinned git even when an absolute PATH entry
|
|
389
|
+
* inside the tree holds a git of its own. Returns that directory, for the
|
|
390
|
+
* caller to remove when the run ends, or null on Windows, where none is made.
|
|
391
|
+
*/
|
|
392
|
+
function pinPathForTrustBase(start) {
|
|
393
|
+
const { value, removed } = absolutePathEntries(process.env.PATH ?? '');
|
|
394
|
+
if (removed.length > 0) {
|
|
395
|
+
process.env.PATH = value;
|
|
396
|
+
process.stderr.write(`conductor: pull-request mode removed ${removed.length} PATH ` +
|
|
397
|
+
`${removed.length === 1 ? 'entry' : 'entries'} that resolve against the working ` +
|
|
398
|
+
`directory (${removed.map((entry) => JSON.stringify(entry)).join(', ')}), which on a ` +
|
|
399
|
+
'pull-request run is the tree being judged. Use absolute PATH entries for any tool a ' +
|
|
400
|
+
'gate needs.\n');
|
|
401
|
+
}
|
|
402
|
+
const workTree = workTreeAbove(start);
|
|
403
|
+
const excluded = workTree === null ? [start] : [workTree];
|
|
404
|
+
const pinned = pinGitOutside(value, excluded);
|
|
405
|
+
if (pinned === null) {
|
|
406
|
+
throw new Error(noGitOutsideMessage());
|
|
407
|
+
}
|
|
408
|
+
const shim = createGitShim(pinned, os.tmpdir(), excluded);
|
|
409
|
+
if (shim !== null) {
|
|
410
|
+
// Never a trailing separator: an empty entry would mean the working
|
|
411
|
+
// directory, which is the tree being judged.
|
|
412
|
+
process.env.PATH = value === '' ? shim : `${shim}${path.delimiter}${value}`;
|
|
413
|
+
}
|
|
414
|
+
return shim;
|
|
415
|
+
}
|
|
416
|
+
function noGitOutsideMessage() {
|
|
417
|
+
return ('no git outside the repository was found on PATH. On a pull-request run conductor runs ' +
|
|
418
|
+
'git only from a directory outside the tree being judged. Put the directory that holds ' +
|
|
419
|
+
'your git installation on PATH as an absolute entry. Nothing was checked.');
|
|
420
|
+
}
|
|
332
421
|
function parseFormat(value) {
|
|
333
422
|
if (value !== 'text' && value !== 'sarif') {
|
|
334
423
|
throw new PolicyError(`--format must be "text" or "sarif", got "${value}".`);
|
|
@@ -477,8 +566,8 @@ export function buildProgram() {
|
|
|
477
566
|
.option('--base <ref>', 'measure the intent gate against what this branch changed since <ref>, rather than against the index. In Actions this defaults to the base branch (refs/conductor/trust-base, else refs/remotes/origin/<GITHUB_BASE_REF>, as a commit id) when GITHUB_BASE_REF is set.')
|
|
478
567
|
.option('--trust-base <ref>', 'pull-request mode: read .guardrails.yaml from this ref instead of from the tree being judged, and pass the same ref to every gate that supports it. A policy change in the pull request is reported as a proposal and never takes effect for the run, so a pull request cannot change the rules it is judged by. In Actions the composite action fetches the base branch and passes its full commit id on a pull_request event.')
|
|
479
568
|
.option('--output <path>', 'write the report to this file instead of to stdout, for a CI step that uploads it')
|
|
480
|
-
.option('--text-report <path>', 'with --format sarif, also write the text report to this file, from the same run: exactly what --format text would have rendered for this result, --verbose, --compact-on-refusal and --advisory respected, and no gate is run a second time. In a full report (any run that is not fully clean, or any run with --verbose) the second line is "verdict-token: <token>"; the one-line summary of a clean run without --verbose has none. The token is a label for this run\'s own exit decision: pass, nothing-checked (exit 0 but no gate ran), advisory-blocked (N), unenforced-findings (N), blocked (N) or could-not-run. Only meaningful with --format sarif: with --format text the text report is already the output, so the combination is a usage error (exit 2).')
|
|
481
|
-
.option('--spec <path>', 'the spec the intent gate imports its contract from, outranking a Spec: line in the pull request body and the branch-name convention')
|
|
569
|
+
.option('--text-report <path>', 'with --format sarif, also write the text report to this file, from the same run: exactly what --format text would have rendered for this result, --verbose, --compact-on-refusal and --advisory respected, and no gate is run a second time. In a full report (any run that is not fully clean, or any run with --verbose) the second line is "verdict-token: <token>"; the one-line summary of a clean run without --verbose has none. The token is a label for this run\'s own exit decision: pass, nothing-checked (exit 0 but nothing was checked: no gate ran, or every gate that ran had nothing to scan, read no packages, or had no contract), advisory-blocked (N), unenforced-findings (N), blocked (N) or could-not-run. Only meaningful with --format sarif: with --format text the text report is already the output, so the combination is a usage error (exit 2).')
|
|
570
|
+
.option('--spec <path>', 'the spec the intent gate imports its contract from, outranking a Spec: line in the pull request body and the branch-name convention. On a pull-request run (--trust-base) the spec is read from the base ref, and a frozen contract on the base takes precedence over it')
|
|
482
571
|
.option('--verbose', 'print the full per-gate report even when the run is clean. A clean run prints one summary line by default, because a pre-commit hook that prints a screenful on every commit is a hook a team switches off. Text output only; SARIF is unaffected.')
|
|
483
572
|
.option('--compact-on-refusal', 'when the trust base was refused and no gate ran, print a short body instead of the full refusal report: the version, the verdict, and the refusal reason (with its remedy, when one applies), never the full per-gate report. Built for the pull-request-comment step; every other run is unaffected, whatever --verbose says. Text output only; SARIF is unaffected.')
|
|
484
573
|
.option('--gate <role>', 'restrict the run to this role; repeatable', (value, previous = []) => [...previous, value])
|
|
@@ -488,19 +577,35 @@ export function buildProgram() {
|
|
|
488
577
|
.action((options) => {
|
|
489
578
|
const cwd = process.cwd();
|
|
490
579
|
let textReportPath;
|
|
580
|
+
// The private git directory of a trust-base run, removed in the
|
|
581
|
+
// finally below on every way out of this action.
|
|
582
|
+
let gitShim = null;
|
|
491
583
|
try {
|
|
584
|
+
// BEFORE ANY GIT CALL, including the one that finds the repository.
|
|
585
|
+
if (options.trustBase !== undefined) {
|
|
586
|
+
gitShim = pinPathForTrustBase(options.project === undefined ? cwd : path.resolve(cwd, options.project));
|
|
587
|
+
}
|
|
492
588
|
// Inside the try, because resolveProjectRoot (like repoRoot before
|
|
493
589
|
// it) reports rather than guesses, and the catch below is what turns
|
|
494
590
|
// any of its sentences into one line on stderr and the could-not-run
|
|
495
591
|
// exit code.
|
|
496
592
|
const root = resolveProjectRoot(cwd, options.project);
|
|
593
|
+
// And once more against the root git reported, which is the tree the
|
|
594
|
+
// gates judge: the pinned git is never a program inside it.
|
|
595
|
+
if (options.trustBase !== undefined && pinnedGitInside(root)) {
|
|
596
|
+
throw new Error(noGitOutsideMessage());
|
|
597
|
+
}
|
|
598
|
+
// The same for the private git directory: never inside that tree.
|
|
599
|
+
if (gitShim !== null && realPathInside(root, gitShim)) {
|
|
600
|
+
throw new Error(tempInsideTreeMessage(os.tmpdir()));
|
|
601
|
+
}
|
|
497
602
|
const overrides = {
|
|
498
603
|
...(parseRoles(options.gate) === undefined
|
|
499
604
|
? {}
|
|
500
605
|
: { gates: parseRoles(options.gate) }),
|
|
501
606
|
};
|
|
502
607
|
const stage = parseStage(options.stage);
|
|
503
|
-
const source = policyForRun(root, options.trustBase, overrides, process.env.GITHUB_BASE_REF);
|
|
608
|
+
const source = policyForRun(root, options.trustBase, overrides, process.env.GITHUB_BASE_REF, process.env.GITHUB_ACTIONS);
|
|
504
609
|
const policy = source.kind === 'policy' ? source.policy : source.inventory;
|
|
505
610
|
const format = parseFormat(options.format ?? policy.report.format);
|
|
506
611
|
// BEFORE ANY GATE RUNS. With --format text the text report already is
|
|
@@ -514,6 +619,7 @@ export function buildProgram() {
|
|
|
514
619
|
const result = source.kind === 'refused'
|
|
515
620
|
? refusedTrustBase(source.inventory, source.ref, source.detail, {
|
|
516
621
|
...(stage === undefined ? {} : { stage }),
|
|
622
|
+
...(source.notGiven === true ? { notGiven: true } : {}),
|
|
517
623
|
})
|
|
518
624
|
: runAll(source.policy, {
|
|
519
625
|
repoRoot: root,
|
|
@@ -576,6 +682,17 @@ export function buildProgram() {
|
|
|
576
682
|
process.stdout.write(`conductor run: ${jobLogSummary(result)}; verdict-token ${verdictToken(result, advisory)}; ` +
|
|
577
683
|
`${format} report written to ${options.output}\n`);
|
|
578
684
|
}
|
|
685
|
+
// One plain line per gate on stderr, on every run and after the report
|
|
686
|
+
// is out, so the job log says which gate did what and why without
|
|
687
|
+
// anybody opening a report. stderr rather than stdout so that stdout
|
|
688
|
+
// stays exactly the report (SARIF or text) for a caller that pipes it.
|
|
689
|
+
// Written after the report file, so a failure above still takes the
|
|
690
|
+
// catch below and these lines never describe a run that then exits 2
|
|
691
|
+
// for an unwritable file.
|
|
692
|
+
const logLines = [...gateLogLines(result), ...versionSkewWarnings(result)];
|
|
693
|
+
if (logLines.length > 0) {
|
|
694
|
+
process.stderr.write(`${logLines.join('\n')}\n`);
|
|
695
|
+
}
|
|
579
696
|
process.exitCode = applyAdvisory(result.exitCode, advisory);
|
|
580
697
|
}
|
|
581
698
|
catch (err) {
|
|
@@ -606,6 +723,11 @@ export function buildProgram() {
|
|
|
606
723
|
? err.message
|
|
607
724
|
: `conductor: ${err instanceof Error ? err.message : String(err)}`);
|
|
608
725
|
}
|
|
726
|
+
finally {
|
|
727
|
+
if (gitShim !== null) {
|
|
728
|
+
removeGitShim(gitShim);
|
|
729
|
+
}
|
|
730
|
+
}
|
|
609
731
|
});
|
|
610
732
|
return program;
|
|
611
733
|
}
|
package/dist/envelope.d.ts
CHANGED
|
@@ -111,6 +111,14 @@ export interface NormalizedGateOutput {
|
|
|
111
111
|
/** One line per control input the head proposes to change. */
|
|
112
112
|
proposals: string[];
|
|
113
113
|
};
|
|
114
|
+
/**
|
|
115
|
+
* osv-scanner only: every package that carried a verdict which is not an
|
|
116
|
+
* advisory, one line each ("license_violations (click@8.1.7)"). osv-scanner
|
|
117
|
+
* exits 1 for those as well as for an advisory, and none of them is a
|
|
118
|
+
* finding here, so the exit-code exception for present-on-base findings
|
|
119
|
+
* (src/exit-codes.ts, gateExitBlocks, condition f) reads this instead.
|
|
120
|
+
*/
|
|
121
|
+
otherVerdicts?: string[];
|
|
114
122
|
}
|
|
115
123
|
export declare class NormalizeError extends Error {
|
|
116
124
|
constructor(message: string);
|
package/dist/exit-codes.d.ts
CHANGED
|
@@ -1,3 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The fields of a gate's outcome `gateExitBlocks` reads. A structural type
|
|
3
|
+
* rather than an import of GateOutcome, so this file stays free of the
|
|
4
|
+
* runner and any caller with these fields can ask.
|
|
5
|
+
*/
|
|
6
|
+
export interface ExitBlocksInput {
|
|
7
|
+
role: string;
|
|
8
|
+
product: string;
|
|
9
|
+
/** The child's own exit code, or null when there was no child. */
|
|
10
|
+
exitCode: number | null;
|
|
11
|
+
couldNotRun: unknown;
|
|
12
|
+
findings: ReadonlyArray<{
|
|
13
|
+
details: Record<string, unknown>;
|
|
14
|
+
}>;
|
|
15
|
+
baseComparison?: {
|
|
16
|
+
policy: 'block' | 'report';
|
|
17
|
+
otherVerdicts: readonly string[];
|
|
18
|
+
};
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Whether this gate's own child exit blocks the run.
|
|
22
|
+
*
|
|
23
|
+
* Every "the child exited non-zero" decision goes through here: the composed
|
|
24
|
+
* exit code, the verdict token's count, the verdict sentence, the
|
|
25
|
+
* not-enforced note and the SARIF gate-not-enforced notification. A reader
|
|
26
|
+
* that compares the raw exit with 0 instead would say "blocked" on a run
|
|
27
|
+
* that exits 0 (tests/osv-exit.test.ts holds every reader to this).
|
|
28
|
+
*
|
|
29
|
+
* False for an exit of 0 (or no child). For a non-zero exit, true unless ALL
|
|
30
|
+
* of these hold:
|
|
31
|
+
* (a) the gate is the vulnerabilities gate, osv-scanner in that role;
|
|
32
|
+
* (b) its base policy said present-on-base: report;
|
|
33
|
+
* (c) a base comparison ran (it is carried on the outcome only then);
|
|
34
|
+
* (d) at least one finding was parsed, since exit 1 with nothing parsed
|
|
35
|
+
* is a verdict this umbrella cannot read;
|
|
36
|
+
* (e) every finding is labelled present-on-base. Redundant by
|
|
37
|
+
* construction: under report an introduced finding stays blocking,
|
|
38
|
+
* which blocks the run through `hasBlockingFinding` whatever this
|
|
39
|
+
* returns. Kept so the predicate states the whole rule;
|
|
40
|
+
* (f) the head output carried no verdict that is not an advisory: no
|
|
41
|
+
* license_violations, no deprecated package, no other unmapped
|
|
42
|
+
* package-level field. osv-scanner exits 1 for those too, and none of
|
|
43
|
+
* them is a finding here.
|
|
44
|
+
*/
|
|
45
|
+
export declare function gateExitBlocks(gate: ExitBlocksInput): boolean;
|
|
1
46
|
export declare const EXIT_OK = 0;
|
|
2
47
|
export declare const EXIT_BLOCKED = 1;
|
|
3
48
|
export declare const EXIT_COULD_NOT_RUN = 2;
|
|
@@ -6,8 +51,13 @@ export interface ExitInput {
|
|
|
6
51
|
couldNotRun: {
|
|
7
52
|
reason: string;
|
|
8
53
|
} | null;
|
|
9
|
-
/**
|
|
10
|
-
|
|
54
|
+
/**
|
|
55
|
+
* Whether the child's own exit blocks: `gateExitBlocks(outcome)`, never the
|
|
56
|
+
* raw exit code compared with 0. REQUIRED, like `enforce`, so a caller
|
|
57
|
+
* that has not thought about the present-on-base exception does not
|
|
58
|
+
* compile.
|
|
59
|
+
*/
|
|
60
|
+
exitBlocks: boolean;
|
|
11
61
|
/** Whether any finding from this gate is one the gate itself blocks on. */
|
|
12
62
|
hasBlockingFinding: boolean;
|
|
13
63
|
/**
|
package/dist/exit-codes.js
CHANGED
|
@@ -30,20 +30,70 @@
|
|
|
30
30
|
// maximum of the children's, and that is deliberate.
|
|
31
31
|
//
|
|
32
32
|
// The umbrella never overrules a gate's own blocking decision. A gate that
|
|
33
|
-
// exited non-zero produces a non-zero composed code,
|
|
34
|
-
// per-finding `blocking` flag can only ADD to that,
|
|
35
|
-
// exists so a gate whose exit code somehow said clean
|
|
36
|
-
// carried a blocking finding still fails the run.
|
|
33
|
+
// exited non-zero produces a non-zero composed code, with exactly one
|
|
34
|
+
// exception, below. The per-finding `blocking` flag can only ADD to that,
|
|
35
|
+
// never subtract: it exists so a gate whose exit code somehow said clean
|
|
36
|
+
// while its own report carried a blocking finding still fails the run.
|
|
37
37
|
//
|
|
38
|
-
//
|
|
39
|
-
//
|
|
40
|
-
//
|
|
41
|
-
//
|
|
42
|
-
//
|
|
43
|
-
//
|
|
44
|
-
//
|
|
45
|
-
//
|
|
46
|
-
//
|
|
38
|
+
// Two written decisions change what reaches this composition, and both are
|
|
39
|
+
// the repository's own lines in its policy file rather than a judgment made
|
|
40
|
+
// here.
|
|
41
|
+
//
|
|
42
|
+
// First, a gate carrying `enforce: false` is left out of this composition
|
|
43
|
+
// entirely. That is the adoption ramp, so a gate can be switched on and read
|
|
44
|
+
// for a few weeks before it is allowed to refuse anybody's commit. It is not
|
|
45
|
+
// a downgrade: the gate still runs, its findings keep their own levels, its
|
|
46
|
+
// blocking flags are untouched, and both output formats say plainly that it
|
|
47
|
+
// blocked and was not enforced. Nothing here reads a gate's output and
|
|
48
|
+
// decides on its own judgment to ignore it.
|
|
49
|
+
//
|
|
50
|
+
// Second, the vulnerabilities gate under `present-on-base: report` (osv
|
|
51
|
+
// design, section 4.3): a non-zero osv-scanner exit does not block when ALL
|
|
52
|
+
// of (a) to (f) in `gateExitBlocks` hold, which is a compared pull-request
|
|
53
|
+
// run whose every parsed finding is also on the base branch, under a key the
|
|
54
|
+
// BASE policy wrote, with no non-advisory verdict in the output. That is a
|
|
55
|
+
// set difference of two runs of the same tool, not a judgment about any one
|
|
56
|
+
// finding, and the findings still print with their labels.
|
|
57
|
+
/**
|
|
58
|
+
* Whether this gate's own child exit blocks the run.
|
|
59
|
+
*
|
|
60
|
+
* Every "the child exited non-zero" decision goes through here: the composed
|
|
61
|
+
* exit code, the verdict token's count, the verdict sentence, the
|
|
62
|
+
* not-enforced note and the SARIF gate-not-enforced notification. A reader
|
|
63
|
+
* that compares the raw exit with 0 instead would say "blocked" on a run
|
|
64
|
+
* that exits 0 (tests/osv-exit.test.ts holds every reader to this).
|
|
65
|
+
*
|
|
66
|
+
* False for an exit of 0 (or no child). For a non-zero exit, true unless ALL
|
|
67
|
+
* of these hold:
|
|
68
|
+
* (a) the gate is the vulnerabilities gate, osv-scanner in that role;
|
|
69
|
+
* (b) its base policy said present-on-base: report;
|
|
70
|
+
* (c) a base comparison ran (it is carried on the outcome only then);
|
|
71
|
+
* (d) at least one finding was parsed, since exit 1 with nothing parsed
|
|
72
|
+
* is a verdict this umbrella cannot read;
|
|
73
|
+
* (e) every finding is labelled present-on-base. Redundant by
|
|
74
|
+
* construction: under report an introduced finding stays blocking,
|
|
75
|
+
* which blocks the run through `hasBlockingFinding` whatever this
|
|
76
|
+
* returns. Kept so the predicate states the whole rule;
|
|
77
|
+
* (f) the head output carried no verdict that is not an advisory: no
|
|
78
|
+
* license_violations, no deprecated package, no other unmapped
|
|
79
|
+
* package-level field. osv-scanner exits 1 for those too, and none of
|
|
80
|
+
* them is a finding here.
|
|
81
|
+
*/
|
|
82
|
+
export function gateExitBlocks(gate) {
|
|
83
|
+
if ((gate.exitCode ?? 0) === 0) {
|
|
84
|
+
return false;
|
|
85
|
+
}
|
|
86
|
+
const comparison = gate.baseComparison;
|
|
87
|
+
const reportedNotBlocking = gate.role === 'vulnerabilities' &&
|
|
88
|
+
gate.product === 'osv-scanner' &&
|
|
89
|
+
comparison !== undefined &&
|
|
90
|
+
comparison.policy === 'report' &&
|
|
91
|
+
gate.couldNotRun === null &&
|
|
92
|
+
gate.findings.length > 0 &&
|
|
93
|
+
gate.findings.every((finding) => finding.details.baseline === 'present-on-base') &&
|
|
94
|
+
comparison.otherVerdicts.length === 0;
|
|
95
|
+
return !reportedNotBlocking;
|
|
96
|
+
}
|
|
47
97
|
export const EXIT_OK = 0;
|
|
48
98
|
export const EXIT_BLOCKED = 1;
|
|
49
99
|
export const EXIT_COULD_NOT_RUN = 2;
|
|
@@ -52,7 +102,7 @@ export function composeExitCode(gates) {
|
|
|
52
102
|
if (enforced.some((gate) => gate.couldNotRun !== null)) {
|
|
53
103
|
return EXIT_COULD_NOT_RUN;
|
|
54
104
|
}
|
|
55
|
-
if (enforced.some((gate) =>
|
|
105
|
+
if (enforced.some((gate) => gate.exitBlocks || gate.hasBlockingFinding)) {
|
|
56
106
|
return EXIT_BLOCKED;
|
|
57
107
|
}
|
|
58
108
|
return EXIT_OK;
|
|
@@ -41,7 +41,8 @@ export declare function extendPath(config: string): string | null;
|
|
|
41
41
|
* a nested file added or edited by the pull request has no effect on the run
|
|
42
42
|
* (measured against 2.6.0: a nested file ignoring lodash passes without
|
|
43
43
|
* --config and blocks with it). It is still a change to how the tool behaves
|
|
44
|
-
* once merged, so it is reported the way the root config is.
|
|
44
|
+
* once merged, so it is reported the way the root config is. A base copy git
|
|
45
|
+
* could not read throws ExternalConfigError, like every other base read here.
|
|
45
46
|
*/
|
|
46
47
|
export declare function nestedConfigProposals(repoRoot: string, trustBase: string, trackedFiles: readonly string[], configFile: string): string[];
|
|
47
48
|
export declare function materializeExternalConfig(args: {
|
package/dist/external-config.js
CHANGED
|
@@ -15,9 +15,9 @@
|
|
|
15
15
|
// head's file on its own. A head-side difference is not an error: it is
|
|
16
16
|
// reported as a proposal, which takes effect once it merges and the base
|
|
17
17
|
// carries it.
|
|
18
|
-
import { spawnSync } from 'node:child_process';
|
|
19
18
|
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
20
19
|
import path from 'node:path';
|
|
20
|
+
import { readFileAtRef, unreadableBaseRemedy } from './trust-base.js';
|
|
21
21
|
/** The base ref's config cannot be materialised; the gate cannot run safely. */
|
|
22
22
|
export class ExternalConfigError extends Error {
|
|
23
23
|
constructor(message) {
|
|
@@ -60,26 +60,38 @@ export function extendPath(config) {
|
|
|
60
60
|
}
|
|
61
61
|
return null;
|
|
62
62
|
}
|
|
63
|
-
/**
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
63
|
+
/**
|
|
64
|
+
* A file's contents at the base ref, or null when the base does not carry
|
|
65
|
+
* it. A read git could not make THROWS: it is never null, because null
|
|
66
|
+
* selects the neutral config, and a trusted file that exists but could not
|
|
67
|
+
* be read must not be replaced by a default (src/trust-base.ts,
|
|
68
|
+
* readFileAtRef).
|
|
69
|
+
*/
|
|
70
|
+
function baseCopy(repoRoot, ref, file) {
|
|
71
|
+
const read = readFileAtRef(repoRoot, ref, file);
|
|
72
|
+
if (read.kind === 'error') {
|
|
73
|
+
throw new ExternalConfigError(`${file} could not be read from the base ref: ${read.detail}. Nothing was checked by this ` +
|
|
74
|
+
`gate. ${unreadableBaseRemedy(file)}`);
|
|
67
75
|
}
|
|
68
|
-
|
|
69
|
-
cwd: repoRoot,
|
|
70
|
-
encoding: 'utf8',
|
|
71
|
-
});
|
|
72
|
-
return child.status === 0 && typeof child.stdout === 'string' ? child.stdout : null;
|
|
76
|
+
return read.kind === 'file' ? read.text : null;
|
|
73
77
|
}
|
|
74
78
|
function headCopy(repoRoot, file) {
|
|
75
79
|
const full = path.join(repoRoot, file);
|
|
76
80
|
return existsSync(full) ? readFileSync(full, 'utf8') : null;
|
|
77
81
|
}
|
|
78
|
-
|
|
82
|
+
/**
|
|
83
|
+
* The proposal line for a head-side difference, or null. It says which copy
|
|
84
|
+
* was actually used: the base's own, or, when the base carries none, the
|
|
85
|
+
* stand-in the umbrella wrote. Saying "the base's copy" for a stand-in would
|
|
86
|
+
* claim a file the base does not have.
|
|
87
|
+
*/
|
|
88
|
+
function differs(file, base, head, standIn = "conductor's neutral stand-in") {
|
|
79
89
|
if (head === null || head === base) {
|
|
80
90
|
return null;
|
|
81
91
|
}
|
|
82
|
-
return
|
|
92
|
+
return base === null
|
|
93
|
+
? `${file} is not on the base ref; ${standIn} was used and this file takes effect after merge.`
|
|
94
|
+
: `${file} differs from the base ref; the base's copy was used and this change takes effect after merge.`;
|
|
83
95
|
}
|
|
84
96
|
/**
|
|
85
97
|
* Copies one relative file from the base ref into the run directory, at the
|
|
@@ -93,7 +105,7 @@ function materializeRelative(repoRoot, trustBase, cwd, file, what) {
|
|
|
93
105
|
throw new ExternalConfigError(`${what} ${file} is not a path inside the repository, so conductor cannot read it from ` +
|
|
94
106
|
'the base ref; name it relative to the repository root.');
|
|
95
107
|
}
|
|
96
|
-
const base =
|
|
108
|
+
const base = baseCopy(repoRoot, trustBase, path.relative(cwd, target).split(path.sep).join('/'));
|
|
97
109
|
if (base === null) {
|
|
98
110
|
throw new ExternalConfigError(`${what} ${file} does not exist on the base ref ${trustBase}, so there is no approved copy ` +
|
|
99
111
|
'to read; commit it to the base branch or remove the reference.');
|
|
@@ -110,12 +122,13 @@ function materializeRelative(repoRoot, trustBase, cwd, file, what) {
|
|
|
110
122
|
* a nested file added or edited by the pull request has no effect on the run
|
|
111
123
|
* (measured against 2.6.0: a nested file ignoring lodash passes without
|
|
112
124
|
* --config and blocks with it). It is still a change to how the tool behaves
|
|
113
|
-
* once merged, so it is reported the way the root config is.
|
|
125
|
+
* once merged, so it is reported the way the root config is. A base copy git
|
|
126
|
+
* could not read throws ExternalConfigError, like every other base read here.
|
|
114
127
|
*/
|
|
115
128
|
export function nestedConfigProposals(repoRoot, trustBase, trackedFiles, configFile) {
|
|
116
129
|
return trackedFiles
|
|
117
130
|
.filter((file) => file !== configFile && path.posix.basename(file) === configFile)
|
|
118
|
-
.map((file) => differs(file,
|
|
131
|
+
.map((file) => differs(file, baseCopy(repoRoot, trustBase, file), headCopy(repoRoot, file), 'the root config'))
|
|
119
132
|
.filter((proposal) => proposal !== null);
|
|
120
133
|
}
|
|
121
134
|
export function materializeExternalConfig(args) {
|
|
@@ -123,7 +136,9 @@ export function materializeExternalConfig(args) {
|
|
|
123
136
|
if (profile.configFile === null) {
|
|
124
137
|
return null;
|
|
125
138
|
}
|
|
126
|
-
|
|
139
|
+
// Only an ABSENT base config selects the neutral one. An unreadable one has
|
|
140
|
+
// already thrown, so the tool never runs under a default in its place.
|
|
141
|
+
const base = baseCopy(repoRoot, trustBase, profile.configFile);
|
|
127
142
|
const ext = path.extname(profile.configFile) || '.toml';
|
|
128
143
|
const out = path.join(tempRoot, `${profile.product}-config${ext}`);
|
|
129
144
|
writeFileSync(out, base ?? profile.neutralConfig ?? '');
|
|
@@ -158,13 +173,13 @@ export function materializeExternalConfig(args) {
|
|
|
158
173
|
let ignore = null;
|
|
159
174
|
if (profile.ignoreFile !== null) {
|
|
160
175
|
const name = profile.ignoreFile.name;
|
|
161
|
-
const baseIgnore =
|
|
176
|
+
const baseIgnore = baseCopy(repoRoot, trustBase, name);
|
|
162
177
|
const dir = path.join(tempRoot, `${profile.product}-ignore`);
|
|
163
178
|
mkdirSync(dir, { recursive: true });
|
|
164
179
|
// An empty file when the base has none, for the reason the neutral
|
|
165
180
|
// config exists: pointing the tool anywhere else lets it find the head's.
|
|
166
181
|
writeFileSync(path.join(dir, name), baseIgnore ?? '');
|
|
167
|
-
ignore = { dir, proposal: differs(name, baseIgnore, headCopy(repoRoot, name)) };
|
|
182
|
+
ignore = { dir, proposal: differs(name, baseIgnore, headCopy(repoRoot, name), 'an empty one') };
|
|
168
183
|
}
|
|
169
184
|
return {
|
|
170
185
|
path: out,
|