@vaultcompass/conductor 0.4.7 → 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.
@@ -338,6 +338,38 @@ function refusalLines(result) {
338
338
  ` ${refusal}`,
339
339
  ];
340
340
  }
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
+ }
341
373
  function verdict(result, advisory) {
342
374
  const refusal = result.trustBase?.refusal;
343
375
  if (refusal !== undefined && refusal !== null) {
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
package/dist/policy.js CHANGED
@@ -1,6 +1,7 @@
1
1
  // The one policy file.
2
2
  //
3
- // Gates are keyed by the ROLE they fill (dependencies, secrets, intent) and
3
+ // Gates are keyed by the ROLE they fill (dependencies, secrets, intent,
4
+ // secrets-history, vulnerabilities) and
4
5
  // name the product filling it in a `product` field. That indirection is
5
6
  // worth the extra line: a product rename, or swapping one gate for another,
6
7
  // becomes a one-line edit instead of a rename of the key a repository wrote
@@ -9,18 +10,19 @@
9
10
  // Two rules this file exists to enforce, both of them decisions rather than
10
11
  // mechanics:
11
12
  //
12
- // 1. THERE IS NO SHARED SEVERITY THRESHOLD. Two of the three products
13
- // happen to share a four-level scale; the third scores a weighted
14
- // rubric from 0 to 100 and has no per-finding severity at all. A single
15
- // `failOn` at the top of the file would read as one decision and mean
16
- // three different things, so a top-level `failOn` is rejected outright
13
+ // 1. THERE IS NO SHARED SEVERITY THRESHOLD. Five products, two of them
14
+ // external tools. Two of the family's three share a four-level scale; the
15
+ // third scores a weighted rubric from 0 to 100, gitleaks reports match
16
+ // or no match, and osv-scanner carries CVSS scores. A single `failOn` at
17
+ // the top of the file would read as one decision and mean five
18
+ // different things, so a top-level `failOn` is rejected outright
17
19
  // rather than silently ignored. Each gate keeps its own threshold in
18
20
  // its own passthrough block, spelled the way that gate spells it.
19
21
  //
20
22
  // 2. THE PASSTHROUGH IS ACTUALLY A PASSTHROUGH. `options` keys are the
21
23
  // gate's own long-flag names with the dashes stripped, and this file
22
24
  // never maps, renames, or interprets one. That is what keeps the
23
- // umbrella from growing a second, drifting copy of three CLIs, and it
25
+ // umbrella from growing a second, drifting copy of five CLIs, and it
24
26
  // is why a gate gains a flag without this package needing a release.
25
27
  // The only keys rejected are the handful the umbrella itself passes,
26
28
  // because two writers of the same flag is a fight the user would have
@@ -34,8 +36,20 @@ import path from 'node:path';
34
36
  import { fileURLToPath } from 'node:url';
35
37
  import { parse as parseYaml } from 'yaml';
36
38
  export const POLICY_FILE_NAME = '.guardrails.yaml';
37
- export const GATE_ROLES = ['dependencies', 'secrets', 'intent'];
38
- export const PRODUCTS = ['dep-guard', 'vault-guard', 'intent-guard'];
39
+ export const GATE_ROLES = [
40
+ 'dependencies',
41
+ 'secrets',
42
+ 'intent',
43
+ 'secrets-history',
44
+ 'vulnerabilities',
45
+ ];
46
+ /**
47
+ * Five products. The first three are this family's own npm packages, which
48
+ * the Action installs. The last two are external tools the adopter installs
49
+ * on their own machine or runner; conductor finds them on PATH and downloads
50
+ * nothing (src/products.ts, `managed: false`).
51
+ */
52
+ export const PRODUCTS = ['dep-guard', 'vault-guard', 'intent-guard', 'gitleaks', 'osv-scanner'];
39
53
  /**
40
54
  * When a gate runs, in order, earliest first.
41
55
  *
@@ -49,8 +63,8 @@ export const GATE_STAGES = ['commit', 'push', 'ci'];
49
63
  /**
50
64
  * Where each gate sits when the policy file does not say.
51
65
  *
52
- * Runtime is not what decides this. All three gates together take under a
53
- * second on a staged commit; the cost is CEREMONY, and only the intent gate
66
+ * Runtime is not what decides this for the three family gates: together they
67
+ * take under a second on a staged commit; the cost is CEREMONY, and only the intent gate
54
68
  * has any, because it wants a contract approved before the work starts.
55
69
  * The other two are silent until they find something, and a secret that
56
70
  * reaches a pull request is already on a remote, so the earliest stage is
@@ -60,6 +74,11 @@ export const DEFAULT_STAGE_FOR_ROLE = {
60
74
  dependencies: 'commit',
61
75
  secrets: 'commit',
62
76
  intent: 'ci',
77
+ // A history scan and a registry lookup are pull-request work, not
78
+ // commit-time work: one reads every commit, the other asks a network
79
+ // service, and neither says anything about the files being staged.
80
+ 'secrets-history': 'ci',
81
+ vulnerabilities: 'ci',
63
82
  };
64
83
  /** Whether a gate at `gateStage` runs during a run asked for at `requested`. */
65
84
  export function runsAtStage(gateStage, requested) {
@@ -79,6 +98,8 @@ export const PRODUCT_FOR_ROLE = {
79
98
  dependencies: 'dep-guard',
80
99
  secrets: 'vault-guard',
81
100
  intent: 'intent-guard',
101
+ 'secrets-history': 'gitleaks',
102
+ vulnerabilities: 'osv-scanner',
82
103
  };
83
104
  /**
84
105
  * Flags the umbrella supplies itself, per product. A policy that also sets
@@ -112,6 +133,27 @@ export const RESERVED_OPTIONS = {
112
133
  // problem rather than a confusion, since the loser decides where the gate
113
134
  // reads its rules from.
114
135
  'intent-guard': ['json', 'staged', 'project', 'paths', 'base', 'trust-base'],
136
+ // The umbrella writes every one of these for gitleaks: the report goes to a
137
+ // file it owns, the exit code for a leak is moved off 1 so an error and a
138
+ // leak stop sharing a number, history is scoped by --log-opts so one
139
+ // branch's secret cannot redden every other pull request, and the config
140
+ // is read from the base ref on a pull request, as is the ignore file.
141
+ gitleaks: [
142
+ 'report-format',
143
+ 'report-path',
144
+ 'exit-code',
145
+ 'log-opts',
146
+ 'config',
147
+ 'gitleaks-ignore-path',
148
+ 'ignore-gitleaks-allow',
149
+ 'redact',
150
+ 'no-banner',
151
+ 'log-level',
152
+ ],
153
+ // osv-scanner: the umbrella owns the format (json to stdout), the config on
154
+ // a pull-request run, and which lockfiles are scanned (every tracked one,
155
+ // by name; there is no directory walk and so no --recursive).
156
+ 'osv-scanner': ['format', 'config', 'lockfile'],
115
157
  };
116
158
  export class PolicyError extends Error {
117
159
  constructor(message) {
@@ -175,18 +217,62 @@ function reservedReason(product, key) {
175
217
  "Use the umbrella's own --base instead.");
176
218
  }
177
219
  if (product === 'dep-guard' && key === 'base') {
178
- return ('The umbrella never passes --base to this gate; it passes --staged, and a base here ' +
179
- 'would fight it over which change set is being scanned. Use the umbrella own --staged, ' +
180
- 'or leave it off to scan the working tree.');
220
+ return ('On a pull-request run the umbrella writes --base to this gate itself, pointing at the ' +
221
+ 'same ref as --trust-base, so a value here would be a second writer of the flag that ' +
222
+ 'decides what changed. Otherwise the umbrella passes --staged on a staged run, and a ' +
223
+ "base here would fight it: dep-guard's own CLI refuses --staged and --base together. On " +
224
+ 'a plain run the umbrella passes neither flag, and a base here would silently decide ' +
225
+ 'what that run compares dependencies against, without going through the trust base the ' +
226
+ 'umbrella itself decided. Leave it off; the umbrella decides it either way.');
181
227
  }
182
228
  if (product === 'vault-guard' && key === 'format') {
183
229
  return ('The umbrella writes this option itself under its short name, -f json. A --format here ' +
184
230
  'is a second writer of the same option, and which one wins depends on that CLI argument ' +
185
231
  'parser. The report format is chosen with the umbrella own --format.');
186
232
  }
233
+ const external = EXTERNAL_RESERVED_REASONS[product]?.[key];
234
+ if (external !== undefined) {
235
+ return `The umbrella passes --${key} to ${product} itself. ${external}`;
236
+ }
187
237
  return (`The umbrella passes that flag to ${product} itself, and two writers of one flag ` +
188
238
  'would resolve differently depending on that CLI argument parser.');
189
239
  }
240
+ /**
241
+ * Why each flag the umbrella writes for an external tool is the umbrella's.
242
+ * Every one of them is written; the sentence says what a second writer would
243
+ * break, which for these tools is a verdict rather than a formatting detail.
244
+ */
245
+ const EXTERNAL_RESERVED_REASONS = {
246
+ gitleaks: {
247
+ 'report-format': 'The report is parsed as JSON; another format would make every run unparseable.',
248
+ 'report-path': 'The report goes to a file the umbrella owns and reads back; pointing it elsewhere would ' +
249
+ 'leave the umbrella nothing to read.',
250
+ 'exit-code': 'The umbrella moves the leak exit code to 3 because gitleaks also exits 1 on an error; ' +
251
+ 'another value would make a crash read as a leak, or a leak read as clean.',
252
+ 'log-opts': 'The umbrella scopes history to HEAD, or to base..HEAD on a pull request, so a secret on ' +
253
+ 'another branch cannot redden this one. Narrow the scan in .gitleaks.toml instead.',
254
+ config: 'On a pull request the config is read from the base ref, so the pull request cannot ' +
255
+ 'allowlist what it adds. Commit .gitleaks.toml instead.',
256
+ 'gitleaks-ignore-path': 'On a pull request the ignore file is read from the base ref, so the pull request cannot ' +
257
+ 'ignore the fingerprint of the leak it adds. Commit .gitleaksignore instead.',
258
+ 'ignore-gitleaks-allow': 'On a pull request inline gitleaks:allow comments are ignored, because an inline allow ' +
259
+ 'lives in the tree being judged and the pull request controls it. A legitimate allow ' +
260
+ 'belongs in the base ref .gitleaks.toml allowlist or .gitleaksignore.',
261
+ redact: 'Findings reach a pull-request comment and a SARIF upload; the umbrella keeps secrets ' +
262
+ 'redacted in the report it reads.',
263
+ 'no-banner': 'The banner is noise on stderr, which the report shows when a gate fails.',
264
+ 'log-level': 'The umbrella depends on gitleaks ERR lines to tell a failed scan from a clean one: gitleaks ' +
265
+ 'reports a git failure as exit 0 with an empty report. A lower level would silence them and ' +
266
+ 'turn a scan that never happened into a pass, so the umbrella pins it at info.',
267
+ },
268
+ 'osv-scanner': {
269
+ format: 'The output is parsed as JSON from stdout; another format would make every run unparseable.',
270
+ config: 'On a pull request the config is read from the base ref, so the pull request cannot ' +
271
+ 'ignore the advisory it introduces. Commit osv-scanner.toml instead.',
272
+ lockfile: 'The umbrella hands osv-scanner every tracked lockfile by name, so no lockfile is left ' +
273
+ 'out by a policy line or by a .gitignore entry.',
274
+ },
275
+ };
190
276
  /**
191
277
  * Parses and validates policy YAML.
192
278
  *