@vaultcompass/conductor 0.9.0 → 0.11.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
@@ -797,7 +797,36 @@ export function normalizeGitleaks(raw, version, blocked) {
797
797
  seen.alsoIn.push(droppedCommit);
798
798
  }
799
799
  });
800
- const findings = [...byPlace.values()].map(({ finding, alsoIn }) => alsoIn.length === 0 ? finding : { ...finding, details: { ...finding.details, alsoIn } });
800
+ const kept = [...byPlace.values()].map(({ finding, alsoIn }) => alsoIn.length === 0 ? finding : { ...finding, details: { ...finding.details, alsoIn } });
801
+ // THE MERGE COPY ON A MOVED LINE IS NOT COLLAPSED, and that is deliberate
802
+ // (tests/fixtures/gitleaks-8.30.1-merge-doubled.json, measured on 8.30.1).
803
+ // When the base branch moved the lines above a pull request's secret, the
804
+ // merge's first-parent diff reports it at a different StartLine, so the two
805
+ // records differ in StartLine, Commit, Date, Message and Fingerprint and
806
+ // agree on RuleID, File, StartColumn, EndColumn and Entropy. Under --redact
807
+ // nothing in the record identifies the secret itself: Entropy is a
808
+ // character-frequency score, the same for any two secrets that are
809
+ // anagrams, so collapsing on it could fold two different leaks into one
810
+ // SARIF result. Each record is kept, and each names the other here, so a
811
+ // reader sees the likely pair without the report hiding either of them.
812
+ const shape = (finding) => {
813
+ const subject = finding.subject;
814
+ return subject.kind === 'location' && typeof finding.details.entropy === 'number'
815
+ ? JSON.stringify([finding.ruleId, subject.file, subject.column, subject.endColumn ?? null, finding.details.entropy])
816
+ : null;
817
+ };
818
+ const findings = kept.map((finding) => {
819
+ const key = shape(finding);
820
+ const twins = key === null
821
+ ? []
822
+ : kept
823
+ // A merge re-report is by definition another commit: two records
824
+ // of one shape in the same commit are two places, not a pair.
825
+ .filter((other) => other !== finding && shape(other) === key && other.details.commit !== finding.details.commit)
826
+ .map((other) => other.fingerprint?.value)
827
+ .filter((value) => value !== undefined);
828
+ return twins.length === 0 ? finding : { ...finding, details: { ...finding.details, possiblySameSecretAs: twins } };
829
+ });
801
830
  return {
802
831
  findings,
803
832
  run: {
@@ -806,7 +835,10 @@ export function normalizeGitleaks(raw, version, blocked) {
806
835
  suppressed: 0,
807
836
  ignored: 0,
808
837
  diagnostics: [],
809
- details: { entries: entries.length },
838
+ // Both counts, labelled: the raw number of records in gitleaks' report,
839
+ // and the distinct places left after the merge collapse above. One
840
+ // unlabelled `entries` read as the finding count when it was not.
841
+ details: { 'entries-raw': entries.length, 'entries-distinct': findings.length },
810
842
  },
811
843
  diagnostics: [],
812
844
  };
@@ -951,11 +983,55 @@ export function describeLockfiles(lockfiles, emptied = new Set()) {
951
983
  const named = lockfiles.map((file) => (emptied.has(file) ? `${file} [no packages read]` : file));
952
984
  return lockfiles.length === 0 ? '0' : `${lockfiles.length} (${named.join(', ')})`;
953
985
  }
986
+ const OSV_FILTERED_COUNT = /^Filtered (\d+) vulnerabilit(?:y|ies) from output$/;
987
+ // The id is restricted to an advisory id's shape. osv-scanner prints a
988
+ // reason from osv-scanner.toml verbatim, newlines and escape bytes included
989
+ // (measured on 2.4.0), so a reason can forge what looks like a second line;
990
+ // an id that is not id-shaped is not read at all, and every id that is still
991
+ // goes through the same cleaner as the reason.
992
+ const OSV_FILTERED_ID = /^([A-Za-z0-9._:-]+) and \d+ alias(?:es)? ha(?:s|ve) been filtered out because: (.*)$/;
993
+ /** Printable ASCII only, capped: the reason is text from the repository's own config. */
994
+ function cleanReason(reason) {
995
+ const printable = reason.replace(/[^\x20-\x7e]/g, '').trim();
996
+ return printable.length <= 80 ? printable : `${printable.slice(0, 80)}...`;
997
+ }
998
+ export function osvSuppressions(stderr) {
999
+ let count = null;
1000
+ const ids = [];
1001
+ for (const raw of stderr.split('\n')) {
1002
+ const line = raw.trim();
1003
+ const total = OSV_FILTERED_COUNT.exec(line);
1004
+ if (total !== null) {
1005
+ // A count that is not a safe integer is not a count (a 400-digit one
1006
+ // printed as "suppressed Infinity"); it is ignored like a missing one.
1007
+ const value = Number(total[1]);
1008
+ if (Number.isSafeInteger(value)) {
1009
+ count = value;
1010
+ }
1011
+ continue;
1012
+ }
1013
+ const one = OSV_FILTERED_ID.exec(line);
1014
+ const id = one === null ? '' : cleanReason(one[1]);
1015
+ if (one !== null && id !== '' && !ids.some((entry) => entry.id === id)) {
1016
+ ids.push({ id, reason: cleanReason(one[2]) });
1017
+ }
1018
+ }
1019
+ return count === null ? null : { count, ids };
1020
+ }
1021
+ /** osv-scanner's `dependency_groups` on a package (2.4.0 writes ["dev"]), read leniently. */
1022
+ function osvDependencyGroups(entry) {
1023
+ const groups = entry.dependency_groups;
1024
+ return Array.isArray(groups) && groups.every((group) => typeof group === 'string')
1025
+ ? groups
1026
+ : undefined;
1027
+ }
954
1028
  export function normalizeOsvScanner(raw, version, blocked,
955
1029
  /** The scan root as a path osv-scanner may have printed it, in any spelling. */
956
1030
  roots = [],
957
1031
  /** The lockfiles the umbrella passed with --lockfile, repository-relative. */
958
- lockfiles = []) {
1032
+ lockfiles = [],
1033
+ /** osv-scanner's stderr, read only for the osv-scanner.toml suppressions it names. */
1034
+ stderr = '') {
959
1035
  const product = 'osv-scanner';
960
1036
  const top = needRecord(raw, product, 'the output');
961
1037
  const results = needArray(top.results, product, 'results');
@@ -974,6 +1050,7 @@ lockfiles = []) {
974
1050
  const name = needString(pkg.name, product, `${packageWhere}.package.name`);
975
1051
  const installed = optionalString(pkg.version, product, `${packageWhere}.package.version`) ?? '';
976
1052
  const ecosystem = optionalString(pkg.ecosystem, product, `${packageWhere}.package.ecosystem`);
1053
+ const dependencyGroups = osvDependencyGroups(entry);
977
1054
  otherVerdicts.push(...osvOtherVerdicts(entry, pkg, `${name}@${installed}`));
978
1055
  const groups = (entry.groups === undefined ? [] : needArray(entry.groups, product, `${packageWhere}.groups`)).filter(isRecord);
979
1056
  const vulns = entry.vulnerabilities === undefined
@@ -1006,26 +1083,45 @@ lockfiles = []) {
1006
1083
  aliases: Array.isArray(vuln.aliases) ? vuln.aliases : [],
1007
1084
  ...(score === null ? {} : { cvss: score }),
1008
1085
  ...(fixedVersion === undefined ? {} : { fixedVersion }),
1086
+ // Carried, never mapped: whether a dev-only dependency carries
1087
+ // the advisory is for the reader, and changes no verdict.
1088
+ ...(dependencyGroups === undefined ? {} : { dependencyGroups }),
1009
1089
  },
1010
1090
  });
