@vaultcompass/conductor 0.4.7 → 0.6.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 +658 -145
- package/dist/cli.js +185 -46
- package/dist/envelope.js +1 -1
- package/dist/exit-codes.js +5 -1
- package/dist/external-config.d.ts +54 -0
- package/dist/external-config.js +171 -0
- package/dist/gate-runner.d.ts +43 -3
- package/dist/gate-runner.js +474 -38
- package/dist/init-policy.d.ts +19 -1
- package/dist/init-policy.js +42 -8
- package/dist/init.d.ts +30 -1
- package/dist/init.js +108 -19
- package/dist/normalize.d.ts +19 -2
- package/dist/normalize.js +444 -11
- package/dist/output-sarif.js +61 -2
- package/dist/output-text.d.ts +26 -0
- package/dist/output-text.js +91 -20
- package/dist/policy.d.ts +10 -4
- package/dist/policy.js +100 -14
- package/dist/products.d.ts +107 -0
- package/dist/products.js +132 -0
- package/dist/resolve.js +18 -4
- package/dist/run.d.ts +40 -0
- package/dist/run.js +42 -1
- package/dist/trust-base.d.ts +68 -0
- package/dist/trust-base.js +152 -0
- package/package.json +4 -3
- package/schema/guardrails.schema.json +7 -5
package/dist/normalize.js
CHANGED
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
// Turning each gate's own JSON into the internal envelope.
|
|
2
2
|
//
|
|
3
|
-
//
|
|
4
|
-
//
|
|
5
|
-
//
|
|
6
|
-
//
|
|
7
|
-
//
|
|
3
|
+
// Separate functions rather than one table-driven mapper, because the
|
|
4
|
+
// shapes disagree in ways a table would have to paper over: one is a flat
|
|
5
|
+
// findings array, one is nested by file, the third is two different streams
|
|
6
|
+
// (a change-budget evaluation and a scored drift rubric) plus a gate status
|
|
7
|
+
// that can block for neither reason, and the two external tools' reports
|
|
8
|
+
// (gitleaks, osv-scanner) carry no blocking flag at all, so whether they
|
|
9
|
+
// block comes from the exit code the runner read.
|
|
8
10
|
//
|
|
9
11
|
// What every one of them refuses to do, in one place so it is reviewable:
|
|
10
12
|
// invent a line number, invent a fingerprint, re-derive a severity a
|
|
@@ -112,13 +114,42 @@ function readDiagnostics(value, product, where) {
|
|
|
112
114
|
};
|
|
113
115
|
});
|
|
114
116
|
}
|
|
115
|
-
|
|
117
|
+
function readOnlineInfo(value) {
|
|
118
|
+
if (!isRecord(value)) {
|
|
119
|
+
return null;
|
|
120
|
+
}
|
|
121
|
+
const info = {};
|
|
122
|
+
if (value.enabled !== undefined) {
|
|
123
|
+
if (typeof value.enabled !== 'boolean') {
|
|
124
|
+
return null;
|
|
125
|
+
}
|
|
126
|
+
info.enabled = value.enabled;
|
|
127
|
+
}
|
|
128
|
+
if (value.lookupsAttempted !== undefined) {
|
|
129
|
+
if (typeof value.lookupsAttempted !== 'number' || !Number.isFinite(value.lookupsAttempted)) {
|
|
130
|
+
return null;
|
|
131
|
+
}
|
|
132
|
+
info.lookupsAttempted = value.lookupsAttempted;
|
|
133
|
+
}
|
|
134
|
+
if (value.lookupsSkippedByDeadline !== undefined) {
|
|
135
|
+
if (typeof value.lookupsSkippedByDeadline !== 'number' ||
|
|
136
|
+
!Number.isFinite(value.lookupsSkippedByDeadline)) {
|
|
137
|
+
return null;
|
|
138
|
+
}
|
|
139
|
+
info.lookupsSkippedByDeadline = value.lookupsSkippedByDeadline;
|
|
140
|
+
}
|
|
141
|
+
return info;
|
|
142
|
+
}
|
|
143
|
+
export function normalizeDepGuard(raw, version,
|
|
144
|
+
/** Whether the umbrella passed --online to dep-guard, read from its own argv. */
|
|
145
|
+
onlineRequested = false) {
|
|
116
146
|
const product = 'dep-guard';
|
|
117
147
|
const root = needRecord(raw, product, 'the output');
|
|
118
148
|
const run = needRecord(root.run, product, 'run');
|
|
119
149
|
const threshold = optionalString(run.failOn, product, 'run.failOn') ?? null;
|
|
120
150
|
const trustBase = readTrustBase(root.trustBase, product);
|
|
121
151
|
const diagnostics = [];
|
|
152
|
+
const onlineInfo = readOnlineInfo(run.online);
|
|
122
153
|
const findings = needArray(root.findings, product, 'findings').map((entry, index) => {
|
|
123
154
|
const where = `findings[${index}]`;
|
|
124
155
|
const source = needRecord(entry, product, where);
|
|
@@ -165,12 +196,34 @@ export function normalizeDepGuard(raw, version) {
|
|
|
165
196
|
suppressed: typeof root.suppressed === 'number' ? root.suppressed : 0,
|
|
166
197
|
ignored: typeof root.ignored === 'number' ? root.ignored : 0,
|
|
167
198
|
// Diagnostics never move dep-guard's own exit code, so they stay out
|
|
168
|
-
// of findings[] here too rather than becoming pseudo-findings.
|
|
199
|
+
// of findings[] here too rather than becoming pseudo-findings. An
|
|
200
|
+
// installed dep-guard old enough to have no `run.online` object, or
|
|
201
|
+
// one whose online object says the budget ran out, raises its own
|
|
202
|
+
// online-deadline-exceeded diagnostic here, and it is carried through
|
|
203
|
+
// unchanged rather than the umbrella minting a second note about the
|
|
204
|
+
// same event (issue #72 fix round: dep-guard's own diagnostic already
|
|
205
|
+
// names the count, so nothing here duplicates it).
|
|
169
206
|
diagnostics: readDiagnostics(run.diagnostics, product, 'run.diagnostics'),
|
|
170
207
|
details: {
|
|
171
208
|
mode: run.mode ?? null,
|
|
172
209
|
corpusBuiltAt: run.corpusBuiltAt ?? null,
|
|
173
210
|
lockfileFormat: run.lockfileFormat ?? null,
|
|
211
|
+
// dep-guard's own `enabled` claim wins whenever the online object is
|
|
212
|
+
// present and valid: dep-guard can turn online checks on from
|
|
213
|
+
// ".dep-guard.json"'s own "online" key with no flag at all, so the
|
|
214
|
+
// umbrella's argv does not always know the true answer. Only when
|
|
215
|
+
// there is no trustworthy claim to read does this fall back to
|
|
216
|
+
// stating what the umbrella itself asked for, worded so it is never
|
|
217
|
+
// mistaken for a claim about what dep-guard actually did.
|
|
218
|
+
...(onlineInfo?.enabled === undefined
|
|
219
|
+
? { 'online-flag': onlineRequested ? 'passed' : 'not passed' }
|
|
220
|
+
: { online: onlineInfo.enabled }),
|
|
221
|
+
...(onlineInfo?.lookupsAttempted === undefined
|
|
222
|
+
? {}
|
|
223
|
+
: { lookups: onlineInfo.lookupsAttempted }),
|
|
224
|
+
...(onlineInfo?.lookupsSkippedByDeadline === undefined
|
|
225
|
+
? {}
|
|
226
|
+
: { 'skipped-by-deadline': onlineInfo.lookupsSkippedByDeadline }),
|
|
174
227
|
},
|
|
175
228
|
},
|
|
176
229
|
diagnostics,
|
|
@@ -329,6 +382,57 @@ const DRIFT_SEVERITY = {
|
|
|
329
382
|
info: 'low',
|
|
330
383
|
proceed: 'info',
|
|
331
384
|
};
|
|
385
|
+
/**
|
|
386
|
+
* intent-guard's own namespace for its advance-notice warnings, not the
|
|
387
|
+
* umbrella's: the umbrella never mints a `conductor/` id for this, because
|
|
388
|
+
* the statement being relayed is entirely intent-guard's own (see AGENTS.md
|
|
389
|
+
* on the umbrella's fixed set of ids).
|
|
390
|
+
*/
|
|
391
|
+
export const INTENT_WARNING = 'intent-guard/warning';
|
|
392
|
+
/**
|
|
393
|
+
* intent-guard 1.7.0's own advance notice that a frozen contract's
|
|
394
|
+
* `protected_paths` or `allowed_paths` carries an entry no git path can
|
|
395
|
+
* ever match (a leading slash, an empty path segment, and the like), read
|
|
396
|
+
* from the optional `warnings` array. 1.7.0 warns about this; 2.0.0 turns it
|
|
397
|
+
* into a blocking reason (intent-guard's own budget-paths.ts).
|
|
398
|
+
*
|
|
399
|
+
* Tolerant on purpose, unlike everything else this file validates: this is
|
|
400
|
+
* reporting, never judgment, so a shape an installed intent-guard did not
|
|
401
|
+
* send correctly must never turn into a could-not-run for the gate. Absent
|
|
402
|
+
* (1.6.0 and earlier, which never sent this field) means none. A value that
|
|
403
|
+
* is not an array, or an array holding even one non-string entry, is
|
|
404
|
+
* ignored outright rather than partially read: half-reading it would print
|
|
405
|
+
* some warnings and silently drop others, which is worse than saying
|
|
406
|
+
* nothing until the shape is understood again.
|
|
407
|
+
*/
|
|
408
|
+
function readIntentWarnings(raw) {
|
|
409
|
+
if (!Array.isArray(raw)) {
|
|
410
|
+
return [];
|
|
411
|
+
}
|
|
412
|
+
return raw.every((entry) => typeof entry === 'string') ? raw : [];
|
|
413
|
+
}
|
|
414
|
+
/**
|
|
415
|
+
* intent-guard 1.6.0 (issue #34) caps a constraint finding at advisory when
|
|
416
|
+
* its `source` is a prose rules file (CLAUDE.md, AGENTS.md, GEMINI.md,
|
|
417
|
+
* cursor rules): a strong match is still reported, but it never raises
|
|
418
|
+
* `constraint_violation`, `criticalViolated`, or the gate's own exit code.
|
|
419
|
+
*
|
|
420
|
+
* `finding_details` carries no field saying so. `strength` is "strong" for a
|
|
421
|
+
* capped prose match exactly the same as an uncapped one, and the
|
|
422
|
+
* constraint's `source` is never carried onto the finding at all. The ONLY
|
|
423
|
+
* surviving signal is this literal prefix, which intent-guard's own drift.ts
|
|
424
|
+
* puts on the message for this one case.
|
|
425
|
+
*
|
|
426
|
+
* THIS IS NOT A SAFETY NET. Nothing in this repository detects an upstream
|
|
427
|
+
* rewording of that prefix: there is no test against the live binary, only
|
|
428
|
+
* a static fixture capture, so a wording change in a future intent-guard
|
|
429
|
+
* release would silently stop matching here and a capped finding would go
|
|
430
|
+
* back to rendering as blocking with no warning anywhere in this report or
|
|
431
|
+
* in CI. Filed upstream as intent-guard #114, asking for a machine-readable
|
|
432
|
+
* per-finding field so this can stop keying on message text; this constant
|
|
433
|
+
* is the interim measure until that lands, not a substitute for it.
|
|
434
|
+
*/
|
|
435
|
+
const ADVISORY_CONSTRAINT_PREFIX = 'advisory ';
|
|
332
436
|
/**
|
|
333
437
|
* The three ways the intent gate can block on the STATE of the contract
|
|
334
438
|
* rather than on anything in the diff.
|
|
@@ -430,6 +534,7 @@ export function normalizeIntentGuard(raw, version) {
|
|
|
430
534
|
fail(product, 'status', 'either "ok" or "blocked"');
|
|
431
535
|
}
|
|
432
536
|
const trustBase = readTrustBase(root.trustBase, product);
|
|
537
|
+
const warnings = readIntentWarnings(root.warnings);
|
|
433
538
|
const findings = [];
|
|
434
539
|
const budget = root.budget === undefined ? undefined : needRecord(root.budget, product, 'budget');
|
|
435
540
|
const drift = root.drift === undefined ? undefined : needRecord(root.drift, product, 'drift');
|
|
@@ -484,6 +589,11 @@ export function normalizeIntentGuard(raw, version) {
|
|
|
484
589
|
const where = `drift.finding_details[${index}]`;
|
|
485
590
|
const detail = needRecord(rawDetail, product, where);
|
|
486
591
|
const category = needString(detail.category, product, `${where}.category`);
|
|
592
|
+
const message = needString(detail.message, product, `${where}.message`);
|
|
593
|
+
// See ADVISORY_CONSTRAINT_PREFIX. A capped finding never contributed to
|
|
594
|
+
// driftAction, so it must not inherit that action's blocking flag or
|
|
595
|
+
// severity the way every other drift finding here does (issue #34).
|
|
596
|
+
const advisoryCapped = category === 'constraint_violation' && message.startsWith(ADVISORY_CONSTRAINT_PREFIX);
|
|
487
597
|
findings.push({
|
|
488
598
|
schemaVersion: 1,
|
|
489
599
|
product,
|
|
@@ -492,10 +602,10 @@ export function normalizeIntentGuard(raw, version) {
|
|
|
492
602
|
// rule id that contains a user's sentence is not a rule id. The full
|
|
493
603
|
// value goes in details.
|
|
494
604
|
ruleId: `intent-guard/drift.${category}`,
|
|
495
|
-
severity: DRIFT_SEVERITY[driftAction] ?? 'info',
|
|
605
|
+
severity: advisoryCapped ? 'low' : (DRIFT_SEVERITY[driftAction] ?? 'info'),
|
|
496
606
|
severityIsDerived: true,
|
|
497
|
-
blocking: driftBlocks,
|
|
498
|
-
message
|
|
607
|
+
blocking: advisoryCapped ? false : driftBlocks,
|
|
608
|
+
message,
|
|
499
609
|
// No paths subject: `matched` here is "tokens or paths", so treating
|
|
500
610
|
// it as a path list would sometimes point at a file that does not
|
|
501
611
|
// exist. It stays in details, where it is not claiming to be a location.
|
|
@@ -575,7 +685,10 @@ export function normalizeIntentGuard(raw, version) {
|
|
|
575
685
|
failOn: null,
|
|
576
686
|
suppressed: 0,
|
|
577
687
|
ignored: 0,
|
|
578
|
-
|
|
688
|
+
// intent-guard's own advance-notice warnings (1.7.0's budget-path
|
|
689
|
+
// deprecation notes). Reporting, never a finding: no severity, no
|
|
690
|
+
// fingerprint, no blocking flag, and no effect on the exit code.
|
|
691
|
+
diagnostics: warnings.map((message) => ({ code: INTENT_WARNING, message })),
|
|
579
692
|
details: {
|
|
580
693
|
contractFound: root.contractFound ?? null,
|
|
581
694
|
contractFrozen: root.contractFrozen ?? null,
|
|
@@ -589,6 +702,326 @@ export function normalizeIntentGuard(raw, version) {
|
|
|
589
702
|
diagnostics: [],
|
|
590
703
|
};
|
|
591
704
|
}
|
|
705
|
+
// -- gitleaks (external, git history mode) -------------------------------
|
|
706
|
+
//
|
|
707
|
+
// The report is a JSON array written to a file, one entry per leak, with
|
|
708
|
+
// the field names in tests/fixtures/README.md. gitleaks has no severity of
|
|
709
|
+
// its own: a rule matched or it did not. So every finding is `high`, marked
|
|
710
|
+
// derived, and whether it blocks comes from the exit code the runner read
|
|
711
|
+
// (3, the leak code the umbrella moves it to), not from anything in the
|
|
712
|
+
// entry.
|
|
713
|
+
//
|
|
714
|
+
// NEVER CARRIED: Secret, Match and Line. The umbrella passes --redact, but a
|
|
715
|
+
// report can be unredacted if a tool changes or a policy finds a way round
|
|
716
|
+
// it, and this report is posted to a pull request and uploaded as SARIF.
|
|
717
|
+
// Neither Email nor Author is carried: who made the commit has no bearing on
|
|
718
|
+
// fixing a leak, and a name or address would be published with it.
|
|
719
|
+
//
|
|
720
|
+
// ONE FINDING PER PLACE. The umbrella asks git for each merge's first-parent
|
|
721
|
+
// diff (--diff-merges=first-parent) so a secret added inside a merge is seen,
|
|
722
|
+
// and under an Actions-style merge that shows a pull request's change twice:
|
|
723
|
+
// in its own commit and in the merge. Entries sharing rule, file, line and
|
|
724
|
+
// column collapse to the one with the earliest Date (the last in report
|
|
725
|
+
// order on a tie or a missing date, since git log lists newest first), and
|
|
726
|
+
// the other commits are listed in details.alsoIn.
|
|
727
|
+
export function normalizeGitleaks(raw, version, blocked) {
|
|
728
|
+
const product = 'gitleaks';
|
|
729
|
+
const entries = needArray(raw, product, 'the report');
|
|
730
|
+
const byPlace = new Map();
|
|
731
|
+
entries.forEach((rawEntry, index) => {
|
|
732
|
+
const where = `report[${index}]`;
|
|
733
|
+
const entry = needRecord(rawEntry, product, where);
|
|
734
|
+
const rule = needString(entry.RuleID, product, `${where}.RuleID`);
|
|
735
|
+
const file = needString(entry.File, product, `${where}.File`);
|
|
736
|
+
const line = needNumber(entry.StartLine, product, `${where}.StartLine`);
|
|
737
|
+
// Carried as gitleaks reports them, which is also what its own SARIF
|
|
738
|
+
// output uses. gitleaks 8.30.1 column numbers are not consistently 0- or
|
|
739
|
+
// 1-based across findings (one token at character 21 was reported at 22,
|
|
740
|
+
// another at character 15 at 15), so no correction is applied.
|
|
741
|
+
const column = typeof entry.StartColumn === 'number' ? entry.StartColumn : 1;
|
|
742
|
+
const endColumn = typeof entry.EndColumn === 'number' ? entry.EndColumn : undefined;
|
|
743
|
+
const commit = optionalString(entry.Commit, product, `${where}.Commit`);
|
|
744
|
+
const date = optionalString(entry.Date, product, `${where}.Date`);
|
|
745
|
+
// gitleaks' own Fingerprint is commit:file:rule:line, identical across
|
|
746
|
+
// runs over the same history, so it is stable. Rebuilt in that shape if
|
|
747
|
+
// a report ever omits it.
|
|
748
|
+
const fingerprint = optionalString(entry.Fingerprint, product, `${where}.Fingerprint`) ??
|
|
749
|
+
`${commit ?? ''}:${file}:${rule}:${line}`;
|
|
750
|
+
const finding = {
|
|
751
|
+
schemaVersion: 1,
|
|
752
|
+
product,
|
|
753
|
+
productVersion: version,
|
|
754
|
+
ruleId: `gitleaks/${rule}`,
|
|
755
|
+
severity: 'high',
|
|
756
|
+
severityIsDerived: true,
|
|
757
|
+
blocking: blocked,
|
|
758
|
+
message: optionalString(entry.Description, product, `${where}.Description`) ?? `${rule} matched`,
|
|
759
|
+
subject: {
|
|
760
|
+
kind: 'location',
|
|
761
|
+
file,
|
|
762
|
+
line,
|
|
763
|
+
column,
|
|
764
|
+
...(endColumn === undefined ? {} : { endColumn }),
|
|
765
|
+
},
|
|
766
|
+
fingerprint: { value: fingerprint, scope: product, stability: 'stable' },
|
|
767
|
+
details: {
|
|
768
|
+
...(commit === undefined ? {} : { commit }),
|
|
769
|
+
...(date === undefined ? {} : { date }),
|
|
770
|
+
...(typeof entry.Entropy === 'number' ? { entropy: entry.Entropy } : {}),
|
|
771
|
+
...(Array.isArray(entry.Tags) ? { tags: entry.Tags } : {}),
|
|
772
|
+
},
|
|
773
|
+
};
|
|
774
|
+
const place = JSON.stringify([rule, file, line, column]);
|
|
775
|
+
const time = date === undefined ? Number.NaN : Date.parse(date);
|
|
776
|
+
const seen = byPlace.get(place);
|
|
777
|
+
if (seen === undefined) {
|
|
778
|
+
byPlace.set(place, { finding, time, alsoIn: [] });
|
|
779
|
+
return;
|
|
780
|
+
}
|
|
781
|
+
// The later entry replaces the kept one unless both dates are known and
|
|
782
|
+
// it is strictly newer. So an earlier date wins, and on a tie or a
|
|
783
|
+
// missing date the LAST entry in report order wins: git log lists newer
|
|
784
|
+
// commits first, so the last is the oldest, never a synthetic merge.
|
|
785
|
+
const bothDated = !Number.isNaN(time) && !Number.isNaN(seen.time);
|
|
786
|
+
const replace = !bothDated || time <= seen.time;
|
|
787
|
+
const dropped = replace ? seen.finding : finding;
|
|
788
|
+
const droppedCommit = dropped.details.commit;
|
|
789
|
+
if (replace) {
|
|
790
|
+
seen.finding = finding;
|
|
791
|
+
seen.time = time;
|
|
792
|
+
}
|
|
793
|
+
if (typeof droppedCommit === 'string') {
|
|
794
|
+
seen.alsoIn.push(droppedCommit);
|
|
795
|
+
}
|
|
796
|
+
});
|
|
797
|
+
const findings = [...byPlace.values()].map(({ finding, alsoIn }) => alsoIn.length === 0 ? finding : { ...finding, details: { ...finding.details, alsoIn } });
|
|
798
|
+
return {
|
|
799
|
+
findings,
|
|
800
|
+
run: {
|
|
801
|
+
// Any match fails the gate: gitleaks has no threshold to report.
|
|
802
|
+
failOn: 'any',
|
|
803
|
+
suppressed: 0,
|
|
804
|
+
ignored: 0,
|
|
805
|
+
diagnostics: [],
|
|
806
|
+
details: { entries: entries.length },
|
|
807
|
+
},
|
|
808
|
+
diagnostics: [],
|
|
809
|
+
};
|
|
810
|
+
}
|
|
811
|
+
// -- osv-scanner (external, known vulnerabilities) ------------------------
|
|
812
|
+
//
|
|
813
|
+
// `osv-scanner scan source --format json` prints results[] per lockfile,
|
|
814
|
+
// packages[] per resolved package, vulnerabilities[] per advisory, and
|
|
815
|
+
// groups[] that merge an advisory with its aliases and carry the highest
|
|
816
|
+
// CVSS base score among them as `max_severity`, a string. Every field read
|
|
817
|
+
// below was checked against the 2.6.0 capture (tests/fixtures/README.md).
|
|
818
|
+
/** CVSS base score onto the shared four-level ladder, by the CVSS v3 bands. */
|
|
819
|
+
export function cvssToSeverity(score) {
|
|
820
|
+
if (score === null || Number.isNaN(score)) {
|
|
821
|
+
return 'medium';
|
|
822
|
+
}
|
|
823
|
+
if (score >= 9) {
|
|
824
|
+
return 'critical';
|
|
825
|
+
}
|
|
826
|
+
if (score >= 7) {
|
|
827
|
+
return 'high';
|
|
828
|
+
}
|
|
829
|
+
if (score >= 4) {
|
|
830
|
+
return 'medium';
|
|
831
|
+
}
|
|
832
|
+
return 'low';
|
|
833
|
+
}
|
|
834
|
+
function osvScore(vuln, groups) {
|
|
835
|
+
const id = typeof vuln.id === 'string' ? vuln.id : '';
|
|
836
|
+
for (const group of groups) {
|
|
837
|
+
const ids = Array.isArray(group.ids) ? group.ids : [];
|
|
838
|
+
if (ids.includes(id) && typeof group.max_severity === 'string' && group.max_severity !== '') {
|
|
839
|
+
const score = Number(group.max_severity);
|
|
840
|
+
if (!Number.isNaN(score)) {
|
|
841
|
+
return score;
|
|
842
|
+
}
|
|
843
|
+
}
|
|
844
|
+
}
|
|
845
|
+
// No group score: fall back to the advisory database's own word, mapped
|
|
846
|
+
// to a representative score inside the matching band.
|
|
847
|
+
const specific = vuln.database_specific;
|
|
848
|
+
if (isRecord(specific) && typeof specific.severity === 'string') {
|
|
849
|
+
const word = specific.severity.toUpperCase();
|
|
850
|
+
if (word === 'CRITICAL')
|
|
851
|
+
return 9.5;
|
|
852
|
+
if (word === 'HIGH')
|
|
853
|
+
return 7.5;
|
|
854
|
+
if (word === 'MODERATE' || word === 'MEDIUM')
|
|
855
|
+
return 5;
|
|
856
|
+
if (word === 'LOW')
|
|
857
|
+
return 2;
|
|
858
|
+
}
|
|
859
|
+
return null;
|
|
860
|
+
}
|
|
861
|
+
/** Numeric parts of a version, for ordering; "0" and "4.0.0" both parse. */
|
|
862
|
+
function versionParts(value) {
|
|
863
|
+
return (value.match(/\d+/g) ?? []).map(Number);
|
|
864
|
+
}
|
|
865
|
+
function compareVersions(a, b) {
|
|
866
|
+
const left = versionParts(a);
|
|
867
|
+
const right = versionParts(b);
|
|
868
|
+
for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
|
|
869
|
+
const difference = (left[i] ?? 0) - (right[i] ?? 0);
|
|
870
|
+
if (difference !== 0) {
|
|
871
|
+
return difference;
|
|
872
|
+
}
|
|
873
|
+
}
|
|
874
|
+
return 0;
|
|
875
|
+
}
|
|
876
|
+
/**
|
|
877
|
+
* The release that fixes this advisory for the INSTALLED version.
|
|
878
|
+
*
|
|
879
|
+
* An advisory can list several ranges for one package (nanoid's fixes at
|
|
880
|
+
* 3.3.16 for the 3.x line and 5.1.16 for 4.x and 5.x), so the first `fixed`
|
|
881
|
+
* event is not the answer: the fix is the one closing the range the
|
|
882
|
+
* installed version sits in. When no range can be shown to contain it, the
|
|
883
|
+
* lowest fix above the installed version is the next best statement; when
|
|
884
|
+
* there is none, no fix is claimed.
|
|
885
|
+
*/
|
|
886
|
+
function osvFixedVersion(vuln, name, installed) {
|
|
887
|
+
const affected = Array.isArray(vuln.affected) ? vuln.affected : [];
|
|
888
|
+
const candidates = [];
|
|
889
|
+
for (const entry of affected) {
|
|
890
|
+
if (!isRecord(entry))
|
|
891
|
+
continue;
|
|
892
|
+
if (isRecord(entry.package) && entry.package.name !== name)
|
|
893
|
+
continue;
|
|
894
|
+
const ranges = Array.isArray(entry.ranges) ? entry.ranges : [];
|
|
895
|
+
for (const range of ranges) {
|
|
896
|
+
if (!isRecord(range) || !Array.isArray(range.events))
|
|
897
|
+
continue;
|
|
898
|
+
let introduced;
|
|
899
|
+
for (const event of range.events) {
|
|
900
|
+
if (!isRecord(event))
|
|
901
|
+
continue;
|
|
902
|
+
if (typeof event.introduced === 'string') {
|
|
903
|
+
introduced = event.introduced;
|
|
904
|
+
}
|
|
905
|
+
if (typeof event.fixed === 'string') {
|
|
906
|
+
candidates.push(event.fixed);
|
|
907
|
+
const inRange = installed !== '' &&
|
|
908
|
+
(introduced === undefined || compareVersions(installed, introduced) >= 0) &&
|
|
909
|
+
compareVersions(installed, event.fixed) < 0;
|
|
910
|
+
if (inRange) {
|
|
911
|
+
return event.fixed;
|
|
912
|
+
}
|
|
913
|
+
}
|
|
914
|
+
}
|
|
915
|
+
}
|
|
916
|
+
}
|
|
917
|
+
const above = candidates
|
|
918
|
+
.filter((fixed) => installed === '' || compareVersions(fixed, installed) > 0)
|
|
919
|
+
.sort(compareVersions);
|
|
920
|
+
return above[0];
|
|
921
|
+
}
|
|
922
|
+
/**
|
|
923
|
+
* osv-scanner writes every manifest path absolute, whatever scan root or
|
|
924
|
+
* relative --lockfile path it is given, so in CI it names the runner's
|
|
925
|
+
* checkout. Made relative to the first root that contains it; left as it is
|
|
926
|
+
* when none does, rather than guessed.
|
|
927
|
+
*/
|
|
928
|
+
function relativeToRoots(file, roots) {
|
|
929
|
+
for (const root of roots) {
|
|
930
|
+
const prefix = root.endsWith('/') ? root : `${root}/`;
|
|
931
|
+
if (file.startsWith(prefix)) {
|
|
932
|
+
return file.slice(prefix.length);
|
|
933
|
+
}
|
|
934
|
+
}
|
|
935
|
+
return file;
|
|
936
|
+
}
|
|
937
|
+
/**
|
|
938
|
+
* The vulnerabilities summary line's lockfile fact (issue #72): the count and
|
|
939
|
+
* names of the lockfiles the UMBRELLA handed osv-scanner with --lockfile,
|
|
940
|
+
* never osv-scanner's own results[], which 2.x prints only for a source with
|
|
941
|
+
* findings. A clean scan of one lockfile and a run that scanned none both
|
|
942
|
+
* have results: [], and only this list tells them apart.
|
|
943
|
+
*/
|
|
944
|
+
function describeLockfiles(lockfiles) {
|
|
945
|
+
return lockfiles.length === 0 ? '0' : `${lockfiles.length} (${lockfiles.join(', ')})`;
|
|
946
|
+
}
|
|
947
|
+
export function normalizeOsvScanner(raw, version, blocked,
|
|
948
|
+
/** The scan root as a path osv-scanner may have printed it, in any spelling. */
|
|
949
|
+
roots = [],
|
|
950
|
+
/** The lockfiles the umbrella passed with --lockfile, repository-relative. */
|
|
951
|
+
lockfiles = []) {
|
|
952
|
+
const product = 'osv-scanner';
|
|
953
|
+
const top = needRecord(raw, product, 'the output');
|
|
954
|
+
const results = needArray(top.results, product, 'results');
|
|
955
|
+
const findings = [];
|
|
956
|
+
for (const [ri, rawResult] of results.entries()) {
|
|
957
|
+
const resultWhere = `results[${ri}]`;
|
|
958
|
+
const result = needRecord(rawResult, product, resultWhere);
|
|
959
|
+
const source = needRecord(result.source, product, `${resultWhere}.source`);
|
|
960
|
+
const manifest = relativeToRoots(needString(source.path, product, `${resultWhere}.source.path`), roots);
|
|
961
|
+
const packages = needArray(result.packages, product, `${resultWhere}.packages`);
|
|
962
|
+
for (const [pi, rawPackage] of packages.entries()) {
|
|
963
|
+
const packageWhere = `${resultWhere}.packages[${pi}]`;
|
|
964
|
+
const entry = needRecord(rawPackage, product, packageWhere);
|
|
965
|
+
const pkg = needRecord(entry.package, product, `${packageWhere}.package`);
|
|
966
|
+
const name = needString(pkg.name, product, `${packageWhere}.package.name`);
|
|
967
|
+
const installed = optionalString(pkg.version, product, `${packageWhere}.package.version`) ?? '';
|
|
968
|
+
const ecosystem = optionalString(pkg.ecosystem, product, `${packageWhere}.package.ecosystem`);
|
|
969
|
+
const groups = (entry.groups === undefined ? [] : needArray(entry.groups, product, `${packageWhere}.groups`)).filter(isRecord);
|
|
970
|
+
const vulns = entry.vulnerabilities === undefined
|
|
971
|
+
? []
|
|
972
|
+
: needArray(entry.vulnerabilities, product, `${packageWhere}.vulnerabilities`);
|
|
973
|
+
for (const [vi, rawVuln] of vulns.entries()) {
|
|
974
|
+
const where = `${packageWhere}.vulnerabilities[${vi}]`;
|
|
975
|
+
const vuln = needRecord(rawVuln, product, where);
|
|
976
|
+
const id = needString(vuln.id, product, `${where}.id`);
|
|
977
|
+
const score = osvScore(vuln, groups);
|
|
978
|
+
const fixedVersion = osvFixedVersion(vuln, name, installed);
|
|
979
|
+
findings.push({
|
|
980
|
+
schemaVersion: 1,
|
|
981
|
+
product,
|
|
982
|
+
productVersion: version,
|
|
983
|
+
ruleId: `osv-scanner/${id}`,
|
|
984
|
+
severity: cvssToSeverity(score),
|
|
985
|
+
severityIsDerived: true,
|
|
986
|
+
blocking: blocked,
|
|
987
|
+
message: optionalString(vuln.summary, product, `${where}.summary`) ??
|
|
988
|
+
`${id} affects ${name}@${installed}`,
|
|
989
|
+
subject: { kind: 'package', name, manifest },
|
|
990
|
+
// The advisory, the package and version it applies to, and the
|
|
991
|
+
// manifest it was found through: the same four facts on every run
|
|
992
|
+
// over the same lockfile, so the value is stable.
|
|
993
|
+
fingerprint: { value: `${id}|${name}|${installed}|${manifest}`, scope: product, stability: 'stable' },
|
|
994
|
+
details: {
|
|
995
|
+
version: installed,
|
|
996
|
+
...(ecosystem === undefined ? {} : { ecosystem }),
|
|
997
|
+
aliases: Array.isArray(vuln.aliases) ? vuln.aliases : [],
|
|
998
|
+
...(score === null ? {} : { cvss: score }),
|
|
999
|
+
...(fixedVersion === undefined ? {} : { fixedVersion }),
|
|
1000
|
+
},
|
|
1001
|
+
});
|
|
1002
|
+
}
|
|
1003
|
+
}
|
|
1004
|
+
}
|
|
1005
|
+
return {
|
|
1006
|
+
findings,
|
|
1007
|
+
run: {
|
|
1008
|
+
// Any known vulnerability fails the gate; a threshold, when an adopter
|
|
1009
|
+
// wants one, lives in osv-scanner.toml.
|
|
1010
|
+
failOn: 'any',
|
|
1011
|
+
suppressed: 0,
|
|
1012
|
+
ignored: 0,
|
|
1013
|
+
diagnostics: [],
|
|
1014
|
+
details: {
|
|
1015
|
+
lockfiles: describeLockfiles(lockfiles),
|
|
1016
|
+
// Distinct from the old "sources" name on purpose: this counts only
|
|
1017
|
+
// the sources osv-scanner reported findings for, never how many were
|
|
1018
|
+
// scanned, and the old name read as the latter.
|
|
1019
|
+
'sources-with-findings': results.length,
|
|
1020
|
+
},
|
|
1021
|
+
},
|
|
1022
|
+
diagnostics: [],
|
|
1023
|
+
};
|
|
1024
|
+
}
|
|
592
1025
|
function gateProblem(ruleId, role, product, message, details) {
|
|
593
1026
|
return {
|
|
594
1027
|
schemaVersion: 1,
|
package/dist/output-sarif.js
CHANGED
|
@@ -2,8 +2,9 @@
|
|
|
2
2
|
//
|
|
3
3
|
// SARIF is the family's published finding format; the envelope in
|
|
4
4
|
// envelope.ts is internal and never leaves this process. The mapping below
|
|
5
|
-
// is dep-guard's mapping, applied to
|
|
6
|
-
//
|
|
5
|
+
// is dep-guard's mapping, applied to every gate (the three family gates and
|
|
6
|
+
// the two external ones) from one place, which is the whole point: one
|
|
7
|
+
// hand-written emitter per gate is how a family ends up
|
|
7
8
|
// with one tool emitting absolute paths and another omitting fingerprints
|
|
8
9
|
// entirely, and both of those really happened here.
|
|
9
10
|
//
|
|
@@ -117,6 +118,7 @@
|
|
|
117
118
|
// normalize.ts, which is where the omission would stop mattering if the
|
|
118
119
|
// field were ever carried.
|
|
119
120
|
import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
|
|
121
|
+
import { INTENT_WARNING } from './normalize.js';
|
|
120
122
|
import { POLICY_FILE_NAME } from './policy.js';
|
|
121
123
|
const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
|
|
122
124
|
export const UMBRELLA_DRIVER_NAME = 'conductor';
|
|
@@ -498,6 +500,25 @@ function excludedNotifications(result) {
|
|
|
498
500
|
details: { role: gate.role, product: gate.product },
|
|
499
501
|
}));
|
|
500
502
|
}
|
|
503
|
+
/**
|
|
504
|
+
* The gates skipped because the head tree equals the trust base's tree, as
|
|
505
|
+
* notifications (issue #69).
|
|
506
|
+
*
|
|
507
|
+
* Same discriminator as excludedNotifications just above: how much of the
|
|
508
|
+
* policy this run covered is a statement about the run, not about anybody's
|
|
509
|
+
* code, so it is a NOTE and never a result. Reachable only on the one
|
|
510
|
+
* accepted equal-tree shape (a merge commit whose first parent is the trust
|
|
511
|
+
* base; see trust-base.ts), where every enabled gate whose profile does not
|
|
512
|
+
* say readsHistory is recorded here instead of being spawned.
|
|
513
|
+
*/
|
|
514
|
+
function treeUnchangedNotifications(result) {
|
|
515
|
+
return result.treeUnchanged.map((gate) => ({
|
|
516
|
+
id: 'conductor/tree-unchanged',
|
|
517
|
+
message: `The ${gate.role} gate (${gate.product}) did not run: the head tree is identical to the ` +
|
|
518
|
+
'base tree, so there is no change for this gate to judge.',
|
|
519
|
+
details: { role: gate.role, product: gate.product },
|
|
520
|
+
}));
|
|
521
|
+
}
|
|
501
522
|
/**
|
|
502
523
|
* The gates that had nothing to check, as notifications.
|
|
503
524
|
*
|
|
@@ -551,6 +572,36 @@ function skippedNotifications(result) {
|
|
|
551
572
|
details: { role: gate.role, product: gate.product, reason: gate.reason },
|
|
552
573
|
}));
|
|
553
574
|
}
|
|
575
|
+
/**
|
|
576
|
+
* intent-guard 1.7.0's own advance-notice warnings, as notifications.
|
|
577
|
+
*
|
|
578
|
+
* A frozen contract's protected_paths or allowed_paths entry that no git
|
|
579
|
+
* path can ever match is a statement about that contract's own
|
|
580
|
+
* configuration, in the same sense skippedNotifications above already
|
|
581
|
+
* describes: nothing went wrong with this commit, nobody's code is at
|
|
582
|
+
* fault, and the statement is true of every run against this contract until
|
|
583
|
+
* it is edited. As a result it belongs beside no-contract and the rest, a
|
|
584
|
+
* notification rather than a result, so it never gains a severity, a
|
|
585
|
+
* fingerprint, or a place in the exit code.
|
|
586
|
+
*
|
|
587
|
+
* Read off `run.diagnostics` rather than `diagnostics`, deliberately: this
|
|
588
|
+
* repository's `diagnostics` field is the umbrella's OWN fixed set of ids
|
|
589
|
+
* (see AGENTS.md), and intent-guard/warning is not one of them. It is the
|
|
590
|
+
* gate's own statement, carried through unchanged, the same way
|
|
591
|
+
* dep-guard's online-deadline-exceeded diagnostic already prints under the
|
|
592
|
+
* gate in the text report; this is the SARIF half of that same channel,
|
|
593
|
+
* scoped to intent-guard's own warning code so a future run-diagnostic on
|
|
594
|
+
* another gate does not silently start appearing here too.
|
|
595
|
+
*/
|
|
596
|
+
function intentWarningNotifications(result) {
|
|
597
|
+
return result.gates.flatMap((gate) => gate.run.diagnostics
|
|
598
|
+
.filter((diagnostic) => diagnostic.code === INTENT_WARNING)
|
|
599
|
+
.map((diagnostic) => ({
|
|
600
|
+
id: diagnostic.code,
|
|
601
|
+
message: diagnostic.message,
|
|
602
|
+
details: { role: gate.role, product: gate.product },
|
|
603
|
+
})));
|
|
604
|
+
}
|
|
554
605
|
/**
|
|
555
606
|
* The control inputs this pull request proposes to change, as notifications.
|
|
556
607
|
*
|
|
@@ -809,6 +860,12 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
809
860
|
...(gate.intent === undefined
|
|
810
861
|
? {}
|
|
811
862
|
: { contractSource: gate.intent.contractSource, baseRef: gate.intent.baseRef }),
|
|
863
|
+
// The gate's own run facts (issue #72: the lockfiles the umbrella
|
|
864
|
+
// handed osv-scanner, and dep-guard's online-lookup reporting), the
|
|
865
|
+
// same bag the text report renders as scalars. Carried verbatim and
|
|
866
|
+
// only when there is something in it, so a gate that reports none of
|
|
867
|
+
// this keeps the properties shape it had before.
|
|
868
|
+
...(Object.keys(gate.run.details).length === 0 ? {} : { details: gate.run.details }),
|
|
812
869
|
}));
|
|
813
870
|
}
|
|
814
871
|
// Still RESULTS, deliberately, and the asymmetry with the three above is
|
|
@@ -827,6 +884,7 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
827
884
|
const notifications = [
|
|
828
885
|
...deferredNotifications(result),
|
|
829
886
|
...excludedNotifications(result),
|
|
887
|
+
...treeUnchangedNotifications(result),
|
|
830
888
|
...skippedNotifications(result),
|
|
831
889
|
...unenforcedNotifications(result),
|
|
832
890
|
...legacyStateDirNotifications(result),
|
|
@@ -835,6 +893,7 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
835
893
|
...proposalNotifications(result),
|
|
836
894
|
...trustBaseWithheldNotifications(result),
|
|
837
895
|
...nodeModulesSkippedNotifications(result),
|
|
896
|
+
...intentWarningNotifications(result),
|
|
838
897
|
];
|
|
839
898
|
// Notifications earn the run on their own. Before this, the umbrella run
|
|
840
899
|
// existed only when it had findings and a deferred gate was one; without
|
package/dist/output-text.d.ts
CHANGED
|
@@ -1,4 +1,30 @@
|
|
|
1
1
|
import type { RunResult } from './run.js';
|
|
2
|
+
/**
|
|
3
|
+
* The one-line summary a `--output` run prints to the job log after writing
|
|
4
|
+
* its report to a file (see cli.ts). Refused first, exactly like every other
|
|
5
|
+
* renderer in this file, and for the same reason: `refusedTrustBase` fills
|
|
6
|
+
* `result.gates` and `result.findings` with a could-not-run outcome PER
|
|
7
|
+
* ENABLED GATE, so counting them the ordinary way reports "N gate(s), N
|
|
8
|
+
* finding(s)" on a run where nothing ran and nothing was found -- issue #46.
|
|
9
|
+
* A reader with only this line, no --verbose and no pull-request comment
|
|
10
|
+
* (a fork's read-only token, or pr-comment left off) deserves the same words
|
|
11
|
+
* the comment's own compact body gives them, not a count that implies gates
|
|
12
|
+
* ran.
|
|
13
|
+
*
|
|
14
|
+
* `refusal` (from refuseTrustBaseRef in trust-base.ts) already says "Nothing
|
|
15
|
+
* was checked" itself as part of its own sentence, so this does not repeat
|
|
16
|
+
* that lead-in: doing so used to print the phrase twice on one line. Nor
|
|
17
|
+
* does it append its own closing sentence: cli.ts joins this return value
|
|
18
|
+
* with "; " before the rest of the job-log line, and a trailing period here
|
|
19
|
+
* left every refused run's log line reading "...; sarif report written",
|
|
20
|
+
* with a period sitting directly before that semicolon. A trailing period
|
|
21
|
+
* on `refusal` itself is trimmed for the same reason.
|
|
22
|
+
*
|
|
23
|
+
* A normal run is untouched: the exact same
|
|
24
|
+
* "N gate(s), N finding(s)" text as before, so a working adopter's log does
|
|
25
|
+
* not change.
|
|
26
|
+
*/
|
|
27
|
+
export declare function jobLogSummary(result: RunResult): string;
|
|
2
28
|
export interface TextOptions {
|
|
3
29
|
/**
|
|
4
30
|
* Print the full report even when the run is fully clean.
|