@vaultcompass/conductor 0.13.2 → 0.14.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 +69 -12
- package/dist/cli.d.ts +38 -0
- package/dist/cli.js +77 -6
- package/dist/gate-runner.d.ts +63 -4
- package/dist/gate-runner.js +237 -47
- package/dist/output-sarif.d.ts +2 -2
- package/dist/output-sarif.js +47 -2
- package/dist/output-text.d.ts +37 -1
- package/dist/output-text.js +111 -21
- package/dist/policy-diff.d.ts +34 -0
- package/dist/policy-diff.js +173 -0
- package/dist/run.d.ts +63 -0
- package/dist/run.js +142 -21
- package/package.json +1 -1
- package/schema/guardrails.schema.json +1 -1
package/dist/run.js
CHANGED
|
@@ -1,13 +1,19 @@
|
|
|
1
1
|
// One run across every enabled gate.
|
|
2
|
+
import { mkdtempSync, rmSync } from 'node:fs';
|
|
3
|
+
import os from 'node:os';
|
|
4
|
+
import path from 'node:path';
|
|
2
5
|
import { compareFindings } from './envelope.js';
|
|
3
6
|
import { EXIT_COULD_NOT_RUN, composeExitCode, gateExitBlocks } from './exit-codes.js';
|
|
4
|
-
import { expectedVersionBeforePreparation, gateProgramRefused, preparationFailed, preparationTimedOut, refuseHeadControlledBinary, resolveTimeLimit, runGate, } from './gate-runner.js';
|
|
7
|
+
import { cleanOutputLine, expectedVersionBeforePreparation, gateProgramRefused, preparationFailed, preparationTimedOut, refuseHeadControlledBinary, resolveTimeLimit, runGate, } from './gate-runner.js';
|
|
5
8
|
import { resolveBaseRef } from './intent-base.js';
|
|
6
9
|
import { frozenNativeContractPath, prepareIntent, } from './intent-prepare.js';
|
|
7
10
|
import { GATE_ROLES, enabledGates, runsAtStage } from './policy.js';
|
|
8
11
|
import { profileFor } from './products.js';
|
|
9
12
|
import { ResolveError, resolveGateBinary } from './resolve.js';
|
|
10
13
|
import { POLICY_PROPOSAL_LINE } from './trust-base.js';
|
|
14
|
+
import { policyChangeLine } from './policy-diff.js';
|
|
15
|
+
/** The whole preview's hard deadline (spec 5.2, finding 2). */
|
|
16
|
+
export const PREVIEW_BUDGET_MS = 300_000;
|
|
11
17
|
/**
|
|
12
18
|
* Whether this run is the pull-request shaped one.
|
|
13
19
|
*
|
|
@@ -169,7 +175,13 @@ function collectProposals(outcomes, trustBase,
|
|
|
169
175
|
preparation = []) {
|
|
170
176
|
const proposals = [];
|
|
171
177
|
if (trustBase?.policyChanged === true) {
|
|
172
|
-
|
|
178
|
+
const changes = trustBase.policyChanges ?? [];
|
|
179
|
+
if (changes.length === 0) {
|
|
180
|
+
proposals.push({ product: 'conductor', role: null, line: POLICY_PROPOSAL_LINE });
|
|
181
|
+
}
|
|
182
|
+
for (const change of changes) {
|
|
183
|
+
proposals.push({ product: 'conductor', role: null, line: policyChangeLine(change) });
|
|
184
|
+
}
|
|
173
185
|
}
|
|
174
186
|
proposals.push(...preparation);
|
|
175
187
|
for (const outcome of outcomes) {
|
|
@@ -246,6 +258,107 @@ function expectedVersionOption(product, env) {
|
|
|
246
258
|
? { expectedVersion: value }
|
|
247
259
|
: {};
|
|
248
260
|
}
|
|
261
|
+
/**
|
|
262
|
+
* The runGate options every gate of a run gets, the preview's included: the
|
|
263
|
+
* preview runs a gate with exactly these, plus its own `preview`.
|
|
264
|
+
*/
|
|
265
|
+
function gateRunOptions(gate, options, env) {
|
|
266
|
+
return {
|
|
267
|
+
repoRoot: options.repoRoot,
|
|
268
|
+
staged: options.staged,
|
|
269
|
+
pathValue: options.pathValue,
|
|
270
|
+
...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
|
|
271
|
+
...expectedVersionOption(gate.product, env),
|
|
272
|
+
// Offered to every child. runGate decides which ones take it: a gate
|
|
273
|
+
// below its pull-request-mode minimum is could-not-run, and a gate it is
|
|
274
|
+
// withheld from carries the reason on the outcome. NEVER left out of the
|
|
275
|
+
// preview: every pull-request protection keys off it (spec 5.2, finding 1).
|
|
276
|
+
...(options.trustBase === undefined ? {} : { trustBase: options.trustBase.ref }),
|
|
277
|
+
// Where an external gate's working directory goes (its report file, its
|
|
278
|
+
// config from the base ref). The runner removes what it makes.
|
|
279
|
+
...(options.tempRoot === undefined ? {} : { tempRoot: options.tempRoot }),
|
|
280
|
+
};
|
|
281
|
+
}
|
|
282
|
+
/**
|
|
283
|
+
* Runs `work`, and turns any throw into `fallback(message)`, the message
|
|
284
|
+
* cleaned for a log line and cut to 200 characters. Never rethrows: nothing
|
|
285
|
+
* the preview does may reach the verdict, and a throw would (spec 5.2,
|
|
286
|
+
* finding 3).
|
|
287
|
+
*/
|
|
288
|
+
export function guardPreview(work, fallback) {
|
|
289
|
+
try {
|
|
290
|
+
return work();
|
|
291
|
+
}
|
|
292
|
+
catch (err) {
|
|
293
|
+
let raw;
|
|
294
|
+
try {
|
|
295
|
+
raw = err instanceof Error ? err.message : String(err);
|
|
296
|
+
}
|
|
297
|
+
catch {
|
|
298
|
+
raw = 'an error that could not be described';
|
|
299
|
+
}
|
|
300
|
+
return fallback(cleanOutputLine(raw).slice(0, 200));
|
|
301
|
+
}
|
|
302
|
+
}
|
|
303
|
+
/**
|
|
304
|
+
* The preview under the proposed rules: each role of `policy` run once more,
|
|
305
|
+
* with the primary run's own options, trust base included, under one hard
|
|
306
|
+
* deadline. The intent role is deferred and never prepared.
|
|
307
|
+
*/
|
|
308
|
+
export function runPreview(policy, options) {
|
|
309
|
+
const clock = options.previewClock ?? Date.now;
|
|
310
|
+
const start = clock();
|
|
311
|
+
const deadline = start + PREVIEW_BUDGET_MS;
|
|
312
|
+
const env = options.env ?? {};
|
|
313
|
+
const skipped = [];
|
|
314
|
+
const deferred = [];
|
|
315
|
+
const toRun = [];
|
|
316
|
+
for (const role of GATE_ROLES) {
|
|
317
|
+
const gate = policy.gates[role];
|
|
318
|
+
if (gate === undefined)
|
|
319
|
+
continue;
|
|
320
|
+
if (gate.excludedByCli) {
|
|
321
|
+
skipped.push({ role, product: gate.product, reason: 'excluded' });
|
|
322
|
+
}
|
|
323
|
+
else if (!gate.enabled) {
|
|
324
|
+
skipped.push({ role, product: gate.product, reason: 'disabled' });
|
|
325
|
+
}
|
|
326
|
+
else if (role === 'intent') {
|
|
327
|
+
// BEFORE the loop, and it never enters it: prepareIntent spawns the
|
|
328
|
+
// intent program (spec 5.2, finding 9).
|
|
329
|
+
deferred.push(role);
|
|
330
|
+
}
|
|
331
|
+
else if (options.stage !== undefined && !runsAtStage(gate.stage, options.stage)) {
|
|
332
|
+
skipped.push({ role, product: gate.product, reason: 'stage' });
|
|
333
|
+
}
|
|
334
|
+
else {
|
|
335
|
+
toRun.push(gate);
|
|
336
|
+
}
|
|
337
|
+
}
|
|
338
|
+
const gates = [];
|
|
339
|
+
const overBudget = [];
|
|
340
|
+
const cacheDir = mkdtempSync(path.join(options.tempRoot ?? os.tmpdir(), 'conductor-preview-'));
|
|
341
|
+
try {
|
|
342
|
+
for (const [index, gate] of toRun.entries()) {
|
|
343
|
+
if (deadline - clock() <= 0) {
|
|
344
|
+
overBudget.push(...toRun.slice(index).map((later) => later.role));
|
|
345
|
+
break;
|
|
346
|
+
}
|
|
347
|
+
gates.push(runGate(gate, { ...gateRunOptions(gate, options, env), preview: { deadline, clock, cacheDir } }));
|
|
348
|
+
}
|
|
349
|
+
}
|
|
350
|
+
finally {
|
|
351
|
+
rmSync(cacheDir, { recursive: true, force: true });
|
|
352
|
+
}
|
|
353
|
+
return {
|
|
354
|
+
gates,
|
|
355
|
+
findings: gates.flatMap((outcome) => outcome.findings).sort(compareFindings),
|
|
356
|
+
skipped,
|
|
357
|
+
deferred,
|
|
358
|
+
overBudget,
|
|
359
|
+
threw: null,
|
|
360
|
+
};
|
|
361
|
+
}
|
|
249
362
|
export function runAll(policy, options) {
|
|
250
363
|
const { gates: partitioned, deferred, excluded } = partitionGates(policy, options.stage);
|
|
251
364
|
const { toRun: gates, treeUnchanged } = splitOnTreeUnchanged(partitioned, options.trustBase);
|
|
@@ -365,25 +478,14 @@ export function runAll(policy, options) {
|
|
|
365
478
|
}
|
|
366
479
|
}
|
|
367
480
|
outcomes.push(runGate(gate, {
|
|
368
|
-
|
|
369
|
-
staged: options.staged,
|
|
370
|
-
pathValue: options.pathValue,
|
|
371
|
-
...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
|
|
481
|
+
...gateRunOptions(gate, options, env),
|
|
372
482
|
...(intent === undefined ? {} : { intent }),
|
|
373
|
-
...expectedVersionOption(gate.product, env),
|
|
374
483
|
// For a run with no preparation: which contract the child will read
|
|
375
484
|
// out of the repository itself. Looked up only for the gate it is
|
|
376
485
|
// about, so no other gate pays for the two stat calls.
|
|
377
486
|
...(intent !== undefined || gate.role !== 'intent'
|
|
378
487
|
? {}
|
|
379
488
|
: nativeContractOption(options.repoRoot)),
|
|
380
|
-
// Offered to every child. runGate decides which ones take it: a
|
|
381
|
-
// gate below its pull-request-mode minimum is could-not-run, and a
|
|
382
|
-
// gate it is withheld from carries the reason on the outcome.
|
|
383
|
-
...(options.trustBase === undefined ? {} : { trustBase: options.trustBase.ref }),
|
|
384
|
-
// Where an external gate's working directory goes (its report file,
|
|
385
|
-
// its config from the base ref). The runner removes what it makes.
|
|
386
|
-
...(options.tempRoot === undefined ? {} : { tempRoot: options.tempRoot }),
|
|
387
489
|
}));
|
|
388
490
|
}
|
|
389
491
|
}
|
|
@@ -410,9 +512,31 @@ export function runAll(policy, options) {
|
|
|
410
512
|
hasBlockingFinding: outcome.findings.some((finding) => finding.blocking),
|
|
411
513
|
enforce: outcome.enforce,
|
|
412
514
|
})));
|
|
515
|
+
const summary = {
|
|
516
|
+
blocking: findings.filter((finding) => finding.blocking).length,
|
|
517
|
+
byProduct,
|
|
518
|
+
bySeverity,
|
|
519
|
+
};
|
|
520
|
+
const proposals = collectProposals(outcomes, options.trustBase, preparationProposals);
|
|
521
|
+
// Before the preview too, so a preview of up to 300 s cannot move it.
|
|
522
|
+
const generatedAt = (options.now?.() ?? new Date()).toISOString();
|
|
523
|
+
// LAST, after outcomes, findings, summary, exitCode and proposals are
|
|
524
|
+
// fixed, and nothing above reads it. Inside the throw wrapper, so a throw
|
|
525
|
+
// here is one line in the report and never exit 2 (spec 5.2, finding 3).
|
|
526
|
+
const previewPolicy = options.preview?.policy;
|
|
527
|
+
const preview = previewPolicy === undefined
|
|
528
|
+
? undefined
|
|
529
|
+
: guardPreview(() => runPreview(previewPolicy, options), (message) => ({
|
|
530
|
+
gates: [],
|
|
531
|
+
findings: [],
|
|
532
|
+
skipped: [],
|
|
533
|
+
deferred: [],
|
|
534
|
+
overBudget: [],
|
|
535
|
+
threw: message,
|
|
536
|
+
}));
|
|
413
537
|
return {
|
|
414
538
|
schemaVersion: 1,
|
|
415
|
-
generatedAt
|
|
539
|
+
generatedAt,
|
|
416
540
|
gates: outcomes,
|
|
417
541
|
// Absent rather than empty when nothing is disabled, so a run with every
|
|
418
542
|
// gate on serialises exactly as it did before this field existed.
|
|
@@ -423,12 +547,9 @@ export function runAll(policy, options) {
|
|
|
423
547
|
treeUnchanged,
|
|
424
548
|
findings,
|
|
425
549
|
trustBase: options.trustBase ?? null,
|
|
426
|
-
proposals
|
|
427
|
-
summary
|
|
428
|
-
blocking: findings.filter((finding) => finding.blocking).length,
|
|
429
|
-
byProduct,
|
|
430
|
-
bySeverity,
|
|
431
|
-
},
|
|
550
|
+
proposals,
|
|
551
|
+
summary,
|
|
432
552
|
exitCode,
|
|
553
|
+
...(preview === undefined ? {} : { preview }),
|
|
433
554
|
};
|
|
434
555
|
}
|
package/package.json
CHANGED
|
@@ -59,7 +59,7 @@
|
|
|
59
59
|
"enum": ["block", "report"]
|
|
60
60
|
},
|
|
61
61
|
"timeout-seconds": {
|
|
62
|
-
"description": "How long conductor lets this gate run before stopping it, in whole seconds, from 10 to 21600 (six hours, the GitHub-hosted job limit). Every spawn of the gate gets the full limit: the version probe, the scan, the intent gate's preparation steps and osv-scanner's base run. Absent means the default for the product: 120 for dep-guard, vault-guard and intent-guard, 600 for gitleaks, 300 for osv-scanner. A gate stopped at its limit could not run (timed-out). Read from the base branch policy on a pull request, so a pull request cannot change its own limit. Not the same as a gate's own timeout flag under options.",
|
|
62
|
+
"description": "How long conductor lets this gate run before stopping it, in whole seconds, from 10 to 21600 (six hours, the GitHub-hosted job limit). Every spawn of the gate gets the full limit: the version probe, the scan, the intent gate's preparation steps and osv-scanner's base run. Absent means the default for the product: 120 for dep-guard, vault-guard and intent-guard, 600 for gitleaks, 300 for osv-scanner. A gate stopped at its limit could not run (timed-out). Read from the base branch policy on a pull request, so a pull request cannot change its own limit. The preview under the proposed rules also uses the base value, or the product default for a role the base does not have, capped by its 300 second deadline. Not the same as a gate's own timeout flag under options.",
|
|
63
63
|
"type": "integer",
|
|
64
64
|
"minimum": 10,
|
|
65
65
|
"maximum": 21600
|