@vaultcompass/conductor 0.13.2 → 0.15.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 +145 -20
- package/dist/cli.d.ts +38 -0
- package/dist/cli.js +77 -6
- package/dist/gate-runner.d.ts +83 -4
- package/dist/gate-runner.js +288 -49
- 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 +125 -27
- package/dist/policy-diff.d.ts +43 -0
- package/dist/policy-diff.js +181 -0
- package/dist/resolve.d.ts +68 -0
- package/dist/resolve.js +156 -2
- package/dist/run.d.ts +63 -0
- package/dist/run.js +142 -21
- package/dist/trust-base.d.ts +34 -0
- package/dist/trust-base.js +83 -1
- package/package.json +1 -1
- package/schema/guardrails.schema.json +1 -1
package/dist/resolve.js
CHANGED
|
@@ -59,7 +59,7 @@
|
|
|
59
59
|
// depend on a package cache the report cannot describe, and a gate that
|
|
60
60
|
// "ran" from an unknown version is worse than one that is honestly
|
|
61
61
|
// reported missing.
|
|
62
|
-
import { accessSync, constants, statSync } from 'node:fs';
|
|
62
|
+
import { accessSync, constants, lstatSync, statSync } from 'node:fs';
|
|
63
63
|
import path from 'node:path';
|
|
64
64
|
import { profileFor } from './products.js';
|
|
65
65
|
export const CANDIDATES = {
|
|
@@ -220,6 +220,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
220
220
|
const prefix = gate.args ?? inferred?.prefix ?? table[0].prefix;
|
|
221
221
|
const candidateName = inferred?.name ?? baseName(gate.command);
|
|
222
222
|
const candidate = inferred ?? table[0];
|
|
223
|
+
const argumentPaths = argumentPathsOf(gate, repoRoot);
|
|
223
224
|
// A build directory holds plain .js files with a shebang but no
|
|
224
225
|
// executable bit surprisingly often (a fresh tsc output, a file copied
|
|
225
226
|
// out of a tarball). Running it through this same Node is exactly what
|
|
@@ -231,6 +232,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
231
232
|
// Node is the command; the script is what actually decides anything.
|
|
232
233
|
program: gate.command,
|
|
233
234
|
argvPrefix: [gate.command, ...prefix],
|
|
235
|
+
argumentPaths,
|
|
234
236
|
source: 'policy',
|
|
235
237
|
candidate: candidateName,
|
|
236
238
|
versionProbe: candidate.versionSafe && profileFor(gate.product).versionProbe !== null
|
|
@@ -241,13 +243,20 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
241
243
|
: versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
|
|
242
244
|
};
|
|
243
245
|
}
|
|
246
|
+
// A command that is not itself a gate name (an interpreter, typically)
|
|
247
|
+
// and whose args hand it a script is asked through the script, or the
|
|
248
|
+
// version reported is the interpreter's (audit 2026-10-27, N4). A
|
|
249
|
+
// version-unsafe candidate keeps its sibling lookup: rule 2 above.
|
|
250
|
+
const viaScript = inferred === undefined && candidate.versionSafe ? scriptVersionProbe(gate, repoRoot) : null;
|
|
244
251
|
return {
|
|
245
252
|
command: gate.command,
|
|
246
253
|
program: gate.command,
|
|
247
254
|
argvPrefix: prefix,
|
|
255
|
+
argumentPaths,
|
|
248
256
|
source: 'policy',
|
|
249
257
|
candidate: candidateName,
|
|
250
|
-
versionProbe:
|
|
258
|
+
versionProbe: viaScript ??
|
|
259
|
+
versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
|
|
251
260
|
};
|
|
252
261
|
}
|
|
253
262
|
for (const candidate of table) {
|
|
@@ -259,6 +268,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
259
268
|
command: found.command,
|
|
260
269
|
program: found.command,
|
|
261
270
|
argvPrefix: [...candidate.prefix],
|
|
271
|
+
argumentPaths: [],
|
|
262
272
|
source: found.source,
|
|
263
273
|
candidate: candidate.name,
|
|
264
274
|
versionProbe: versionProbeFor(gate.product, candidate, found.command, repoRoot, pathValue, skipNodeModules),
|
|
@@ -270,3 +280,147 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
270
280
|
export function candidateNames(product) {
|
|
271
281
|
return CANDIDATES[product].map((candidate) => candidate.name);
|
|
272
282
|
}
|
|
283
|
+
/**
|
|
284
|
+
* The extensions an interpreter can add to an entry before it looks at the
|
|
285
|
+
* entry as written: Node's main-entry resolution tries `.js`, `.json` and
|
|
286
|
+
* `.node` BEFORE a directory of the same name (`node tools/gate` runs
|
|
287
|
+
* `tools/gate.js` over `tools/gate/index.js`, measured on Node 22), and the
|
|
288
|
+
* ES module forms are listed too, so a sibling a loader might take is vetted
|
|
289
|
+
* whether or not this Node takes it (audit 2026-10-27 fix round, MB1 and
|
|
290
|
+
* MB2).
|
|
291
|
+
*/
|
|
292
|
+
const LOADABLE_EXTENSIONS = ['.js', '.mjs', '.cjs', '.json', '.node'];
|
|
293
|
+
function existsAtAll(candidate) {
|
|
294
|
+
try {
|
|
295
|
+
lstatSync(candidate);
|
|
296
|
+
return true;
|
|
297
|
+
}
|
|
298
|
+
catch {
|
|
299
|
+
return false;
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
/**
|
|
303
|
+
* Whether the policy's `command:` is itself the gate program, so its `args:`
|
|
304
|
+
* are that gate's own argv rather than something an interpreter will load.
|
|
305
|
+
*
|
|
306
|
+
* True when the command's name is a candidate name (`vault-guard`,
|
|
307
|
+
* `intent-guard.js`), and for a non-executable `.js` command, which this
|
|
308
|
+
* package runs through its own Node with the script as the program. False
|
|
309
|
+
* for anything else, an interpreter such as `node` or `python3` above all.
|
|
310
|
+
* Only then are the product's subcommand words (`scan`, `source`) exempt
|
|
311
|
+
* from being read as paths: an interpreter handed `scan` runs `scan.js` or
|
|
312
|
+
* `scan/index.js`, so for it the word is a path like any other (audit
|
|
313
|
+
* 2026-10-27 fix round, MB3).
|
|
314
|
+
*/
|
|
315
|
+
export function commandIsGateProgram(gate) {
|
|
316
|
+
if (gate.command === undefined) {
|
|
317
|
+
return true;
|
|
318
|
+
}
|
|
319
|
+
if (!isExecutableFile(gate.command) && /\.(?:js|mjs|cjs)$/.test(gate.command)) {
|
|
320
|
+
return true;
|
|
321
|
+
}
|
|
322
|
+
const name = baseName(gate.command);
|
|
323
|
+
return CANDIDATES[gate.product].some((candidate) => candidate.name === name);
|
|
324
|
+
}
|
|
325
|
+
/**
|
|
326
|
+
* Every path an interpreter could load for one `args:` entry, as absolute
|
|
327
|
+
* paths, in the order checked; empty when the entry names nothing on disk
|
|
328
|
+
* (audit 2026-10-27, B1, and its fix round).
|
|
329
|
+
*
|
|
330
|
+
* Relative entries are resolved against `repoRoot`. That is the working
|
|
331
|
+
* directory of the version probe and of the gate's own spawn for every
|
|
332
|
+
* product except one whose base config can name further files
|
|
333
|
+
* (`followsConfigExtend`): on a pull request that gate runs from a temporary
|
|
334
|
+
* directory holding the base ref's copies (src/gate-runner.ts, spawnCwd), so
|
|
335
|
+
* a relative script there resolves against base copies or not at all, never
|
|
336
|
+
* against the head tree. The rules, in order:
|
|
337
|
+
*
|
|
338
|
+
* - An option with no `=` (`--json`, `-r`) names nothing. An option with one
|
|
339
|
+
* (`--config=tools/cfg.json`, `--import=./hook.mjs`) is read for the value
|
|
340
|
+
* after the first `=`, since that is where an interpreter takes a file to
|
|
341
|
+
* load and a gate takes a file to read its rules from.
|
|
342
|
+
* - When `exemptSubcommands` is true (the command is the gate program
|
|
343
|
+
* itself, commandIsGateProgram), a bare word that is one of the product's
|
|
344
|
+
* own subcommands (`scan`, `git`, `source`, `check`) names nothing, even
|
|
345
|
+
* when a directory of that name exists. For an interpreter nothing is
|
|
346
|
+
* exempt.
|
|
347
|
+
* - The entry as written, when it exists as a file, a directory or a
|
|
348
|
+
* symlink, without following the symlink, so the caller can refuse an
|
|
349
|
+
* in-tree link on its own entry.
|
|
350
|
+
* - Then every `<entry>.js`, `.mjs`, `.cjs`, `.json` and `.node` that exists,
|
|
351
|
+
* slash or not, and whether or not the entry itself exists: Node tries
|
|
352
|
+
* those before a directory of the same name, and a bare `run` runs
|
|
353
|
+
* `run.js`. A sibling the head ADDED is listed too, which is what refuses
|
|
354
|
+
* it: the base does not track it.
|
|
355
|
+
*
|
|
356
|
+
* A directory's contents are covered by the caller's tree comparison, so
|
|
357
|
+
* `index.js` and `package.json` inside it are not listed separately; a
|
|
358
|
+
* `main` that points outside the directory is not vetted, the same limit as
|
|
359
|
+
* a program's directory. Everything else, a Python `-m` module name, a bare
|
|
360
|
+
* package specifier an interpreter resolves for itself, code passed as a
|
|
361
|
+
* string (`node -e`, `bash -c`), is not recognised as a path. The README says
|
|
362
|
+
* so.
|
|
363
|
+
*/
|
|
364
|
+
export function argumentCandidates(arg, repoRoot, product, exemptSubcommands) {
|
|
365
|
+
let value = arg;
|
|
366
|
+
if (arg.startsWith('-')) {
|
|
367
|
+
const equals = arg.indexOf('=');
|
|
368
|
+
if (equals < 0) {
|
|
369
|
+
return [];
|
|
370
|
+
}
|
|
371
|
+
value = arg.slice(equals + 1);
|
|
372
|
+
}
|
|
373
|
+
else if (exemptSubcommands && CANDIDATES[product].some((candidate) => candidate.prefix.includes(arg))) {
|
|
374
|
+
return [];
|
|
375
|
+
}
|
|
376
|
+
if (value === '') {
|
|
377
|
+
return [];
|
|
378
|
+
}
|
|
379
|
+
const absolute = path.resolve(repoRoot, value);
|
|
380
|
+
return [absolute, ...LOADABLE_EXTENSIONS.map((extension) => absolute + extension)].filter(existsAtAll);
|
|
381
|
+
}
|
|
382
|
+
/** `argumentCandidates` for every entry of a policy's `args:`, flattened. */
|
|
383
|
+
function argumentPathsOf(gate, repoRoot) {
|
|
384
|
+
const exempt = commandIsGateProgram(gate);
|
|
385
|
+
return (gate.args ?? []).flatMap((arg) => argumentCandidates(arg, repoRoot, gate.product, exempt));
|
|
386
|
+
}
|
|
387
|
+
/**
|
|
388
|
+
* The version probe for a policy `command:` that is not itself a gate name,
|
|
389
|
+
* when its `args:` hand it a script: the args up to and including the first
|
|
390
|
+
* non-option entry, when that entry names something the interpreter can load
|
|
391
|
+
* (argumentCandidates: a file, a directory, or a bare or extension-less name
|
|
392
|
+
* with a loadable sibling), then the product's own probe argv. The entry is
|
|
393
|
+
* passed as written, so the interpreter resolves it exactly as it will for
|
|
394
|
+
* the scan. So `node tools/gate/run.mjs scan` is asked `node
|
|
395
|
+
* tools/gate/run.mjs --version`, `node tools/gate` is asked `node tools/gate
|
|
396
|
+
* --version`, and the version reported is the script's, not Node's (audit
|
|
397
|
+
* 2026-10-27, N4). Null when the first non-option entry names nothing, or
|
|
398
|
+
* there is none, and the caller keeps the probe it would have made anyway.
|
|
399
|
+
*
|
|
400
|
+
* Only the first: everything after the script is the script's own argv, and
|
|
401
|
+
* carrying a subcommand or a target into a probe would make it do work,
|
|
402
|
+
* which is the one thing a probe must not do.
|
|
403
|
+
* An interpreter flag that takes a file as a separate entry (`-r
|
|
404
|
+
* ./setup.js`) makes that file the first, so the probe asks the interpreter
|
|
405
|
+
* and reports its version, as it did before; under an expected-version pin
|
|
406
|
+
* that is could-not-run, the fail-closed direction.
|
|
407
|
+
*/
|
|
408
|
+
function scriptVersionProbe(gate, repoRoot) {
|
|
409
|
+
const spec = profileFor(gate.product).versionProbe;
|
|
410
|
+
if (spec === null || gate.command === undefined || gate.args === undefined) {
|
|
411
|
+
return null;
|
|
412
|
+
}
|
|
413
|
+
for (let index = 0; index < gate.args.length; index += 1) {
|
|
414
|
+
const arg = gate.args[index];
|
|
415
|
+
if (arg.startsWith('-')) {
|
|
416
|
+
continue;
|
|
417
|
+
}
|
|
418
|
+
// Only the FIRST non-option entry can be the script. A later file is the
|
|
419
|
+
// script's own argument (`my-build check rules.json`), and a probe that
|
|
420
|
+
// carried the subcommand before it would make the gate do work.
|
|
421
|
+
return argumentCandidates(arg, repoRoot, gate.product, false).length > 0
|
|
422
|
+
? { command: gate.command, argv: [...gate.args.slice(0, index + 1), ...spec.argv] }
|
|
423
|
+
: null;
|
|
424
|
+
}
|
|
425
|
+
return null;
|
|
426
|
+
}
|
package/dist/run.d.ts
CHANGED
|
@@ -2,6 +2,7 @@ import { type Finding } from './envelope.js';
|
|
|
2
2
|
import { type GateOutcome } from './gate-runner.js';
|
|
3
3
|
import type { SelectionMiss } from './intent-spec.js';
|
|
4
4
|
import type { GateRole, GateStage, Policy, Product } from './policy.js';
|
|
5
|
+
import type { PolicyKeyChange } from './policy-diff.js';
|
|
5
6
|
/**
|
|
6
7
|
* An enabled gate the stage filter held back.
|
|
7
8
|
*
|
|
@@ -113,6 +114,15 @@ export interface RunTrustBase {
|
|
|
113
114
|
ref: string;
|
|
114
115
|
/** Whether the head commit's own policy file differs from that one. */
|
|
115
116
|
policyChanged: boolean;
|
|
117
|
+
/**
|
|
118
|
+
* The keys that differ, when `policyChanged` is true: one entry per key,
|
|
119
|
+
* computed from the parsed base and head files before any CLI override.
|
|
120
|
+
* Empty or absent on a changed policy means no effective key differs (a
|
|
121
|
+
* default spelled out, or the YAML reordered), and the report falls back to
|
|
122
|
+
* the one-line POLICY_PROPOSAL_LINE. A head whose keys are not known is not
|
|
123
|
+
* an empty list: it is the single not-known entry.
|
|
124
|
+
*/
|
|
125
|
+
policyChanges?: PolicyKeyChange[];
|
|
116
126
|
/**
|
|
117
127
|
* Why this ref could not be used at all, or null when it was.
|
|
118
128
|
*
|
|
@@ -201,6 +211,35 @@ export interface RunResult {
|
|
|
201
211
|
bySeverity: Record<string, number>;
|
|
202
212
|
};
|
|
203
213
|
exitCode: number;
|
|
214
|
+
/**
|
|
215
|
+
* The preview under the proposed rules: the roles whose `enabled` or
|
|
216
|
+
* `stage` the pull request changes, run once more under those keys. It
|
|
217
|
+
* decides nothing: computed after every field above is fixed, and never
|
|
218
|
+
* read back by any of them. Absent, not empty, when the run was not asked
|
|
219
|
+
* for one.
|
|
220
|
+
*/
|
|
221
|
+
preview?: RunPreview;
|
|
222
|
+
}
|
|
223
|
+
/** The whole preview's hard deadline (spec 5.2, finding 2). */
|
|
224
|
+
export declare const PREVIEW_BUDGET_MS = 300000;
|
|
225
|
+
/** A preview role that did not run, and why: the run's --stage, enabled: false, or --gate. */
|
|
226
|
+
export interface PreviewSkipped {
|
|
227
|
+
role: GateRole;
|
|
228
|
+
product: Product;
|
|
229
|
+
reason: 'stage' | 'disabled' | 'excluded';
|
|
230
|
+
}
|
|
231
|
+
/** What the preview under the proposed rules did. */
|
|
232
|
+
export interface RunPreview {
|
|
233
|
+
gates: GateOutcome[];
|
|
234
|
+
/** Every preview finding, ordered as the primary run's are. */
|
|
235
|
+
findings: Finding[];
|
|
236
|
+
skipped: PreviewSkipped[];
|
|
237
|
+
/** The intent role, when enabled: the preview never prepares it (finding 9). */
|
|
238
|
+
deferred: GateRole[];
|
|
239
|
+
/** The gate reached with no budget left, and every gate after it. */
|
|
240
|
+
overBudget: GateRole[];
|
|
241
|
+
/** The preview threw: its message, cleaned and cut to 200 characters. */
|
|
242
|
+
threw: string | null;
|
|
204
243
|
}
|
|
205
244
|
export interface RunOptions {
|
|
206
245
|
repoRoot: string;
|
|
@@ -247,6 +286,17 @@ export interface RunOptions {
|
|
|
247
286
|
* IntentPrepareOptions.tempRoot.
|
|
248
287
|
*/
|
|
249
288
|
tempRoot?: string;
|
|
289
|
+
/**
|
|
290
|
+
* The preview under the proposed rules, run after the primary result is
|
|
291
|
+
* fixed. Its policy is built by the caller (`previewPolicy`, which takes
|
|
292
|
+
* only `enabled`, `stage` and `enforce` from the head). Absent means no
|
|
293
|
+
* preview, which is every run without --preview.
|
|
294
|
+
*/
|
|
295
|
+
preview?: {
|
|
296
|
+
policy: Policy;
|
|
297
|
+
};
|
|
298
|
+
/** A test hook: the preview's clock. No CLI path sets it; absent is Date.now. */
|
|
299
|
+
previewClock?: () => number;
|
|
250
300
|
}
|
|
251
301
|
/**
|
|
252
302
|
* The run that never happened, because the trust base could not be judged
|
|
@@ -276,4 +326,17 @@ export declare function refusedTrustBase(policy: Policy, ref: string, detail: st
|
|
|
276
326
|
now?: () => Date;
|
|
277
327
|
notGiven?: boolean;
|
|
278
328
|
}): RunResult;
|
|
329
|
+
/**
|
|
330
|
+
* Runs `work`, and turns any throw into `fallback(message)`, the message
|
|
331
|
+
* cleaned for a log line and cut to 200 characters. Never rethrows: nothing
|
|
332
|
+
* the preview does may reach the verdict, and a throw would (spec 5.2,
|
|
333
|
+
* finding 3).
|
|
334
|
+
*/
|
|
335
|
+
export declare function guardPreview<T>(work: () => T, fallback: (message: string) => T): T;
|
|
336
|
+
/**
|
|
337
|
+
* The preview under the proposed rules: each role of `policy` run once more,
|
|
338
|
+
* with the primary run's own options, trust base included, under one hard
|
|
339
|
+
* deadline. The intent role is deferred and never prepared.
|
|
340
|
+
*/
|
|
341
|
+
export declare function runPreview(policy: Policy, options: RunOptions): RunPreview;
|
|
279
342
|
export declare function runAll(policy: Policy, options: RunOptions): RunResult;
|
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/dist/trust-base.d.ts
CHANGED
|
@@ -336,3 +336,37 @@ export declare function refuseHeadControlledProgram(repoRoot: string, trustBase:
|
|
|
336
336
|
* for every repository pinning an older gate.
|
|
337
337
|
*/
|
|
338
338
|
export declare function atLeastVersion(version: string | null, minimum: string): boolean;
|
|
339
|
+
/**
|
|
340
|
+
* Why a path named in a gate's `args:` cannot be trusted on a pull-request
|
|
341
|
+
* run, or null (audit 2026-10-27, B1).
|
|
342
|
+
*
|
|
343
|
+
* An interpreter `command:` takes the program as an argument: with
|
|
344
|
+
* `command: /usr/bin/node` and `args: [tools/gate/run.mjs, scan]` the script
|
|
345
|
+
* judges and Node only runs it, so vetting `command:` alone let a pull request
|
|
346
|
+
* rewrite the script and choose its own judge. `argumentCandidates`
|
|
347
|
+
* (src/resolve.ts) lists every path an interpreter could load for an entry,
|
|
348
|
+
* the entry and each of its loadable siblings (`tools/gate.js` beside
|
|
349
|
+
* `tools/gate/`), and each one is asked here separately; this decides
|
|
350
|
+
* whether that one path is the base's.
|
|
351
|
+
*
|
|
352
|
+
* - A FILE, or a symlink of any kind, goes through refuseHeadControlledProgram
|
|
353
|
+
* unchanged: blob and containing directory identical at both refs, an
|
|
354
|
+
* in-tree link refused on its own entry, the root refused, anything outside
|
|
355
|
+
* the tree accepted. The same rule as a `command:`, because it is the same
|
|
356
|
+
* question.
|
|
357
|
+
* - A DIRECTORY inside the tree is accepted only when it is a tracked tree
|
|
358
|
+
* at both refs with the same tree object id: when no sibling file wins,
|
|
359
|
+
* an interpreter handed a directory (`node tools/gate`) runs what is
|
|
360
|
+
* inside it, so the whole subtree is the unit, as it is beside a program.
|
|
361
|
+
* A sibling file that would win is a separate candidate, vetted as a file.
|
|
362
|
+
* - THE REPOSITORY ROOT ITSELF is refused (`node .` runs the head's own
|
|
363
|
+
* package.json main). Approving it would mean comparing the whole tree,
|
|
364
|
+
* which differs on every pull request; conductor already hands every gate
|
|
365
|
+
* the repository it scans, so no gate needs the root in `args:`.
|
|
366
|
+
*
|
|
367
|
+
* NOTHING HERE READS THE WORKING TREE's CONTENTS, as for the program: both
|
|
368
|
+
* sides are `git ls-tree` listings. Only whether the entry is a directory is
|
|
369
|
+
* read from disk, and a link is never followed for that, so a link is always
|
|
370
|
+
* vetted as a link.
|
|
371
|
+
*/
|
|
372
|
+
export declare function refuseHeadControlledArgument(repoRoot: string, trustBase: string, argumentPath: string): string | null;
|
package/dist/trust-base.js
CHANGED
|
@@ -71,7 +71,7 @@
|
|
|
71
71
|
// RUN proceeds, so the caller can still learn the trees matched
|
|
72
72
|
// (`headTreeEqualsBase` below) and run only the gates whose input is
|
|
73
73
|
// history rather than the tree.
|
|
74
|
-
import { realpathSync } from 'node:fs';
|
|
74
|
+
import { lstatSync, realpathSync } from 'node:fs';
|
|
75
75
|
import path from 'node:path';
|
|
76
76
|
import { parse as parseYaml } from 'yaml';
|
|
77
77
|
import { gitComplaint, runGit, runGitBytes } from './git.js';
|
|
@@ -886,3 +886,85 @@ export function atLeastVersion(version, minimum) {
|
|
|
886
886
|
}
|
|
887
887
|
return true;
|
|
888
888
|
}
|
|
889
|
+
/**
|
|
890
|
+
* Why a path named in a gate's `args:` cannot be trusted on a pull-request
|
|
891
|
+
* run, or null (audit 2026-10-27, B1).
|
|
892
|
+
*
|
|
893
|
+
* An interpreter `command:` takes the program as an argument: with
|
|
894
|
+
* `command: /usr/bin/node` and `args: [tools/gate/run.mjs, scan]` the script
|
|
895
|
+
* judges and Node only runs it, so vetting `command:` alone let a pull request
|
|
896
|
+
* rewrite the script and choose its own judge. `argumentCandidates`
|
|
897
|
+
* (src/resolve.ts) lists every path an interpreter could load for an entry,
|
|
898
|
+
* the entry and each of its loadable siblings (`tools/gate.js` beside
|
|
899
|
+
* `tools/gate/`), and each one is asked here separately; this decides
|
|
900
|
+
* whether that one path is the base's.
|
|
901
|
+
*
|
|
902
|
+
* - A FILE, or a symlink of any kind, goes through refuseHeadControlledProgram
|
|
903
|
+
* unchanged: blob and containing directory identical at both refs, an
|
|
904
|
+
* in-tree link refused on its own entry, the root refused, anything outside
|
|
905
|
+
* the tree accepted. The same rule as a `command:`, because it is the same
|
|
906
|
+
* question.
|
|
907
|
+
* - A DIRECTORY inside the tree is accepted only when it is a tracked tree
|
|
908
|
+
* at both refs with the same tree object id: when no sibling file wins,
|
|
909
|
+
* an interpreter handed a directory (`node tools/gate`) runs what is
|
|
910
|
+
* inside it, so the whole subtree is the unit, as it is beside a program.
|
|
911
|
+
* A sibling file that would win is a separate candidate, vetted as a file.
|
|
912
|
+
* - THE REPOSITORY ROOT ITSELF is refused (`node .` runs the head's own
|
|
913
|
+
* package.json main). Approving it would mean comparing the whole tree,
|
|
914
|
+
* which differs on every pull request; conductor already hands every gate
|
|
915
|
+
* the repository it scans, so no gate needs the root in `args:`.
|
|
916
|
+
*
|
|
917
|
+
* NOTHING HERE READS THE WORKING TREE's CONTENTS, as for the program: both
|
|
918
|
+
* sides are `git ls-tree` listings. Only whether the entry is a directory is
|
|
919
|
+
* read from disk, and a link is never followed for that, so a link is always
|
|
920
|
+
* vetted as a link.
|
|
921
|
+
*/
|
|
922
|
+
export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath) {
|
|
923
|
+
const repoReal = realOrNull(repoRoot);
|
|
924
|
+
if (repoReal === null) {
|
|
925
|
+
return `the repository root ${repoRoot} could not be resolved, so the gate arguments could not be checked against "${trustBase}". Nothing was checked by this gate.`;
|
|
926
|
+
}
|
|
927
|
+
const spellings = [withResolvedParent(argumentPath), realOrNull(argumentPath)].filter((spelling) => spelling !== null);
|
|
928
|
+
if (spellings.some((spelling) => path.relative(repoReal, spelling) === '')) {
|
|
929
|
+
return (`the gate's args: name the repository root (${argumentPath}), so what would run is decided by ` +
|
|
930
|
+
`the whole working tree, and this pull request differs from "${trustBase}" somewhere in it. ` +
|
|
931
|
+
'conductor already hands each gate the repository it scans; name a script in its own ' +
|
|
932
|
+
'directory instead. Nothing was checked by this gate.');
|
|
933
|
+
}
|
|
934
|
+
let isDirectory;
|
|
935
|
+
try {
|
|
936
|
+
isDirectory = lstatSync(argumentPath).isDirectory();
|
|
937
|
+
}
|
|
938
|
+
catch {
|
|
939
|
+
// Gone between resolution and now: nothing for a child to run from here,
|
|
940
|
+
// and nothing for the program rule to approve either. Asking it anyway
|
|
941
|
+
// is the fail-closed direction, since an untracked or absent path refuses.
|
|
942
|
+
isDirectory = false;
|
|
943
|
+
}
|
|
944
|
+
if (!isDirectory) {
|
|
945
|
+
return refuseHeadControlledProgram(repoRoot, trustBase, argumentPath);
|
|
946
|
+
}
|
|
947
|
+
for (const spelling of new Set(spellings)) {
|
|
948
|
+
if (!insideWorkingTree(repoReal, spelling)) {
|
|
949
|
+
continue;
|
|
950
|
+
}
|
|
951
|
+
const relative = path.relative(repoReal, spelling).split(path.sep).join('/');
|
|
952
|
+
const baseEntry = treeEntryAt(repoRoot, trustBase, relative);
|
|
953
|
+
const headEntry = treeEntryAt(repoRoot, 'HEAD', relative);
|
|
954
|
+
for (const listed of [baseEntry, headEntry]) {
|
|
955
|
+
if (listed.kind === 'error') {
|
|
956
|
+
return (`the directory ${relative} named in the gate's args: could not be checked against ` +
|
|
957
|
+
`"${trustBase}": ${listed.detail}. Nothing was checked by this gate.`);
|
|
958
|
+
}
|
|
959
|
+
}
|
|
960
|
+
const base = baseEntry.kind === 'entry' ? baseEntry : null;
|
|
961
|
+
const head = headEntry.kind === 'entry' ? headEntry : null;
|
|
962
|
+
if (base === null || head === null || base.type !== 'tree' || head.type !== 'tree' || base.sha !== head.sha) {
|
|
963
|
+
return (`the directory ${relative} named in the gate's args: is not what "${trustBase}" approved: ` +
|
|
964
|
+
'this pull request adds, removes or changes something in it, and an interpreter handed a ' +
|
|
965
|
+
'directory runs what is inside. Land the change on the base branch first, or name a ' +
|
|
966
|
+
'script outside the repository. Nothing was checked by this gate.');
|
|
967
|
+
}
|
|
968
|
+
}
|
|
969
|
+
return null;
|
|
970
|
+
}
|
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
|