@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/README.md +526 -169
- package/dist/cli.js +47 -9
- 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 +41 -0
- package/dist/output-text.js +68 -9
- 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.
|
|
@@ -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;
|
package/dist/output-text.js
CHANGED
|
@@ -338,18 +338,52 @@ function refusalLines(result) {
|
|
|
338
338
|
` ${refusal}`,
|
|
339
339
|
];
|
|
340
340
|
}
|
|
341
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 = [
|
|
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
|
-
|
|
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
|