@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/README.md +462 -138
- package/dist/cli.js +17 -7
- package/dist/envelope.js +1 -1
- package/dist/exit-codes.js +5 -1
- package/dist/external-config.d.ts +54 -0
- package/dist/external-config.js +171 -0
- package/dist/gate-runner.d.ts +43 -3
- package/dist/gate-runner.js +463 -37
- package/dist/init-policy.d.ts +19 -1
- package/dist/init-policy.js +42 -8
- package/dist/init.d.ts +30 -1
- package/dist/init.js +108 -19
- package/dist/normalize.d.ts +7 -1
- package/dist/normalize.js +309 -5
- package/dist/output-sarif.js +3 -2
- package/dist/output-text.d.ts +26 -0
- package/dist/output-text.js +32 -0
- package/dist/policy.d.ts +10 -4
- package/dist/policy.js +100 -14
- package/dist/products.d.ts +91 -0
- package/dist/products.js +123 -0
- package/dist/resolve.js +18 -4
- package/dist/run.js +3 -0
- package/package.json +1 -1
- package/schema/guardrails.schema.json +7 -5
package/dist/normalize.js
CHANGED
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
// Turning each gate's own JSON into the internal envelope.
|
|
2
2
|
//
|
|
3
|
-
//
|
|
4
|
-
//
|
|
5
|
-
//
|
|
6
|
-
//
|
|
7
|
-
//
|
|
3
|
+
// Separate functions rather than one table-driven mapper, because the
|
|
4
|
+
// shapes disagree in ways a table would have to paper over: one is a flat
|
|
5
|
+
// findings array, one is nested by file, the third is two different streams
|
|
6
|
+
// (a change-budget evaluation and a scored drift rubric) plus a gate status
|
|
7
|
+
// that can block for neither reason, and the two external tools' reports
|
|
8
|
+
// (gitleaks, osv-scanner) carry no blocking flag at all, so whether they
|
|
9
|
+
// block comes from the exit code the runner read.
|
|
8
10
|
//
|
|
9
11
|
// What every one of them refuses to do, in one place so it is reviewable:
|
|
10
12
|
// invent a line number, invent a fingerprint, re-derive a severity a
|
|
@@ -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,
|
package/dist/output-sarif.js
CHANGED
|
@@ -2,8 +2,9 @@
|
|
|
2
2
|
//
|
|
3
3
|
// SARIF is the family's published finding format; the envelope in
|
|
4
4
|
// envelope.ts is internal and never leaves this process. The mapping below
|
|
5
|
-
// is dep-guard's mapping, applied to
|
|
6
|
-
//
|
|
5
|
+
// is dep-guard's mapping, applied to every gate (the three family gates and
|
|
6
|
+
// the two external ones) from one place, which is the whole point: one
|
|
7
|
+
// hand-written emitter per gate is how a family ends up
|
|
7
8
|
// with one tool emitting absolute paths and another omitting fingerprints
|
|
8
9
|
// entirely, and both of those really happened here.
|
|
9
10
|
//
|
package/dist/output-text.d.ts
CHANGED
|
@@ -1,4 +1,30 @@
|
|
|
1
1
|
import type { RunResult } from './run.js';
|
|
2
|
+
/**
|
|
3
|
+
* The one-line summary a `--output` run prints to the job log after writing
|
|
4
|
+
* its report to a file (see cli.ts). Refused first, exactly like every other
|
|
5
|
+
* renderer in this file, and for the same reason: `refusedTrustBase` fills
|
|
6
|
+
* `result.gates` and `result.findings` with a could-not-run outcome PER
|
|
7
|
+
* ENABLED GATE, so counting them the ordinary way reports "N gate(s), N
|
|
8
|
+
* finding(s)" on a run where nothing ran and nothing was found -- issue #46.
|
|
9
|
+
* A reader with only this line, no --verbose and no pull-request comment
|
|
10
|
+
* (a fork's read-only token, or pr-comment left off) deserves the same words
|
|
11
|
+
* the comment's own compact body gives them, not a count that implies gates
|
|
12
|
+
* ran.
|
|
13
|
+
*
|
|
14
|
+
* `refusal` (from refuseTrustBaseRef in trust-base.ts) already says "Nothing
|
|
15
|
+
* was checked" itself as part of its own sentence, so this does not repeat
|
|
16
|
+
* that lead-in: doing so used to print the phrase twice on one line. Nor
|
|
17
|
+
* does it append its own closing sentence: cli.ts joins this return value
|
|
18
|
+
* with "; " before the rest of the job-log line, and a trailing period here
|
|
19
|
+
* left every refused run's log line reading "...; sarif report written",
|
|
20
|
+
* with a period sitting directly before that semicolon. A trailing period
|
|
21
|
+
* on `refusal` itself is trimmed for the same reason.
|
|
22
|
+
*
|
|
23
|
+
* A normal run is untouched: the exact same
|
|
24
|
+
* "N gate(s), N finding(s)" text as before, so a working adopter's log does
|
|
25
|
+
* not change.
|
|
26
|
+
*/
|
|
27
|
+
export declare function jobLogSummary(result: RunResult): string;
|
|
2
28
|
export interface TextOptions {
|
|
3
29
|
/**
|
|
4
30
|
* Print the full report even when the run is fully clean.
|
package/dist/output-text.js
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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
|
|
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.
|
|
13
|
-
//
|
|
14
|
-
// rubric from 0 to 100
|
|
15
|
-
//
|
|
16
|
-
//
|
|
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
|
|
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 = [
|
|
38
|
-
|
|
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
|
|
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 ('
|
|
179
|
-
'
|
|
180
|
-
'
|
|
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
|
*
|