@vaultcompass/conductor 0.2.3 → 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 +96 -15
- package/dist/envelope.d.ts +16 -0
- package/dist/gate-runner.d.ts +118 -2
- package/dist/gate-runner.js +211 -9
- package/dist/init.d.ts +15 -1
- package/dist/init.js +215 -33
- 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 +134 -3
- 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/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
|
*
|
package/dist/output-sarif.js
CHANGED
|
@@ -88,6 +88,24 @@
|
|
|
88
88
|
// Everything genuinely inside keeps the relative, forward-slashed,
|
|
89
89
|
// `%SRCROOT%`-based spelling that GitHub code scanning wants.
|
|
90
90
|
//
|
|
91
|
+
// - EVERY RESULT CARRIES AT LEAST ONE LOCATION, and the fallback is a real
|
|
92
|
+
// file rather than an invented one. GitHub code scanning rejects a whole
|
|
93
|
+
// uploaded log with "locationFromSarifResult: expected at least one
|
|
94
|
+
// location" the moment any single result has none, so one location-less
|
|
95
|
+
// result loses the entire report rather than one alert. That happened on
|
|
96
|
+
// every main-branch run of a sibling repository's guardrails job, and the
|
|
97
|
+
// offender was `intent-guard/gate-blocked`, whose subject is `none`.
|
|
98
|
+
//
|
|
99
|
+
// This does NOT weaken the two rules above it. A location the gate gave is
|
|
100
|
+
// never overwritten, no region is invented, and no path is fabricated: the
|
|
101
|
+
// fallback is the CONTROL FILE this result is a statement about, which is
|
|
102
|
+
// a file that exists in the repository and is the one a reader would open.
|
|
103
|
+
// For the umbrella's own results and for the two gates whose control files
|
|
104
|
+
// the umbrella does not read, that is the policy file, which is where the
|
|
105
|
+
// gate that produced the result is enabled. For the intent gate it is the
|
|
106
|
+
// frozen contract, when the run recorded which of the two state
|
|
107
|
+
// directories answered.
|
|
108
|
+
//
|
|
91
109
|
// - A REGION ONLY WHEN A REAL POSITION IS KNOWN. One of the three gates
|
|
92
110
|
// reports a line and a column; the other two report no position at all.
|
|
93
111
|
// An invented startLine annotates an unrelated line of somebody's file
|
|
@@ -99,6 +117,7 @@
|
|
|
99
117
|
// normalize.ts, which is where the omission would stop mattering if the
|
|
100
118
|
// field were ever carried.
|
|
101
119
|
import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
|
|
120
|
+
import { POLICY_FILE_NAME } from './policy.js';
|
|
102
121
|
const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
|
|
103
122
|
export const UMBRELLA_DRIVER_NAME = 'conductor';
|
|
104
123
|
/**
|
|
@@ -242,7 +261,41 @@ function locationsFor(finding) {
|
|
|
242
261
|
return undefined;
|
|
243
262
|
}
|
|
244
263
|
}
|
|
245
|
-
|
|
264
|
+
/**
|
|
265
|
+
* The file a result with no location of its own is filed against.
|
|
266
|
+
*
|
|
267
|
+
* A real, repository-relative path, never a placeholder: the policy file is
|
|
268
|
+
* where every gate is enabled and where a reader goes to change what ran, and
|
|
269
|
+
* for the intent gate the frozen contract is the file its gate-state findings
|
|
270
|
+
* are literally about. Both exist in the repository whenever a run happened at
|
|
271
|
+
* all, so this never points at nothing.
|
|
272
|
+
*/
|
|
273
|
+
export function fallbackLocationFor(gate) {
|
|
274
|
+
const source = gate?.intent?.contractSource;
|
|
275
|
+
if (source !== undefined && source.kind === 'native') {
|
|
276
|
+
return source.path;
|
|
277
|
+
}
|
|
278
|
+
return POLICY_FILE_NAME;
|
|
279
|
+
}
|
|
280
|
+
/**
|
|
281
|
+
* The locations for one result, with the fallback filled in where a real one
|
|
282
|
+
* is missing.
|
|
283
|
+
*
|
|
284
|
+
* TWO SEPARATE CASES, and conflating them would lose information. A finding
|
|
285
|
+
* with no locations at all gets one made of the fallback. A finding that has
|
|
286
|
+
* a LOGICAL location and no physical one (a drift finding's contract
|
|
287
|
+
* category, a package whose manifest could not be placed) keeps the logical
|
|
288
|
+
* one and gains the physical fallback beside it, because the logical location
|
|
289
|
+
* is what a consumer groups on and replacing it would drop that.
|
|
290
|
+
*/
|
|
291
|
+
function withFallbackLocation(locations, fallbackUri) {
|
|
292
|
+
const physicalLocation = { artifactLocation: { uri: fallbackUri, uriBaseId: '%SRCROOT%' } };
|
|
293
|
+
if (locations === undefined || locations.length === 0) {
|
|
294
|
+
return [{ physicalLocation }];
|
|
295
|
+
}
|
|
296
|
+
return locations.map((location) => location.physicalLocation === undefined ? { ...location, physicalLocation } : location);
|
|
297
|
+
}
|
|
298
|
+
function toResult(finding, fallbackUri) {
|
|
246
299
|
// A path that escapes the source root gets no physical location, so the
|
|
247
300
|
// path itself is carried here instead. Dropping a location is honest;
|
|
248
301
|
// dropping the information as well would just lose the finding's subject.
|
|
@@ -265,10 +318,9 @@ function toResult(finding) {
|
|
|
265
318
|
if (finding.fingerprint !== null) {
|
|
266
319
|
entry.partialFingerprints = { [fingerprintKey(finding.fingerprint.scope)]: finding.fingerprint.value };
|
|
267
320
|
}
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
}
|
|
321
|
+
// Unconditional. The old code omitted the key when there was nothing
|
|
322
|
+
// honest to say, and one such result makes GitHub reject the whole log.
|
|
323
|
+
entry.locations = withFallbackLocation(locationsFor(finding), fallbackUri);
|
|
272
324
|
return entry;
|
|
273
325
|
}
|
|
274
326
|
function ruleDeclarations(findings) {
|
|
@@ -286,10 +338,7 @@ function toNotification(notification) {
|
|
|
286
338
|
// filed under when it was a result, so a consumer that had rules for
|
|
287
339
|
// these still recognises them.
|
|
288
340
|
descriptor: { id: notification.id },
|
|
289
|
-
|
|
290
|
-
// code, and a notification that arrived as a warning would push these
|
|
291
|
-
// straight back into the alert list they were moved out of.
|
|
292
|
-
level: 'note',
|
|
341
|
+
level: notification.level ?? 'note',
|
|
293
342
|
message: { text: notification.message },
|
|
294
343
|
properties: { details: notification.details },
|
|
295
344
|
};
|
|
@@ -298,7 +347,9 @@ function notificationDeclarations(notifications) {
|
|
|
298
347
|
const ids = [...new Set(notifications.map((notification) => notification.id))].sort();
|
|
299
348
|
return ids.map((id) => ({ id, name: id.slice(id.indexOf('/') + 1) }));
|
|
300
349
|
}
|
|
301
|
-
function makeRun(name, version, findings,
|
|
350
|
+
function makeRun(name, version, findings,
|
|
351
|
+
/** The artifact a result with no location of its own is filed against. */
|
|
352
|
+
fallbackUri, properties, invocation) {
|
|
302
353
|
const notifications = invocation?.notifications ?? [];
|
|
303
354
|
return {
|
|
304
355
|
tool: {
|
|
@@ -316,7 +367,7 @@ function makeRun(name, version, findings, properties, invocation) {
|
|
|
316
367
|
: { notifications: notificationDeclarations(notifications) }),
|
|
317
368
|
},
|
|
318
369
|
},
|
|
319
|
-
results: findings.map(toResult),
|
|
370
|
+
results: findings.map((finding) => toResult(finding, fallbackUri)),
|
|
320
371
|
...(invocation === undefined
|
|
321
372
|
? {}
|
|
322
373
|
: {
|
|
@@ -500,6 +551,141 @@ function skippedNotifications(result) {
|
|
|
500
551
|
details: { role: gate.role, product: gate.product, reason: gate.reason },
|
|
501
552
|
}));
|
|
502
553
|
}
|
|
554
|
+
/**
|
|
555
|
+
* The control inputs this pull request proposes to change, as notifications.
|
|
556
|
+
*
|
|
557
|
+
* A NOTIFICATION and never a result, decided by the rule at
|
|
558
|
+
* skippedNotifications below rather than by a fresh judgment. A proposed
|
|
559
|
+
* control change is a statement about CONFIGURATION in the purest form that
|
|
560
|
+
* rule describes: nothing went wrong, nobody's code is at fault, the
|
|
561
|
+
* proposal did not take effect, and it is true of every run of this pull
|
|
562
|
+
* request until it merges or the file is reverted. As a result it would be a
|
|
563
|
+
* fingerprint-less alert reappearing on every push to the branch, which is
|
|
564
|
+
* how a code scanning tab becomes something nobody reads.
|
|
565
|
+
*
|
|
566
|
+
* The id is the UMBRELLA'S, even for a line a gate wrote, and that is a
|
|
567
|
+
* deliberate departure from skippedNotifications, which uses the gate's
|
|
568
|
+
* namespace. The statement here is the umbrella's summing: it is the one
|
|
569
|
+
* place a reviewer sees that a pull request tried to change three gates'
|
|
570
|
+
* rules at once, which is the sentence the whole wave exists to produce. The
|
|
571
|
+
* gate that raised each line is in the details.
|
|
572
|
+
*/
|
|
573
|
+
function proposalNotifications(result) {
|
|
574
|
+
return result.proposals.map((proposal) => ({
|
|
575
|
+
id: 'conductor/control-change-proposed',
|
|
576
|
+
message: `This pull request proposes a control change that did NOT take effect for this run: ` +
|
|
577
|
+
`${proposal.line} (${proposal.product}). The rules came from ` +
|
|
578
|
+
`${result.trustBase?.ref ?? 'the base ref'}; the proposed change decides what runs once ` +
|
|
579
|
+
'it is on the base branch.',
|
|
580
|
+
details: {
|
|
581
|
+
product: proposal.product,
|
|
582
|
+
role: proposal.role,
|
|
583
|
+
proposal: proposal.line,
|
|
584
|
+
ref: result.trustBase?.ref ?? null,
|
|
585
|
+
},
|
|
586
|
+
}));
|
|
587
|
+
}
|
|
588
|
+
/**
|
|
589
|
+
* The trust base the umbrella refused, when it refused one.
|
|
590
|
+
*
|
|
591
|
+
* ERROR LEVEL, and the only notification here that is not a note. Every other
|
|
592
|
+
* one says how much of the policy a run covered; this one says the run did
|
|
593
|
+
* not happen. It is the one statement in this file that a reader must not be
|
|
594
|
+
* able to scroll past.
|
|
595
|
+
*
|
|
596
|
+
* A NOTIFICATION rather than a result even so, and the reason is the
|
|
597
|
+
* discriminator further down: a result is about a place in somebody's code,
|
|
598
|
+
* and this is about a ref. The could-not-run RESULTS for whatever gates the
|
|
599
|
+
* inventory named sit beside it in the same run and carry the same sentence,
|
|
600
|
+
* so a consumer that reads only results still learns that nothing ran.
|
|
601
|
+
*/
|
|
602
|
+
function trustBaseRefusedNotifications(result) {
|
|
603
|
+
const refusal = result.trustBase?.refusal;
|
|
604
|
+
if (refusal === undefined || refusal === null) {
|
|
605
|
+
return [];
|
|
606
|
+
}
|
|
607
|
+
return [
|
|
608
|
+
{
|
|
609
|
+
id: 'conductor/trust-base-refused',
|
|
610
|
+
level: 'error',
|
|
611
|
+
message: `conductor refused the trust base "${result.trustBase?.ref ?? ''}", so no gate ran and ` +
|
|
612
|
+
`NOTHING WAS CHECKED by this run. ${refusal}`,
|
|
613
|
+
details: { ref: result.trustBase?.ref ?? null, reason: refusal },
|
|
614
|
+
},
|
|
615
|
+
];
|
|
616
|
+
}
|
|
617
|
+
/**
|
|
618
|
+
* The gates whose PROGRAM the umbrella refused to run.
|
|
619
|
+
*
|
|
620
|
+
* ERROR level, beside the refused trust base and for the same reason: this is
|
|
621
|
+
* not a statement about how much of the policy a run covered. A pull request
|
|
622
|
+
* put a file where the gate's binary resolves and the umbrella declined to
|
|
623
|
+
* execute it, which a reviewer has to meet rather than scroll past.
|
|
624
|
+
*
|
|
625
|
+
* The gate's could-not-run RESULT carries the same sentence, so a consumer
|
|
626
|
+
* reading only results still learns the gate did not run. This adds the
|
|
627
|
+
* structured half: which gate, which program, and which ref it was measured
|
|
628
|
+
* against.
|
|
629
|
+
*/
|
|
630
|
+
function programRefusedNotifications(result) {
|
|
631
|
+
return result.gates.flatMap((gate) => {
|
|
632
|
+
if (gate.couldNotRun?.reason !== 'gate-program-refused') {
|
|
633
|
+
return [];
|
|
634
|
+
}
|
|
635
|
+
return [
|
|
636
|
+
{
|
|
637
|
+
id: 'conductor/gate-program-refused',
|
|
638
|
+
level: 'error',
|
|
639
|
+
message: `The ${gate.role} gate (${gate.product}) did NOT run: its program is a file this pull ` +
|
|
640
|
+
`request controls, so running it would let the pull request choose the program that ` +
|
|
641
|
+
`judges it. ${gate.couldNotRun.detail}`,
|
|
642
|
+
details: {
|
|
643
|
+
role: gate.role,
|
|
644
|
+
product: gate.product,
|
|
645
|
+
program: gate.binary?.program ?? null,
|
|
646
|
+
ref: gate.trustBase?.ref ?? null,
|
|
647
|
+
reason: gate.couldNotRun.detail,
|
|
648
|
+
},
|
|
649
|
+
},
|
|
650
|
+
];
|
|
651
|
+
});
|
|
652
|
+
}
|
|
653
|
+
/**
|
|
654
|
+
* The gates the umbrella could not put into pull-request mode.
|
|
655
|
+
*
|
|
656
|
+
* The loud half of the same mode, and by the discriminator below it is a
|
|
657
|
+
* close call that lands on notification: nothing went wrong with the run, and
|
|
658
|
+
* the fact is true of the configuration (an older gate is installed) rather
|
|
659
|
+
* than of this change, so it is identical on every run until somebody
|
|
660
|
+
* upgrades. What it says is how much of the pull-request boundary this run
|
|
661
|
+
* actually had, which is a coverage statement.
|
|
662
|
+
*
|
|
663
|
+
* It is still the most important notification in the log. A gate here read
|
|
664
|
+
* its own control inputs out of the tree under judgment.
|
|
665
|
+
*/
|
|
666
|
+
function trustBaseWithheldNotifications(result) {
|
|
667
|
+
return result.gates.flatMap((gate) => {
|
|
668
|
+
const withheld = gate.trustBase?.withheld;
|
|
669
|
+
if (withheld === undefined || withheld === null) {
|
|
670
|
+
return [];
|
|
671
|
+
}
|
|
672
|
+
return [
|
|
673
|
+
{
|
|
674
|
+
id: 'conductor/trust-base-not-passed',
|
|
675
|
+
message: `The ${gate.role} gate (${gate.product}) did NOT run in pull-request mode, so it read ` +
|
|
676
|
+
`its own control inputs from the tree being judged rather than from ` +
|
|
677
|
+
`${gate.trustBase?.ref ?? 'the base ref'}. ${withheld}`,
|
|
678
|
+
details: {
|
|
679
|
+
role: gate.role,
|
|
680
|
+
product: gate.product,
|
|
681
|
+
productVersion: gate.productVersion,
|
|
682
|
+
ref: gate.trustBase?.ref ?? null,
|
|
683
|
+
reason: withheld,
|
|
684
|
+
},
|
|
685
|
+
},
|
|
686
|
+
];
|
|
687
|
+
});
|
|
688
|
+
}
|
|
503
689
|
/**
|
|
504
690
|
* The gates the policy file told not to decide anything, as notifications.
|
|
505
691
|
*
|
|
@@ -582,7 +768,7 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
582
768
|
// and one measured against a contract somebody approved by hand are
|
|
583
769
|
// different claims, and so are one over a branch diff and one over an
|
|
584
770
|
// index.
|
|
585
|
-
runs.push(makeRun(gate.product, gate.productVersion, own, {
|
|
771
|
+
runs.push(makeRun(gate.product, gate.productVersion, own, fallbackLocationFor(gate), {
|
|
586
772
|
enforced: gate.enforce,
|
|
587
773
|
stage: gate.stage,
|
|
588
774
|
...(gate.intent === undefined
|
|
@@ -609,18 +795,43 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
609
795
|
...skippedNotifications(result),
|
|
610
796
|
...unenforcedNotifications(result),
|
|
611
797
|
...legacyStateDirNotifications(result),
|
|
798
|
+
...trustBaseRefusedNotifications(result),
|
|
799
|
+
...programRefusedNotifications(result),
|
|
800
|
+
...proposalNotifications(result),
|
|
801
|
+
...trustBaseWithheldNotifications(result),
|
|
612
802
|
];
|
|
613
803
|
// Notifications earn the run on their own. Before this, the umbrella run
|
|
614
804
|
// existed only when it had findings and a deferred gate was one; without
|
|
615
805
|
// this clause a commit-stage log would say nothing whatever about the gate
|
|
616
806
|
// that did not run there.
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
807
|
+
//
|
|
808
|
+
// A REFUSAL EARNS IT UNCONDITIONALLY, and that clause is not redundant with
|
|
809
|
+
// the two beside it even though a refusal always adds a notification: it
|
|
810
|
+
// says out loud that the worst run this tool can have is the one case where
|
|
811
|
+
// an empty log is not acceptable. `{"runs": []}` was the output when the
|
|
812
|
+
// base ref could not be read and the head's inventory named no gate, and an
|
|
813
|
+
// empty log uploads cleanly and is indistinguishable from a repository
|
|
814
|
+
// nobody scanned.
|
|
815
|
+
if (umbrellaFindings.length > 0 ||
|
|
816
|
+
notifications.length > 0 ||
|
|
817
|
+
(result.trustBase?.refusal ?? null) !== null) {
|
|
818
|
+
runs.push(makeRun(UMBRELLA_DRIVER_NAME, umbrellaVersion, umbrellaFindings, POLICY_FILE_NAME,
|
|
819
|
+
// On the umbrella's run rather than on any gate's, because it is a
|
|
820
|
+
// fact about the whole run: every gate that could take the flag was
|
|
821
|
+
// handed this same ref. A consumer reading only the log can then tell
|
|
822
|
+
// a pull-request run from an ordinary one without parsing sentences.
|
|
823
|
+
result.trustBase === null ? undefined : { trustBase: result.trustBase }, {
|
|
824
|
+
// A claim about whether the analysis completed, taken from the
|
|
825
|
+
// gates rather than from the exit code: an unenforced gate that
|
|
826
|
+
// could not run leaves the run at exit 0, and nothing was checked
|
|
827
|
+
// by it either way. Written whenever this run is written, in both
|
|
828
|
+
// directions.
|
|
829
|
+
// A refusal is false whatever the gate list says, and with an
|
|
830
|
+
// empty inventory `every` over nothing is vacuously true, which
|
|
831
|
+
// would have claimed the analysis completed on the one run where
|
|
832
|
+
// nothing was even attempted.
|
|
833
|
+
executionSuccessful: (result.trustBase?.refusal ?? null) === null &&
|
|
834
|
+
result.gates.every((gate) => gate.couldNotRun === null),
|
|
624
835
|
notifications,
|
|
625
836
|
}));
|
|
626
837
|
}
|