@vaultcompass/conductor 0.2.4 → 0.3.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 +147 -2
- package/dist/cli.js +91 -14
- package/dist/envelope.d.ts +16 -0
- package/dist/gate-runner.d.ts +118 -2
- package/dist/gate-runner.js +211 -9
- package/dist/intent-prepare.d.ts +16 -0
- package/dist/intent-prepare.js +18 -0
- package/dist/normalize.d.ts +14 -1
- package/dist/normalize.js +76 -0
- package/dist/output-sarif.d.ts +11 -0
- package/dist/output-sarif.js +230 -19
- package/dist/output-text.js +102 -1
- package/dist/policy.js +24 -3
- package/dist/resolve.d.ts +11 -0
- package/dist/resolve.js +4 -0
- package/dist/run.d.ts +92 -0
- package/dist/run.js +119 -5
- package/dist/trust-base.d.ts +142 -0
- package/dist/trust-base.js +414 -0
- package/package.json +1 -1
package/dist/gate-runner.js
CHANGED
|
@@ -19,7 +19,95 @@ import { spawnSync } from 'node:child_process';
|
|
|
19
19
|
import { NormalizeError } from './envelope.js';
|
|
20
20
|
import { normalizeDepGuard, normalizeFailedGate, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
|
|
21
21
|
import { renderOptionFlags } from './policy.js';
|
|
22
|
+
import { atLeastVersion, refuseHeadControlledProgram } from './trust-base.js';
|
|
22
23
|
import { ResolveError, candidateNames, resolveGateBinary } from './resolve.js';
|
|
24
|
+
/**
|
|
25
|
+
* The first version of each gate that understands `--trust-base`.
|
|
26
|
+
*
|
|
27
|
+
* A TABLE rather than a boolean, because the three gates get pull-request
|
|
28
|
+
* mode in three separate releases and the umbrella has to keep working
|
|
29
|
+
* against every combination in the meantime. A product missing from this
|
|
30
|
+
* table has no pull-request mode yet and is never handed the flag; a product
|
|
31
|
+
* in it is handed the flag only when the installed build says it is at least
|
|
32
|
+
* this version. Both directions matter: handing an older build a flag it does
|
|
33
|
+
* not parse makes it exit non-zero with no JSON, which the umbrella correctly
|
|
34
|
+
* reports as could-not-run, so a wrong guess here turns a working repository's
|
|
35
|
+
* pull requests red rather than merely leaving a gate un-hardened.
|
|
36
|
+
*
|
|
37
|
+
* The umbrella is deliberately NOT the place a version pin lives otherwise
|
|
38
|
+
* (nothing here imports any gate's package), and this is the one exception:
|
|
39
|
+
* it is a statement about a command-line flag, which is the only interface
|
|
40
|
+
* this package has to those tools.
|
|
41
|
+
*/
|
|
42
|
+
export const TRUST_BASE_MIN_VERSION = {
|
|
43
|
+
'intent-guard': '1.4.0',
|
|
44
|
+
'vault-guard': '1.7.0',
|
|
45
|
+
'dep-guard': '0.6.0',
|
|
46
|
+
// All three products are in. The table stays a table rather than becoming
|
|
47
|
+
// a boolean: a fourth role can arrive without one, and the "no
|
|
48
|
+
// pull-request mode yet" branch below is what keeps that gate from being
|
|
49
|
+
// handed a flag it would reject.
|
|
50
|
+
};
|
|
51
|
+
/**
|
|
52
|
+
* Whether this gate can be handed `--trust-base`, and why not when it cannot.
|
|
53
|
+
*
|
|
54
|
+
* Exported so the decision can be tested directly rather than only through a
|
|
55
|
+
* spawned child, and so there is exactly one copy of it.
|
|
56
|
+
*
|
|
57
|
+
* THE PROJECT DIRECTORY IS THE FIRST TEST, not the version. The flag names a
|
|
58
|
+
* git ref, and intent-guard resolves it against its own `--project`. On a
|
|
59
|
+
* run with an imported contract that directory is a temporary one the
|
|
60
|
+
* umbrella made, holding a contract and nothing else, with no repository in
|
|
61
|
+
* it: the child would exit 2 on a ref it could not resolve, and the gate that
|
|
62
|
+
* was working a moment ago would report could-not-run. So the flag goes only
|
|
63
|
+
* where `--project` is the repository itself.
|
|
64
|
+
*/
|
|
65
|
+
export function decideTrustBase(gate, intent, trustBase, productVersion) {
|
|
66
|
+
if (trustBase === undefined) {
|
|
67
|
+
return undefined;
|
|
68
|
+
}
|
|
69
|
+
const withheld = (reason) => ({
|
|
70
|
+
ref: trustBase,
|
|
71
|
+
withheld: reason,
|
|
72
|
+
refused: null,
|
|
73
|
+
proposals: [],
|
|
74
|
+
});
|
|
75
|
+
const refused = (reason) => ({
|
|
76
|
+
ref: trustBase,
|
|
77
|
+
withheld: null,
|
|
78
|
+
refused: reason,
|
|
79
|
+
proposals: [],
|
|
80
|
+
});
|
|
81
|
+
if (intent !== undefined && intent.contractSource.kind !== 'native') {
|
|
82
|
+
return withheld('the intent gate is running against a contract imported for this run, which lives in a ' +
|
|
83
|
+
'temporary directory with no repository in it, so there is no ref there to read control ' +
|
|
84
|
+
'inputs from. The contract it is judging against came from a spec in the head tree.');
|
|
85
|
+
}
|
|
86
|
+
const minimum = TRUST_BASE_MIN_VERSION[gate.product];
|
|
87
|
+
if (minimum === undefined) {
|
|
88
|
+
return withheld(`${gate.product} has no pull-request mode yet, so it read its own configuration from the ` +
|
|
89
|
+
'tree being judged.');
|
|
90
|
+
}
|
|
91
|
+
// An UNREADABLE version is refused, not withheld, and only for a product in
|
|
92
|
+
// the table. The old code folded the two together and interpolated the
|
|
93
|
+
// missing version straight into the sentence, which read "intent-guard
|
|
94
|
+
// reported no version does not understand --trust-base": not a sentence,
|
|
95
|
+
// and it named a version that does not exist. Worse than the wording, it
|
|
96
|
+
// said the gate had been left outside the boundary on purpose when what had
|
|
97
|
+
// actually happened is that the umbrella could not tell.
|
|
98
|
+
if (productVersion === null) {
|
|
99
|
+
return refused(`${gate.product} is expected to run in pull-request mode from ${minimum} onwards, and its ` +
|
|
100
|
+
'version could not be read, so the umbrella cannot establish that this gate would take ' +
|
|
101
|
+
'its rules from the base ref. Nothing was checked by it. Running it anyway would put it ' +
|
|
102
|
+
'quietly outside the trust boundary on exactly the runs where something is already wrong.');
|
|
103
|
+
}
|
|
104
|
+
if (!atLeastVersion(productVersion, minimum)) {
|
|
105
|
+
return withheld(`${gate.product} ${productVersion} does not understand --trust-base, which arrived in ` +
|
|
106
|
+
`${minimum}, so it read its own control inputs from the tree being judged. Upgrade it to ` +
|
|
107
|
+
'put this gate into pull-request mode.');
|
|
108
|
+
}
|
|
109
|
+
return { ref: trustBase, withheld: null, refused: null, proposals: [] };
|
|
110
|
+
}
|
|
23
111
|
/**
|
|
24
112
|
* A gate that never got as far as being spawned.
|
|
25
113
|
*
|
|
@@ -69,19 +157,41 @@ const EMPTY_RUN = {
|
|
|
69
157
|
* decided by that gate's own argument parser rather than by anything the
|
|
70
158
|
* user could read in their own policy file.
|
|
71
159
|
*/
|
|
72
|
-
export function gateArgs(gate, staged, intent
|
|
160
|
+
export function gateArgs(gate, staged, intent,
|
|
161
|
+
/**
|
|
162
|
+
* The trust base to hand THIS gate, or undefined. Already decided by
|
|
163
|
+
* `decideTrustBase`; nothing here re-decides it, so a gate that cannot take
|
|
164
|
+
* the flag is never handed one by a second opinion written in this switch.
|
|
165
|
+
*/
|
|
166
|
+
trustBase) {
|
|
73
167
|
const passthrough = renderOptionFlags(gate.options);
|
|
168
|
+
const trust = trustBase === undefined ? [] : ['--trust-base', trustBase];
|
|
74
169
|
switch (gate.product) {
|
|
75
170
|
case 'dep-guard':
|
|
76
|
-
|
|
171
|
+
// `scan` takes --trust-base from 0.6.0. It sits beside whatever the
|
|
172
|
+
// umbrella already passes rather than replacing it: --trust-base says
|
|
173
|
+
// where the RULES come from and the mode flags say what is scanned,
|
|
174
|
+
// and a pull-request run passes both.
|
|
175
|
+
return [...(staged ? ['--staged'] : []), '--format', 'json', ...trust, ...passthrough];
|
|
77
176
|
case 'vault-guard':
|
|
78
177
|
// No path argument: the CLI defaults it to "." and the umbrella runs
|
|
79
178
|
// with cwd at the repository root anyway. Passing one would also risk
|
|
80
179
|
// a passthrough value being read as the positional.
|
|
81
|
-
|
|
180
|
+
//
|
|
181
|
+
// `scan` takes --trust-base from 1.7.0, and on exit 2 it prints one
|
|
182
|
+
// line on stderr and NO document at all, which the could-not-run path
|
|
183
|
+
// above already handles before JSON.parse is reached.
|
|
184
|
+
return [...(staged ? ['--staged'] : []), '-f', 'json', ...trust, ...passthrough];
|
|
82
185
|
case 'intent-guard': {
|
|
83
186
|
if (intent === undefined) {
|
|
84
|
-
return [
|
|
187
|
+
return [
|
|
188
|
+
'--project',
|
|
189
|
+
'.',
|
|
190
|
+
...(staged ? ['--staged'] : []),
|
|
191
|
+
...trust,
|
|
192
|
+
'--json',
|
|
193
|
+
...passthrough,
|
|
194
|
+
];
|
|
85
195
|
}
|
|
86
196
|
// A prepared run replaces --staged entirely rather than adding to it.
|
|
87
197
|
// The two path sources are ADDITIVE in intent-guard, so leaving
|
|
@@ -99,6 +209,10 @@ export function gateArgs(gate, staged, intent) {
|
|
|
99
209
|
? ['--staged']
|
|
100
210
|
: []
|
|
101
211
|
: ['--paths', intent.paths.join(',')]),
|
|
212
|
+
// Beside --paths on purpose, and they are independent: --trust-base
|
|
213
|
+
// says where the RULES come from, --paths says which paths are
|
|
214
|
+
// judged. A pull-request run passes both.
|
|
215
|
+
...trust,
|
|
102
216
|
'--json',
|
|
103
217
|
...passthrough,
|
|
104
218
|
];
|
|
@@ -178,14 +292,25 @@ export function runGate(gate, options) {
|
|
|
178
292
|
// Carried on every return path below, including the failures: which
|
|
179
293
|
// contract a gate WOULD have used is exactly as interesting when it could
|
|
180
294
|
// not run as when it could.
|
|
181
|
-
...(options.intent
|
|
182
|
-
? {
|
|
183
|
-
: {
|
|
295
|
+
...(options.intent !== undefined
|
|
296
|
+
? {
|
|
184
297
|
intent: {
|
|
185
298
|
contractSource: options.intent.contractSource,
|
|
186
299
|
baseRef: options.intent.baseRef,
|
|
187
300
|
},
|
|
188
|
-
}
|
|
301
|
+
}
|
|
302
|
+
: options.intentContract === undefined
|
|
303
|
+
? {}
|
|
304
|
+
: {
|
|
305
|
+
// No preparation, but the repository has a frozen contract and
|
|
306
|
+
// the child will read it from `--project .`. Same shape, and the
|
|
307
|
+
// base is null because nothing was diffed: this run is the index
|
|
308
|
+
// or the working tree, not a branch against a ref.
|
|
309
|
+
intent: {
|
|
310
|
+
contractSource: { kind: 'native', path: options.intentContract },
|
|
311
|
+
baseRef: null,
|
|
312
|
+
},
|
|
313
|
+
}),
|
|
189
314
|
};
|
|
190
315
|
const started = Date.now();
|
|
191
316
|
try {
|
|
@@ -257,8 +382,71 @@ function runGateInner(gate, options, started, progress) {
|
|
|
257
382
|
diagnostics: [],
|
|
258
383
|
};
|
|
259
384
|
}
|
|
385
|
+
// BEFORE the version probe, and that ordering is the whole of it: the probe
|
|
386
|
+
// RUNS the program, so asking a head-controlled binary for its version is
|
|
387
|
+
// already executing it. A planted stub answering "1.7.0" is the cheapest
|
|
388
|
+
// version of this attack and it would have been run before anything checked
|
|
389
|
+
// where it came from.
|
|
390
|
+
if (options.trustBase !== undefined) {
|
|
391
|
+
const refusal = refuseHeadControlledProgram(options.repoRoot, options.trustBase, binary.program);
|
|
392
|
+
if (refusal !== null) {
|
|
393
|
+
return {
|
|
394
|
+
...base,
|
|
395
|
+
binary,
|
|
396
|
+
durationMs: Date.now() - started,
|
|
397
|
+
// ENFORCED, whatever the policy says. enforce: false is a standing
|
|
398
|
+
// decision about what a gate's FINDINGS are worth, and this gate
|
|
399
|
+
// produced none: the umbrella refused to run a program the pull
|
|
400
|
+
// request chose. Letting an unenforced gate swallow that would let a
|
|
401
|
+
// pull request pick its own judge and keep the run green.
|
|
402
|
+
enforce: true,
|
|
403
|
+
trustBase: { ref: options.trustBase, withheld: null, refused: refusal, proposals: [] },
|
|
404
|
+
couldNotRun: { reason: 'gate-program-refused', detail: refusal },
|
|
405
|
+
findings: [normalizeFailedGate(gate.role, gate.product, refusal)],
|
|
406
|
+
run: EMPTY_RUN,
|
|
407
|
+
diagnostics: [],
|
|
408
|
+
};
|
|
409
|
+
}
|
|
410
|
+
}
|
|
260
411
|
const version = probeVersion(binary, options.repoRoot, timeoutMs);
|
|
261
|
-
|
|
412
|
+
// AFTER the version probe and BEFORE the command line is built, because the
|
|
413
|
+
// decision reads the version. That ordering is the whole capability gate:
|
|
414
|
+
// an intent-guard older than 1.4.0 must not be handed a flag it would
|
|
415
|
+
// reject, and a gate IN the table whose version could not be read is
|
|
416
|
+
// refused rather than run outside the boundary.
|
|
417
|
+
const trustBase = decideTrustBase(gate, options.intent, options.trustBase, version);
|
|
418
|
+
if (trustBase !== undefined && trustBase.refused !== null) {
|
|
419
|
+
return {
|
|
420
|
+
...base,
|
|
421
|
+
productVersion: version,
|
|
422
|
+
binary,
|
|
423
|
+
durationMs: Date.now() - started,
|
|
424
|
+
// ENFORCED, whatever the policy says, for the same reason a refused
|
|
425
|
+
// program is: the gate produced no findings for `enforce: false` to be
|
|
426
|
+
// a decision about, and this is the umbrella saying it could not
|
|
427
|
+
// establish that the gate was inside the boundary.
|
|
428
|
+
//
|
|
429
|
+
// Reachable now only as a PACKAGING problem, not as an attack: the
|
|
430
|
+
// program check above runs first, and with its directory-subtree rule a
|
|
431
|
+
// pull request can no longer put a program here whose version probe it
|
|
432
|
+
// controls. Before that rule it could, through the wrapper shape: a
|
|
433
|
+
// head-replaced inner script exiting 3 on --version landed exactly
|
|
434
|
+
// here, with enforce false and exit 0. A packaging quirk that
|
|
435
|
+
// fails a build loudly is the better failure: the alternative is a
|
|
436
|
+
// boundary that quietly downgrades itself on the runs where something
|
|
437
|
+
// is already wrong, which is the shape of every bug in this file.
|
|
438
|
+
enforce: true,
|
|
439
|
+
trustBase,
|
|
440
|
+
couldNotRun: { reason: 'trust-base-unverified', detail: trustBase.refused },
|
|
441
|
+
findings: [normalizeFailedGate(gate.role, gate.product, trustBase.refused)],
|
|
442
|
+
run: EMPTY_RUN,
|
|
443
|
+
diagnostics: [],
|
|
444
|
+
};
|
|
445
|
+
}
|
|
446
|
+
const argv = [
|
|
447
|
+
...binary.argvPrefix,
|
|
448
|
+
...gateArgs(gate, options.staged, options.intent, trustBase === undefined || trustBase.withheld !== null ? undefined : trustBase.ref),
|
|
449
|
+
];
|
|
262
450
|
const child = spawnSync(binary.command, argv, {
|
|
263
451
|
cwd: options.repoRoot,
|
|
264
452
|
encoding: 'utf8',
|
|
@@ -272,6 +460,12 @@ function runGateInner(gate, options, started, progress) {
|
|
|
272
460
|
binary,
|
|
273
461
|
durationMs: Date.now() - started,
|
|
274
462
|
stderr: child.stderr ?? '',
|
|
463
|
+
// Carried on every return path below, the failures included: WHETHER
|
|
464
|
+
// this gate was in pull-request mode is exactly as interesting when it
|
|
465
|
+
// could not run as when it could, and the withheld reason is the only
|
|
466
|
+
// place a report can say a gate read its own rules out of the tree under
|
|
467
|
+
// judgment.
|
|
468
|
+
...(trustBase === undefined ? {} : { trustBase }),
|
|
275
469
|
};
|
|
276
470
|
// Keep the backstop's view current, so an unexpected throw below still
|
|
277
471
|
// reports which binary ran and what it printed.
|
|
@@ -339,6 +533,14 @@ function runGateInner(gate, options, started, progress) {
|
|
|
339
533
|
findings: normalized.findings,
|
|
340
534
|
run: normalized.run,
|
|
341
535
|
diagnostics: normalized.diagnostics,
|
|
536
|
+
// The gate's own answer about the control inputs, folded onto the
|
|
537
|
+
// decision the umbrella made before spawning it. A gate that was NOT
|
|
538
|
+
// put into pull-request mode reports no proposals, and its trustBase
|
|
539
|
+
// keeps the withheld reason rather than being overwritten with an
|
|
540
|
+
// empty list that would read as "nothing was proposed".
|
|
541
|
+
...(trustBase === undefined || normalized.trustBase === undefined
|
|
542
|
+
? {}
|
|
543
|
+
: { trustBase: { ...trustBase, proposals: normalized.trustBase.proposals } }),
|
|
342
544
|
};
|
|
343
545
|
}
|
|
344
546
|
catch (err) {
|
package/dist/intent-prepare.d.ts
CHANGED
|
@@ -118,4 +118,20 @@ export interface IntentPrepareOptions {
|
|
|
118
118
|
*/
|
|
119
119
|
tempRoot?: string;
|
|
120
120
|
}
|
|
121
|
+
/**
|
|
122
|
+
* The repository's own frozen contract, or null, for a run with no
|
|
123
|
+
* preparation at all.
|
|
124
|
+
*
|
|
125
|
+
* The whole of `prepareIntent` only runs on a pull-request shaped run. A
|
|
126
|
+
* plain `conductor run` against a repository that HAS a frozen contract still
|
|
127
|
+
* judges against that contract -- the child resolves it from `--project .` --
|
|
128
|
+
* but the umbrella recorded nothing about it, so both reports had to say
|
|
129
|
+
* nothing and the SARIF fallback filed the gate's own results against the
|
|
130
|
+
* policy file rather than against the contract they are actually about.
|
|
131
|
+
*
|
|
132
|
+
* Exported for that one caller. It is deliberately the same predicate the
|
|
133
|
+
* preparation uses, FROZEN rather than present, so the two cannot disagree
|
|
134
|
+
* about which file the gate will read.
|
|
135
|
+
*/
|
|
136
|
+
export declare function frozenNativeContractPath(repoRoot: string): string | null;
|
|
121
137
|
export declare function prepareIntent(options: IntentPrepareOptions): IntentPrepareResult;
|
package/dist/intent-prepare.js
CHANGED
|
@@ -133,6 +133,24 @@ function contractIsFrozenAt(absolutePath) {
|
|
|
133
133
|
function frozenNativeContracts(repoRoot) {
|
|
134
134
|
return NATIVE_CONTRACT_PATHS.filter((relative) => contractIsFrozenAt(path.join(repoRoot, relative)));
|
|
135
135
|
}
|
|
136
|
+
/**
|
|
137
|
+
* The repository's own frozen contract, or null, for a run with no
|
|
138
|
+
* preparation at all.
|
|
139
|
+
*
|
|
140
|
+
* The whole of `prepareIntent` only runs on a pull-request shaped run. A
|
|
141
|
+
* plain `conductor run` against a repository that HAS a frozen contract still
|
|
142
|
+
* judges against that contract -- the child resolves it from `--project .` --
|
|
143
|
+
* but the umbrella recorded nothing about it, so both reports had to say
|
|
144
|
+
* nothing and the SARIF fallback filed the gate's own results against the
|
|
145
|
+
* policy file rather than against the contract they are actually about.
|
|
146
|
+
*
|
|
147
|
+
* Exported for that one caller. It is deliberately the same predicate the
|
|
148
|
+
* preparation uses, FROZEN rather than present, so the two cannot disagree
|
|
149
|
+
* about which file the gate will read.
|
|
150
|
+
*/
|
|
151
|
+
export function frozenNativeContractPath(repoRoot) {
|
|
152
|
+
return frozenNativeContracts(repoRoot)[0] ?? null;
|
|
153
|
+
}
|
|
136
154
|
/**
|
|
137
155
|
* The files only intent-guard writes into its state directory.
|
|
138
156
|
*
|
package/dist/normalize.d.ts
CHANGED
|
@@ -17,8 +17,21 @@ export declare function normalizeVaultGuard(raw: unknown, version: string | null
|
|
|
17
17
|
* interpolates an error message, and they are enumerated in a test against
|
|
18
18
|
* the real strings, so an upstream rewording turns that test red instead of
|
|
19
19
|
* silently dropping a reason out of every report.
|
|
20
|
+
*
|
|
21
|
+
* THE NO-CONTRACT SENTENCE INTERPOLATES THE STATE DIRECTORY NAME, so it has
|
|
22
|
+
* two spellings and needs two entries. The gate builds it as
|
|
23
|
+
* `No ${STATE_DIR}/intent-contract.yaml found.`, and 1.3.0 renamed STATE_DIR
|
|
24
|
+
* from `.conductor` to `.intent-guard`. Matching only the old name left this
|
|
25
|
+
* classifier DEAD against every gate anybody can install today: the reason
|
|
26
|
+
* fell through to the unattributed backstop, so the finding said
|
|
27
|
+
* `kind: unattributed` where a consumer filters on `contract-missing`, and a
|
|
28
|
+
* run that also had a budget violation dropped the no-contract reason out of
|
|
29
|
+
* the report entirely, since the backstop only fires when nothing else
|
|
30
|
+
* blocked. Both names stay, because the umbrella reads both state
|
|
31
|
+
* directories elsewhere and a repository on either version has to be
|
|
32
|
+
* classified the same way.
|
|
20
33
|
*/
|
|
21
|
-
export declare const GATE_STATE_REASON_KINDS: readonly ["contract-invalid", "contract-missing", "contract-unfrozen"];
|
|
34
|
+
export declare const GATE_STATE_REASON_KINDS: readonly ["contract-invalid", "contract-missing", "contract-unfrozen", "self-approval-refused", "control-input-refused"];
|
|
22
35
|
export type GateStateReasonKind = (typeof GATE_STATE_REASON_KINDS)[number];
|
|
23
36
|
/** Which gate-state reason this is, or null when it is a budget or drift reason. */
|
|
24
37
|
export declare function classifyGateStateReason(reason: string): GateStateReasonKind | null;
|
package/dist/normalize.js
CHANGED
|
@@ -117,6 +117,7 @@ export function normalizeDepGuard(raw, version) {
|
|
|
117
117
|
const root = needRecord(raw, product, 'the output');
|
|
118
118
|
const run = needRecord(root.run, product, 'run');
|
|
119
119
|
const threshold = optionalString(run.failOn, product, 'run.failOn') ?? null;
|
|
120
|
+
const trustBase = readTrustBase(root.trustBase, product);
|
|
120
121
|
const diagnostics = [];
|
|
121
122
|
const findings = needArray(root.findings, product, 'findings').map((entry, index) => {
|
|
122
123
|
const where = `findings[${index}]`;
|
|
@@ -154,6 +155,11 @@ export function normalizeDepGuard(raw, version) {
|
|
|
154
155
|
reconcileBlocking(findings, typeof run.blockingMatches === 'number' ? run.blockingMatches : undefined, threshold, product, diagnostics);
|
|
155
156
|
return {
|
|
156
157
|
findings,
|
|
158
|
+
// Third gate, same key, same two fields read. dep-guard carries three
|
|
159
|
+
// changed flags and three shape changes, one pair about .npmrc, which
|
|
160
|
+
// the other two have no equivalent of; none of it is read here. The
|
|
161
|
+
// sentences are that gate's claims about its own control files.
|
|
162
|
+
...(trustBase === undefined ? {} : { trustBase }),
|
|
157
163
|
run: {
|
|
158
164
|
failOn: threshold,
|
|
159
165
|
suppressed: typeof root.suppressed === 'number' ? root.suppressed : 0,
|
|
@@ -180,6 +186,7 @@ export function normalizeVaultGuard(raw, version) {
|
|
|
180
186
|
// because the latter ignores the threshold. A sibling tool in this family
|
|
181
187
|
// read summary.secrets and that is the bug not to copy.
|
|
182
188
|
const threshold = optionalString(run.fail_on, product, 'run.fail_on') ?? null;
|
|
189
|
+
const trustBase = readTrustBase(root.trustBase, product);
|
|
183
190
|
const diagnostics = [];
|
|
184
191
|
const findings = [];
|
|
185
192
|
const results = needArray(root.results, product, 'results');
|
|
@@ -265,6 +272,14 @@ export function normalizeVaultGuard(raw, version) {
|
|
|
265
272
|
reconcileBlocking(findings, typeof run.blocking_matches === 'number' ? run.blocking_matches : undefined, threshold, product, diagnostics);
|
|
266
273
|
return {
|
|
267
274
|
findings,
|
|
275
|
+
// vault-guard 1.7.0 puts its pull-request summary at the TOP LEVEL, the
|
|
276
|
+
// same place intent-guard puts its own, and carries more fields than the
|
|
277
|
+
// umbrella reads (configChanged, baselineChanged, and a shape change for
|
|
278
|
+
// each). Only `ref` and `proposals` are read, which is the passthrough
|
|
279
|
+
// rule applied to a second gate: the sentences are that gate's claims
|
|
280
|
+
// about its own control files, and this package has no standing to
|
|
281
|
+
// rewrite them or to act on the structured half.
|
|
282
|
+
...(trustBase === undefined ? {} : { trustBase }),
|
|
268
283
|
run: {
|
|
269
284
|
failOn: threshold,
|
|
270
285
|
suppressed: typeof run.baseline_suppressed === 'number' ? run.baseline_suppressed : 0,
|
|
@@ -329,16 +344,49 @@ const DRIFT_SEVERITY = {
|
|
|
329
344
|
* interpolates an error message, and they are enumerated in a test against
|
|
330
345
|
* the real strings, so an upstream rewording turns that test red instead of
|
|
331
346
|
* silently dropping a reason out of every report.
|
|
347
|
+
*
|
|
348
|
+
* THE NO-CONTRACT SENTENCE INTERPOLATES THE STATE DIRECTORY NAME, so it has
|
|
349
|
+
* two spellings and needs two entries. The gate builds it as
|
|
350
|
+
* `No ${STATE_DIR}/intent-contract.yaml found.`, and 1.3.0 renamed STATE_DIR
|
|
351
|
+
* from `.conductor` to `.intent-guard`. Matching only the old name left this
|
|
352
|
+
* classifier DEAD against every gate anybody can install today: the reason
|
|
353
|
+
* fell through to the unattributed backstop, so the finding said
|
|
354
|
+
* `kind: unattributed` where a consumer filters on `contract-missing`, and a
|
|
355
|
+
* run that also had a budget violation dropped the no-contract reason out of
|
|
356
|
+
* the report entirely, since the backstop only fires when nothing else
|
|
357
|
+
* blocked. Both names stay, because the umbrella reads both state
|
|
358
|
+
* directories elsewhere and a repository on either version has to be
|
|
359
|
+
* classified the same way.
|
|
332
360
|
*/
|
|
333
361
|
export const GATE_STATE_REASON_KINDS = [
|
|
334
362
|
'contract-invalid',
|
|
335
363
|
'contract-missing',
|
|
336
364
|
'contract-unfrozen',
|
|
365
|
+
/**
|
|
366
|
+
* The two pull-request-mode refusals, from intent-guard 1.4.0.
|
|
367
|
+
*
|
|
368
|
+
* They are here rather than left to the backstop for the reason the whole
|
|
369
|
+
* list exists. The backstop fires only when NOTHING ELSE BLOCKED, so a pull
|
|
370
|
+
* request that forged a contract approval AND breached a change budget
|
|
371
|
+
* reported only the budget breach: the run still failed, but the report
|
|
372
|
+
* never said the approval was self-granted, which is the single most
|
|
373
|
+
* important sentence pull-request mode produces. Found by running the real
|
|
374
|
+
* gate against a crafted pull request rather than by reading the code.
|
|
375
|
+
*/
|
|
376
|
+
'self-approval-refused',
|
|
377
|
+
'control-input-refused',
|
|
337
378
|
];
|
|
338
379
|
const GATE_STATE_REASON_PREFIXES = [
|
|
339
380
|
['Intent contract is invalid:', 'contract-invalid'],
|
|
381
|
+
['No .intent-guard/intent-contract.yaml found', 'contract-missing'],
|
|
340
382
|
['No .conductor/intent-contract.yaml found', 'contract-missing'],
|
|
341
383
|
['Intent contract exists but is not frozen', 'contract-unfrozen'],
|
|
384
|
+
// Copied from intent-guard's own trust-base.ts, where both are exported
|
|
385
|
+
// constants for exactly this: SELF_APPROVAL_REASON_PREFIX and
|
|
386
|
+
// CONTROL_INPUT_REASON_PREFIX. Prefixes, because each interpolates the ref
|
|
387
|
+
// and the path.
|
|
388
|
+
['Self-approval refused:', 'self-approval-refused'],
|
|
389
|
+
['Control input refused:', 'control-input-refused'],
|
|
342
390
|
];
|
|
343
391
|
/** Which gate-state reason this is, or null when it is a budget or drift reason. */
|
|
344
392
|
export function classifyGateStateReason(reason) {
|
|
@@ -349,12 +397,39 @@ export function classifyGateStateReason(reason) {
|
|
|
349
397
|
}
|
|
350
398
|
return null;
|
|
351
399
|
}
|
|
400
|
+
/**
|
|
401
|
+
* The pull-request-mode summary intent-guard 1.4.0 puts on its check output,
|
|
402
|
+
* or undefined when the run was not in pull-request mode.
|
|
403
|
+
*
|
|
404
|
+
* ABSENCE IS THE SIGNAL, and it is the gate's own: the field is present only
|
|
405
|
+
* on a run that was given `--trust-base`, so an ordinary run has nothing here
|
|
406
|
+
* and no report has to guess. Validated element by element like everything
|
|
407
|
+
* else, because a malformed proposal reaching String() would put
|
|
408
|
+
* "[object Object]" on the one line a reviewer reads.
|
|
409
|
+
*
|
|
410
|
+
* The proposal SENTENCES are the gate's, carried verbatim and never
|
|
411
|
+
* rewritten. Every one of them is a claim about that gate's own control
|
|
412
|
+
* files, which the umbrella does not read and has no standing to describe.
|
|
413
|
+
*/
|
|
414
|
+
function readTrustBase(raw, product) {
|
|
415
|
+
if (raw === undefined || raw === null) {
|
|
416
|
+
return undefined;
|
|
417
|
+
}
|
|
418
|
+
const record = needRecord(raw, product, 'trustBase');
|
|
419
|
+
return {
|
|
420
|
+
ref: needString(record.ref, product, 'trustBase.ref'),
|
|
421
|
+
proposals: record.proposals === undefined
|
|
422
|
+
? []
|
|
423
|
+
: needStringArray(record.proposals, product, 'trustBase.proposals'),
|
|
424
|
+
};
|
|
425
|
+
}
|
|
352
426
|
export function normalizeIntentGuard(raw, version) {
|
|
353
427
|
const product = 'intent-guard';
|
|
354
428
|
const root = needRecord(raw, product, 'the output');
|
|
355
429
|
if (root.status !== 'blocked' && root.status !== 'ok') {
|
|
356
430
|
fail(product, 'status', 'either "ok" or "blocked"');
|
|
357
431
|
}
|
|
432
|
+
const trustBase = readTrustBase(root.trustBase, product);
|
|
358
433
|
const findings = [];
|
|
359
434
|
const budget = root.budget === undefined ? undefined : needRecord(root.budget, product, 'budget');
|
|
360
435
|
const drift = root.drift === undefined ? undefined : needRecord(root.drift, product, 'drift');
|
|
@@ -492,6 +567,7 @@ export function normalizeIntentGuard(raw, version) {
|
|
|
492
567
|
}
|
|
493
568
|
return {
|
|
494
569
|
findings,
|
|
570
|
+
...(trustBase === undefined ? {} : { trustBase }),
|
|
495
571
|
run: {
|
|
496
572
|
// intent-guard has no threshold flag and no reported threshold: its
|
|
497
573
|
// drift thresholds live in its own config file and its budget rules
|
package/dist/output-sarif.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { GateOutcome } from './gate-runner.js';
|
|
1
2
|
import type { RunResult } from './run.js';
|
|
2
3
|
export declare const UMBRELLA_DRIVER_NAME = "conductor";
|
|
3
4
|
/** The partialFingerprints key for a product's own fingerprint. */
|
|
@@ -24,6 +25,16 @@ export type ArtifactPlacement =
|
|
|
24
25
|
* through a whole rendered log.
|
|
25
26
|
*/
|
|
26
27
|
export declare function placeArtifact(rawPath: string): ArtifactPlacement;
|
|
28
|
+
/**
|
|
29
|
+
* The file a result with no location of its own is filed against.
|
|
30
|
+
*
|
|
31
|
+
* A real, repository-relative path, never a placeholder: the policy file is
|
|
32
|
+
* where every gate is enabled and where a reader goes to change what ran, and
|
|
33
|
+
* for the intent gate the frozen contract is the file its gate-state findings
|
|
34
|
+
* are literally about. Both exist in the repository whenever a run happened at
|
|
35
|
+
* all, so this never points at nothing.
|
|
36
|
+
*/
|
|
37
|
+
export declare function fallbackLocationFor(gate: GateOutcome | null): string;
|
|
27
38
|
/**
|
|
28
39
|
* Renders a whole run as one SARIF log.
|
|
29
40
|
*
|