1011
1091
  }
1012
1092
  }
1013
1093
  }
1094
+ const suppressions = osvSuppressions(stderr);
1014
1095
  return {
1015
1096
  findings,
1016
1097
  run: {
1017
1098
  // Any known vulnerability fails the gate; a threshold, when an adopter
1018
1099
  // wants one, lives in osv-scanner.toml.
1019
1100
  failOn: 'any',
1020
- suppressed: 0,
1101
+ // osv-scanner's own count of what osv-scanner.toml filtered, from its
1102
+ // stderr (osvSuppressions): one per advisory per lockfile. 0 when it
1103
+ // printed no count, which was the only value this ever had before.
1104
+ suppressed: suppressions?.count ?? 0,
1021
1105
  ignored: 0,
1022
1106
  diagnostics: [],
1023
1107
  details: {
1024
1108
  lockfiles: describeLockfiles(lockfiles),
1025
1109
  // Distinct from the old "sources" name on purpose: this counts only
1026
1110
  // the sources osv-scanner reported findings for, never how many were
1027
- // scanned, and the old name read as the latter.
1028
- 'sources-with-findings': results.length,
1111
+ // scanned. Counted as the distinct lockfiles the FINDINGS name rather
1112
+ // than results.length: osv-scanner 2.4.0 prints one result per
1113
+ // lockfile handed with --lockfile (measured,
1114
+ // tests/fixtures/osv-scanner-2.4.0-two-lockfiles.json), but a result
1115
+ // carrying only a non-advisory verdict (a licence, a deprecation) has
1116
+ // no finding, and counting it said a lockfile had findings that the
1117
+ // report then showed none for.
1118
+ 'sources-with-findings': new Set(findings.map((finding) => (finding.subject.kind === 'package' ? finding.subject.manifest : ''))).size,
1119
+ ...(suppressions === null || suppressions.ids.length === 0
1120
+ ? {}
1121
+ : {
1122
+ 'suppressed-by-osv-scanner.toml': `${suppressions.ids.map((entry) => `${entry.id} (${entry.reason})`).join(', ')}; ` +
1123
+ 'counted by osv-scanner once per advisory per lockfile; expiry not reported by osv-scanner',
1124
+ }),
1029
1125
  },
1030
1126
  },
1031
1127
  diagnostics: [],
@@ -1035,10 +1131,18 @@ lockfiles = []) {
1035
1131
  /**
1036
1132
  * The package-level keys of an osv-scanner result this normalizer knows:
1037
1133
  * the package itself, its advisories, their groups, and the licences it was
1038
- * found to carry. `license_violations` is deliberately NOT here: it is a
1039
- * verdict (osv-scanner exits 1 for it, measured on 2.4.0 with --licenses).
1134
+ * found to carry, and `dependency_groups`, the dev marker osvDependencyGroups
1135
+ * reads (2.4.0 writes ["dev"]; a marker, not a verdict). `license_violations`
1136
+ * is deliberately NOT here: it is a verdict (osv-scanner exits 1 for it,
1137
+ * measured on 2.4.0 with --licenses).
1040
1138
  */
1041
- const OSV_KNOWN_PACKAGE_KEYS = new Set(['package', 'vulnerabilities', 'groups', 'licenses']);
1139
+ const OSV_KNOWN_PACKAGE_KEYS = new Set([
1140
+ 'package',
1141
+ 'vulnerabilities',
1142
+ 'groups',
1143
+ 'licenses',
1144
+ 'dependency_groups',
1145
+ ]);
1042
1146
  function isEmptyValue(value) {
1043
1147
  if (value === undefined || value === null || value === false || value === '') {
1044
1148
  return true;
@@ -1219,8 +1323,10 @@ export function summariseStderr(stderr) {
1219
1323
  * the product and never over the message, so a gate that reworded its error
1220
1324
  * is the same alert rather than a new one every run.
1221
1325
  */
1222
- export function normalizeFailedGate(role, product, detail, stderr) {
1326
+ export function normalizeFailedGate(role, product, detail, stderr,
1327
+ /** Structured facts beside the detail, such as a timed-out gate's limit and elapsed time. */
1328
+ extra = {}) {
1223
1329
  const said = summariseStderr(stderr);
1224
1330
  return gateProblem('conductor/gate-failed', role, product, `The "${role}" gate did not complete: ${detail} Nothing was verified by this gate.` +
1225
- (said === null ? '' : ` The gate wrote to stderr: ${said}`), { detail, stderr: said });
1331
+ (said === null ? '' : ` The gate wrote to stderr: ${said}`), { detail, stderr: said, ...extra });
1226
1332
  }
@@ -582,9 +582,54 @@ function skippedNotifications(result) {
582
582
  // body on purpose, so it is a notification and never a result.
583
583
  id: `${gate.product}/${gate.reason}`,
584
584
  message: `The ${gate.role} gate (${gate.product}) checked nothing on this branch. ${gate.detail}`,
585
- details: { role: gate.role, product: gate.product, reason: gate.reason },
585
+ details: {
586
+ role: gate.role,
587
+ product: gate.product,
588
+ reason: gate.reason,
589
+ // The full tied list here; the message caps it for reading.
590
+ ...(gate.selection?.why === 'ambiguous'
591
+ ? { tied: gate.selection.tied, tiedCount: gate.selection.tied.length }
592
+ : {}),
593
+ ...(gate.selection === undefined || gate.selection.legacy === null
594
+ ? {}
595
+ : { legacySelection: gate.selection.legacy }),
596
+ },
586
597
  }));
587
598
  }
599
+ /**
600
+ * A spec the branch-name convention chose on thin evidence, as a NOTE.
601
+ *
602
+ * A notification by the rule above: it says how much this run's verdict can
603
+ * be trusted to be about the right contract, which is a statement about the
604
+ * run's coverage, true on every run of this branch until somebody pins the
605
+ * spec. The verdict and enforcement are unchanged by it.
606
+ */
607
+ function weakMatchNotifications(result) {
608
+ return result.gates.flatMap((gate) => {
609
+ const source = gate.intent?.contractSource;
610
+ if (source === undefined || source.kind !== 'imported' || source.match?.strength !== 'weak') {
611
+ return [];
612
+ }
613
+ const match = source.match;
614
+ return [
615
+ {
616
+ id: `${gate.product}/spec-weak-match`,
617
+ message: `The ${gate.role} gate (${gate.product}) used ${source.spec}, chosen by the branch name on ` +
618
+ `a weak match (${match.weakBecause.join(', ')}). Name the spec with a "Spec: <path>" line ` +
619
+ 'or --spec, or rename the branch to the spec name, to be sure it is the right contract.',
620
+ details: {
621
+ role: gate.role,
622
+ product: gate.product,
623
+ spec: source.spec,
624
+ shared: match.shared,
625
+ weakBecause: match.weakBecause,
626
+ runnerUp: match.runnerUp,
627
+ ...(match.legacy === null ? {} : { legacySelection: match.legacy }),
628
+ },
629
+ },
630
+ ];
631
+ });
632
+ }
588
633
  /**
589
634
  * intent-guard 1.7.0's own advance-notice warnings, as notifications.
590
635
  *
@@ -784,6 +829,23 @@ function nodeModulesSkippedNotifications(result) {
784
829
  },
785
830
  ];
786
831
  }
832
+ /**
833
+ * A passthrough option that is a gate's own setting under a name conductor
834
+ * also uses (gitleaks' `options.timeout`), as notifications. A NOTE: nothing
835
+ * went wrong, and the gate's own outcome, whatever it was, is reported on its
836
+ * own. It says which deadline is whose.
837
+ */
838
+ function gateOwnOptionNotifications(result) {
839
+ return result.gates.flatMap((gate) => gate.gateOwnOption === undefined
840
+ ? []
841
+ : [
842
+ {
843
+ id: 'conductor/option-is-gate-own',
844
+ message: gate.gateOwnOption,
845
+ details: { role: gate.role, product: gate.product, option: 'timeout' },
846
+ },
847
+ ]);
848
+ }
787
849
  /**
788
850
  * The gates the policy file told not to decide anything, as notifications.
789
851
  *
@@ -900,6 +962,13 @@ export function renderSarif(result, umbrellaVersion) {
900
962
  ...(gate.intent === undefined
901
963
  ? {}
902
964
  : { contractSource: gate.intent.contractSource, baseRef: gate.intent.baseRef }),
965
+ // What 0.10.0 would have chosen, when the branch-name convention now
966
+ // chooses a different spec. Reporting only, for one minor release.
967
+ ...(gate.intent?.contractSource.kind === 'imported' &&
968
+ gate.intent.contractSource.match !== undefined &&
969
+ gate.intent.contractSource.match.legacy !== null
970
+ ? { legacySelection: gate.intent.contractSource.match.legacy }
971
+ : {}),
903
972
  // The gate's own run facts (issue #72: the lockfiles the umbrella
904
973
  // handed osv-scanner, and dep-guard's online-lookup reporting), the
905
974
  // same bag the text report renders as scalars. Carried verbatim and
@@ -928,12 +997,14 @@ export function renderSarif(result, umbrellaVersion) {
928
997
  ...skippedNotifications(result),
929
998
  ...unenforcedNotifications(result),
930
999
  ...legacyStateDirNotifications(result),
1000
+ ...weakMatchNotifications(result),
931
1001
  ...trustBaseRefusedNotifications(result),
932
1002
  ...programRefusedNotifications(result),
933
1003
  ...proposalNotifications(result),
934
1004
  ...trustBaseWithheldNotifications(result),
935
1005
  ...nodeModulesSkippedNotifications(result),
936
1006
  ...intentWarningNotifications(result),
1007
+ ...gateOwnOptionNotifications(result),
937
1008
  ];
938
1009
  // Notifications earn the run on their own. Before this, the umbrella run
939
1010
  // existed only when it had findings and a deferred gate was one; without
@@ -1,4 +1,17 @@
1
+ import { type GateOutcome } from './gate-runner.js';
2
+ import type { ReportedMatch } from './intent-prepare.js';
1
3
  import type { RunResult } from './run.js';
4
+ /**
5
+ * How many entries a section prints before it rolls the rest up into one
6
+ * line, unless --verbose. A full-history gitleaks scan or an osv-scanner run
7
+ * over an old lockfile printed six hundred lines on one repository, which
8
+ * buries the verdict and every other gate. Findings past the cap are still
9
+ * findings: they are counted in every number on the report, they are in the
10
+ * SARIF log, --verbose prints them, and the exit code never reads this.
11
+ */
12
+ export declare const FINDINGS_SHOWN_PER_GATE = 20;
13
+ /** The convention match behind a gate's contract, when the branch name chose it. */
14
+ export declare function conventionMatch(gate: GateOutcome): ReportedMatch | null;
2
15
  /**
3
16
  * The one sentence the whole of pull-request mode has to fit into.
4
17
  *
@@ -61,7 +74,9 @@ export declare function jobLogSummary(result: RunResult): string;
61
74
  * Describes, decides nothing: every word is read off the outcomes the exit
62
75
  * code was already composed from. Same plain ASCII as the rest of this file.
63
76
  */
64
- export declare function gateLogLines(result: RunResult): string[];
77
+ export declare function gateLogLines(result: RunResult, options?: {
78
+ terminal?: boolean;
79
+ }): string[];
65
80
  /**
66
81
  * One warning per gate that was found on PATH at a version other than the one
67
82
  * this run expected (the Action's pin).
@@ -163,5 +178,26 @@ export interface TextOptions {
163
178
  * that did not block, never about a gate that did not run.
164
179
  */
165
180
  advisory?: boolean;
181
+ /**
182
+ * The report is going straight to a terminal (cli.ts: stdout is a TTY and
183
+ * no --output). Only one thing reads it: a refused trust base prints its
184
+ * refusal once at the top and one line per gate, rather than the refusal
185
+ * again in every gate's section and again in every gate's finding. A file,
186
+ * a pipe and a pull request comment never set it and are unchanged.
187
+ */
188
+ terminal?: boolean;
166
189
  }
190
+ /**
191
+ * The intent-spec header line: a CLOSED SET of four strings, in precedence
192
+ * order, naming no branch, no file and no token. The Action copies one to the
193
+ * step summary only on a whole-line match, so nothing the repository or the
194
+ * head branch carries can reach that summary through it.
195
+ */
196
+ export declare const INTENT_SPEC_LINES: readonly ["intent-spec: none chosen, two or more specs matched the branch equally", "intent-spec: none chosen, this branch chose a spec before conductor 0.11.0", "intent-spec: a different spec chosen than before conductor 0.11.0, see the report", "intent-spec: weak match, see the intent gate in the report"];
197
+ /**
198
+ * dep-guard's own diagnostic code for an online budget that ran out before
199
+ * every lookup was made (dep-guard core, online/deadline.ts,
200
+ * ONLINE_DEADLINE_CODE). Read, never minted: the umbrella only repeats it.
201
+ */
202
+ export declare const DEP_GUARD_DEADLINE_CODE = "online-deadline-exceeded";
167
203
  export declare function renderText(result: RunResult, options?: TextOptions): string;