@vaultcompass/conductor 0.2.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/LICENSE +21 -0
- package/README.md +412 -0
- package/dist/cli.d.ts +3 -0
- package/dist/cli.js +231 -0
- package/dist/envelope.d.ts +105 -0
- package/dist/envelope.js +75 -0
- package/dist/exit-codes.d.ts +30 -0
- package/dist/exit-codes.js +67 -0
- package/dist/gate-runner.d.ts +97 -0
- package/dist/gate-runner.js +354 -0
- package/dist/init.d.ts +138 -0
- package/dist/init.js +973 -0
- package/dist/intent-base.d.ts +54 -0
- package/dist/intent-base.js +135 -0
- package/dist/intent-prepare.d.ts +57 -0
- package/dist/intent-prepare.js +297 -0
- package/dist/intent-spec.d.ts +62 -0
- package/dist/intent-spec.js +268 -0
- package/dist/normalize.d.ts +58 -0
- package/dist/normalize.js +582 -0
- package/dist/output-sarif.d.ts +34 -0
- package/dist/output-sarif.js +564 -0
- package/dist/output-text.d.ts +12 -0
- package/dist/output-text.js +448 -0
- package/dist/policy.d.ts +126 -0
- package/dist/policy.js +328 -0
- package/dist/resolve.d.ts +52 -0
- package/dist/resolve.js +207 -0
- package/dist/run.d.ts +100 -0
- package/dist/run.js +147 -0
- package/package.json +43 -0
- package/schema/guardrails.schema.json +88 -0
|
@@ -0,0 +1,582 @@
|
|
|
1
|
+
// Turning each gate's own JSON into the internal envelope.
|
|
2
|
+
//
|
|
3
|
+
// Three separate functions rather than one table-driven mapper, because the
|
|
4
|
+
// three shapes disagree in ways a table would have to paper over: one is a
|
|
5
|
+
// flat findings array, one is nested by file, and the third is two
|
|
6
|
+
// different streams (a change-budget evaluation and a scored drift rubric)
|
|
7
|
+
// plus a gate status that can block for neither reason.
|
|
8
|
+
//
|
|
9
|
+
// What every one of them refuses to do, in one place so it is reviewable:
|
|
10
|
+
// invent a line number, invent a fingerprint, re-derive a severity a
|
|
11
|
+
// product already stated, or claim a finding is blocking when the gate's
|
|
12
|
+
// own reported count says otherwise.
|
|
13
|
+
import { createHash } from 'node:crypto';
|
|
14
|
+
import { NormalizeError, atOrAboveThreshold, } from './envelope.js';
|
|
15
|
+
const BLOCKING_MISMATCH = 'conductor/blocking-count-mismatch';
|
|
16
|
+
const THRESHOLD_UNKNOWN = 'conductor/blocking-threshold-unknown';
|
|
17
|
+
function isRecord(value) {
|
|
18
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
19
|
+
}
|
|
20
|
+
// Element-level validation.
|
|
21
|
+
//
|
|
22
|
+
// A top-level shape check is not enough, and that was a real defect rather
|
|
23
|
+
// than a hypothetical: `{"findings": [null]}` passed the old check that
|
|
24
|
+
// findings was an array, and then reading a property off null threw a
|
|
25
|
+
// TypeError, which is not a NormalizeError, so it escaped the gate runner,
|
|
26
|
+
// escaped the run, and reached the user as a stack trace carrying a local
|
|
27
|
+
// path, with exit 1 -- which the hook reports as "a gate blocked" -- and the
|
|
28
|
+
// remaining gates never ran.
|
|
29
|
+
//
|
|
30
|
+
// So every field the mapping actually reads is checked before it is read,
|
|
31
|
+
// and every failure is a NormalizeError naming the product and the path to
|
|
32
|
+
// the offending field. Fields the mapping only passes through are NOT
|
|
33
|
+
// required: rejecting output because a gate stopped emitting a field nobody
|
|
34
|
+
// maps would turn a harmless upstream change into a blocked commit.
|
|
35
|
+
function fail(product, where, wanted) {
|
|
36
|
+
throw new NormalizeError(`${product} output did not have the shape the umbrella knows: ${where} should be ${wanted}.`);
|
|
37
|
+
}
|
|
38
|
+
function needRecord(value, product, where) {
|
|
39
|
+
return isRecord(value) ? value : fail(product, where, 'an object');
|
|
40
|
+
}
|
|
41
|
+
function needArray(value, product, where) {
|
|
42
|
+
return Array.isArray(value) ? value : fail(product, where, 'an array');
|
|
43
|
+
}
|
|
44
|
+
function needString(value, product, where) {
|
|
45
|
+
return typeof value === 'string' ? value : fail(product, where, 'a string');
|
|
46
|
+
}
|
|
47
|
+
function needNumber(value, product, where) {
|
|
48
|
+
return typeof value === 'number' && Number.isFinite(value)
|
|
49
|
+
? value
|
|
50
|
+
: fail(product, where, 'a number');
|
|
51
|
+
}
|
|
52
|
+
function optionalString(value, product, where) {
|
|
53
|
+
return value === undefined ? undefined : needString(value, product, where);
|
|
54
|
+
}
|
|
55
|
+
function optionalDetails(value, product, where) {
|
|
56
|
+
return value === undefined ? {} : needRecord(value, product, where);
|
|
57
|
+
}
|
|
58
|
+
/** A string array, used for the two products that report matched path lists. */
|
|
59
|
+
function needStringArray(value, product, where) {
|
|
60
|
+
return needArray(value, product, where).map((entry, index) => needString(entry, product, `${where}[${index}]`));
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* Reconciles per-finding blocking against the count the gate reported.
|
|
64
|
+
*
|
|
65
|
+
* Neither dep-guard nor vault-guard marks a finding as blocking; each
|
|
66
|
+
* reports the threshold it used and how many findings met it. So the
|
|
67
|
+
* per-finding flag is reconstructed from that threshold and then checked
|
|
68
|
+
* against that count. When the two disagree, the gate wins: every flag
|
|
69
|
+
* drops to false and a diagnostic says why, because the alternative is the
|
|
70
|
+
* report telling a user a finding blocked their commit when the tool that
|
|
71
|
+
* blocks commits disagrees.
|
|
72
|
+
*/
|
|
73
|
+
function reconcileBlocking(findings, reportedBlocking, threshold, product, diagnostics) {
|
|
74
|
+
if (threshold === null) {
|
|
75
|
+
for (const finding of findings) {
|
|
76
|
+
finding.blocking = false;
|
|
77
|
+
}
|
|
78
|
+
diagnostics.push({
|
|
79
|
+
code: THRESHOLD_UNKNOWN,
|
|
80
|
+
message: `${product} did not report the threshold it gated on, so no finding is marked blocking. ` +
|
|
81
|
+
'The gate exit code still decides the run.',
|
|
82
|
+
});
|
|
83
|
+
return;
|
|
84
|
+
}
|
|
85
|
+
for (const finding of findings) {
|
|
86
|
+
finding.blocking = atOrAboveThreshold(finding.severity, threshold);
|
|
87
|
+
}
|
|
88
|
+
const derived = findings.filter((finding) => finding.blocking).length;
|
|
89
|
+
if (reportedBlocking !== undefined && derived !== reportedBlocking) {
|
|
90
|
+
for (const finding of findings) {
|
|
91
|
+
finding.blocking = false;
|
|
92
|
+
}
|
|
93
|
+
diagnostics.push({
|
|
94
|
+
code: BLOCKING_MISMATCH,
|
|
95
|
+
message: `${product} reported ${reportedBlocking} blocking finding(s) at threshold "${threshold}" ` +
|
|
96
|
+
`but the umbrella reconstructed ${derived}. No finding is marked blocking; the gate own ` +
|
|
97
|
+
'exit code still decides the run. This means the gate output shape has moved.',
|
|
98
|
+
});
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
// -- dep-guard ------------------------------------------------------------
|
|
102
|
+
/** Diagnostics from a gate, validated element by element like everything else. */
|
|
103
|
+
function readDiagnostics(value, product, where) {
|
|
104
|
+
if (value === undefined) {
|
|
105
|
+
return [];
|
|
106
|
+
}
|
|
107
|
+
return needArray(value, product, where).map((entry, index) => {
|
|
108
|
+
const record = needRecord(entry, product, `${where}[${index}]`);
|
|
109
|
+
return {
|
|
110
|
+
code: needString(record.code, product, `${where}[${index}].code`),
|
|
111
|
+
message: needString(record.message, product, `${where}[${index}].message`),
|
|
112
|
+
};
|
|
113
|
+
});
|
|
114
|
+
}
|
|
115
|
+
export function normalizeDepGuard(raw, version) {
|
|
116
|
+
const product = 'dep-guard';
|
|
117
|
+
const root = needRecord(raw, product, 'the output');
|
|
118
|
+
const run = needRecord(root.run, product, 'run');
|
|
119
|
+
const threshold = optionalString(run.failOn, product, 'run.failOn') ?? null;
|
|
120
|
+
const diagnostics = [];
|
|
121
|
+
const findings = needArray(root.findings, product, 'findings').map((entry, index) => {
|
|
122
|
+
const where = `findings[${index}]`;
|
|
123
|
+
const source = needRecord(entry, product, where);
|
|
124
|
+
return {
|
|
125
|
+
schemaVersion: 1,
|
|
126
|
+
product,
|
|
127
|
+
productVersion: version,
|
|
128
|
+
ruleId: `dep-guard/${needString(source.ruleId, product, `${where}.ruleId`)}`,
|
|
129
|
+
// dep-guard's four levels are the shared ladder exactly, so this is
|
|
130
|
+
// identity and nothing is derived.
|
|
131
|
+
severity: needString(source.severity, product, `${where}.severity`),
|
|
132
|
+
severityIsDerived: false,
|
|
133
|
+
blocking: false,
|
|
134
|
+
message: needString(source.message, product, `${where}.message`),
|
|
135
|
+
subject: {
|
|
136
|
+
kind: 'package',
|
|
137
|
+
name: needString(source.packageName, product, `${where}.packageName`),
|
|
138
|
+
manifest: needString(source.manifestPath, product, `${where}.manifestPath`),
|
|
139
|
+
...(source.lockfilePath === undefined
|
|
140
|
+
? {}
|
|
141
|
+
: { lockfile: needString(source.lockfilePath, product, `${where}.lockfilePath`) }),
|
|
142
|
+
},
|
|
143
|
+
fingerprint: {
|
|
144
|
+
value: needString(source.fingerprint, product, `${where}.fingerprint`),
|
|
145
|
+
scope: product,
|
|
146
|
+
// dep-guard hashes the rule id, the package name, the manifest path,
|
|
147
|
+
// and the signal. Position-free, so an unrelated edit above a finding
|
|
148
|
+
// does not mint a new one.
|
|
149
|
+
stability: 'stable',
|
|
150
|
+
},
|
|
151
|
+
details: optionalDetails(source.details, product, `${where}.details`),
|
|
152
|
+
};
|
|
153
|
+
});
|
|
154
|
+
reconcileBlocking(findings, typeof run.blockingMatches === 'number' ? run.blockingMatches : undefined, threshold, product, diagnostics);
|
|
155
|
+
return {
|
|
156
|
+
findings,
|
|
157
|
+
run: {
|
|
158
|
+
failOn: threshold,
|
|
159
|
+
suppressed: typeof root.suppressed === 'number' ? root.suppressed : 0,
|
|
160
|
+
ignored: typeof root.ignored === 'number' ? root.ignored : 0,
|
|
161
|
+
// Diagnostics never move dep-guard's own exit code, so they stay out
|
|
162
|
+
// of findings[] here too rather than becoming pseudo-findings.
|
|
163
|
+
diagnostics: readDiagnostics(run.diagnostics, product, 'run.diagnostics'),
|
|
164
|
+
details: {
|
|
165
|
+
mode: run.mode ?? null,
|
|
166
|
+
corpusBuiltAt: run.corpusBuiltAt ?? null,
|
|
167
|
+
lockfileFormat: run.lockfileFormat ?? null,
|
|
168
|
+
},
|
|
169
|
+
},
|
|
170
|
+
diagnostics,
|
|
171
|
+
};
|
|
172
|
+
}
|
|
173
|
+
// -- vault-guard ----------------------------------------------------------
|
|
174
|
+
export function normalizeVaultGuard(raw, version) {
|
|
175
|
+
const product = 'vault-guard';
|
|
176
|
+
const root = needRecord(raw, product, 'the output');
|
|
177
|
+
const run = root.run === undefined ? {} : needRecord(root.run, product, 'run');
|
|
178
|
+
// run.blocking_matches, never summary.secrets. vault-guard's own type
|
|
179
|
+
// documentation says integrators gating a build must read the former,
|
|
180
|
+
// because the latter ignores the threshold. A sibling tool in this family
|
|
181
|
+
// read summary.secrets and that is the bug not to copy.
|
|
182
|
+
const threshold = optionalString(run.fail_on, product, 'run.fail_on') ?? null;
|
|
183
|
+
const diagnostics = [];
|
|
184
|
+
const findings = [];
|
|
185
|
+
const results = needArray(root.results, product, 'results');
|
|
186
|
+
for (const [fileIndex, rawEntry] of results.entries()) {
|
|
187
|
+
const entryWhere = `results[${fileIndex}]`;
|
|
188
|
+
const entry = needRecord(rawEntry, product, entryWhere);
|
|
189
|
+
const file = needString(entry.file, product, `${entryWhere}.file`);
|
|
190
|
+
const matches = entry.matches === undefined
|
|
191
|
+
? []
|
|
192
|
+
: needArray(entry.matches, product, `${entryWhere}.matches`);
|
|
193
|
+
for (const [matchIndex, rawMatch] of matches.entries()) {
|
|
194
|
+
const where = `${entryWhere}.matches[${matchIndex}]`;
|
|
195
|
+
const match = needRecord(rawMatch, product, where);
|
|
196
|
+
const type = needString(match.type, product, `${where}.type`);
|
|
197
|
+
const severity = needString(match.severity, product, `${where}.severity`);
|
|
198
|
+
const line = needNumber(match.line, product, `${where}.line`);
|
|
199
|
+
const column = needNumber(match.column, product, `${where}.column`);
|
|
200
|
+
const known = ['critical', 'high', 'medium', 'low'].includes(severity);
|
|
201
|
+
findings.push({
|
|
202
|
+
schemaVersion: 1,
|
|
203
|
+
product,
|
|
204
|
+
productVersion: version,
|
|
205
|
+
// `type` is an open vocabulary: a user's own extra_patterns choose
|
|
206
|
+
// their own ids, which is exactly why the namespace is not optional.
|
|
207
|
+
ruleId: `vault-guard/${type}`,
|
|
208
|
+
// Unknown levels land on info rather than being passed through, so
|
|
209
|
+
// a downstream consumer never sees a level outside the union. An
|
|
210
|
+
// unrecognised level is the umbrella's guess, hence derived.
|
|
211
|
+
severity: known ? severity : 'info',
|
|
212
|
+
severityIsDerived: !known,
|
|
213
|
+
blocking: false,
|
|
214
|
+
// The JSON output carries no message at all. This is vault-guard's
|
|
215
|
+
// own SARIF template, so the wording comes from the product rather
|
|
216
|
+
// than from here.
|
|
217
|
+
message: `Possible secret of type '${type}'`,
|
|
218
|
+
subject: {
|
|
219
|
+
kind: 'location',
|
|
220
|
+
file,
|
|
221
|
+
line,
|
|
222
|
+
// The JSON column is 0-based and the envelope's is 1-based. The
|
|
223
|
+
// product's own SARIF does the same conversion; doing it here too
|
|
224
|
+
// is what makes one shared mapping possible.
|
|
225
|
+
column: column + 1,
|
|
226
|
+
// No endColumn. vault-guard DOES know the match length: it hashes
|
|
227
|
+
// it into the fingerprint and puts an end column in its own SARIF.
|
|
228
|
+
// What it omits is matchLength on the match object in the JSON
|
|
229
|
+
// output, which is the channel the umbrella reads. So the end of
|
|
230
|
+
// the match is unknown from THIS CHANNEL rather than unknown to
|
|
231
|
+
// the product, which makes it a fixable upstream ask (carry
|
|
232
|
+
// matchLength on the match) rather than a permanent limitation.
|
|
233
|
+
// Until it is carried, it is not guessed.
|
|
234
|
+
},
|
|
235
|
+
fingerprint: {
|
|
236
|
+
value: needString(match.fingerprint, product, `${where}.fingerprint`),
|
|
237
|
+
scope: product,
|
|
238
|
+
// Hashed over the relative path, the type, the line, the offset,
|
|
239
|
+
// and the match length. Inserting an unrelated line above a
|
|
240
|
+
// secret changes it, so a baseline entry expires on the next edit.
|
|
241
|
+
stability: 'positional',
|
|
242
|
+
},
|
|
243
|
+
// The passthrough half. These are not required: they are carried,
|
|
244
|
+
// not mapped, so a gate that stops emitting one should not turn
|
|
245
|
+
// into a blocked commit.
|
|
246
|
+
details: {
|
|
247
|
+
type,
|
|
248
|
+
severity,
|
|
249
|
+
line,
|
|
250
|
+
// Spelled with its base in the key. This bag is carried, not
|
|
251
|
+
// mapped, so the number stays the gate's own 0-based one; calling
|
|
252
|
+
// it "column" put it next to a 1-based SARIF startColumn in the
|
|
253
|
+
// same result, where it read as an off-by-one in this tool rather
|
|
254
|
+
// than as two different conventions side by side. Renaming the key
|
|
255
|
+
// says which is which without rewriting a gate's own output into
|
|
256
|
+
// units that gate never used.
|
|
257
|
+
columnZeroBased: column,
|
|
258
|
+
offset: match.offset ?? null,
|
|
259
|
+
// Already redacted at the source, so it is safe to carry.
|
|
260
|
+
value: match.value ?? null,
|
|
261
|
+
},
|
|
262
|
+
});
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
reconcileBlocking(findings, typeof run.blocking_matches === 'number' ? run.blocking_matches : undefined, threshold, product, diagnostics);
|
|
266
|
+
return {
|
|
267
|
+
findings,
|
|
268
|
+
run: {
|
|
269
|
+
failOn: threshold,
|
|
270
|
+
suppressed: typeof run.baseline_suppressed === 'number' ? run.baseline_suppressed : 0,
|
|
271
|
+
// vault-guard does not report an ignore count separately; ignored
|
|
272
|
+
// files never reach the output at all. Reporting 0 here would claim a
|
|
273
|
+
// fact the gate did not state, so the report says "not reported"
|
|
274
|
+
// instead, driven by this null.
|
|
275
|
+
ignored: 0,
|
|
276
|
+
// vault-guard's diagnostics carry a context object rather than a
|
|
277
|
+
// message, so the context is rendered as one. Validated the same way
|
|
278
|
+
// as everything else, since a malformed entry here would otherwise
|
|
279
|
+
// reach String() and produce "[object Object]" in a report.
|
|
280
|
+
diagnostics: root.diagnostics === undefined
|
|
281
|
+
? []
|
|
282
|
+
: needArray(root.diagnostics, product, 'diagnostics').map((entry, index) => {
|
|
283
|
+
const where = `diagnostics[${index}]`;
|
|
284
|
+
const record = needRecord(entry, product, where);
|
|
285
|
+
return {
|
|
286
|
+
code: needString(record.code, product, `${where}.code`),
|
|
287
|
+
message: JSON.stringify(record.ctx ?? {}),
|
|
288
|
+
};
|
|
289
|
+
}),
|
|
290
|
+
details: {
|
|
291
|
+
filesScanned: run.files_scanned ?? null,
|
|
292
|
+
patternsActive: run.patterns_active ?? null,
|
|
293
|
+
ignoredReported: false,
|
|
294
|
+
},
|
|
295
|
+
},
|
|
296
|
+
diagnostics,
|
|
297
|
+
};
|
|
298
|
+
}
|
|
299
|
+
// -- intent-guard ---------------------------------------------------------
|
|
300
|
+
/**
|
|
301
|
+
* intent-guard has no per-finding severity, so every level below is the
|
|
302
|
+
* umbrella's invention and every finding it produces carries
|
|
303
|
+
* severityIsDerived: true. The product's own action string is kept in
|
|
304
|
+
* `details` so a consumer can ignore this mapping entirely.
|
|
305
|
+
*/
|
|
306
|
+
const BUDGET_SEVERITY = {
|
|
307
|
+
hard_block: 'critical',
|
|
308
|
+
soft_block: 'high',
|
|
309
|
+
};
|
|
310
|
+
const DRIFT_SEVERITY = {
|
|
311
|
+
hard_block: 'critical',
|
|
312
|
+
soft_block: 'high',
|
|
313
|
+
warn: 'medium',
|
|
314
|
+
info: 'low',
|
|
315
|
+
proceed: 'info',
|
|
316
|
+
};
|
|
317
|
+
/**
|
|
318
|
+
* The three ways the intent gate can block on the STATE of the contract
|
|
319
|
+
* rather than on anything in the diff.
|
|
320
|
+
*
|
|
321
|
+
* These matter because the gate pushes them into the same `reasons` array as
|
|
322
|
+
* its budget and drift reasons, and exposes no structured field saying which
|
|
323
|
+
* is which. So a run with an unfrozen contract AND a budget violation used
|
|
324
|
+
* to report only the budget violation: the reason the commit could not be
|
|
325
|
+
* fixed by editing the diff was in neither report.
|
|
326
|
+
*
|
|
327
|
+
* The prefixes are copied from intent-guard's own gate.ts. They are matched
|
|
328
|
+
* as prefixes rather than whole strings because one of the three
|
|
329
|
+
* interpolates an error message, and they are enumerated in a test against
|
|
330
|
+
* the real strings, so an upstream rewording turns that test red instead of
|
|
331
|
+
* silently dropping a reason out of every report.
|
|
332
|
+
*/
|
|
333
|
+
export const GATE_STATE_REASON_KINDS = [
|
|
334
|
+
'contract-invalid',
|
|
335
|
+
'contract-missing',
|
|
336
|
+
'contract-unfrozen',
|
|
337
|
+
];
|
|
338
|
+
const GATE_STATE_REASON_PREFIXES = [
|
|
339
|
+
['Intent contract is invalid:', 'contract-invalid'],
|
|
340
|
+
['No .conductor/intent-contract.yaml found', 'contract-missing'],
|
|
341
|
+
['Intent contract exists but is not frozen', 'contract-unfrozen'],
|
|
342
|
+
];
|
|
343
|
+
/** Which gate-state reason this is, or null when it is a budget or drift reason. */
|
|
344
|
+
export function classifyGateStateReason(reason) {
|
|
345
|
+
for (const [prefix, kind] of GATE_STATE_REASON_PREFIXES) {
|
|
346
|
+
if (reason.startsWith(prefix)) {
|
|
347
|
+
return kind;
|
|
348
|
+
}
|
|
349
|
+
}
|
|
350
|
+
return null;
|
|
351
|
+
}
|
|
352
|
+
export function normalizeIntentGuard(raw, version) {
|
|
353
|
+
const product = 'intent-guard';
|
|
354
|
+
const root = needRecord(raw, product, 'the output');
|
|
355
|
+
if (root.status !== 'blocked' && root.status !== 'ok') {
|
|
356
|
+
fail(product, 'status', 'either "ok" or "blocked"');
|
|
357
|
+
}
|
|
358
|
+
const findings = [];
|
|
359
|
+
const budget = root.budget === undefined ? undefined : needRecord(root.budget, product, 'budget');
|
|
360
|
+
const drift = root.drift === undefined ? undefined : needRecord(root.drift, product, 'drift');
|
|
361
|
+
// Budget violations. The gate raises one reason per violation and blocks
|
|
362
|
+
// when it has any reason at all, so every violation is blocking. That is
|
|
363
|
+
// read off the gate's own composition rule, not off a severity ladder.
|
|
364
|
+
const violations = budget?.violations === undefined
|
|
365
|
+
? []
|
|
366
|
+
: needArray(budget.violations, product, 'budget.violations');
|
|
367
|
+
for (const [index, rawViolation] of violations.entries()) {
|
|
368
|
+
const where = `budget.violations[${index}]`;
|
|
369
|
+
const violation = needRecord(rawViolation, product, where);
|
|
370
|
+
const rule = needString(violation.rule, product, `${where}.rule`);
|
|
371
|
+
const severity = needString(violation.severity, product, `${where}.severity`);
|
|
372
|
+
const matched = violation.matched === undefined
|
|
373
|
+
? []
|
|
374
|
+
: needStringArray(violation.matched, product, `${where}.matched`);
|
|
375
|
+
findings.push({
|
|
376
|
+
schemaVersion: 1,
|
|
377
|
+
product,
|
|
378
|
+
productVersion: version,
|
|
379
|
+
ruleId: `intent-guard/budget.${rule}`,
|
|
380
|
+
severity: BUDGET_SEVERITY[severity] ?? 'info',
|
|
381
|
+
severityIsDerived: true,
|
|
382
|
+
blocking: true,
|
|
383
|
+
message: needString(violation.message, product, `${where}.message`),
|
|
384
|
+
subject: { kind: 'paths', paths: matched },
|
|
385
|
+
fingerprint: {
|
|
386
|
+
value: needString(violation.fingerprint, product, `${where}.fingerprint`),
|
|
387
|
+
scope: product,
|
|
388
|
+
// Hashed over the contract id, the rule, and the sorted normalized
|
|
389
|
+
// matched paths. Order-independent and position-free.
|
|
390
|
+
stability: 'stable',
|
|
391
|
+
},
|
|
392
|
+
details: { rule, severity, matched },
|
|
393
|
+
});
|
|
394
|
+
}
|
|
395
|
+
// Drift findings. 1.2.0 gave these stable fingerprints and a bounded
|
|
396
|
+
// rule_id, which is what makes one finding per entry honest; before that
|
|
397
|
+
// they were bare prose strings and the only truthful rendering was a
|
|
398
|
+
// single synthetic finding for the whole run.
|
|
399
|
+
//
|
|
400
|
+
// The blocking decision is the SCORE's, not the finding's: the gate
|
|
401
|
+
// raises one drift reason for the overall action and none per finding, so
|
|
402
|
+
// a finding is blocking exactly when the overall action blocks.
|
|
403
|
+
const driftAction = optionalString(drift?.action, product, 'drift.action') ?? 'proceed';
|
|
404
|
+
const driftBlocks = driftAction === 'soft_block' || driftAction === 'hard_block';
|
|
405
|
+
const driftDetails = drift?.finding_details === undefined
|
|
406
|
+
? []
|
|
407
|
+
: needArray(drift.finding_details, product, 'drift.finding_details');
|
|
408
|
+
for (const [index, rawDetail] of driftDetails.entries()) {
|
|
409
|
+
const where = `drift.finding_details[${index}]`;
|
|
410
|
+
const detail = needRecord(rawDetail, product, where);
|
|
411
|
+
const category = needString(detail.category, product, `${where}.category`);
|
|
412
|
+
findings.push({
|
|
413
|
+
schemaVersion: 1,
|
|
414
|
+
product,
|
|
415
|
+
productVersion: version,
|
|
416
|
+
// The category, not rule_id: rule_id can carry contract prose, and a
|
|
417
|
+
// rule id that contains a user's sentence is not a rule id. The full
|
|
418
|
+
// value goes in details.
|
|
419
|
+
ruleId: `intent-guard/drift.${category}`,
|
|
420
|
+
severity: DRIFT_SEVERITY[driftAction] ?? 'info',
|
|
421
|
+
severityIsDerived: true,
|
|
422
|
+
blocking: driftBlocks,
|
|
423
|
+
message: needString(detail.message, product, `${where}.message`),
|
|
424
|
+
// No paths subject: `matched` here is "tokens or paths", so treating
|
|
425
|
+
// it as a path list would sometimes point at a file that does not
|
|
426
|
+
// exist. It stays in details, where it is not claiming to be a location.
|
|
427
|
+
subject: { kind: 'contract', category },
|
|
428
|
+
fingerprint: {
|
|
429
|
+
value: needString(detail.fingerprint, product, `${where}.fingerprint`),
|
|
430
|
+
scope: product,
|
|
431
|
+
stability: 'stable',
|
|
432
|
+
},
|
|
433
|
+
details: {
|
|
434
|
+
ruleId: detail.rule_id ?? null,
|
|
435
|
+
category,
|
|
436
|
+
matched: detail.matched ?? [],
|
|
437
|
+
},
|
|
438
|
+
});
|
|
439
|
+
}
|
|
440
|
+
// The gate can block for a reason that is neither a budget violation nor
|
|
441
|
+
// drift: no contract, an unfrozen contract, an unreadable one. Those
|
|
442
|
+
// arrive only as prose in `reasons`, mixed in with the budget and drift
|
|
443
|
+
// reasons and with no structured field separating them.
|
|
444
|
+
//
|
|
445
|
+
// One finding PER gate-state reason, and always, not only when nothing
|
|
446
|
+
// else blocked. The old rule ("only when nothing else is blocking") meant
|
|
447
|
+
// a run with both an unfrozen contract and a budget violation reported
|
|
448
|
+
// only the budget violation, hiding the one problem the user could not fix
|
|
449
|
+
// by editing the diff.
|
|
450
|
+
const reasons = root.reasons === undefined ? [] : needStringArray(root.reasons, product, 'reasons');
|
|
451
|
+
function gateBlocked(message, kind) {
|
|
452
|
+
return {
|
|
453
|
+
schemaVersion: 1,
|
|
454
|
+
product,
|
|
455
|
+
productVersion: version,
|
|
456
|
+
ruleId: 'intent-guard/gate-blocked',
|
|
457
|
+
severity: 'critical',
|
|
458
|
+
severityIsDerived: true,
|
|
459
|
+
blocking: true,
|
|
460
|
+
message,
|
|
461
|
+
subject: { kind: 'none' },
|
|
462
|
+
// No fingerprint: the product mints none for a gate-state block, and
|
|
463
|
+
// inventing one would produce an id no baseline anywhere contains.
|
|
464
|
+
fingerprint: null,
|
|
465
|
+
details: {
|
|
466
|
+
kind,
|
|
467
|
+
reasons,
|
|
468
|
+
contractFound: root.contractFound ?? null,
|
|
469
|
+
contractFrozen: root.contractFrozen ?? null,
|
|
470
|
+
},
|
|
471
|
+
};
|
|
472
|
+
}
|
|
473
|
+
if (root.status === 'blocked') {
|
|
474
|
+
const gateStateReasons = reasons
|
|
475
|
+
.map((reason) => ({ reason, kind: classifyGateStateReason(reason) }))
|
|
476
|
+
.filter((entry) => entry.kind !== null);
|
|
477
|
+
for (const entry of gateStateReasons) {
|
|
478
|
+
findings.push(gateBlocked(entry.reason, entry.kind));
|
|
479
|
+
}
|
|
480
|
+
// The backstop, unchanged in spirit: a blocked gate with nothing blocking
|
|
481
|
+
// in the report reads as a bug in the umbrella and hides the one thing
|
|
482
|
+
// the user needs to see. It fires only when no gate-state reason was
|
|
483
|
+
// recognised AND nothing else blocked, so it never doubles up with the
|
|
484
|
+
// findings above, and it never invents a contract complaint the gate did
|
|
485
|
+
// not make (a contract left unfrozen under --no-require-frozen is not a
|
|
486
|
+
// reason, and must not become one here).
|
|
487
|
+
if (gateStateReasons.length === 0 && !findings.some((finding) => finding.blocking)) {
|
|
488
|
+
findings.push(gateBlocked(reasons.length > 0
|
|
489
|
+
? reasons.join(' ')
|
|
490
|
+
: 'The intent gate blocked without stating a reason.', 'unattributed'));
|
|
491
|
+
}
|
|
492
|
+
}
|
|
493
|
+
return {
|
|
494
|
+
findings,
|
|
495
|
+
run: {
|
|
496
|
+
// intent-guard has no threshold flag and no reported threshold: its
|
|
497
|
+
// drift thresholds live in its own config file and its budget rules
|
|
498
|
+
// have no threshold at all.
|
|
499
|
+
failOn: null,
|
|
500
|
+
suppressed: 0,
|
|
501
|
+
ignored: 0,
|
|
502
|
+
diagnostics: [],
|
|
503
|
+
details: {
|
|
504
|
+
contractFound: root.contractFound ?? null,
|
|
505
|
+
contractFrozen: root.contractFrozen ?? null,
|
|
506
|
+
driftOverall: typeof drift?.overall === 'number' ? drift.overall : null,
|
|
507
|
+
driftAction,
|
|
508
|
+
driftCategories: drift?.categories ?? null,
|
|
509
|
+
budgetAction: budget?.action ?? null,
|
|
510
|
+
reasons,
|
|
511
|
+
},
|
|
512
|
+
},
|
|
513
|
+
diagnostics: [],
|
|
514
|
+
};
|
|
515
|
+
}
|
|
516
|
+
function gateProblem(ruleId, role, product, message, details) {
|
|
517
|
+
return {
|
|
518
|
+
schemaVersion: 1,
|
|
519
|
+
product: 'conductor',
|
|
520
|
+
productVersion: null,
|
|
521
|
+
ruleId,
|
|
522
|
+
severity: 'critical',
|
|
523
|
+
severityIsDerived: true,
|
|
524
|
+
blocking: true,
|
|
525
|
+
message,
|
|
526
|
+
// No location: none of these is somewhere in the tree.
|
|
527
|
+
subject: { kind: 'none' },
|
|
528
|
+
fingerprint: {
|
|
529
|
+
// Deterministic over the rule, the role, and the product, and NOT over
|
|
530
|
+
// the message: a repeat run is the same alert rather than a new one
|
|
531
|
+
// every commit, and a reworded detail is not a new problem.
|
|
532
|
+
value: createHash('sha256').update(`${ruleId}|${role}|${product}`).digest('hex'),
|
|
533
|
+
scope: 'conductor',
|
|
534
|
+
stability: 'stable',
|
|
535
|
+
},
|
|
536
|
+
details: { role, product, ...details },
|
|
537
|
+
};
|
|
538
|
+
}
|
|
539
|
+
/**
|
|
540
|
+
* The finding raised when an ENABLED gate's binary cannot be found.
|
|
541
|
+
*
|
|
542
|
+
* A gate that is switched on and silently does not run is the failure this
|
|
543
|
+
* whole family exists to prevent: the report reads clean because nothing
|
|
544
|
+
* looked. So it is a finding, it blocks, and it says which names were
|
|
545
|
+
* tried, so the fix is in the message rather than in a support thread.
|
|
546
|
+
*/
|
|
547
|
+
export function normalizeMissingGate(role, product, candidates) {
|
|
548
|
+
return gateProblem('conductor/gate-missing', role, product, `The "${role}" gate is enabled but no ${product} binary was found. ` +
|
|
549
|
+
`Looked for: ${candidates.join(', ')}. Install it, point the gate at a build with an ` +
|
|
550
|
+
`absolute "command:", or set enabled: false to switch the gate off on purpose.`, { candidates });
|
|
551
|
+
}
|
|
552
|
+
/**
|
|
553
|
+
* The finding raised when a gate's `command:` names a file that is not
|
|
554
|
+
* there.
|
|
555
|
+
*
|
|
556
|
+
* It names ONLY that path. The candidate list belongs to resolution, and
|
|
557
|
+
* resolution never happened here: the user pointed at one specific file, so
|
|
558
|
+
* listing the names the umbrella would otherwise have searched for suggests
|
|
559
|
+
* it looked for them and implies the fix is to install one of them, when
|
|
560
|
+
* the fix is in their policy file.
|
|
561
|
+
*/
|
|
562
|
+
export function normalizeMisconfiguredGate(role, product, command, detail) {
|
|
563
|
+
return gateProblem('conductor/gate-missing', role, product, `The "${role}" gate points at "${command}", which the umbrella could not run: ${detail}`, { command });
|
|
564
|
+
}
|
|
565
|
+
/**
|
|
566
|
+
* The finding raised when a gate answered but the umbrella could not read
|
|
567
|
+
* the answer: invalid JSON, a shape the normalizer does not know, or any
|
|
568
|
+
* unexpected error thrown while normalizing.
|
|
569
|
+
*
|
|
570
|
+
* `detail` is an error MESSAGE, never a stack. A stack would put a local
|
|
571
|
+
* filesystem path into a report that gets uploaded, and it would tell the
|
|
572
|
+
* user nothing they can act on.
|
|
573
|
+
*/
|
|
574
|
+
export function normalizeUnparseableGate(role, product, detail) {
|
|
575
|
+
return gateProblem('conductor/gate-output-unparseable', role, product, `The "${role}" gate ran but the umbrella could not read its output: ${detail} ` +
|
|
576
|
+
'This is the umbrella being out of date with that gate, not a problem in your code. ' +
|
|
577
|
+
'Nothing was verified by this gate.', { detail });
|
|
578
|
+
}
|
|
579
|
+
/** The finding raised when a gate could not be run or did not complete. */
|
|
580
|
+
export function normalizeFailedGate(role, product, detail) {
|
|
581
|
+
return gateProblem('conductor/gate-failed', role, product, `The "${role}" gate did not complete: ${detail} Nothing was verified by this gate.`, { detail });
|
|
582
|
+
}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import type { RunResult } from './run.js';
|
|
2
|
+
export declare const UMBRELLA_DRIVER_NAME = "conductor";
|
|
3
|
+
/** The partialFingerprints key for a product's own fingerprint. */
|
|
4
|
+
export declare function fingerprintKey(scope: string): string;
|
|
5
|
+
export type ArtifactPlacement =
|
|
6
|
+
/** Inside the source root: relative uri under %SRCROOT%. */
|
|
7
|
+
{
|
|
8
|
+
placement: 'in-root';
|
|
9
|
+
uri: string;
|
|
10
|
+
}
|
|
11
|
+
/** Known to be elsewhere: an absolute file uri with no uriBaseId. */
|
|
12
|
+
| {
|
|
13
|
+
placement: 'outside-root';
|
|
14
|
+
uri: string;
|
|
15
|
+
}
|
|
16
|
+
/** Unresolvable from here: no physical location at all. */
|
|
17
|
+
| {
|
|
18
|
+
placement: 'unresolvable';
|
|
19
|
+
};
|
|
20
|
+
/**
|
|
21
|
+
* Decides how one path can honestly be named in SARIF.
|
|
22
|
+
*
|
|
23
|
+
* Exported so the rules above can be tested directly rather than only
|
|
24
|
+
* through a whole rendered log.
|
|
25
|
+
*/
|
|
26
|
+
export declare function placeArtifact(rawPath: string): ArtifactPlacement;
|
|
27
|
+
/**
|
|
28
|
+
* Renders a whole run as one SARIF log.
|
|
29
|
+
*
|
|
30
|
+
* `umbrellaVersion` names this package's own version, used only for the
|
|
31
|
+
* umbrella's own run. Passed in rather than read from disk so this module
|
|
32
|
+
* stays free of filesystem access.
|
|
33
|
+
*/
|
|
34
|
+
export declare function renderSarif(result: RunResult, umbrellaVersion: string): string;
|