@vaultcompass/conductor 0.2.4 → 0.4.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 +239 -15
- package/dist/cli.js +91 -14
- package/dist/envelope.d.ts +16 -0
- package/dist/gate-runner.d.ts +160 -2
- package/dist/gate-runner.js +311 -14
- package/dist/intent-prepare.d.ts +16 -0
- package/dist/intent-prepare.js +18 -0
- package/dist/normalize.d.ts +26 -2
- package/dist/normalize.js +89 -2
- package/dist/output-sarif.d.ts +11 -0
- package/dist/output-sarif.js +266 -19
- package/dist/output-text.js +126 -1
- package/dist/policy.js +24 -3
- package/dist/resolve.d.ts +39 -1
- package/dist/resolve.js +63 -12
- package/dist/run.d.ts +92 -0
- package/dist/run.js +155 -9
- package/dist/trust-base.d.ts +142 -0
- package/dist/trust-base.js +414 -0
- package/package.json +1 -1
package/dist/gate-runner.d.ts
CHANGED
|
@@ -8,11 +8,100 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
|
|
|
8
8
|
* an unresolvable base ref, or a spec that would not import. Distinct from
|
|
9
9
|
* gate-error on purpose, since the gate itself said nothing at all.
|
|
10
10
|
*/
|
|
11
|
-
| 'preparation-failed'
|
|
11
|
+
| 'preparation-failed'
|
|
12
|
+
/**
|
|
13
|
+
* On a pull-request run, the umbrella could not establish that this gate
|
|
14
|
+
* would take its rules from the base ref, so it was not spawned. Raised for
|
|
15
|
+
* a gate in `TRUST_BASE_MIN_VERSION` whose version could not be read.
|
|
16
|
+
* Distinct from `preparation-failed`, which is about the run rather than
|
|
17
|
+
* about this gate, and from `binary-missing`, since the binary was found.
|
|
18
|
+
*/
|
|
19
|
+
| 'trust-base-unverified'
|
|
20
|
+
/**
|
|
21
|
+
* On a pull-request run, the gate's PROGRAM is a file the head controls, so
|
|
22
|
+
* it was not run. Its own reason rather than a shape of
|
|
23
|
+
* `trust-base-unverified`, because the two send a reader to different
|
|
24
|
+
* places: one is a packaging problem with the installed gate, and this one
|
|
25
|
+
* is a pull request choosing the program that judges it.
|
|
26
|
+
*/
|
|
27
|
+
| 'gate-program-refused';
|
|
12
28
|
export interface CouldNotRun {
|
|
13
29
|
reason: CouldNotRunReason;
|
|
14
30
|
detail: string;
|
|
15
31
|
}
|
|
32
|
+
/**
|
|
33
|
+
* The first version of each gate that understands `--trust-base`.
|
|
34
|
+
*
|
|
35
|
+
* A TABLE rather than a boolean, because the three gates get pull-request
|
|
36
|
+
* mode in three separate releases and the umbrella has to keep working
|
|
37
|
+
* against every combination in the meantime. A product missing from this
|
|
38
|
+
* table has no pull-request mode yet and is never handed the flag; a product
|
|
39
|
+
* in it is handed the flag only when the installed build says it is at least
|
|
40
|
+
* this version. Both directions matter: handing an older build a flag it does
|
|
41
|
+
* not parse makes it exit non-zero with no JSON, which the umbrella correctly
|
|
42
|
+
* reports as could-not-run, so a wrong guess here turns a working repository's
|
|
43
|
+
* pull requests red rather than merely leaving a gate un-hardened.
|
|
44
|
+
*
|
|
45
|
+
* The umbrella is deliberately NOT the place a version pin lives otherwise
|
|
46
|
+
* (nothing here imports any gate's package), and this is the one exception:
|
|
47
|
+
* it is a statement about a command-line flag, which is the only interface
|
|
48
|
+
* this package has to those tools.
|
|
49
|
+
*/
|
|
50
|
+
export declare const TRUST_BASE_MIN_VERSION: Partial<Record<Product, string>>;
|
|
51
|
+
/**
|
|
52
|
+
* Pull-request mode as it applied to ONE gate.
|
|
53
|
+
*
|
|
54
|
+
* Carried on the outcome rather than worked out again by each reporter,
|
|
55
|
+
* because two different things have to be visible and neither is derivable
|
|
56
|
+
* from the other: whether this gate was actually put into pull-request mode,
|
|
57
|
+
* and what it said about the control inputs the head proposes to change.
|
|
58
|
+
*
|
|
59
|
+
* `withheld` is the half that must never be silent. A gate the umbrella could
|
|
60
|
+
* not put into pull-request mode read its own control inputs out of the tree
|
|
61
|
+
* under judgment, which is the whole hole this release exists to close, and a
|
|
62
|
+
* run where that happened must not look like a run where it did not.
|
|
63
|
+
*/
|
|
64
|
+
export interface GateTrustBase {
|
|
65
|
+
/** The ref the umbrella took its own policy from, and offered to this gate. */
|
|
66
|
+
ref: string;
|
|
67
|
+
/**
|
|
68
|
+
* Null when the flag was passed; otherwise the reason it was not, for a
|
|
69
|
+
* gate that was never going to be inside the boundary in the first place.
|
|
70
|
+
* The run continues: that gate read its own control inputs from the tree
|
|
71
|
+
* being judged, and the report says so.
|
|
72
|
+
*/
|
|
73
|
+
withheld: string | null;
|
|
74
|
+
/**
|
|
75
|
+
* Set when the umbrella could not ESTABLISH that this gate would be in
|
|
76
|
+
* pull-request mode, which is could-not-run rather than a downgrade.
|
|
77
|
+
*
|
|
78
|
+
* The distinction is the whole point and it is not symmetry with
|
|
79
|
+
* `withheld`. A gate outside the table was never going to get the flag, so
|
|
80
|
+
* nothing is unknown about it. A gate INSIDE the table is one this
|
|
81
|
+
* repository expects to be inside the boundary, and a version probe that
|
|
82
|
+
* fails leaves that unestablished for an unexplained reason. Falling back
|
|
83
|
+
* to running it anyway would put it quietly outside the boundary on the
|
|
84
|
+
* exact runs where something is already wrong.
|
|
85
|
+
*/
|
|
86
|
+
refused: string | null;
|
|
87
|
+
/** The control-input changes this gate reported as proposed. */
|
|
88
|
+
proposals: string[];
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* Whether this gate can be handed `--trust-base`, and why not when it cannot.
|
|
92
|
+
*
|
|
93
|
+
* Exported so the decision can be tested directly rather than only through a
|
|
94
|
+
* spawned child, and so there is exactly one copy of it.
|
|
95
|
+
*
|
|
96
|
+
* THE PROJECT DIRECTORY IS THE FIRST TEST, not the version. The flag names a
|
|
97
|
+
* git ref, and intent-guard resolves it against its own `--project`. On a
|
|
98
|
+
* run with an imported contract that directory is a temporary one the
|
|
99
|
+
* umbrella made, holding a contract and nothing else, with no repository in
|
|
100
|
+
* it: the child would exit 2 on a ref it could not resolve, and the gate that
|
|
101
|
+
* was working a moment ago would report could-not-run. So the flag goes only
|
|
102
|
+
* where `--project` is the repository itself.
|
|
103
|
+
*/
|
|
104
|
+
export declare function decideTrustBase(gate: GatePolicy, intent: IntentPreparation | undefined, trustBase: string | undefined, productVersion: string | null): GateTrustBase | undefined;
|
|
16
105
|
export interface GateOutcome {
|
|
17
106
|
role: GateRole;
|
|
18
107
|
product: Product;
|
|
@@ -47,6 +136,22 @@ export interface GateOutcome {
|
|
|
47
136
|
contractSource: ContractSource;
|
|
48
137
|
baseRef: string | null;
|
|
49
138
|
};
|
|
139
|
+
/**
|
|
140
|
+
* Present only on a pull-request run. Whether this gate was put into
|
|
141
|
+
* pull-request mode, and what it said was proposed.
|
|
142
|
+
*/
|
|
143
|
+
trustBase?: GateTrustBase;
|
|
144
|
+
/**
|
|
145
|
+
* The `node_modules/.bin` candidate resolution did NOT try, repository
|
|
146
|
+
* relative, on a pull-request run where one was there.
|
|
147
|
+
*
|
|
148
|
+
* Absent outside pull-request mode, and absent inside it when there was
|
|
149
|
+
* nothing to skip: it is a claim that something was there and was declined,
|
|
150
|
+
* not a claim about the mode. Reported so an adopter whose gates are
|
|
151
|
+
* devDependencies learns why the gate came from somewhere else, or from
|
|
152
|
+
* nowhere. Repository-relative because it reaches a published log.
|
|
153
|
+
*/
|
|
154
|
+
nodeModulesSkipped?: string;
|
|
50
155
|
}
|
|
51
156
|
export interface RunGateOptions {
|
|
52
157
|
repoRoot: string;
|
|
@@ -57,6 +162,22 @@ export interface RunGateOptions {
|
|
|
57
162
|
timeoutMs?: number;
|
|
58
163
|
/** The contract and change set prepared for the intent gate, when there is one. */
|
|
59
164
|
intent?: IntentPreparation;
|
|
165
|
+
/**
|
|
166
|
+
* The repository's own frozen contract, for a run with NO preparation.
|
|
167
|
+
*
|
|
168
|
+
* A plain `conductor run` never prepares anything, but the intent gate
|
|
169
|
+
* still judges against the contract in the repository, resolved by the
|
|
170
|
+
* child from `--project .`. Recording it makes that visible: the report
|
|
171
|
+
* says which contract, and the SARIF fallback files the gate's own results
|
|
172
|
+
* against the contract they are about rather than against the policy file.
|
|
173
|
+
* Ignored when `intent` is set, which already carries the same fact.
|
|
174
|
+
*/
|
|
175
|
+
intentContract?: string;
|
|
176
|
+
/**
|
|
177
|
+
* The ref the umbrella took its own policy from, on a pull-request run.
|
|
178
|
+
* Offered to every child; `decideTrustBase` says which ones can take it.
|
|
179
|
+
*/
|
|
180
|
+
trustBase?: string;
|
|
60
181
|
}
|
|
61
182
|
/**
|
|
62
183
|
* A gate that never got as far as being spawned.
|
|
@@ -68,6 +189,37 @@ export interface RunGateOptions {
|
|
|
68
189
|
* would have to learn about.
|
|
69
190
|
*/
|
|
70
191
|
export declare function preparationFailed(gate: GatePolicy, detail: string): GateOutcome;
|
|
192
|
+
/**
|
|
193
|
+
* EVERY program this binary would spawn, vetted against the trust base.
|
|
194
|
+
*
|
|
195
|
+
* Two files and not one. `program` is what the gate runs, and
|
|
196
|
+
* `versionProbe.command` can be a DIFFERENT file: for a per-command binary
|
|
197
|
+
* that ignores `--version`, resolution finds the version-safe sibling
|
|
198
|
+
* somewhere else entirely (`versionProbeFor`, src/resolve.ts:238-262). Vetting
|
|
199
|
+
* only the first left the probe free to spawn whatever the head put at the
|
|
200
|
+
* second, and a probe RUNS a program as thoroughly as a scan does.
|
|
201
|
+
*
|
|
202
|
+
* The first refusal wins and the rest is not consulted. The verdict is the
|
|
203
|
+
* same either way, and the sentence a reader has to act on should name one
|
|
204
|
+
* file rather than two.
|
|
205
|
+
*/
|
|
206
|
+
export declare function refuseHeadControlledBinary(repoRoot: string, trustBase: string, binary: ResolvedBinary): string | null;
|
|
207
|
+
/**
|
|
208
|
+
* The outcome for a gate whose program the umbrella declined to run.
|
|
209
|
+
*
|
|
210
|
+
* ONE BUILDER, TWO CALLERS, and that is the point of it being here rather
|
|
211
|
+
* than written out at the return that needs it. `runGate` reaches this before
|
|
212
|
+
* it spawns anything; `runAll` reaches it earlier still, before the intent
|
|
213
|
+
* gate's preparation spawns the same program three times. A second copy of
|
|
214
|
+
* the shape would be a second chance to forget the override below.
|
|
215
|
+
*
|
|
216
|
+
* ENFORCED, whatever the policy says. `enforce: false` is a standing decision
|
|
217
|
+
* about what a gate's FINDINGS are worth, and this gate produced none: the
|
|
218
|
+
* umbrella refused to run a program the pull request chose. Letting an
|
|
219
|
+
* unenforced gate swallow that would let a pull request pick its own judge
|
|
220
|
+
* and keep the run green.
|
|
221
|
+
*/
|
|
222
|
+
export declare function gateProgramRefused(gate: GatePolicy, trustBase: string, refusal: string, binary: ResolvedBinary): GateOutcome;
|
|
71
223
|
/**
|
|
72
224
|
* The arguments the umbrella adds, per product.
|
|
73
225
|
*
|
|
@@ -83,7 +235,13 @@ export declare function preparationFailed(gate: GatePolicy, detail: string): Gat
|
|
|
83
235
|
* decided by that gate's own argument parser rather than by anything the
|
|
84
236
|
* user could read in their own policy file.
|
|
85
237
|
*/
|
|
86
|
-
export declare function gateArgs(gate: GatePolicy, staged: boolean, intent: IntentPreparation | undefined
|
|
238
|
+
export declare function gateArgs(gate: GatePolicy, staged: boolean, intent: IntentPreparation | undefined,
|
|
239
|
+
/**
|
|
240
|
+
* The trust base to hand THIS gate, or undefined. Already decided by
|
|
241
|
+
* `decideTrustBase`; nothing here re-decides it, so a gate that cannot take
|
|
242
|
+
* the flag is never handed one by a second opinion written in this switch.
|
|
243
|
+
*/
|
|
244
|
+
trustBase?: string): string[];
|
|
87
245
|
/**
|
|
88
246
|
* Runs one gate. TOTAL: this never throws.
|
|
89
247
|
*
|
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 {
|
|
22
|
+
import { atLeastVersion, refuseHeadControlledProgram } from './trust-base.js';
|
|
23
|
+
import { ResolveError, candidateNames, nodeModulesCandidate, 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
|
*
|
|
@@ -54,6 +142,66 @@ const EMPTY_RUN = {
|
|
|
54
142
|
diagnostics: [],
|
|
55
143
|
details: {},
|
|
56
144
|
};
|
|
145
|
+
/**
|
|
146
|
+
* EVERY program this binary would spawn, vetted against the trust base.
|
|
147
|
+
*
|
|
148
|
+
* Two files and not one. `program` is what the gate runs, and
|
|
149
|
+
* `versionProbe.command` can be a DIFFERENT file: for a per-command binary
|
|
150
|
+
* that ignores `--version`, resolution finds the version-safe sibling
|
|
151
|
+
* somewhere else entirely (`versionProbeFor`, src/resolve.ts:238-262). Vetting
|
|
152
|
+
* only the first left the probe free to spawn whatever the head put at the
|
|
153
|
+
* second, and a probe RUNS a program as thoroughly as a scan does.
|
|
154
|
+
*
|
|
155
|
+
* The first refusal wins and the rest is not consulted. The verdict is the
|
|
156
|
+
* same either way, and the sentence a reader has to act on should name one
|
|
157
|
+
* file rather than two.
|
|
158
|
+
*/
|
|
159
|
+
export function refuseHeadControlledBinary(repoRoot, trustBase, binary) {
|
|
160
|
+
for (const program of [binary.program, binary.versionProbe?.command]) {
|
|
161
|
+
if (program === undefined) {
|
|
162
|
+
continue;
|
|
163
|
+
}
|
|
164
|
+
const refusal = refuseHeadControlledProgram(repoRoot, trustBase, program);
|
|
165
|
+
if (refusal !== null) {
|
|
166
|
+
return refusal;
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
return null;
|
|
170
|
+
}
|
|
171
|
+
/**
|
|
172
|
+
* The outcome for a gate whose program the umbrella declined to run.
|
|
173
|
+
*
|
|
174
|
+
* ONE BUILDER, TWO CALLERS, and that is the point of it being here rather
|
|
175
|
+
* than written out at the return that needs it. `runGate` reaches this before
|
|
176
|
+
* it spawns anything; `runAll` reaches it earlier still, before the intent
|
|
177
|
+
* gate's preparation spawns the same program three times. A second copy of
|
|
178
|
+
* the shape would be a second chance to forget the override below.
|
|
179
|
+
*
|
|
180
|
+
* ENFORCED, whatever the policy says. `enforce: false` is a standing decision
|
|
181
|
+
* about what a gate's FINDINGS are worth, and this gate produced none: the
|
|
182
|
+
* umbrella refused to run a program the pull request chose. Letting an
|
|
183
|
+
* unenforced gate swallow that would let a pull request pick its own judge
|
|
184
|
+
* and keep the run green.
|
|
185
|
+
*/
|
|
186
|
+
export function gateProgramRefused(gate, trustBase, refusal, binary) {
|
|
187
|
+
return {
|
|
188
|
+
role: gate.role,
|
|
189
|
+
product: gate.product,
|
|
190
|
+
stage: gate.stage,
|
|
191
|
+
enforce: true,
|
|
192
|
+
productVersion: null,
|
|
193
|
+
argv: [],
|
|
194
|
+
binary,
|
|
195
|
+
exitCode: null,
|
|
196
|
+
durationMs: 0,
|
|
197
|
+
stderr: '',
|
|
198
|
+
trustBase: { ref: trustBase, withheld: null, refused: refusal, proposals: [] },
|
|
199
|
+
couldNotRun: { reason: 'gate-program-refused', detail: refusal },
|
|
200
|
+
findings: [normalizeFailedGate(gate.role, gate.product, refusal)],
|
|
201
|
+
run: EMPTY_RUN,
|
|
202
|
+
diagnostics: [],
|
|
203
|
+
};
|
|
204
|
+
}
|
|
57
205
|
/**
|
|
58
206
|
* The arguments the umbrella adds, per product.
|
|
59
207
|
*
|
|
@@ -69,19 +217,41 @@ const EMPTY_RUN = {
|
|
|
69
217
|
* decided by that gate's own argument parser rather than by anything the
|
|
70
218
|
* user could read in their own policy file.
|
|
71
219
|
*/
|
|
72
|
-
export function gateArgs(gate, staged, intent
|
|
220
|
+
export function gateArgs(gate, staged, intent,
|
|
221
|
+
/**
|
|
222
|
+
* The trust base to hand THIS gate, or undefined. Already decided by
|
|
223
|
+
* `decideTrustBase`; nothing here re-decides it, so a gate that cannot take
|
|
224
|
+
* the flag is never handed one by a second opinion written in this switch.
|
|
225
|
+
*/
|
|
226
|
+
trustBase) {
|
|
73
227
|
const passthrough = renderOptionFlags(gate.options);
|
|
228
|
+
const trust = trustBase === undefined ? [] : ['--trust-base', trustBase];
|
|
74
229
|
switch (gate.product) {
|
|
75
230
|
case 'dep-guard':
|
|
76
|
-
|
|
231
|
+
// `scan` takes --trust-base from 0.6.0. It sits beside whatever the
|
|
232
|
+
// umbrella already passes rather than replacing it: --trust-base says
|
|
233
|
+
// where the RULES come from and the mode flags say what is scanned,
|
|
234
|
+
// and a pull-request run passes both.
|
|
235
|
+
return [...(staged ? ['--staged'] : []), '--format', 'json', ...trust, ...passthrough];
|
|
77
236
|
case 'vault-guard':
|
|
78
237
|
// No path argument: the CLI defaults it to "." and the umbrella runs
|
|
79
238
|
// with cwd at the repository root anyway. Passing one would also risk
|
|
80
239
|
// a passthrough value being read as the positional.
|
|
81
|
-
|
|
240
|
+
//
|
|
241
|
+
// `scan` takes --trust-base from 1.7.0, and on exit 2 it prints one
|
|
242
|
+
// line on stderr and NO document at all, which the could-not-run path
|
|
243
|
+
// above already handles before JSON.parse is reached.
|
|
244
|
+
return [...(staged ? ['--staged'] : []), '-f', 'json', ...trust, ...passthrough];
|
|
82
245
|
case 'intent-guard': {
|
|
83
246
|
if (intent === undefined) {
|
|
84
|
-
return [
|
|
247
|
+
return [
|
|
248
|
+
'--project',
|
|
249
|
+
'.',
|
|
250
|
+
...(staged ? ['--staged'] : []),
|
|
251
|
+
...trust,
|
|
252
|
+
'--json',
|
|
253
|
+
...passthrough,
|
|
254
|
+
];
|
|
85
255
|
}
|
|
86
256
|
// A prepared run replaces --staged entirely rather than adding to it.
|
|
87
257
|
// The two path sources are ADDITIVE in intent-guard, so leaving
|
|
@@ -99,6 +269,10 @@ export function gateArgs(gate, staged, intent) {
|
|
|
99
269
|
? ['--staged']
|
|
100
270
|
: []
|
|
101
271
|
: ['--paths', intent.paths.join(',')]),
|
|
272
|
+
// Beside --paths on purpose, and they are independent: --trust-base
|
|
273
|
+
// says where the RULES come from, --paths says which paths are
|
|
274
|
+
// judged. A pull-request run passes both.
|
|
275
|
+
...trust,
|
|
102
276
|
'--json',
|
|
103
277
|
...passthrough,
|
|
104
278
|
];
|
|
@@ -153,6 +327,31 @@ function messageOf(err) {
|
|
|
153
327
|
}
|
|
154
328
|
return String(err);
|
|
155
329
|
}
|
|
330
|
+
/**
|
|
331
|
+
* The sentence a gate that resolved to nothing gets on a pull-request run.
|
|
332
|
+
*
|
|
333
|
+
* EMPTY OUTSIDE PULL-REQUEST MODE, because outside it nothing about
|
|
334
|
+
* resolution changed and the old message is still the whole story. Inside it
|
|
335
|
+
* the message would otherwise be actively misleading in the common case: an
|
|
336
|
+
* adopter with the gates as devDependencies is looking straight at a
|
|
337
|
+
* node_modules/.bin/<gate> while being told no binary was found.
|
|
338
|
+
*
|
|
339
|
+
* It names `npm install -g` and the Action's own input rather than "install
|
|
340
|
+
* it", because those are the two places the fix actually is: on a runner, the
|
|
341
|
+
* Action installs the gates itself at a version pinned in a workflow file that
|
|
342
|
+
* lives on the base branch, which is the protected side.
|
|
343
|
+
*/
|
|
344
|
+
function missingGateRemedy(product, skipNodeModules, skipped) {
|
|
345
|
+
if (!skipNodeModules) {
|
|
346
|
+
return '';
|
|
347
|
+
}
|
|
348
|
+
return (' On a pull-request run node_modules/.bin is not consulted at all: what is installed there ' +
|
|
349
|
+
'is chosen by the head own manifest and lockfile, so no ref approves it.' +
|
|
350
|
+
(skipped === null ? '' : ` There is a ${skipped}, and it was skipped for that reason.`) +
|
|
351
|
+
` Install the gate outside the tree with npm install -g @vaultcompass/${product}. The ` +
|
|
352
|
+
`conductor Action does exactly that, at the version its ${product}-version input pins, and ` +
|
|
353
|
+
'that pin lives in the workflow file on the base branch.');
|
|
354
|
+
}
|
|
156
355
|
/**
|
|
157
356
|
* Runs one gate. TOTAL: this never throws.
|
|
158
357
|
*
|
|
@@ -178,14 +377,25 @@ export function runGate(gate, options) {
|
|
|
178
377
|
// Carried on every return path below, including the failures: which
|
|
179
378
|
// contract a gate WOULD have used is exactly as interesting when it could
|
|
180
379
|
// not run as when it could.
|
|
181
|
-
...(options.intent
|
|
182
|
-
? {
|
|
183
|
-
: {
|
|
380
|
+
...(options.intent !== undefined
|
|
381
|
+
? {
|
|
184
382
|
intent: {
|
|
185
383
|
contractSource: options.intent.contractSource,
|
|
186
384
|
baseRef: options.intent.baseRef,
|
|
187
385
|
},
|
|
188
|
-
}
|
|
386
|
+
}
|
|
387
|
+
: options.intentContract === undefined
|
|
388
|
+
? {}
|
|
389
|
+
: {
|
|
390
|
+
// No preparation, but the repository has a frozen contract and
|
|
391
|
+
// the child will read it from `--project .`. Same shape, and the
|
|
392
|
+
// base is null because nothing was diffed: this run is the index
|
|
393
|
+
// or the working tree, not a branch against a ref.
|
|
394
|
+
intent: {
|
|
395
|
+
contractSource: { kind: 'native', path: options.intentContract },
|
|
396
|
+
baseRef: null,
|
|
397
|
+
},
|
|
398
|
+
}),
|
|
189
399
|
};
|
|
190
400
|
const started = Date.now();
|
|
191
401
|
try {
|
|
@@ -212,10 +422,20 @@ export function runGate(gate, options) {
|
|
|
212
422
|
}
|
|
213
423
|
function runGateInner(gate, options, started, progress) {
|
|
214
424
|
const timeoutMs = options.timeoutMs ?? 120_000;
|
|
425
|
+
// ONE PLACE DECIDES WHAT PULL-REQUEST MODE IS, and it is the presence of a
|
|
426
|
+
// trust base. resolve.ts knows nothing about refs, so it is told rather than
|
|
427
|
+
// asked.
|
|
428
|
+
const skipNodeModules = options.trustBase !== undefined;
|
|
429
|
+
const skipped = skipNodeModules ? nodeModulesCandidate(gate, options.repoRoot) : null;
|
|
430
|
+
if (skipped !== null) {
|
|
431
|
+
// Onto `progress` rather than only onto the returns below, so the
|
|
432
|
+
// backstop's view carries it too.
|
|
433
|
+
Object.assign(progress, { nodeModulesSkipped: skipped });
|
|
434
|
+
}
|
|
215
435
|
const base = progress;
|
|
216
436
|
let binary;
|
|
217
437
|
try {
|
|
218
|
-
binary = resolveGateBinary(gate, options.repoRoot, options.pathValue);
|
|
438
|
+
binary = resolveGateBinary(gate, options.repoRoot, options.pathValue, { skipNodeModules });
|
|
219
439
|
}
|
|
220
440
|
catch (err) {
|
|
221
441
|
// A ResolveError is the expected shape here; anything else is still a
|
|
@@ -239,6 +459,7 @@ function runGateInner(gate, options, started, progress) {
|
|
|
239
459
|
};
|
|
240
460
|
}
|
|
241
461
|
if (binary === null) {
|
|
462
|
+
const remedy = missingGateRemedy(gate.product, skipNodeModules, skipped);
|
|
242
463
|
return {
|
|
243
464
|
...base,
|
|
244
465
|
durationMs: Date.now() - started,
|
|
@@ -246,19 +467,81 @@ function runGateInner(gate, options, started, progress) {
|
|
|
246
467
|
reason: 'binary-missing',
|
|
247
468
|
// Named in resolution order, which is the repository's own copy
|
|
248
469
|
// first. Saying PATH first points a reader at the location this
|
|
249
|
-
// tool prefers second, which is the wrong place to install it.
|
|
250
|
-
|
|
470
|
+
// tool prefers second, which is the wrong place to install it. On a
|
|
471
|
+
// pull-request run that order has one entry, because the other one is
|
|
472
|
+
// not a location this run has.
|
|
473
|
+
detail: (skipNodeModules
|
|
474
|
+
? `no ${gate.product} binary on PATH`
|
|
475
|
+
: `no ${gate.product} binary in node_modules/.bin or on PATH`) + remedy,
|
|
251
476
|
},
|
|
252
477
|
// A missing enabled gate is a finding of the umbrella's own, never a
|
|
253
478
|
// silent skip. Skipping is how a gate ends up switched on in the
|
|
254
479
|
// policy file and absent in reality for months.
|
|
255
|
-
findings: [
|
|
480
|
+
findings: [
|
|
481
|
+
normalizeMissingGate(gate.role, gate.product, candidateNames(gate.product), remedy),
|
|
482
|
+
],
|
|
256
483
|
run: EMPTY_RUN,
|
|
257
484
|
diagnostics: [],
|
|
258
485
|
};
|
|
259
486
|
}
|
|
487
|
+
// BEFORE the version probe, and that ordering is the whole of it: the probe
|
|
488
|
+
// RUNS the program, so asking a head-controlled binary for its version is
|
|
489
|
+
// already executing it. A planted stub answering "1.7.0" is the cheapest
|
|
490
|
+
// version of this attack and it would have been run before anything checked
|
|
491
|
+
// where it came from.
|
|
492
|
+
if (options.trustBase !== undefined) {
|
|
493
|
+
// BOTH SPAWNABLE PATHS, not just the program: the probe below can be a
|
|
494
|
+
// different file from binary.program, and it is executed just as
|
|
495
|
+
// thoroughly. The enforce override and the rest of the shape live in
|
|
496
|
+
// gateProgramRefused, which the intent gate's preparation shares.
|
|
497
|
+
const refusal = refuseHeadControlledBinary(options.repoRoot, options.trustBase, binary);
|
|
498
|
+
if (refusal !== null) {
|
|
499
|
+
return {
|
|
500
|
+
...base,
|
|
501
|
+
...gateProgramRefused(gate, options.trustBase, refusal, binary),
|
|
502
|
+
durationMs: Date.now() - started,
|
|
503
|
+
};
|
|
504
|
+
}
|
|
505
|
+
}
|
|
260
506
|
const version = probeVersion(binary, options.repoRoot, timeoutMs);
|
|
261
|
-
|
|
507
|
+
// AFTER the version probe and BEFORE the command line is built, because the
|
|
508
|
+
// decision reads the version. That ordering is the whole capability gate:
|
|
509
|
+
// an intent-guard older than 1.4.0 must not be handed a flag it would
|
|
510
|
+
// reject, and a gate IN the table whose version could not be read is
|
|
511
|
+
// refused rather than run outside the boundary.
|
|
512
|
+
const trustBase = decideTrustBase(gate, options.intent, options.trustBase, version);
|
|
513
|
+
if (trustBase !== undefined && trustBase.refused !== null) {
|
|
514
|
+
return {
|
|
515
|
+
...base,
|
|
516
|
+
productVersion: version,
|
|
517
|
+
binary,
|
|
518
|
+
durationMs: Date.now() - started,
|
|
519
|
+
// ENFORCED, whatever the policy says, for the same reason a refused
|
|
520
|
+
// program is: the gate produced no findings for `enforce: false` to be
|
|
521
|
+
// a decision about, and this is the umbrella saying it could not
|
|
522
|
+
// establish that the gate was inside the boundary.
|
|
523
|
+
//
|
|
524
|
+
// Reachable now only as a PACKAGING problem, not as an attack: the
|
|
525
|
+
// program check above runs first, and with its directory-subtree rule a
|
|
526
|
+
// pull request can no longer put a program here whose version probe it
|
|
527
|
+
// controls. Before that rule it could, through the wrapper shape: a
|
|
528
|
+
// head-replaced inner script exiting 3 on --version landed exactly
|
|
529
|
+
// here, with enforce false and exit 0. A packaging quirk that
|
|
530
|
+
// fails a build loudly is the better failure: the alternative is a
|
|
531
|
+
// boundary that quietly downgrades itself on the runs where something
|
|
532
|
+
// is already wrong, which is the shape of every bug in this file.
|
|
533
|
+
enforce: true,
|
|
534
|
+
trustBase,
|
|
535
|
+
couldNotRun: { reason: 'trust-base-unverified', detail: trustBase.refused },
|
|
536
|
+
findings: [normalizeFailedGate(gate.role, gate.product, trustBase.refused)],
|
|
537
|
+
run: EMPTY_RUN,
|
|
538
|
+
diagnostics: [],
|
|
539
|
+
};
|
|
540
|
+
}
|
|
541
|
+
const argv = [
|
|
542
|
+
...binary.argvPrefix,
|
|
543
|
+
...gateArgs(gate, options.staged, options.intent, trustBase === undefined || trustBase.withheld !== null ? undefined : trustBase.ref),
|
|
544
|
+
];
|
|
262
545
|
const child = spawnSync(binary.command, argv, {
|
|
263
546
|
cwd: options.repoRoot,
|
|
264
547
|
encoding: 'utf8',
|
|
@@ -272,6 +555,12 @@ function runGateInner(gate, options, started, progress) {
|
|
|
272
555
|
binary,
|
|
273
556
|
durationMs: Date.now() - started,
|
|
274
557
|
stderr: child.stderr ?? '',
|
|
558
|
+
// Carried on every return path below, the failures included: WHETHER
|
|
559
|
+
// this gate was in pull-request mode is exactly as interesting when it
|
|
560
|
+
// could not run as when it could, and the withheld reason is the only
|
|
561
|
+
// place a report can say a gate read its own rules out of the tree under
|
|
562
|
+
// judgment.
|
|
563
|
+
...(trustBase === undefined ? {} : { trustBase }),
|
|
275
564
|
};
|
|
276
565
|
// Keep the backstop's view current, so an unexpected throw below still
|
|
277
566
|
// reports which binary ran and what it printed.
|
|
@@ -339,6 +628,14 @@ function runGateInner(gate, options, started, progress) {
|
|
|
339
628
|
findings: normalized.findings,
|
|
340
629
|
run: normalized.run,
|
|
341
630
|
diagnostics: normalized.diagnostics,
|
|
631
|
+
// The gate's own answer about the control inputs, folded onto the
|
|
632
|
+
// decision the umbrella made before spawning it. A gate that was NOT
|
|
633
|
+
// put into pull-request mode reports no proposals, and its trustBase
|
|
634
|
+
// keeps the withheld reason rather than being overwritten with an
|
|
635
|
+
// empty list that would read as "nothing was proposed".
|
|
636
|
+
...(trustBase === undefined || normalized.trustBase === undefined
|
|
637
|
+
? {}
|
|
638
|
+
: { trustBase: { ...trustBase, proposals: normalized.trustBase.proposals } }),
|
|
342
639
|
};
|
|
343
640
|
}
|
|
344
641
|
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
|
*
|