@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/dist/normalize.js CHANGED
@@ -1,10 +1,12 @@
1
1
  // Turning each gate's own JSON into the internal envelope.
2
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.
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
- export function normalizeDepGuard(raw, version) {
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: needString(detail.message, product, `${where}.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
- diagnostics: [],
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,
@@ -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 all three gates from one place, which
6
- // is the whole point: three hand-written emitters is how a family ends up
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
@@ -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.