@vaultcompass/conductor 0.4.6 → 0.5.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
@@ -589,6 +591,308 @@ export function normalizeIntentGuard(raw, version) {
589
591
  diagnostics: [],
590
592
  };
591
593
  }
594
+ // -- gitleaks (external, git history mode) -------------------------------
595
+ //
596
+ // The report is a JSON array written to a file, one entry per leak, with
597
+ // the field names in tests/fixtures/README.md. gitleaks has no severity of
598
+ // its own: a rule matched or it did not. So every finding is `high`, marked
599
+ // derived, and whether it blocks comes from the exit code the runner read
600
+ // (3, the leak code the umbrella moves it to), not from anything in the
601
+ // entry.
602
+ //
603
+ // NEVER CARRIED: Secret, Match and Line. The umbrella passes --redact, but a
604
+ // report can be unredacted if a tool changes or a policy finds a way round
605
+ // it, and this report is posted to a pull request and uploaded as SARIF.
606
+ // Neither Email nor Author is carried: who made the commit has no bearing on
607
+ // fixing a leak, and a name or address would be published with it.
608
+ //
609
+ // ONE FINDING PER PLACE. The umbrella asks git for each merge's first-parent
610
+ // diff (--diff-merges=first-parent) so a secret added inside a merge is seen,
611
+ // and under an Actions-style merge that shows a pull request's change twice:
612
+ // in its own commit and in the merge. Entries sharing rule, file, line and
613
+ // column collapse to the one with the earliest Date (the last in report
614
+ // order on a tie or a missing date, since git log lists newest first), and
615
+ // the other commits are listed in details.alsoIn.
616
+ export function normalizeGitleaks(raw, version, blocked) {
617
+ const product = 'gitleaks';
618
+ const entries = needArray(raw, product, 'the report');
619
+ const byPlace = new Map();
620
+ entries.forEach((rawEntry, index) => {
621
+ const where = `report[${index}]`;
622
+ const entry = needRecord(rawEntry, product, where);
623
+ const rule = needString(entry.RuleID, product, `${where}.RuleID`);
624
+ const file = needString(entry.File, product, `${where}.File`);
625
+ const line = needNumber(entry.StartLine, product, `${where}.StartLine`);
626
+ // Carried as gitleaks reports them, which is also what its own SARIF
627
+ // output uses. gitleaks 8.30.1 column numbers are not consistently 0- or
628
+ // 1-based across findings (one token at character 21 was reported at 22,
629
+ // another at character 15 at 15), so no correction is applied.
630
+ const column = typeof entry.StartColumn === 'number' ? entry.StartColumn : 1;
631
+ const endColumn = typeof entry.EndColumn === 'number' ? entry.EndColumn : undefined;
632
+ const commit = optionalString(entry.Commit, product, `${where}.Commit`);
633
+ const date = optionalString(entry.Date, product, `${where}.Date`);
634
+ // gitleaks' own Fingerprint is commit:file:rule:line, identical across
635
+ // runs over the same history, so it is stable. Rebuilt in that shape if
636
+ // a report ever omits it.
637
+ const fingerprint = optionalString(entry.Fingerprint, product, `${where}.Fingerprint`) ??
638
+ `${commit ?? ''}:${file}:${rule}:${line}`;
639
+ const finding = {
640
+ schemaVersion: 1,
641
+ product,
642
+ productVersion: version,
643
+ ruleId: `gitleaks/${rule}`,
644
+ severity: 'high',
645
+ severityIsDerived: true,
646
+ blocking: blocked,
647
+ message: optionalString(entry.Description, product, `${where}.Description`) ?? `${rule} matched`,
648
+ subject: {
649
+ kind: 'location',
650
+ file,
651
+ line,
652
+ column,
653
+ ...(endColumn === undefined ? {} : { endColumn }),
654
+ },
655
+ fingerprint: { value: fingerprint, scope: product, stability: 'stable' },
656
+ details: {
657
+ ...(commit === undefined ? {} : { commit }),
658
+ ...(date === undefined ? {} : { date }),
659
+ ...(typeof entry.Entropy === 'number' ? { entropy: entry.Entropy } : {}),
660
+ ...(Array.isArray(entry.Tags) ? { tags: entry.Tags } : {}),
661
+ },
662
+ };
663
+ const place = JSON.stringify([rule, file, line, column]);
664
+ const time = date === undefined ? Number.NaN : Date.parse(date);
665
+ const seen = byPlace.get(place);
666
+ if (seen === undefined) {
667
+ byPlace.set(place, { finding, time, alsoIn: [] });
668
+ return;
669
+ }
670
+ // The later entry replaces the kept one unless both dates are known and
671
+ // it is strictly newer. So an earlier date wins, and on a tie or a
672
+ // missing date the LAST entry in report order wins: git log lists newer
673
+ // commits first, so the last is the oldest, never a synthetic merge.
674
+ const bothDated = !Number.isNaN(time) && !Number.isNaN(seen.time);
675
+ const replace = !bothDated || time <= seen.time;
676
+ const dropped = replace ? seen.finding : finding;
677
+ const droppedCommit = dropped.details.commit;
678
+ if (replace) {
679
+ seen.finding = finding;
680
+ seen.time = time;
681
+ }
682
+ if (typeof droppedCommit === 'string') {
683
+ seen.alsoIn.push(droppedCommit);
684
+ }
685
+ });
686
+ const findings = [...byPlace.values()].map(({ finding, alsoIn }) => alsoIn.length === 0 ? finding : { ...finding, details: { ...finding.details, alsoIn } });
687
+ return {
688
+ findings,
689
+ run: {
690
+ // Any match fails the gate: gitleaks has no threshold to report.
691
+ failOn: 'any',
692
+ suppressed: 0,
693
+ ignored: 0,
694
+ diagnostics: [],
695
+ details: { entries: entries.length },
696
+ },
697
+ diagnostics: [],
698
+ };
699
+ }
700
+ // -- osv-scanner (external, known vulnerabilities) ------------------------
701
+ //
702
+ // `osv-scanner scan source --format json` prints results[] per lockfile,
703
+ // packages[] per resolved package, vulnerabilities[] per advisory, and
704
+ // groups[] that merge an advisory with its aliases and carry the highest
705
+ // CVSS base score among them as `max_severity`, a string. Every field read
706
+ // below was checked against the 2.6.0 capture (tests/fixtures/README.md).
707
+ /** CVSS base score onto the shared four-level ladder, by the CVSS v3 bands. */
708
+ export function cvssToSeverity(score) {
709
+ if (score === null || Number.isNaN(score)) {
710
+ return 'medium';
711
+ }
712
+ if (score >= 9) {
713
+ return 'critical';
714
+ }
715
+ if (score >= 7) {
716
+ return 'high';
717
+ }
718
+ if (score >= 4) {
719
+ return 'medium';
720
+ }
721
+ return 'low';
722
+ }
723
+ function osvScore(vuln, groups) {
724
+ const id = typeof vuln.id === 'string' ? vuln.id : '';
725
+ for (const group of groups) {
726
+ const ids = Array.isArray(group.ids) ? group.ids : [];
727
+ if (ids.includes(id) && typeof group.max_severity === 'string' && group.max_severity !== '') {
728
+ const score = Number(group.max_severity);
729
+ if (!Number.isNaN(score)) {
730
+ return score;
731
+ }
732
+ }
733
+ }
734
+ // No group score: fall back to the advisory database's own word, mapped
735
+ // to a representative score inside the matching band.
736
+ const specific = vuln.database_specific;
737
+ if (isRecord(specific) && typeof specific.severity === 'string') {
738
+ const word = specific.severity.toUpperCase();
739
+ if (word === 'CRITICAL')
740
+ return 9.5;
741
+ if (word === 'HIGH')
742
+ return 7.5;
743
+ if (word === 'MODERATE' || word === 'MEDIUM')
744
+ return 5;
745
+ if (word === 'LOW')
746
+ return 2;
747
+ }
748
+ return null;
749
+ }
750
+ /** Numeric parts of a version, for ordering; "0" and "4.0.0" both parse. */
751
+ function versionParts(value) {
752
+ return (value.match(/\d+/g) ?? []).map(Number);
753
+ }
754
+ function compareVersions(a, b) {
755
+ const left = versionParts(a);
756
+ const right = versionParts(b);
757
+ for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
758
+ const difference = (left[i] ?? 0) - (right[i] ?? 0);
759
+ if (difference !== 0) {
760
+ return difference;
761
+ }
762
+ }
763
+ return 0;
764
+ }
765
+ /**
766
+ * The release that fixes this advisory for the INSTALLED version.
767
+ *
768
+ * An advisory can list several ranges for one package (nanoid's fixes at
769
+ * 3.3.16 for the 3.x line and 5.1.16 for 4.x and 5.x), so the first `fixed`
770
+ * event is not the answer: the fix is the one closing the range the
771
+ * installed version sits in. When no range can be shown to contain it, the
772
+ * lowest fix above the installed version is the next best statement; when
773
+ * there is none, no fix is claimed.
774
+ */
775
+ function osvFixedVersion(vuln, name, installed) {
776
+ const affected = Array.isArray(vuln.affected) ? vuln.affected : [];
777
+ const candidates = [];
778
+ for (const entry of affected) {
779
+ if (!isRecord(entry))
780
+ continue;
781
+ if (isRecord(entry.package) && entry.package.name !== name)
782
+ continue;
783
+ const ranges = Array.isArray(entry.ranges) ? entry.ranges : [];
784
+ for (const range of ranges) {
785
+ if (!isRecord(range) || !Array.isArray(range.events))
786
+ continue;
787
+ let introduced;
788
+ for (const event of range.events) {
789
+ if (!isRecord(event))
790
+ continue;
791
+ if (typeof event.introduced === 'string') {
792
+ introduced = event.introduced;
793
+ }
794
+ if (typeof event.fixed === 'string') {
795
+ candidates.push(event.fixed);
796
+ const inRange = installed !== '' &&
797
+ (introduced === undefined || compareVersions(installed, introduced) >= 0) &&
798
+ compareVersions(installed, event.fixed) < 0;
799
+ if (inRange) {
800
+ return event.fixed;
801
+ }
802
+ }
803
+ }
804
+ }
805
+ }
806
+ const above = candidates
807
+ .filter((fixed) => installed === '' || compareVersions(fixed, installed) > 0)
808
+ .sort(compareVersions);
809
+ return above[0];
810
+ }
811
+ /**
812
+ * osv-scanner writes every manifest path absolute, whatever scan root or
813
+ * relative --lockfile path it is given, so in CI it names the runner's
814
+ * checkout. Made relative to the first root that contains it; left as it is
815
+ * when none does, rather than guessed.
816
+ */
817
+ function relativeToRoots(file, roots) {
818
+ for (const root of roots) {
819
+ const prefix = root.endsWith('/') ? root : `${root}/`;
820
+ if (file.startsWith(prefix)) {
821
+ return file.slice(prefix.length);
822
+ }
823
+ }
824
+ return file;
825
+ }
826
+ export function normalizeOsvScanner(raw, version, blocked,
827
+ /** The scan root as a path osv-scanner may have printed it, in any spelling. */
828
+ roots = []) {
829
+ const product = 'osv-scanner';
830
+ const top = needRecord(raw, product, 'the output');
831
+ const results = needArray(top.results, product, 'results');
832
+ const findings = [];
833
+ for (const [ri, rawResult] of results.entries()) {
834
+ const resultWhere = `results[${ri}]`;
835
+ const result = needRecord(rawResult, product, resultWhere);
836
+ const source = needRecord(result.source, product, `${resultWhere}.source`);
837
+ const manifest = relativeToRoots(needString(source.path, product, `${resultWhere}.source.path`), roots);
838
+ const packages = needArray(result.packages, product, `${resultWhere}.packages`);
839
+ for (const [pi, rawPackage] of packages.entries()) {
840
+ const packageWhere = `${resultWhere}.packages[${pi}]`;
841
+ const entry = needRecord(rawPackage, product, packageWhere);
842
+ const pkg = needRecord(entry.package, product, `${packageWhere}.package`);
843
+ const name = needString(pkg.name, product, `${packageWhere}.package.name`);
844
+ const installed = optionalString(pkg.version, product, `${packageWhere}.package.version`) ?? '';
845
+ const ecosystem = optionalString(pkg.ecosystem, product, `${packageWhere}.package.ecosystem`);
846
+ const groups = (entry.groups === undefined ? [] : needArray(entry.groups, product, `${packageWhere}.groups`)).filter(isRecord);
847
+ const vulns = entry.vulnerabilities === undefined
848
+ ? []
849
+ : needArray(entry.vulnerabilities, product, `${packageWhere}.vulnerabilities`);
850
+ for (const [vi, rawVuln] of vulns.entries()) {
851
+ const where = `${packageWhere}.vulnerabilities[${vi}]`;
852
+ const vuln = needRecord(rawVuln, product, where);
853
+ const id = needString(vuln.id, product, `${where}.id`);
854
+ const score = osvScore(vuln, groups);
855
+ const fixedVersion = osvFixedVersion(vuln, name, installed);
856
+ findings.push({
857
+ schemaVersion: 1,
858
+ product,
859
+ productVersion: version,
860
+ ruleId: `osv-scanner/${id}`,
861
+ severity: cvssToSeverity(score),
862
+ severityIsDerived: true,
863
+ blocking: blocked,
864
+ message: optionalString(vuln.summary, product, `${where}.summary`) ??
865
+ `${id} affects ${name}@${installed}`,
866
+ subject: { kind: 'package', name, manifest },
867
+ // The advisory, the package and version it applies to, and the
868
+ // manifest it was found through: the same four facts on every run
869
+ // over the same lockfile, so the value is stable.
870
+ fingerprint: { value: `${id}|${name}|${installed}|${manifest}`, scope: product, stability: 'stable' },
871
+ details: {
872
+ version: installed,
873
+ ...(ecosystem === undefined ? {} : { ecosystem }),
874
+ aliases: Array.isArray(vuln.aliases) ? vuln.aliases : [],
875
+ ...(score === null ? {} : { cvss: score }),
876
+ ...(fixedVersion === undefined ? {} : { fixedVersion }),
877
+ },
878
+ });
879
+ }
880
+ }
881
+ }
882
+ return {
883
+ findings,
884
+ run: {
885
+ // Any known vulnerability fails the gate; a threshold, when an adopter
886
+ // wants one, lives in osv-scanner.toml.
887
+ failOn: 'any',
888
+ suppressed: 0,
889
+ ignored: 0,
890
+ diagnostics: [],
891
+ details: { sources: results.length },
892
+ },
893
+ diagnostics: [],
894
+ };
895
+ }
592
896
  function gateProblem(ruleId, role, product, message, details) {
593
897
  return {
594
898
  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
  //
@@ -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.
@@ -36,5 +62,20 @@ export interface TextOptions {
36
62
  * fires when the trust base was actually refused, whatever --verbose says.
37
63
  */
38
64
  compact?: boolean;
65
+ /**
66
+ * Maps an EXIT_BLOCKED verdict to exit 0 in the printed verdict line, and
67
+ * says so in words. This never touches the RunResult passed in: the exit
68
+ * code composed for this run (`result.exitCode`) is unchanged, and so is
69
+ * every finding's own `blocking` marker in the sections above the verdict.
70
+ * `cli.ts` is what actually maps the PROCESS exit code, from the same
71
+ * `result.exitCode` this option reads; this flag exists so the one line a
72
+ * reader is most likely to read alone does not contradict the exit code
73
+ * the process is about to produce.
74
+ *
75
+ * Has no effect on any other verdict shape: a could-not-run run (exit 2)
76
+ * reads the same whatever this says, because advisory is about a finding
77
+ * that did not block, never about a gate that did not run.
78
+ */
79
+ advisory?: boolean;
39
80
  }
40
81
  export declare function renderText(result: RunResult, options?: TextOptions): string;
@@ -338,18 +338,52 @@ function refusalLines(result) {
338
338
  ` ${refusal}`,
339
339
  ];
340
340
  }
341
- function verdict(result) {
341
+ /**
342
+ * The one-line summary a `--output` run prints to the job log after writing
343
+ * its report to a file (see cli.ts). Refused first, exactly like every other
344
+ * renderer in this file, and for the same reason: `refusedTrustBase` fills
345
+ * `result.gates` and `result.findings` with a could-not-run outcome PER
346
+ * ENABLED GATE, so counting them the ordinary way reports "N gate(s), N
347
+ * finding(s)" on a run where nothing ran and nothing was found -- issue #46.
348
+ * A reader with only this line, no --verbose and no pull-request comment
349
+ * (a fork's read-only token, or pr-comment left off) deserves the same words
350
+ * the comment's own compact body gives them, not a count that implies gates
351
+ * ran.
352
+ *
353
+ * `refusal` (from refuseTrustBaseRef in trust-base.ts) already says "Nothing
354
+ * was checked" itself as part of its own sentence, so this does not repeat
355
+ * that lead-in: doing so used to print the phrase twice on one line. Nor
356
+ * does it append its own closing sentence: cli.ts joins this return value
357
+ * with "; " before the rest of the job-log line, and a trailing period here
358
+ * left every refused run's log line reading "...; sarif report written",
359
+ * with a period sitting directly before that semicolon. A trailing period
360
+ * on `refusal` itself is trimmed for the same reason.
361
+ *
362
+ * A normal run is untouched: the exact same
363
+ * "N gate(s), N finding(s)" text as before, so a working adopter's log does
364
+ * not change.
365
+ */
366
+ export function jobLogSummary(result) {
367
+ const refusal = result.trustBase?.refusal;
368
+ if (refusal !== undefined && refusal !== null) {
369
+ return `refused the trust base "${result.trustBase?.ref ?? ''}": ${refusal.replace(/\.+\s*$/, '')}`;
370
+ }
371
+ return `${result.gates.length} gate(s), ${result.findings.length} finding(s)`;
372
+ }
373
+ function verdict(result, advisory) {
342
374
  const refusal = result.trustBase?.refusal;
343
375
  if (refusal !== undefined && refusal !== null) {
344
376
  // Written rather than composed, exactly as the exit code is: no gate ran,
345
377
  // so there is nothing for the clauses below to count, and every one of
346
- // them would describe a different run from the one that happened.
378
+ // them would describe a different run from the one that happened. A
379
+ // refusal is a could-not-run outcome (exit 2), which --advisory never
380
+ // touches, so this branch reads advisory or not exactly the same.
347
381
  return (`verdict: exit 2, the trust base "${result.trustBase?.ref ?? ''}" could not be used, ` +
348
382
  'so no gate ran and nothing here is a result of any kind.');
349
383
  }
350
- return verdictForRun(result);
384
+ return verdictForRun(result, advisory);
351
385
  }
352
- function verdictForRun(result) {
386
+ function verdictForRun(result, advisory) {
353
387
  // Counted over ENFORCED gates only. The exit code came from those alone,
354
388
  // so a count taken over all of them describes a different run from the one
355
389
  // the number at the front of the line is about, and the umbrella's own
@@ -410,16 +444,37 @@ function verdictForRun(result) {
410
444
  // on the one line somebody reads when they read nothing else contradicts
411
445
  // the exit code printed beside it, and sends a reader looking for a
412
446
  // finding that this report deliberately does not claim.
447
+ //
448
+ // ADVISORY ONLY EVER REWRITES THIS ONE BRANCH. The process's own exit
449
+ // code is decided in cli.ts by mapping EXIT_BLOCKED to EXIT_OK when
450
+ // --advisory was given; this function never changes result.exitCode
451
+ // itself, so a could-not-run verdict a few lines up is untouched
452
+ // whatever `advisory` says. The findings above this line still print
453
+ // with their BLOCKING marker: advisory changes what the exit code
454
+ // claims, never what a gate found.
413
455
  if (blocking === 0) {
456
+ // The mismatch branch: composeExitCode also lands here when an
457
+ // enforced gate exited non-zero but nothing reconciled as a blocking
458
+ // finding (conductor/blocking-count-mismatch or
459
+ // conductor/blocking-threshold-unknown; see normalize.ts). "Findings
460
+ // were advisory and did not block" would claim a finding this branch
461
+ // explicitly says there is none of, so it gets its own, narrower
462
+ // wording that is true here and says nothing about findings at all.
414
463
  const names = enforcedGates
415
464
  .filter((gate) => (gate.exitCode ?? 0) !== 0)
416
465
  .map((gate) => `${gate.role} (exit ${gate.exitCode ?? '?'})`)
417
466
  .join(', ');
418
- return (`verdict: exit 1, and no finding here is marked blocking. Enforced gate(s) that exited ` +
467
+ const base = `and no finding here is marked blocking. Enforced gate(s) that exited ` +
419
468
  `non-zero: ${names}. The umbrella could not reconcile a blocking count with what those ` +
420
- `gates reported, so the gate exit code decided the run.${aside}`);
469
+ `gates reported, so the gate exit code decided the run.${aside}`;
470
+ return advisory
471
+ ? `verdict: exit 0, ${base} This run was advisory, so exit 1 became exit 0.`
472
+ : `verdict: exit 1, ${base}`;
421
473
  }
422
- return `verdict: exit 1, ${blocking} blocking finding(s) across ${enforcedGates.length} gate(s).${aside}`;
474
+ const base = `${blocking} blocking finding(s) across ${enforcedGates.length} gate(s).${aside}`;
475
+ return advisory
476
+ ? `verdict: exit 0, ${base} Findings were advisory and did not block, so this run exits 0 rather than 1.`
477
+ : `verdict: exit 1, ${base}`;
423
478
  }
424
479
  // Exit 0 with red on the screen above it. The verdict is the one line
425
480
  // somebody reads when they read nothing else, so it is the line that has
@@ -618,7 +673,11 @@ export function renderText(result, options = {}) {
618
673
  // "conductor init", or reading the pull request's own file as a
619
674
  // proposal) as part of the same sentence. Nothing here points at a step
620
675
  // log: the reason has to be readable on the comment itself.
621
- const lines = [...versionLine(options.version), verdict(result), ...refusal];
676
+ const lines = [
677
+ ...versionLine(options.version),
678
+ verdict(result, Boolean(options.advisory)),
679
+ ...refusal,
680
+ ];
622
681
  return `${lines.join('\n')}\n`;
623
682
  }
624
683
  if (refusal.length === 0 && !options.verbose && isFullyClean(result)) {
@@ -655,6 +714,6 @@ export function renderText(result, options = {}) {
655
714
  if (result.findings.some((finding) => finding.severityIsDerived)) {
656
715
  lines.push('', '* severity assigned by the umbrella; that gate reports no per-finding severity.');
657
716
  }
658
- lines.push('', verdict(result));
717
+ lines.push('', verdict(result, Boolean(options.advisory)));
659
718
  return `${lines.join('\n')}\n`;
660
719
  }
package/dist/policy.d.ts CHANGED
@@ -1,7 +1,13 @@
1
1
  export declare const POLICY_FILE_NAME = ".guardrails.yaml";
2
- export declare const GATE_ROLES: readonly ["dependencies", "secrets", "intent"];
2
+ export declare const GATE_ROLES: readonly ["dependencies", "secrets", "intent", "secrets-history", "vulnerabilities"];
3
3
  export type GateRole = (typeof GATE_ROLES)[number];
4
- export declare const PRODUCTS: readonly ["dep-guard", "vault-guard", "intent-guard"];
4
+ /**
5
+ * Five products. The first three are this family's own npm packages, which
6
+ * the Action installs. The last two are external tools the adopter installs
7
+ * on their own machine or runner; conductor finds them on PATH and downloads
8
+ * nothing (src/products.ts, `managed: false`).
9
+ */
10
+ export declare const PRODUCTS: readonly ["dep-guard", "vault-guard", "intent-guard", "gitleaks", "osv-scanner"];
5
11
  export type Product = (typeof PRODUCTS)[number];
6
12
  /**
7
13
  * When a gate runs, in order, earliest first.
@@ -17,8 +23,8 @@ export type GateStage = (typeof GATE_STAGES)[number];
17
23
  /**
18
24
  * Where each gate sits when the policy file does not say.
19
25
  *
20
- * Runtime is not what decides this. All three gates together take under a
21
- * second on a staged commit; the cost is CEREMONY, and only the intent gate
26
+ * Runtime is not what decides this for the three family gates: together they
27
+ * take under a second on a staged commit; the cost is CEREMONY, and only the intent gate
22
28
  * has any, because it wants a contract approved before the work starts.
23
29
  * The other two are silent until they find something, and a secret that
24
30
  * reaches a pull request is already on a remote, so the earliest stage is