@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/gate-runner.js
CHANGED
|
@@ -21,7 +21,7 @@ import { spawnSync } from 'node:child_process';
|
|
|
21
21
|
import { existsSync, mkdtempSync, readFileSync, realpathSync, rmSync } from 'node:fs';
|
|
22
22
|
import { tmpdir } from 'node:os';
|
|
23
23
|
import path from 'node:path';
|
|
24
|
-
import { runGit } from './git.js';
|
|
24
|
+
import { realPathInside, runGit } from './git.js';
|
|
25
25
|
import { NormalizeError } from './envelope.js';
|
|
26
26
|
import { describeLockfiles, normalizeDepGuard, normalizeFailedGate, normalizeGitleaks, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeOsvScanner, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
|
|
27
27
|
import { renderOptionFlags } from './policy.js';
|
|
@@ -158,6 +158,9 @@ function limitSourcePhrase(gate, source, trustBase) {
|
|
|
158
158
|
? `gates.${gate.role}.timeout-seconds`
|
|
159
159
|
: `gates.${gate.role}.timeout-seconds on ${trustBase}`;
|
|
160
160
|
}
|
|
161
|
+
if (source === 'preview-budget') {
|
|
162
|
+
return 'what was left of the 300 s preview budget';
|
|
163
|
+
}
|
|
161
164
|
return source === 'default' ? 'the default for this gate' : 'set by the caller';
|
|
162
165
|
}
|
|
163
166
|
/**
|
|
@@ -178,7 +181,17 @@ function timedOutDetail(gate, step, limit, elapsedMs, trustBase) {
|
|
|
178
181
|
const elapsedSeconds = Math.round(elapsedMs / 1000);
|
|
179
182
|
const where = limitSourcePhrase(gate, limit.source, trustBase);
|
|
180
183
|
const own = gateOwnTimeoutNote(gate, limit, trustBase);
|
|
181
|
-
|
|
184
|
+
// A preview stopped by its own budget has no limit to raise: the budget is
|
|
185
|
+
// fixed, and the gate's own limit was not what stopped it.
|
|
186
|
+
const remedies = limit.source === 'preview-budget'
|
|
187
|
+
? 'The preview under the proposed rules has 300 s in all, whatever each gate\'s own limit.'
|
|
188
|
+
: profileFor(gate.product).timeoutRemedies(gate.role);
|
|
189
|
+
// A preview spawn with no budget left was never started (spawnLimits):
|
|
190
|
+
// there is no elapsed time or limit to report.
|
|
191
|
+
if (limit.source === 'preview-budget' && limit.ms === 0) {
|
|
192
|
+
const what = step === 'version-probe' ? `the version probe of ${gate.product}` : gate.product;
|
|
193
|
+
return `${what} was not started: the preview budget was spent, so nothing was checked by it. ${remedies}`;
|
|
194
|
+
}
|
|
182
195
|
if (step === 'version-probe') {
|
|
183
196
|
return (`the version probe of ${gate.product} was stopped at ${limitSeconds} s (${where}), so the gate ` +
|
|
184
197
|
'was not run and nothing was checked by it.');
|
|
@@ -436,6 +449,12 @@ function intentChangeChannel(gate, intent, version) {
|
|
|
436
449
|
}
|
|
437
450
|
return { kind: 'paths' };
|
|
438
451
|
}
|
|
452
|
+
/**
|
|
453
|
+
* Why dep-guard and vault-guard are not handed `--trust-base` in the preview
|
|
454
|
+
* under the proposed rules: the preview shows what the head's rules would do,
|
|
455
|
+
* and their own control files are part of those rules.
|
|
456
|
+
*/
|
|
457
|
+
export const PREVIEW_WITHHELD = 'preview under the proposed rules: this gate read its own control files from the head';
|
|
439
458
|
/**
|
|
440
459
|
* Whether this gate can be handed `--trust-base`, and why not when it cannot.
|
|
441
460
|
*
|
|
@@ -450,7 +469,14 @@ function intentChangeChannel(gate, intent, version) {
|
|
|
450
469
|
* was working a moment ago would report could-not-run. So the flag goes only
|
|
451
470
|
* where `--project` is the repository itself.
|
|
452
471
|
*/
|
|
453
|
-
export function decideTrustBase(gate, intent, trustBase, productVersion
|
|
472
|
+
export function decideTrustBase(gate, intent, trustBase, productVersion,
|
|
473
|
+
/**
|
|
474
|
+
* The preview under the proposed rules. dep-guard and vault-guard then read
|
|
475
|
+
* their own control files from the head, so the flag is withheld from them;
|
|
476
|
+
* the trust base itself stays set on the run, and every other product is
|
|
477
|
+
* decided exactly as without it.
|
|
478
|
+
*/
|
|
479
|
+
preview = false) {
|
|
454
480
|
if (trustBase === undefined) {
|
|
455
481
|
return undefined;
|
|
456
482
|
}
|
|
@@ -493,6 +519,15 @@ export function decideTrustBase(gate, intent, trustBase, productVersion) {
|
|
|
493
519
|
`was checked by it. Fix: install ${gate.product} ${minimum} or newer, or remove an ` +
|
|
494
520
|
'explicit older version pin.');
|
|
495
521
|
}
|
|
522
|
+
// AFTER both version refusals, so a gate refused in the primary run is
|
|
523
|
+
// refused in the preview too. Only the --trust-base flag is withheld: the
|
|
524
|
+
// run keeps its trust base, and with it the node_modules skip, the program
|
|
525
|
+
// refusal and the forced enforce, and dep-guard keeps --base (gateArgs'
|
|
526
|
+
// changeBase). gitleaks and osv-scanner never reach this: the umbrella
|
|
527
|
+
// itself is their pull-request mode, and it stays the base's.
|
|
528
|
+
if (preview && (gate.product === 'dep-guard' || gate.product === 'vault-guard')) {
|
|
529
|
+
return withheld(PREVIEW_WITHHELD);
|
|
530
|
+
}
|
|
496
531
|
// AFTER the version checks, so an imported contract cannot let an older
|
|
497
532
|
// gate run: this withholding is about where --project points, not about
|
|
498
533
|
// what the gate understands, and the contract itself came from the base.
|
|
@@ -506,6 +541,47 @@ export function decideTrustBase(gate, intent, trustBase, productVersion) {
|
|
|
506
541
|
}
|
|
507
542
|
return { ref: trustBase, withheld: null, refused: null, proposals: [] };
|
|
508
543
|
}
|
|
544
|
+
/** The smaller of a spawn's own limit and what is left of the preview budget, never negative. */
|
|
545
|
+
export function previewSpawnTimeout(limitMs, preview) {
|
|
546
|
+
return Math.max(0, Math.min(limitMs, preview.deadline - preview.clock()));
|
|
547
|
+
}
|
|
548
|
+
/**
|
|
549
|
+
* The spawn options of every preview spawn: the timeout above, SIGKILL, so a
|
|
550
|
+
* child that traps SIGTERM cannot outlive the budget, and the spawn's own
|
|
551
|
+
* environment with XDG_CACHE_HOME pointed at the preview's private cache, so
|
|
552
|
+
* nothing the head's rules fetched persists on a shared runner.
|
|
553
|
+
*/
|
|
554
|
+
export function previewSpawnOptions(limitMs, preview, env) {
|
|
555
|
+
return {
|
|
556
|
+
timeout: previewSpawnTimeout(limitMs, preview),
|
|
557
|
+
killSignal: 'SIGKILL',
|
|
558
|
+
env: { ...env, XDG_CACHE_HOME: preview.cacheDir },
|
|
559
|
+
};
|
|
560
|
+
}
|
|
561
|
+
/**
|
|
562
|
+
* The options one spawn passes to spawnSync beside its own, and the limit it
|
|
563
|
+
* ran under. Outside the preview: the full limit and nothing else, exactly as
|
|
564
|
+
* before. In the preview: `previewSpawnOptions`, and the limit's source is
|
|
565
|
+
* `preview-budget` when the budget left was the smaller. `start` false means
|
|
566
|
+
* no budget is left, and the spawn must not be started: a spawnSync timeout
|
|
567
|
+
* of 0 is no timeout at all.
|
|
568
|
+
*/
|
|
569
|
+
function spawnLimits(limit, preview, env) {
|
|
570
|
+
if (preview === undefined) {
|
|
571
|
+
return { start: true, limit, options: { timeout: limit.ms, ...(env === undefined ? {} : { env }) } };
|
|
572
|
+
}
|
|
573
|
+
const options = previewSpawnOptions(limit.ms, preview, env ?? process.env);
|
|
574
|
+
return {
|
|
575
|
+
start: options.timeout > 0,
|
|
576
|
+
limit: options.timeout < limit.ms ? { ms: options.timeout, source: 'preview-budget' } : limit,
|
|
577
|
+
options,
|
|
578
|
+
};
|
|
579
|
+
}
|
|
580
|
+
/** A spawnSync-shaped result for a preview spawn that was never started: no budget left. */
|
|
581
|
+
function notStartedResult() {
|
|
582
|
+
const error = Object.assign(new Error('spawnSync ETIMEDOUT: the preview budget was spent'), { code: 'ETIMEDOUT' });
|
|
583
|
+
return { pid: 0, output: [], stdout: '', stderr: '', status: null, signal: null, error };
|
|
584
|
+
}
|
|
509
585
|
/**
|
|
510
586
|
* A gate that never got as far as being spawned.
|
|
511
587
|
*
|
|
@@ -655,7 +731,22 @@ external = {},
|
|
|
655
731
|
* For the intent gate on a prepared run: hand it this base with its own
|
|
656
732
|
* `--base` in place of `--paths`. Decided by `intentChangeChannel`.
|
|
657
733
|
*/
|
|
658
|
-
intentBase
|
|
734
|
+
intentBase,
|
|
735
|
+
/**
|
|
736
|
+
* dep-guard's `--base` when `trustBase` is withheld from it in the preview
|
|
737
|
+
* under the proposed rules: the change is still measured against the base
|
|
738
|
+
* ref, only the rules are the head's. Ignored when `trustBase` is set, and
|
|
739
|
+
* by every other product.
|
|
740
|
+
*/
|
|
741
|
+
changeBase,
|
|
742
|
+
/**
|
|
743
|
+
* True for a spawn of the preview under the proposed rules. osv-scanner
|
|
744
|
+
* then gets `--no-call-analysis=all` appended after the base's own options,
|
|
745
|
+
* whatever they say: call analysis builds the project it scans, which in
|
|
746
|
+
* the preview is the head's code, and osv-scanner applies its disables
|
|
747
|
+
* after its enables, so the appended flag wins.
|
|
748
|
+
*/
|
|
749
|
+
preview = false) {
|
|
659
750
|
const passthrough = renderOptionFlags(gate.options);
|
|
660
751
|
const trust = trustBase === undefined ? [] : ['--trust-base', trustBase];
|
|
661
752
|
const config = external.configPath === undefined ? [] : ['--config', external.configPath];
|
|
@@ -680,7 +771,8 @@ intentBase) {
|
|
|
680
771
|
// name incompatible comparisons -- the git index versus an arbitrary
|
|
681
772
|
// ref. A staged run already has its own comparison and --trust-base
|
|
682
773
|
// is unaffected, since it answers a different question.
|
|
683
|
-
const
|
|
774
|
+
const baseRef = trustBase ?? changeBase;
|
|
775
|
+
const base = baseRef !== undefined && !staged ? ['--base', baseRef] : [];
|
|
684
776
|
return [...(staged ? ['--staged'] : []), '--format', 'json', ...trust, ...base, ...passthrough];
|
|
685
777
|
}
|
|
686
778
|
case 'vault-guard':
|
|
@@ -832,26 +924,30 @@ intentBase) {
|
|
|
832
924
|
...(noResolve ? ['--no-resolve'] : []),
|
|
833
925
|
...callAnalysis,
|
|
834
926
|
...renderOptionFlags(options),
|
|
927
|
+
...(preview ? ['--no-call-analysis=all'] : []),
|
|
835
928
|
];
|
|
836
929
|
}
|
|
837
930
|
}
|
|
838
931
|
}
|
|
839
|
-
function probeVersion(binary, product, repoRoot,
|
|
932
|
+
function probeVersion(binary, product, repoRoot, timeLimit, preview) {
|
|
840
933
|
const spec = profileFor(product).versionProbe;
|
|
841
934
|
if (binary.versionProbe === null || spec === null) {
|
|
842
935
|
return { kind: 'unreadable' };
|
|
843
936
|
}
|
|
937
|
+
const limits = spawnLimits(timeLimit, preview, undefined);
|
|
844
938
|
const probeStarted = Date.now();
|
|
845
|
-
const probe =
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
939
|
+
const probe = limits.start
|
|
940
|
+
? spawnSync(binary.versionProbe.command, binary.versionProbe.argv, {
|
|
941
|
+
cwd: repoRoot,
|
|
942
|
+
encoding: 'utf8',
|
|
943
|
+
...limits.options,
|
|
944
|
+
})
|
|
945
|
+
: notStartedResult();
|
|
850
946
|
// FIRST, before the status: a probe that handled SIGTERM can exit 0 with a
|
|
851
947
|
// version on stdout, and it was still stopped at the limit.
|
|
852
948
|
const failure = spawnFailure(probe);
|
|
853
949
|
if (failure !== null && failure.reason === 'timed-out') {
|
|
854
|
-
return { kind: 'timed-out', elapsedMs: Date.now() - probeStarted, signal: failure.signal };
|
|
950
|
+
return { kind: 'timed-out', elapsedMs: Date.now() - probeStarted, signal: failure.signal, limit: limits.limit };
|
|
855
951
|
}
|
|
856
952
|
if (probe.status !== 0 || typeof probe.stdout !== 'string') {
|
|
857
953
|
return { kind: 'unreadable' };
|
|
@@ -943,7 +1039,7 @@ export function expectedVersionBeforePreparation(gate, binary, options) {
|
|
|
943
1039
|
const skipped = options.trustBase === undefined ? null : nodeModulesCandidate(gate, options.repoRoot);
|
|
944
1040
|
const carried = { timeLimit, ...(skipped === null ? {} : { nodeModulesSkipped: skipped }) };
|
|
945
1041
|
const started = Date.now();
|
|
946
|
-
const probed = probeVersion(binary, gate.product, options.repoRoot, timeLimit
|
|
1042
|
+
const probed = probeVersion(binary, gate.product, options.repoRoot, timeLimit);
|
|
947
1043
|
if (probed.kind === 'timed-out') {
|
|
948
1044
|
// The same outcome runGate builds for a stopped probe under the
|
|
949
1045
|
// expectation: enforced, because the run cannot show this is the pinned
|
|
@@ -1136,6 +1232,63 @@ export function runGate(gate, options) {
|
|
|
1136
1232
|
};
|
|
1137
1233
|
}
|
|
1138
1234
|
}
|
|
1235
|
+
function callAnalysisOff(options) {
|
|
1236
|
+
const asList = (value) => (Array.isArray(value) ? value : [value]);
|
|
1237
|
+
for (const key of Object.keys(options)) {
|
|
1238
|
+
if (!key.includes('call-analysis'))
|
|
1239
|
+
continue;
|
|
1240
|
+
const value = options[key];
|
|
1241
|
+
if (key === 'no-call-analysis' && (value === true || asList(value).some((item) => item === 'all')))
|
|
1242
|
+
continue;
|
|
1243
|
+
return false;
|
|
1244
|
+
}
|
|
1245
|
+
return true;
|
|
1246
|
+
}
|
|
1247
|
+
/**
|
|
1248
|
+
* The three refusals only the preview under the proposed rules makes.
|
|
1249
|
+
*
|
|
1250
|
+
* An option value starting with "-" would render as a flag of its own
|
|
1251
|
+
* (renderOptionFlags), so a value the base never ran with could add an output
|
|
1252
|
+
* path or a second --log-opts. A base `command:` inside the working tree is
|
|
1253
|
+
* checked by refuseHeadControlledProgram for its own blob only, while what it
|
|
1254
|
+
* imports comes from the head, and the preview can reach a role the base has
|
|
1255
|
+
* switched off, whose command nobody has exercised (spec 5.2, finding 7).
|
|
1256
|
+
* osv-scanner call analysis builds the project it scans, here the head's
|
|
1257
|
+
* code, so only the all-off form of it is allowed (callAnalysisOff), and
|
|
1258
|
+
* gateArgs forces it off on every preview spawn besides.
|
|
1259
|
+
*/
|
|
1260
|
+
function previewRefusal(gate, repoRoot) {
|
|
1261
|
+
for (const name of Object.keys(gate.options).sort()) {
|
|
1262
|
+
const value = gate.options[name];
|
|
1263
|
+
const values = Array.isArray(value) ? value : [value];
|
|
1264
|
+
if (values.some((item) => typeof item === 'string' && item.startsWith('-'))) {
|
|
1265
|
+
return {
|
|
1266
|
+
reason: 'preparation-failed',
|
|
1267
|
+
detail: `preview under the proposed rules: option ${name} has a value starting with "-", so this gate was not run`,
|
|
1268
|
+
};
|
|
1269
|
+
}
|
|
1270
|
+
}
|
|
1271
|
+
// osv-scanner's call analysis builds the project it scans, and in the
|
|
1272
|
+
// preview that is the head's code (a Rust build.rs, for one).
|
|
1273
|
+
// Every option key is rendered as a flag, so the check is by key match:
|
|
1274
|
+
// any key containing "call-analysis" is refused unless it is the one
|
|
1275
|
+
// unambiguous all-off form, `no-call-analysis: true` or `all`. An absent
|
|
1276
|
+
// key is fine. Belt and braces: gateArgs appends --no-call-analysis=all
|
|
1277
|
+
// to every osv-scanner preview spawn as well.
|
|
1278
|
+
if (gate.product === 'osv-scanner' && !callAnalysisOff(gate.options)) {
|
|
1279
|
+
return {
|
|
1280
|
+
reason: 'preparation-failed',
|
|
1281
|
+
detail: "the preview does not run call analysis, because it would build the head's code",
|
|
1282
|
+
};
|
|
1283
|
+
}
|
|
1284
|
+
if (gate.command !== undefined && realPathInside(repoRoot, gate.command)) {
|
|
1285
|
+
return {
|
|
1286
|
+
reason: 'gate-program-refused',
|
|
1287
|
+
detail: `preview under the proposed rules: the base command ${gate.command} is inside the working tree, so this gate was not run`,
|
|
1288
|
+
};
|
|
1289
|
+
}
|
|
1290
|
+
return null;
|
|
1291
|
+
}
|
|
1139
1292
|
/**
|
|
1140
1293
|
* Whether git says the repository at `repoRoot` is shallow. Anything other
|
|
1141
1294
|
* than a clear "true" (no git, an old git that does not know the flag) is
|
|
@@ -1159,9 +1312,10 @@ function isShallowRepository(repoRoot) {
|
|
|
1159
1312
|
function runGateInner(gate, options, started, progress) {
|
|
1160
1313
|
// Every spawn of this gate gets the FULL limit, not a share of it: the
|
|
1161
1314
|
// version probe, the scan and, on a compared pull request, osv-scanner's
|
|
1162
|
-
// base run. Onto `progress` so every outcome from here on carries it.
|
|
1315
|
+
// base run. Onto `progress` so every outcome from here on carries it. In
|
|
1316
|
+
// the preview each spawn gets the smaller of this and what is left of the
|
|
1317
|
+
// preview's budget (spawnLimits), and the outcome says which it was.
|
|
1163
1318
|
const timeLimit = resolveTimeLimit(gate, options.timeoutMs);
|
|
1164
|
-
const timeoutMs = timeLimit.ms;
|
|
1165
1319
|
Object.assign(progress, { timeLimit });
|
|
1166
1320
|
const ownOption = gateOwnTimeoutNote(gate, timeLimit, options.trustBase);
|
|
1167
1321
|
if (ownOption !== null) {
|
|
@@ -1181,6 +1335,24 @@ function runGateInner(gate, options, started, progress) {
|
|
|
1181
1335
|
Object.assign(progress, { nodeModulesSkipped: skipped });
|
|
1182
1336
|
}
|
|
1183
1337
|
const base = progress;
|
|
1338
|
+
// THE PREVIEW'S OWN REFUSALS, before resolution and before any spawn, the
|
|
1339
|
+
// version probe included. The primary run needs neither.
|
|
1340
|
+
if (options.preview !== undefined) {
|
|
1341
|
+
const refused = previewRefusal(gate, options.repoRoot);
|
|
1342
|
+
if (refused !== null) {
|
|
1343
|
+
return {
|
|
1344
|
+
...base,
|
|
1345
|
+
// Enforced under a trust base, like every refusal there; the preview
|
|
1346
|
+
// never reaches the exit code either way.
|
|
1347
|
+
enforce: options.trustBase !== undefined ? true : gate.enforce,
|
|
1348
|
+
durationMs: Date.now() - started,
|
|
1349
|
+
couldNotRun: refused,
|
|
1350
|
+
findings: [normalizeFailedGate(gate.role, gate.product, refused.detail)],
|
|
1351
|
+
run: EMPTY_RUN,
|
|
1352
|
+
diagnostics: [],
|
|
1353
|
+
};
|
|
1354
|
+
}
|
|
1355
|
+
}
|
|
1184
1356
|
let binary;
|
|
1185
1357
|
try {
|
|
1186
1358
|
binary = resolveGateBinary(gate, options.repoRoot, options.pathValue, { skipNodeModules });
|
|
@@ -1302,8 +1474,11 @@ function runGateInner(gate, options, started, progress) {
|
|
|
1302
1474
|
diagnostics: [],
|
|
1303
1475
|
};
|
|
1304
1476
|
}
|
|
1305
|
-
const probed = probeVersion(binary, gate.product, options.repoRoot,
|
|
1477
|
+
const probed = probeVersion(binary, gate.product, options.repoRoot, timeLimit, options.preview);
|
|
1306
1478
|
if (probed.kind === 'timed-out') {
|
|
1479
|
+
// The limit the probe ran under, which in the preview can be what was
|
|
1480
|
+
// left of the budget; onto `progress` so the outcome says so.
|
|
1481
|
+
Object.assign(progress, { timeLimit: probed.limit });
|
|
1307
1482
|
// Stopped here, before the version floor and before decideTrustBase: a
|
|
1308
1483
|
// timed-out probe is not an unreadable version (which on a pull request
|
|
1309
1484
|
// would read as trust-base-unverified, a packaging problem that does not
|
|
@@ -1312,8 +1487,8 @@ function runGateInner(gate, options, started, progress) {
|
|
|
1312
1487
|
// gate could not be placed inside the boundary. Enforced under the
|
|
1313
1488
|
// Action's expected-version signal too, like version-unverified: the run
|
|
1314
1489
|
// cannot show this is the pinned build.
|
|
1315
|
-
const detail = timedOutDetail(gate, 'version-probe',
|
|
1316
|
-
const timedOut = timedOutRecord('version-probe',
|
|
1490
|
+
const detail = timedOutDetail(gate, 'version-probe', probed.limit, probed.elapsedMs, options.trustBase);
|
|
1491
|
+
const timedOut = timedOutRecord('version-probe', probed.limit, probed.elapsedMs, probed.signal);
|
|
1317
1492
|
return {
|
|
1318
1493
|
...base,
|
|
1319
1494
|
binary,
|
|
@@ -1373,7 +1548,7 @@ function runGateInner(gate, options, started, progress) {
|
|
|
1373
1548
|
// decision reads the version. That ordering is the whole capability gate:
|
|
1374
1549
|
// a gate IN the table whose version is below its minimum, or could not be
|
|
1375
1550
|
// read, is refused rather than run outside the boundary.
|
|
1376
|
-
const trustBase = decideTrustBase(gate, options.intent, options.trustBase, version);
|
|
1551
|
+
const trustBase = decideTrustBase(gate, options.intent, options.trustBase, version, options.preview !== undefined);
|
|
1377
1552
|
if (trustBase !== undefined && trustBase.refused !== null) {
|
|
1378
1553
|
return {
|
|
1379
1554
|
...base,
|
|
@@ -1499,7 +1674,7 @@ function spawnAndRead(ctx) {
|
|
|
1499
1674
|
}
|
|
1500
1675
|
const baseArgv = (copies) => [
|
|
1501
1676
|
...binary.argvPrefix,
|
|
1502
|
-
...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: [...copies] }),
|
|
1677
|
+
...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: [...copies] }, undefined, undefined, options.preview !== undefined),
|
|
1503
1678
|
];
|
|
1504
1679
|
const checked = removed === null
|
|
1505
1680
|
? { kind: 'unverified', detail: `the base tree at ${decidedRef} could not be listed` }
|
|
@@ -1516,12 +1691,15 @@ function spawnAndRead(ctx) {
|
|
|
1516
1691
|
baseArgv,
|
|
1517
1692
|
budgetMs: input.budgetMs,
|
|
1518
1693
|
spawn: (argv, cwd, budget) => {
|
|
1519
|
-
const
|
|
1520
|
-
|
|
1521
|
-
|
|
1522
|
-
|
|
1523
|
-
|
|
1524
|
-
|
|
1694
|
+
const limits = spawnLimits({ ...timeLimit, ms: budget }, options.preview, undefined);
|
|
1695
|
+
const baseChild = limits.start
|
|
1696
|
+
? spawnSync(binary.command, [...argv], {
|
|
1697
|
+
cwd,
|
|
1698
|
+
encoding: 'utf8',
|
|
1699
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
1700
|
+
...limits.options,
|
|
1701
|
+
})
|
|
1702
|
+
: notStartedResult();
|
|
1525
1703
|
return {
|
|
1526
1704
|
status: baseChild.status,
|
|
1527
1705
|
stderr: stripAnsi(baseChild.stderr ?? ''),
|
|
@@ -1763,24 +1941,33 @@ function spawnAndRead(ctx) {
|
|
|
1763
1941
|
// intentChangeChannel is pure, and runGateInner already returned on the one
|
|
1764
1942
|
// outcome that does not spawn.
|
|
1765
1943
|
const channel = intentChangeChannel(gate, options.intent, version);
|
|
1944
|
+
// In the preview, dep-guard and vault-guard are not handed --trust-base
|
|
1945
|
+
// (decideTrustBase), and dep-guard still measures the change against the
|
|
1946
|
+
// base ref: --base comes from the run's trust base, which stays set.
|
|
1947
|
+
const changeBase = options.preview !== undefined && trustBase?.withheld === PREVIEW_WITHHELD ? options.trustBase : undefined;
|
|
1766
1948
|
const argv = [
|
|
1767
1949
|
...binary.argvPrefix,
|
|
1768
|
-
...gateArgs(gate, options.staged, options.intent, decidedRef, external, channel.kind === 'base' ? channel.ref : undefined),
|
|
1950
|
+
...gateArgs(gate, options.staged, options.intent, decidedRef, external, channel.kind === 'base' ? channel.ref : undefined, changeBase, options.preview !== undefined),
|
|
1769
1951
|
];
|
|
1952
|
+
// A history gate reads git history, and replace refs or grafts can cut
|
|
1953
|
+
// that history without making the repository shallow. Ignoring replace
|
|
1954
|
+
// objects makes it read the real commits. Other gates keep the inherited
|
|
1955
|
+
// environment untouched, outside the preview.
|
|
1956
|
+
const scanLimits = spawnLimits(timeLimit, options.preview, profile.readsHistory ? { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' } : undefined);
|
|
1957
|
+
if (scanLimits.limit !== timeLimit) {
|
|
1958
|
+
Object.assign(progress, { timeLimit: scanLimits.limit });
|
|
1959
|
+
}
|
|
1770
1960
|
// Taken just before the call, so a timed-out message's elapsed time is the
|
|
1771
1961
|
// scan's own and not resolution plus the version probe.
|
|
1772
1962
|
const spawnStarted = Date.now();
|
|
1773
|
-
const child =
|
|
1774
|
-
|
|
1775
|
-
|
|
1776
|
-
|
|
1777
|
-
|
|
1778
|
-
|
|
1779
|
-
|
|
1780
|
-
|
|
1781
|
-
// inherited environment untouched.
|
|
1782
|
-
...(profile.readsHistory ? { env: { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' } } : {}),
|
|
1783
|
-
});
|
|
1963
|
+
const child = scanLimits.start
|
|
1964
|
+
? spawnSync(binary.command, argv, {
|
|
1965
|
+
cwd: spawnCwd,
|
|
1966
|
+
encoding: 'utf8',
|
|
1967
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
1968
|
+
...scanLimits.options,
|
|
1969
|
+
})
|
|
1970
|
+
: notStartedResult();
|
|
1784
1971
|
const withRun = {
|
|
1785
1972
|
...base,
|
|
1786
1973
|
productVersion: version,
|
|
@@ -1822,8 +2009,8 @@ function spawnAndRead(ctx) {
|
|
|
1822
2009
|
if (failure !== null) {
|
|
1823
2010
|
if (failure.reason === 'timed-out') {
|
|
1824
2011
|
const elapsedMs = Date.now() - spawnStarted;
|
|
1825
|
-
const detail = timedOutDetail(gate, 'scan',
|
|
1826
|
-
const timedOut = timedOutRecord('scan',
|
|
2012
|
+
const detail = timedOutDetail(gate, 'scan', scanLimits.limit, elapsedMs, options.trustBase);
|
|
2013
|
+
const timedOut = timedOutRecord('scan', scanLimits.limit, elapsedMs, failure.signal);
|
|
1827
2014
|
return {
|
|
1828
2015
|
...withRun,
|
|
1829
2016
|
exitCode: null,
|
|
@@ -2071,15 +2258,18 @@ function spawnAndRead(ctx) {
|
|
|
2071
2258
|
headArgv: argv,
|
|
2072
2259
|
baseArgv: (copies) => [
|
|
2073
2260
|
...binary.argvPrefix,
|
|
2074
|
-
...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: copies }),
|
|
2261
|
+
...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: copies }, undefined, undefined, options.preview !== undefined),
|
|
2075
2262
|
],
|
|
2076
2263
|
spawn: (baseArgv, cwd) => {
|
|
2077
|
-
const
|
|
2078
|
-
|
|
2079
|
-
|
|
2080
|
-
|
|
2081
|
-
|
|
2082
|
-
|
|
2264
|
+
const limits = spawnLimits(timeLimit, options.preview, undefined);
|
|
2265
|
+
const baseChild = limits.start
|
|
2266
|
+
? spawnSync(binary.command, [...baseArgv], {
|
|
2267
|
+
cwd,
|
|
2268
|
+
encoding: 'utf8',
|
|
2269
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
2270
|
+
...limits.options,
|
|
2271
|
+
})
|
|
2272
|
+
: notStartedResult();
|
|
2083
2273
|
return { status: baseChild.status, stdout: baseChild.stdout ?? '', error: baseChild.error };
|
|
2084
2274
|
},
|
|
2085
2275
|
rootSpellings,
|
package/dist/output-sarif.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import type
|
|
2
|
-
import type
|
|
1
|
+
import { type GateOutcome } from './gate-runner.js';
|
|
2
|
+
import { type RunResult } from './run.js';
|
|
3
3
|
export declare const UMBRELLA_DRIVER_NAME = "conductor";
|
|
4
4
|
/** The partialFingerprints key for a product's own fingerprint. */
|
|
5
5
|
export declare function fingerprintKey(scope: string): string;
|
package/dist/output-sarif.js
CHANGED
|
@@ -118,10 +118,13 @@
|
|
|
118
118
|
// normalize.ts, which is where the omission would stop mattering if the
|
|
119
119
|
// field were ever carried.
|
|
120
120
|
import { gateExitBlocks } from './exit-codes.js';
|
|
121
|
+
import { cleanOutputLine } from './gate-runner.js';
|
|
121
122
|
import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
|
|
122
123
|
import { INTENT_WARNING } from './normalize.js';
|
|
123
|
-
import { skewFound, skewPlace } from './output-text.js';
|
|
124
|
+
import { gateOutcomeWords, skewFound, skewPlace } from './output-text.js';
|
|
124
125
|
import { POLICY_FILE_NAME } from './policy.js';
|
|
126
|
+
import { policyChangeLine } from './policy-diff.js';
|
|
127
|
+
import { guardPreview } from './run.js';
|
|
125
128
|
const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
|
|
126
129
|
export const UMBRELLA_DRIVER_NAME = 'conductor';
|
|
127
130
|
/**
|
|
@@ -363,6 +366,16 @@ function notificationDeclarations(notifications) {
|
|
|
363
366
|
const ids = [...new Set(notifications.map((notification) => notification.id))].sort();
|
|
364
367
|
return ids.map((id) => ({ id, name: id.slice(id.indexOf('/') + 1) }));
|
|
365
368
|
}
|
|
369
|
+
/**
|
|
370
|
+
* The trust base as the log carries it: the per-key changes become their
|
|
371
|
+
* rendered lines (escaped and truncated), never the raw head values.
|
|
372
|
+
*/
|
|
373
|
+
function sarifTrustBase(trustBase) {
|
|
374
|
+
const { policyChanges, ...rest } = trustBase;
|
|
375
|
+
return policyChanges === undefined
|
|
376
|
+
? rest
|
|
377
|
+
: { ...rest, policyChanges: policyChanges.map(policyChangeLine) };
|
|
378
|
+
}
|
|
366
379
|
function makeRun(name, version, findings,
|
|
367
380
|
/** The artifact a result with no location of its own is filed against. */
|
|
368
381
|
fallbackUri, properties, invocation) {
|
|
@@ -695,6 +708,31 @@ function proposalNotifications(result) {
|
|
|
695
708
|
},
|
|
696
709
|
}));
|
|
697
710
|
}
|
|
711
|
+
/**
|
|
712
|
+
* The preview under the proposed rules, one note per preview gate.
|
|
713
|
+
*
|
|
714
|
+
* NOTES ONLY, and never a result, a rule, a fingerprint or a run: the
|
|
715
|
+
* preview decides nothing, so nothing of it may reach the alert list or the
|
|
716
|
+
* code scanning tab's identity for a finding. The caller appends these only
|
|
717
|
+
* to a notification list that is non-empty without them, so a preview never
|
|
718
|
+
* creates the umbrella's run, and executionSuccessful still reads only the
|
|
719
|
+
* primary gates. A throw here yields no preview notification at all.
|
|
720
|
+
*/
|
|
721
|
+
function previewNotifications(result) {
|
|
722
|
+
const preview = result.preview;
|
|
723
|
+
if (preview === undefined) {
|
|
724
|
+
return [];
|
|
725
|
+
}
|
|
726
|
+
return guardPreview(() => preview.gates.map((gate) => {
|
|
727
|
+
const outcome = cleanOutputLine(gateOutcomeWords(gate));
|
|
728
|
+
return {
|
|
729
|
+
id: 'conductor/preview-under-proposed-rules',
|
|
730
|
+
message: 'Preview under the proposed rules, which does not affect the verdict: ' +
|
|
731
|
+
`${gate.role} (${gate.product}) ${outcome}, ${gate.findings.length} finding(s).`,
|
|
732
|
+
details: { role: gate.role, product: gate.product, outcome, findings: gate.findings.length },
|
|
733
|
+
};
|
|
734
|
+
}), () => []);
|
|
735
|
+
}
|
|
698
736
|
/**
|
|
699
737
|
* The trust base the umbrella refused, when it refused one.
|
|
700
738
|
*
|
|
@@ -1043,6 +1081,11 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
1043
1081
|
...intentWarningNotifications(result),
|
|
1044
1082
|
...gateOwnOptionNotifications(result),
|
|
1045
1083
|
];
|
|
1084
|
+
// Only onto a list that is already non-empty: the preview never earns the
|
|
1085
|
+
// umbrella's run on its own.
|
|
1086
|
+
if (notifications.length > 0) {
|
|
1087
|
+
notifications.push(...previewNotifications(result));
|
|
1088
|
+
}
|
|
1046
1089
|
// Notifications earn the run on their own. Before this, the umbrella run
|
|
1047
1090
|
// existed only when it had findings and a deferred gate was one; without
|
|
1048
1091
|
// this clause a commit-stage log would say nothing whatever about the gate
|
|
@@ -1063,7 +1106,9 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
1063
1106
|
// fact about the whole run: every gate that could take the flag was
|
|
1064
1107
|
// handed this same ref. A consumer reading only the log can then tell
|
|
1065
1108
|
// a pull-request run from an ordinary one without parsing sentences.
|
|
1066
|
-
result.trustBase === null
|
|
1109
|
+
result.trustBase === null
|
|
1110
|
+
? undefined
|
|
1111
|
+
: { trustBase: sarifTrustBase(result.trustBase) }, {
|
|
1067
1112
|
// A claim about whether the analysis completed, taken from the
|
|
1068
1113
|
// gates rather than from the exit code: an unenforced gate that
|
|
1069
1114
|
// could not run leaves the run at exit 0, and nothing was checked
|
package/dist/output-text.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { type GateOutcome } from './gate-runner.js';
|
|
2
2
|
import type { ReportedMatch } from './intent-prepare.js';
|
|
3
|
-
import type
|
|
3
|
+
import { type RunResult } from './run.js';
|
|
4
4
|
/**
|
|
5
5
|
* How many entries a section prints before it rolls the rest up into one
|
|
6
6
|
* line, unless --verbose. A full-history gitleaks scan or an osv-scanner run
|
|
@@ -56,6 +56,42 @@ export declare function proposalCount(result: RunResult): string;
|
|
|
56
56
|
* not change.
|
|
57
57
|
*/
|
|
58
58
|
export declare function jobLogSummary(result: RunResult): string;
|
|
59
|
+
/**
|
|
60
|
+
* The proposal lines for a job log: the count sentence, then one line per
|
|
61
|
+
* proposed control change. Empty outside pull-request mode, and empty when
|
|
62
|
+
* the trust base was refused or never given, because no rules were read and
|
|
63
|
+
* there is nothing proposed to count. Each line goes through
|
|
64
|
+
* cleanOutputLine, since a proposal carries text a gate printed.
|
|
65
|
+
*/
|
|
66
|
+
export declare function proposalLogLines(result: RunResult): string[];
|
|
67
|
+
/**
|
|
68
|
+
* A gate's outcome in the job log's words: `ok`, `findings (N, M blocking)`
|
|
69
|
+
* with dep-guard's deadline clause when it said so, `could-not-run (reason)`
|
|
70
|
+
* or `missing (reason)`. Shared by the per-gate lines and the preview's.
|
|
71
|
+
*/
|
|
72
|
+
export declare function gateOutcomeWords(gate: GateOutcome): string;
|
|
73
|
+
/**
|
|
74
|
+
* The header the preview block starts with, in the report and the comment.
|
|
75
|
+
* scripts/lib/pr-comment.mjs spells it too, to cut the preview first from a
|
|
76
|
+
* comment over the limit, and action.yml stops its summary scan at it.
|
|
77
|
+
*/
|
|
78
|
+
export declare const PREVIEW_HEADER = "Preview under the proposed rules (does not affect the verdict)";
|
|
79
|
+
/**
|
|
80
|
+
* The preview under the proposed rules, as report lines: empty without a
|
|
81
|
+
* preview, otherwise a blank line, the header, the fixed-shape count line,
|
|
82
|
+
* one gate section per preview gate, then the deferred, over-budget, threw
|
|
83
|
+
* and advisory lines. Printed only AFTER the verdict line, and read by
|
|
84
|
+
* nothing that decides one. Every line goes through cleanOutputLine: a
|
|
85
|
+
* preview runs under head-proposed keys, so its gate text is not trusted to
|
|
86
|
+
* be free of a workflow command.
|
|
87
|
+
*/
|
|
88
|
+
export declare function previewLines(result: RunResult, verbose: boolean): string[];
|
|
89
|
+
/**
|
|
90
|
+
* The preview's job log lines: one per preview gate in the per-gate lines'
|
|
91
|
+
* outcome words, one per over-budget role, and one for a deferred intent
|
|
92
|
+
* gate. Empty without a preview. Each line goes through cleanOutputLine.
|
|
93
|
+
*/
|
|
94
|
+
export declare function previewLogLines(result: RunResult): string[];
|
|
59
95
|
/**
|
|
60
96
|
* One plain line per gate, for the job log: which gate, which version, what
|
|
61
97
|
* happened, and the exit code. Written to stderr by cli.ts on EVERY run, so
|