@vaultcompass/conductor 0.8.0 → 0.9.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 +263 -77
- package/dist/cli.js +152 -30
- package/dist/envelope.d.ts +8 -0
- package/dist/exit-codes.d.ts +52 -2
- package/dist/exit-codes.js +64 -14
- package/dist/external-config.d.ts +2 -1
- package/dist/external-config.js +33 -18
- package/dist/gate-runner.d.ts +141 -17
- package/dist/gate-runner.js +537 -83
- package/dist/git.d.ts +95 -0
- package/dist/git.js +244 -0
- package/dist/init-policy.js +38 -2
- package/dist/init.js +40 -3
- package/dist/intent-base.d.ts +35 -1
- package/dist/intent-base.js +124 -64
- package/dist/intent-prepare.d.ts +33 -2
- package/dist/intent-prepare.js +443 -34
- package/dist/intent-spec.d.ts +28 -0
- package/dist/intent-spec.js +22 -5
- package/dist/normalize.d.ts +11 -0
- package/dist/normalize.js +60 -6
- package/dist/osv-baseline.d.ts +84 -0
- package/dist/osv-baseline.js +325 -0
- package/dist/osv-coverage.d.ts +80 -0
- package/dist/osv-coverage.js +223 -0
- package/dist/output-sarif.js +55 -15
- package/dist/output-text.d.ts +53 -2
- package/dist/output-text.js +287 -27
- package/dist/policy.d.ts +10 -0
- package/dist/policy.js +21 -7
- package/dist/products.d.ts +32 -10
- package/dist/products.js +73 -9
- package/dist/requirements-pin.d.ts +47 -0
- package/dist/requirements-pin.js +256 -0
- package/dist/resolve.d.ts +1 -0
- package/dist/resolve.js +1 -1
- package/dist/run.d.ts +21 -0
- package/dist/run.js +74 -15
- package/dist/trust-base.d.ts +101 -20
- package/dist/trust-base.js +219 -73
- package/dist/unread-manifests.d.ts +14 -0
- package/dist/unread-manifests.js +69 -0
- package/package.json +1 -1
- package/schema/guardrails.schema.json +4 -0
package/dist/intent-spec.js
CHANGED
|
@@ -154,7 +154,7 @@ function exists(repoRoot, relative) {
|
|
|
154
154
|
* the failure actually had: "superpowers" beat
|
|
155
155
|
* "1.2.1-base-and-superpowers" by being shorter and vaguer.
|
|
156
156
|
*/
|
|
157
|
-
function bestMatch(names, target) {
|
|
157
|
+
export function bestMatch(names, target) {
|
|
158
158
|
return names
|
|
159
159
|
.filter((name) => stemMatches(normalizeStem(name), target))
|
|
160
160
|
.sort((a, b) => {
|
|
@@ -192,7 +192,18 @@ function planFor(repoRoot, specPath) {
|
|
|
192
192
|
const specStem = normalizeStem(path.basename(specPath));
|
|
193
193
|
const matches = markdownFilesIn(repoRoot, PLAN_DIR).filter((name) => normalizeStem(name) === specStem);
|
|
194
194
|
const newest = matches[matches.length - 1];
|
|
195
|
-
|
|
195
|
+
if (newest === undefined) {
|
|
196
|
+
return { plan: null };
|
|
197
|
+
}
|
|
198
|
+
const plan = `${PLAN_DIR}/${newest}`;
|
|
199
|
+
// Held to the repository like the convention spec: a plans directory
|
|
200
|
+
// linked out of the checkout is refused, never read and never dropped.
|
|
201
|
+
return resolvesInsideRoot(repoRoot, plan) ? { plan } : { escaped: plan };
|
|
202
|
+
}
|
|
203
|
+
/** A found spec with its plan, or the refusal for a plan that escapes. */
|
|
204
|
+
function withPlan(repoRoot, kind, spec) {
|
|
205
|
+
const found = planFor(repoRoot, spec);
|
|
206
|
+
return 'escaped' in found ? { kind: 'escaped', path: found.escaped } : { kind, spec, plan: found.plan };
|
|
196
207
|
}
|
|
197
208
|
/** Normalizes a user-supplied path to a repository-relative one. */
|
|
198
209
|
function relativeToRoot(repoRoot, candidate) {
|
|
@@ -253,7 +264,7 @@ export function discoverSpec(options) {
|
|
|
253
264
|
if (!exists(repoRoot, relative)) {
|
|
254
265
|
return { kind: 'missing-flag', spec: relative };
|
|
255
266
|
}
|
|
256
|
-
return
|
|
267
|
+
return withPlan(repoRoot, 'flag', relative);
|
|
257
268
|
}
|
|
258
269
|
if (options.prBody !== undefined) {
|
|
259
270
|
const named = specFromPrBody(options.prBody);
|
|
@@ -274,7 +285,7 @@ export function discoverSpec(options) {
|
|
|
274
285
|
// Containment subsumes existence here, since a path that does not
|
|
275
286
|
// resolve is not contained.
|
|
276
287
|
if (resolvesInsideRoot(repoRoot, relative)) {
|
|
277
|
-
return
|
|
288
|
+
return withPlan(repoRoot, 'pr-body', relative);
|
|
278
289
|
}
|
|
279
290
|
}
|
|
280
291
|
}
|
|
@@ -282,7 +293,13 @@ export function discoverSpec(options) {
|
|
|
282
293
|
const best = bestMatch(markdownFilesIn(repoRoot, SPEC_DIR), branchSlug(options.branch));
|
|
283
294
|
if (best !== undefined) {
|
|
284
295
|
const relative = `${SPEC_DIR}/${best}`;
|
|
285
|
-
|
|
296
|
+
// The convention spec is held to the repository too: a specs directory
|
|
297
|
+
// linked out of the checkout is refused, never imported. Only --spec is
|
|
298
|
+
// exempt, as a path a person typed.
|
|
299
|
+
if (!resolvesInsideRoot(repoRoot, relative)) {
|
|
300
|
+
return { kind: 'escaped', path: relative };
|
|
301
|
+
}
|
|
302
|
+
return withPlan(repoRoot, 'convention', relative);
|
|
286
303
|
}
|
|
287
304
|
}
|
|
288
305
|
return { kind: 'none' };
|
package/dist/normalize.d.ts
CHANGED
|
@@ -48,6 +48,17 @@ export declare function normalizeIntentGuard(raw: unknown, version: string | nul
|
|
|
48
48
|
export declare function normalizeGitleaks(raw: unknown, version: string | null, blocked: boolean): NormalizedGateOutput;
|
|
49
49
|
/** CVSS base score onto the shared four-level ladder, by the CVSS v3 bands. */
|
|
50
50
|
export declare function cvssToSeverity(score: number | null): Severity;
|
|
51
|
+
/**
|
|
52
|
+
* The vulnerabilities summary line's lockfile fact (issue #72): the count and
|
|
53
|
+
* names of the lockfiles the UMBRELLA handed osv-scanner with --lockfile,
|
|
54
|
+
* never osv-scanner's own results[], which 2.x prints only for a source with
|
|
55
|
+
* findings. A clean scan of one lockfile and a run that scanned none both
|
|
56
|
+
* have results: [], and only this list tells them apart.
|
|
57
|
+
*
|
|
58
|
+
* A file in `emptied` (osv-scanner read no packages from it, audit finding
|
|
59
|
+
* F2) is marked in place, so the count never reads as that many files read.
|
|
60
|
+
*/
|
|
61
|
+
export declare function describeLockfiles(lockfiles: readonly string[], emptied?: ReadonlySet<string>): string;
|
|
51
62
|
export declare function normalizeOsvScanner(raw: unknown, version: string | null, blocked: boolean,
|
|
52
63
|
/** The scan root as a path osv-scanner may have printed it, in any spelling. */
|
|
53
64
|
roots?: readonly string[],
|
package/dist/normalize.js
CHANGED
|
@@ -337,10 +337,12 @@ export function normalizeVaultGuard(raw, version) {
|
|
|
337
337
|
run: {
|
|
338
338
|
failOn: threshold,
|
|
339
339
|
suppressed: typeof run.baseline_suppressed === 'number' ? run.baseline_suppressed : 0,
|
|
340
|
-
//
|
|
341
|
-
//
|
|
342
|
-
//
|
|
343
|
-
//
|
|
340
|
+
// This normalizer reads no ignore count out of vault-guard's run object
|
|
341
|
+
// (which does carry config_ignored_files; it is not mapped here), so 0
|
|
342
|
+
// is a placeholder and not a claim that nothing was ignored. What makes
|
|
343
|
+
// the report say "ignored not reported" is not this number: it is
|
|
344
|
+
// `ignoredReported: false` in `details` below, which output-text.ts and
|
|
345
|
+
// the summary line read in its place.
|
|
344
346
|
ignored: 0,
|
|
345
347
|
// vault-guard's diagnostics carry a context object rather than a
|
|
346
348
|
// message, so the context is rendered as one. Validated the same way
|
|
@@ -941,9 +943,13 @@ function relativeToRoots(file, roots) {
|
|
|
941
943
|
* never osv-scanner's own results[], which 2.x prints only for a source with
|
|
942
944
|
* findings. A clean scan of one lockfile and a run that scanned none both
|
|
943
945
|
* have results: [], and only this list tells them apart.
|
|
946
|
+
*
|
|
947
|
+
* A file in `emptied` (osv-scanner read no packages from it, audit finding
|
|
948
|
+
* F2) is marked in place, so the count never reads as that many files read.
|
|
944
949
|
*/
|
|
945
|
-
function describeLockfiles(lockfiles) {
|
|
946
|
-
|
|
950
|
+
export function describeLockfiles(lockfiles, emptied = new Set()) {
|
|
951
|
+
const named = lockfiles.map((file) => (emptied.has(file) ? `${file} [no packages read]` : file));
|
|
952
|
+
return lockfiles.length === 0 ? '0' : `${lockfiles.length} (${named.join(', ')})`;
|
|
947
953
|
}
|
|
948
954
|
export function normalizeOsvScanner(raw, version, blocked,
|
|
949
955
|
/** The scan root as a path osv-scanner may have printed it, in any spelling. */
|
|
@@ -954,6 +960,7 @@ lockfiles = []) {
|
|
|
954
960
|
const top = needRecord(raw, product, 'the output');
|
|
955
961
|
const results = needArray(top.results, product, 'results');
|
|
956
962
|
const findings = [];
|
|
963
|
+
const otherVerdicts = [];
|
|
957
964
|
for (const [ri, rawResult] of results.entries()) {
|
|
958
965
|
const resultWhere = `results[${ri}]`;
|
|
959
966
|
const result = needRecord(rawResult, product, resultWhere);
|
|
@@ -967,6 +974,7 @@ lockfiles = []) {
|
|
|
967
974
|
const name = needString(pkg.name, product, `${packageWhere}.package.name`);
|
|
968
975
|
const installed = optionalString(pkg.version, product, `${packageWhere}.package.version`) ?? '';
|
|
969
976
|
const ecosystem = optionalString(pkg.ecosystem, product, `${packageWhere}.package.ecosystem`);
|
|
977
|
+
otherVerdicts.push(...osvOtherVerdicts(entry, pkg, `${name}@${installed}`));
|
|
970
978
|
const groups = (entry.groups === undefined ? [] : needArray(entry.groups, product, `${packageWhere}.groups`)).filter(isRecord);
|
|
971
979
|
const vulns = entry.vulnerabilities === undefined
|
|
972
980
|
? []
|
|
@@ -1021,8 +1029,54 @@ lockfiles = []) {
|
|
|
1021
1029
|
},
|
|
1022
1030
|
},
|
|
1023
1031
|
diagnostics: [],
|
|
1032
|
+
otherVerdicts,
|
|
1024
1033
|
};
|
|
1025
1034
|
}
|
|
1035
|
+
/**
|
|
1036
|
+
* The package-level keys of an osv-scanner result this normalizer knows:
|
|
1037
|
+
* the package itself, its advisories, their groups, and the licences it was
|
|
1038
|
+
* found to carry. `license_violations` is deliberately NOT here: it is a
|
|
1039
|
+
* verdict (osv-scanner exits 1 for it, measured on 2.4.0 with --licenses).
|
|
1040
|
+
*/
|
|
1041
|
+
const OSV_KNOWN_PACKAGE_KEYS = new Set(['package', 'vulnerabilities', 'groups', 'licenses']);
|
|
1042
|
+
function isEmptyValue(value) {
|
|
1043
|
+
if (value === undefined || value === null || value === false || value === '') {
|
|
1044
|
+
return true;
|
|
1045
|
+
}
|
|
1046
|
+
if (Array.isArray(value)) {
|
|
1047
|
+
return value.length === 0;
|
|
1048
|
+
}
|
|
1049
|
+
return isRecord(value) && Object.keys(value).length === 0;
|
|
1050
|
+
}
|
|
1051
|
+
/**
|
|
1052
|
+
* Every verdict on one package that is not an advisory, one line each.
|
|
1053
|
+
*
|
|
1054
|
+
* Two shapes, both measured on osv-scanner 2.4.0. `license_violations` beside
|
|
1055
|
+
* `vulnerabilities` (--licenses), and `package.deprecated: true` INSIDE the
|
|
1056
|
+
* package object (--experimental-flag-deprecated-packages; a deprecated
|
|
1057
|
+
* package with no advisory exits 1 too). Beyond those, any other non-empty
|
|
1058
|
+
* PACKAGE-level key this normalizer does not map counts the same, so a
|
|
1059
|
+
* verdict field a later osv-scanner adds fails closed rather than open.
|
|
1060
|
+
* Top-level keys (license_summary, experimental_config) and result-level ones
|
|
1061
|
+
* (source) are summaries and settings, not verdicts on a package, and are
|
|
1062
|
+
* not read.
|
|
1063
|
+
*
|
|
1064
|
+
* KNOWN GAP: inside the package object only `deprecated` is read. A future
|
|
1065
|
+
* verdict field osv-scanner writes INSIDE `package` (a `yanked` flag, say)
|
|
1066
|
+
* is not seen by the catch-all, which looks at package-level keys only.
|
|
1067
|
+
*/
|
|
1068
|
+
function osvOtherVerdicts(entry, pkg, label) {
|
|
1069
|
+
const out = [];
|
|
1070
|
+
for (const [key, value] of Object.entries(entry)) {
|
|
1071
|
+
if (!OSV_KNOWN_PACKAGE_KEYS.has(key) && !isEmptyValue(value)) {
|
|
1072
|
+
out.push(`${key} (${label})`);
|
|
1073
|
+
}
|
|
1074
|
+
}
|
|
1075
|
+
if (!isEmptyValue(pkg.deprecated)) {
|
|
1076
|
+
out.push(`deprecated (${label})`);
|
|
1077
|
+
}
|
|
1078
|
+
return out;
|
|
1079
|
+
}
|
|
1026
1080
|
function gateProblem(ruleId, role, product, message, details) {
|
|
1027
1081
|
return {
|
|
1028
1082
|
schemaVersion: 1,
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import type { Diagnostic, Finding } from './envelope.js';
|
|
2
|
+
import type { PresentOnBase } from './policy.js';
|
|
3
|
+
export type BaselineLabel = 'introduced' | 'present-on-base';
|
|
4
|
+
/**
|
|
5
|
+
* What the comparison did, carried on the gate's outcome so a report (and the
|
|
6
|
+
* exit-code exception) never needs the policy file to explain itself.
|
|
7
|
+
* Present only when a comparison ran (section 3.1).
|
|
8
|
+
*/
|
|
9
|
+
export interface BaseComparison {
|
|
10
|
+
/** The trust base the copies were read from. */
|
|
11
|
+
ref: string;
|
|
12
|
+
/** The base policy's present-on-base value, block when it said nothing. */
|
|
13
|
+
policy: PresentOnBase;
|
|
14
|
+
introduced: number;
|
|
15
|
+
presentOnBase: number;
|
|
16
|
+
/** Lockfiles whose findings all count as introduced because no comparison was possible, with why. */
|
|
17
|
+
unavailable: Array<{
|
|
18
|
+
path: string;
|
|
19
|
+
reason: string;
|
|
20
|
+
}>;
|
|
21
|
+
/**
|
|
22
|
+
* Verdicts in the head run's raw output that are not advisories (licence
|
|
23
|
+
* violations, deprecated packages, any unmapped package-level field). Read
|
|
24
|
+
* by condition (f) of gateExitBlocks.
|
|
25
|
+
*/
|
|
26
|
+
otherVerdicts: string[];
|
|
27
|
+
}
|
|
28
|
+
/** The comparison key: advisory id, ecosystem, package, installed version, lockfile path. */
|
|
29
|
+
export declare function comparisonKey(finding: Finding): string | null;
|
|
30
|
+
/**
|
|
31
|
+
* Labels head findings against base findings. Pure, so the comparison can be
|
|
32
|
+
* tested without spawning anything.
|
|
33
|
+
*
|
|
34
|
+
* A finding in a lockfile in `unchanged` (byte-equal to the base, its whole
|
|
35
|
+
* include closure too) is present-on-base without a base scan: identical
|
|
36
|
+
* input, config and database. A finding in a lockfile in `unavailable` is
|
|
37
|
+
* introduced whatever the base said. Otherwise it is present-on-base exactly
|
|
38
|
+
* when a base finding has the same key.
|
|
39
|
+
*/
|
|
40
|
+
export declare function labelAgainstBase(head: readonly Finding[], base: readonly Finding[], unavailable: ReadonlySet<string>, unchanged: ReadonlySet<string>): Finding[];
|
|
41
|
+
export interface BaseSpawnResult {
|
|
42
|
+
status: number | null;
|
|
43
|
+
stdout: string;
|
|
44
|
+
error: Error | undefined;
|
|
45
|
+
}
|
|
46
|
+
export interface CompareArgs {
|
|
47
|
+
repoRoot: string;
|
|
48
|
+
ref: string;
|
|
49
|
+
workDir: string;
|
|
50
|
+
policy: PresentOnBase;
|
|
51
|
+
version: string | null;
|
|
52
|
+
headFindings: readonly Finding[];
|
|
53
|
+
/** Every file the head run was handed, repository-relative. */
|
|
54
|
+
headLockfiles: readonly string[];
|
|
55
|
+
/** For each requirements file, the head include closure when the head copy passed the pin check. */
|
|
56
|
+
closures: ReadonlyMap<string, readonly string[] | null>;
|
|
57
|
+
otherVerdicts: readonly string[];
|
|
58
|
+
/** The head run's full argv. */
|
|
59
|
+
headArgv: readonly string[];
|
|
60
|
+
/** The base run's full argv for these absolute copy paths, built by the same gateArgs. */
|
|
61
|
+
baseArgv: (copies: readonly string[]) => string[];
|
|
62
|
+
/** Runs the same binary, with the same timeout, from `cwd`. */
|
|
63
|
+
spawn: (argv: readonly string[], cwd: string) => BaseSpawnResult;
|
|
64
|
+
/** Every spelling of a directory a child could print it in. */
|
|
65
|
+
rootSpellings: (dir: string) => string[];
|
|
66
|
+
}
|
|
67
|
+
export interface CompareResult {
|
|
68
|
+
findings: Finding[];
|
|
69
|
+
comparison: BaseComparison;
|
|
70
|
+
diagnostics: Diagnostic[];
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* The result when the comparison itself failed in a way compareWithBase did
|
|
74
|
+
* not anticipate: every lockfile with findings is unavailable and every
|
|
75
|
+
* finding is introduced. Never could-not-run.
|
|
76
|
+
*/
|
|
77
|
+
export declare function comparisonFailed(args: CompareArgs, reason: string): CompareResult;
|
|
78
|
+
/**
|
|
79
|
+
* Runs the comparison. Assumes the caller has established section 3.1: a
|
|
80
|
+
* decided trust base, a head run that exited blocked, at least one finding.
|
|
81
|
+
* Never throws for anything it anticipated; the caller still wraps it, and
|
|
82
|
+
* any throw becomes "every finding introduced", never could-not-run.
|
|
83
|
+
*/
|
|
84
|
+
export declare function compareWithBase(args: CompareArgs): CompareResult;
|
|
@@ -0,0 +1,325 @@
|
|
|
1
|
+
// The vulnerabilities gate's base comparison (osv design, item 1.3, section 3).
|
|
2
|
+
//
|
|
3
|
+
// On a pull-request run whose head scan blocked, osv-scanner is also run on
|
|
4
|
+
// the BASE copies of the lockfiles that carry findings, and each head finding
|
|
5
|
+
// is labelled `introduced` or `present-on-base` by a key that names the
|
|
6
|
+
// advisory, the ecosystem, the package, the installed version and the
|
|
7
|
+
// repository-relative lockfile path. The vulnerabilities gate's own policy
|
|
8
|
+
// key (present-on-base, read from the base policy) then decides whether a
|
|
9
|
+
// present-on-base finding blocks.
|
|
10
|
+
//
|
|
11
|
+
// Every failure here labels toward `introduced`: an unreadable base, a base
|
|
12
|
+
// run that did not finish, output that would not parse, a path that cannot be
|
|
13
|
+
// made relative. The base run never makes the gate could-not-run and never
|
|
14
|
+
// removes a head finding. Nothing the pull request controls can move a
|
|
15
|
+
// finding from introduced to present-on-base except making the head lockfile
|
|
16
|
+
// byte-equal to the base's at the same path, in which case the label is true.
|
|
17
|
+
import { mkdirSync, realpathSync, writeFileSync } from 'node:fs';
|
|
18
|
+
import path from 'node:path';
|
|
19
|
+
import { realPathInside, runGit } from './git.js';
|
|
20
|
+
import { normalizeOsvScanner } from './normalize.js';
|
|
21
|
+
import { ABSENT_ON_BASE, baseReader } from './osv-coverage.js';
|
|
22
|
+
import { osvLockfileKind } from './products.js';
|
|
23
|
+
import { checkRequirementsPins } from './requirements-pin.js';
|
|
24
|
+
import { readFileAtRefBytes, treeEntryAt } from './trust-base.js';
|
|
25
|
+
/** The comparison key: advisory id, ecosystem, package, installed version, lockfile path. */
|
|
26
|
+
export function comparisonKey(finding) {
|
|
27
|
+
if (finding.subject.kind !== 'package') {
|
|
28
|
+
return null;
|
|
29
|
+
}
|
|
30
|
+
const id = finding.ruleId.startsWith('osv-scanner/') ? finding.ruleId.slice('osv-scanner/'.length) : finding.ruleId;
|
|
31
|
+
const ecosystem = typeof finding.details.ecosystem === 'string' ? finding.details.ecosystem : '';
|
|
32
|
+
const version = typeof finding.details.version === 'string' ? finding.details.version : '';
|
|
33
|
+
return JSON.stringify([id, ecosystem, finding.subject.name, version, finding.subject.manifest]);
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* Labels head findings against base findings. Pure, so the comparison can be
|
|
37
|
+
* tested without spawning anything.
|
|
38
|
+
*
|
|
39
|
+
* A finding in a lockfile in `unchanged` (byte-equal to the base, its whole
|
|
40
|
+
* include closure too) is present-on-base without a base scan: identical
|
|
41
|
+
* input, config and database. A finding in a lockfile in `unavailable` is
|
|
42
|
+
* introduced whatever the base said. Otherwise it is present-on-base exactly
|
|
43
|
+
* when a base finding has the same key.
|
|
44
|
+
*/
|
|
45
|
+
export function labelAgainstBase(head, base, unavailable, unchanged) {
|
|
46
|
+
const baseKeys = new Set(base.map(comparisonKey).filter((key) => key !== null));
|
|
47
|
+
return head.map((finding) => {
|
|
48
|
+
const manifest = finding.subject.kind === 'package' ? finding.subject.manifest : null;
|
|
49
|
+
let label = 'introduced';
|
|
50
|
+
if (manifest !== null && !unavailable.has(manifest)) {
|
|
51
|
+
const key = comparisonKey(finding);
|
|
52
|
+
if (unchanged.has(manifest) || (key !== null && baseKeys.has(key))) {
|
|
53
|
+
label = 'present-on-base';
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
return { ...finding, details: { ...finding.details, baseline: label } };
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
/** The argv with every --lockfile pair removed, for the symmetry check. */
|
|
60
|
+
function withoutLockfiles(argv) {
|
|
61
|
+
const out = [];
|
|
62
|
+
for (let i = 0; i < argv.length; i += 1) {
|
|
63
|
+
if (argv[i] === '--lockfile') {
|
|
64
|
+
i += 1;
|
|
65
|
+
continue;
|
|
66
|
+
}
|
|
67
|
+
out.push(argv[i]);
|
|
68
|
+
}
|
|
69
|
+
return out;
|
|
70
|
+
}
|
|
71
|
+
/** The first token where two argvs differ, for the unavailable note. */
|
|
72
|
+
function firstDifference(a, b) {
|
|
73
|
+
const length = Math.max(a.length, b.length);
|
|
74
|
+
for (let i = 0; i < length; i += 1) {
|
|
75
|
+
if (a[i] !== b[i]) {
|
|
76
|
+
return a[i] ?? b[i] ?? '(end)';
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
return '(none)';
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Head object ids for files on disk, with filters OFF: a clean filter comes
|
|
83
|
+
* from the head's own .gitattributes, so a filtered id would let the head
|
|
84
|
+
* decide what "equal to the base" means. One git call for all of them. Null
|
|
85
|
+
* when git could not answer, which disables the shortcut and never enables it.
|
|
86
|
+
*/
|
|
87
|
+
function headObjectIds(repoRoot, files) {
|
|
88
|
+
if (files.length === 0) {
|
|
89
|
+
return new Map();
|
|
90
|
+
}
|
|
91
|
+
const out = runGit(repoRoot, ['hash-object', '--no-filters', '--stdin-paths'], {
|
|
92
|
+
input: `${files.join('\n')}\n`,
|
|
93
|
+
});
|
|
94
|
+
if (out.error !== undefined || out.status !== 0) {
|
|
95
|
+
return null;
|
|
96
|
+
}
|
|
97
|
+
const ids = out.stdout.split('\n').filter((line) => line !== '');
|
|
98
|
+
if (ids.length !== files.length) {
|
|
99
|
+
return null;
|
|
100
|
+
}
|
|
101
|
+
return new Map(files.map((file, i) => [file, ids[i]]));
|
|
102
|
+
}
|
|
103
|
+
/** Writes one base copy under `dir`, refusing an absolute or climbing path. */
|
|
104
|
+
function placeCopy(dir, file, bytes) {
|
|
105
|
+
const target = path.resolve(dir, file);
|
|
106
|
+
if (path.isAbsolute(file) || !target.startsWith(`${dir}${path.sep}`)) {
|
|
107
|
+
throw new Error(`${file} is not a path inside the repository`);
|
|
108
|
+
}
|
|
109
|
+
mkdirSync(path.dirname(target), { recursive: true });
|
|
110
|
+
writeFileSync(target, bytes);
|
|
111
|
+
return target;
|
|
112
|
+
}
|
|
113
|
+
function unavailableNotes(unavailable) {
|
|
114
|
+
const byReason = new Map();
|
|
115
|
+
for (const entry of unavailable) {
|
|
116
|
+
byReason.set(entry.reason, [...(byReason.get(entry.reason) ?? []), entry.path]);
|
|
117
|
+
}
|
|
118
|
+
return [...byReason].map(([reason, paths]) => ({
|
|
119
|
+
code: 'conductor/base-comparison-unavailable',
|
|
120
|
+
message: `base comparison unavailable for ${paths.join(', ')}: ${reason}; every finding there counts ` +
|
|
121
|
+
'as introduced.',
|
|
122
|
+
}));
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* The result when the comparison itself failed in a way compareWithBase did
|
|
126
|
+
* not anticipate: every lockfile with findings is unavailable and every
|
|
127
|
+
* finding is introduced. Never could-not-run.
|
|
128
|
+
*/
|
|
129
|
+
export function comparisonFailed(args, reason) {
|
|
130
|
+
const unavailable = [
|
|
131
|
+
...new Set(args.headFindings
|
|
132
|
+
.map((finding) => (finding.subject.kind === 'package' ? finding.subject.manifest : null))
|
|
133
|
+
.filter((manifest) => manifest !== null)),
|
|
134
|
+
]
|
|
135
|
+
.sort()
|
|
136
|
+
.map((file) => ({ path: file, reason }));
|
|
137
|
+
const findings = labelAgainstBase(args.headFindings, [], new Set(unavailable.map((u) => u.path)), new Set());
|
|
138
|
+
return {
|
|
139
|
+
findings,
|
|
140
|
+
comparison: {
|
|
141
|
+
ref: args.ref,
|
|
142
|
+
policy: args.policy,
|
|
143
|
+
introduced: findings.length,
|
|
144
|
+
presentOnBase: 0,
|
|
145
|
+
unavailable,
|
|
146
|
+
otherVerdicts: [...args.otherVerdicts],
|
|
147
|
+
},
|
|
148
|
+
diagnostics: unavailableNotes(unavailable),
|
|
149
|
+
};
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* Runs the comparison. Assumes the caller has established section 3.1: a
|
|
153
|
+
* decided trust base, a head run that exited blocked, at least one finding.
|
|
154
|
+
* Never throws for anything it anticipated; the caller still wraps it, and
|
|
155
|
+
* any throw becomes "every finding introduced", never could-not-run.
|
|
156
|
+
*/
|
|
157
|
+
export function compareWithBase(args) {
|
|
158
|
+
const unavailable = [];
|
|
159
|
+
const unchanged = new Set();
|
|
160
|
+
const handed = new Set(args.headLockfiles);
|
|
161
|
+
const withFindings = [
|
|
162
|
+
...new Set(args.headFindings
|
|
163
|
+
.map((finding) => (finding.subject.kind === 'package' ? finding.subject.manifest : null))
|
|
164
|
+
.filter((manifest) => manifest !== null && handed.has(manifest))),
|
|
165
|
+
].sort();
|
|
166
|
+
const baseDir = path.join(args.workDir, 'osv-base');
|
|
167
|
+
let baseFindings = [];
|
|
168
|
+
const finish = () => {
|
|
169
|
+
const unavailablePaths = new Set(unavailable.map((entry) => entry.path));
|
|
170
|
+
const labelled = labelAgainstBase(args.headFindings, baseFindings, unavailablePaths, unchanged).map((finding) => args.policy === 'report' && finding.details.baseline === 'present-on-base'
|
|
171
|
+
? { ...finding, blocking: false }
|
|
172
|
+
: finding);
|
|
173
|
+
const present = labelled.filter((finding) => finding.details.baseline === 'present-on-base').length;
|
|
174
|
+
return {
|
|
175
|
+
findings: labelled,
|
|
176
|
+
comparison: {
|
|
177
|
+
ref: args.ref,
|
|
178
|
+
policy: args.policy,
|
|
179
|
+
introduced: labelled.length - present,
|
|
180
|
+
presentOnBase: present,
|
|
181
|
+
unavailable,
|
|
182
|
+
otherVerdicts: [...args.otherVerdicts],
|
|
183
|
+
},
|
|
184
|
+
diagnostics: unavailableNotes(unavailable),
|
|
185
|
+
};
|
|
186
|
+
};
|
|
187
|
+
// The work directory must be outside the repository, or a base copy would
|
|
188
|
+
// sit inside the tree being judged (a TMPDIR set inside the checkout).
|
|
189
|
+
if (realPathInside(args.repoRoot, args.workDir)) {
|
|
190
|
+
for (const file of withFindings) {
|
|
191
|
+
unavailable.push({
|
|
192
|
+
path: file,
|
|
193
|
+
reason: 'the temporary directory is inside the repository, so no base copy can be kept outside ' +
|
|
194
|
+
'the tree being judged',
|
|
195
|
+
});
|
|
196
|
+
}
|
|
197
|
+
return finish();
|
|
198
|
+
}
|
|
199
|
+
// 1. The unchanged shortcut: object ids, filters off, the whole closure.
|
|
200
|
+
const closureOf = (file) => osvLockfileKind(path.posix.basename(file)) === 'requirements' ? (args.closures.get(file) ?? null) : [file];
|
|
201
|
+
const shortcutFiles = [
|
|
202
|
+
...new Set(withFindings.flatMap((file) => closureOf(file) ?? [])),
|
|
203
|
+
].sort();
|
|
204
|
+
const headIds = headObjectIds(args.repoRoot, shortcutFiles);
|
|
205
|
+
const toCopy = [];
|
|
206
|
+
for (const file of withFindings) {
|
|
207
|
+
const closure = closureOf(file);
|
|
208
|
+
if (closure !== null && headIds !== null) {
|
|
209
|
+
const same = closure.every((member) => {
|
|
210
|
+
const entry = treeEntryAt(args.repoRoot, args.ref, member);
|
|
211
|
+
return (entry.kind === 'entry' &&
|
|
212
|
+
entry.type === 'blob' &&
|
|
213
|
+
(entry.mode === '100644' || entry.mode === '100755') &&
|
|
214
|
+
entry.sha === headIds.get(member));
|
|
215
|
+
});
|
|
216
|
+
if (same) {
|
|
217
|
+
unchanged.add(file);
|
|
218
|
+
continue;
|
|
219
|
+
}
|
|
220
|
+
}
|
|
221
|
+
toCopy.push(file);
|
|
222
|
+
}
|
|
223
|
+
// 2 to 4. Absent, unreadable, or copied byte for byte from the base.
|
|
224
|
+
const copies = [];
|
|
225
|
+
const copied = [];
|
|
226
|
+
for (const file of toCopy) {
|
|
227
|
+
const kind = osvLockfileKind(file);
|
|
228
|
+
if (kind === 'requirements') {
|
|
229
|
+
const bytes = new Map();
|
|
230
|
+
const check = checkRequirementsPins(file, baseReader(args.repoRoot, args.ref, bytes));
|
|
231
|
+
if (check.topMissing === ABSENT_ON_BASE) {
|
|
232
|
+
continue;
|
|
233
|
+
}
|
|
234
|
+
if (!check.pinned) {
|
|
235
|
+
unavailable.push({
|
|
236
|
+
path: file,
|
|
237
|
+
reason: 'its base copy, or a file it includes there, is not pinned with == or cannot be read, so ' +
|
|
238
|
+
'it cannot be compared',
|
|
239
|
+
});
|
|
240
|
+
continue;
|
|
241
|
+
}
|
|
242
|
+
try {
|
|
243
|
+
for (const member of check.files) {
|
|
244
|
+
placeCopy(baseDir, member, bytes.get(member));
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
catch (err) {
|
|
248
|
+
unavailable.push({ path: file, reason: err instanceof Error ? err.message : String(err) });
|
|
249
|
+
continue;
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
else {
|
|
253
|
+
const read = readFileAtRefBytes(args.repoRoot, args.ref, file);
|
|
254
|
+
if (read.kind === 'absent') {
|
|
255
|
+
continue;
|
|
256
|
+
}
|
|
257
|
+
if (read.kind === 'error') {
|
|
258
|
+
unavailable.push({ path: file, reason: `the base copy cannot be read (${read.detail})` });
|
|
259
|
+
continue;
|
|
260
|
+
}
|
|
261
|
+
try {
|
|
262
|
+
placeCopy(baseDir, file, read.bytes);
|
|
263
|
+
}
|
|
264
|
+
catch (err) {
|
|
265
|
+
unavailable.push({ path: file, reason: err instanceof Error ? err.message : String(err) });
|
|
266
|
+
continue;
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
copies.push(path.join(baseDir, file));
|
|
270
|
+
copied.push(file);
|
|
271
|
+
}
|
|
272
|
+
if (copies.length === 0) {
|
|
273
|
+
return finish();
|
|
274
|
+
}
|
|
275
|
+
const failAll = (reason) => {
|
|
276
|
+
for (const file of copied) {
|
|
277
|
+
unavailable.push({ path: file, reason });
|
|
278
|
+
}
|
|
279
|
+
baseFindings = [];
|
|
280
|
+
return finish();
|
|
281
|
+
};
|
|
282
|
+
// The symmetry check: the base command line is the head's with only the
|
|
283
|
+
// lockfile arguments replaced. Any other difference (a resolution mode, a
|
|
284
|
+
// call-analysis flag, a config) would compare two different scans.
|
|
285
|
+
const baseArgv = args.baseArgv(copies);
|
|
286
|
+
const headRest = withoutLockfiles(args.headArgv);
|
|
287
|
+
const baseRest = withoutLockfiles(baseArgv);
|
|
288
|
+
if (JSON.stringify(headRest) !== JSON.stringify(baseRest)) {
|
|
289
|
+
return failAll(`the base run's command line would differ from the head run's at ${firstDifference(headRest, baseRest)}`);
|
|
290
|
+
}
|
|
291
|
+
const child = args.spawn(baseArgv, baseDir);
|
|
292
|
+
if (child.error !== undefined || child.status === null) {
|
|
293
|
+
return failAll('osv-scanner did not finish on the base copies (it timed out, was killed or could not start)');
|
|
294
|
+
}
|
|
295
|
+
if (child.status === 128) {
|
|
296
|
+
// The copies parsed to no packages: nothing on the base to match.
|
|
297
|
+
baseFindings = [];
|
|
298
|
+
return finish();
|
|
299
|
+
}
|
|
300
|
+
if (child.status !== 0 && child.status !== 1) {
|
|
301
|
+
return failAll(`osv-scanner exited ${child.status} on the base copies`);
|
|
302
|
+
}
|
|
303
|
+
let parsed;
|
|
304
|
+
try {
|
|
305
|
+
parsed = JSON.parse(child.stdout);
|
|
306
|
+
}
|
|
307
|
+
catch {
|
|
308
|
+
return failAll('osv-scanner printed no valid JSON for the base copies');
|
|
309
|
+
}
|
|
310
|
+
try {
|
|
311
|
+
let roots;
|
|
312
|
+
try {
|
|
313
|
+
roots = args.rootSpellings(realpathSync(baseDir));
|
|
314
|
+
}
|
|
315
|
+
catch {
|
|
316
|
+
roots = [];
|
|
317
|
+
}
|
|
318
|
+
roots = [...new Set([...args.rootSpellings(baseDir), ...roots])];
|
|
319
|
+
baseFindings = normalizeOsvScanner(parsed, args.version, child.status === 1, roots, copied).findings;
|
|
320
|
+
}
|
|
321
|
+
catch (err) {
|
|
322
|
+
return failAll(`the base output could not be read (${err instanceof Error ? err.message : String(err)})`);
|
|
323
|
+
}
|
|
324
|
+
return finish();
|
|
325
|
+
}
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import type { Diagnostic } from './envelope.js';
|
|
2
|
+
import { type IncludeRead } from './requirements-pin.js';
|
|
3
|
+
export interface OsvSelection {
|
|
4
|
+
/** Every file handed over, repository-relative, sorted. */
|
|
5
|
+
handed: string[];
|
|
6
|
+
/** Requirements files left out, in candidate order. */
|
|
7
|
+
notScanned: string[];
|
|
8
|
+
/** The umbrella's own diagnostics: not-scanned and not-pinned. */
|
|
9
|
+
diagnostics: Diagnostic[];
|
|
10
|
+
/** Run notes, one per scanned requirements file: direct requirements only. */
|
|
11
|
+
notes: Diagnostic[];
|
|
12
|
+
/**
|
|
13
|
+
* For each scanned requirements file, the head include closure when the
|
|
14
|
+
* head copy passed the pin check, else null. The unchanged shortcut
|
|
15
|
+
* (section 3.2) compares the whole closure, and a head closure that did
|
|
16
|
+
* not pass is never taken as complete.
|
|
17
|
+
*/
|
|
18
|
+
closures: Map<string, string[] | null>;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* A reader over the head: a TRACKED regular file on disk. On disk because
|
|
22
|
+
* that is the copy osv-scanner reads; tracked because an untracked file is
|
|
23
|
+
* not part of what is being judged.
|
|
24
|
+
*/
|
|
25
|
+
export declare function headReader(repoRoot: string, tracked: ReadonlySet<string>): (file: string) => IncludeRead;
|
|
26
|
+
/** Why a base reader found nothing: the base tree has no such path. */
|
|
27
|
+
export declare const ABSENT_ON_BASE = "does not exist on the base";
|
|
28
|
+
/**
|
|
29
|
+
* A reader over the trust base, through the one reader (readFileAtRef's byte
|
|
30
|
+
* variant). Every byte it hands out is kept in `bytes`, so a base copy that is
|
|
31
|
+
* written out later is exactly the blob that was checked, never a re-read.
|
|
32
|
+
*/
|
|
33
|
+
export declare function baseReader(repoRoot: string, ref: string, bytes?: Map<string, Buffer>): (file: string) => IncludeRead;
|
|
34
|
+
/**
|
|
35
|
+
* Picks what osv-scanner is handed from the tracked files.
|
|
36
|
+
*
|
|
37
|
+
* `decidedRef` is the trust base on a pull-request run, and switches the
|
|
38
|
+
* ratchet on (section 2.3): a requirements file whose head copy fails the pin
|
|
39
|
+
* check is still handed over when its base copy, and the base include
|
|
40
|
+
* closure, passes. A base copy that exists and cannot be read is handed over
|
|
41
|
+
* too: leaving it out would let an unreadable base drop a file from the scan,
|
|
42
|
+
* which is the direction this gate does not fail in.
|
|
43
|
+
*/
|
|
44
|
+
export declare function selectOsvInputs(args: {
|
|
45
|
+
repoRoot: string;
|
|
46
|
+
tracked: readonly string[];
|
|
47
|
+
decidedRef?: string;
|
|
48
|
+
}): OsvSelection;
|
|
49
|
+
/**
|
|
50
|
+
* Notes for every basename-matched file tracked on the base and absent from
|
|
51
|
+
* the head (section 3.2): deleted, moved, or renamed to a name the matcher
|
|
52
|
+
* does not take. Such a file is not scanned on either side, and saying so is
|
|
53
|
+
* all this does: it never blocks. A base listing git could not make yields no
|
|
54
|
+
* note rather than a guess.
|
|
55
|
+
*/
|
|
56
|
+
export declare function noLongerScanned(repoRoot: string, ref: string, tracked: ReadonlySet<string>): Diagnostic[];
|
|
57
|
+
/** The nothing-to-scan sentence when every candidate was a requirements file left out. */
|
|
58
|
+
export declare function nothingScannableMessage(notScanned: readonly string[]): string;
|
|
59
|
+
/** The run detail beside `lockfiles`: how many requirements files were left out, and which. */
|
|
60
|
+
export declare function notScannedDetail(notScanned: readonly string[]): string;
|
|
61
|
+
/**
|
|
62
|
+
* The handed lockfiles osv-scanner said it found 0 packages in (audit
|
|
63
|
+
* finding F2). Its exit 128 covers only the case where EVERY handed file
|
|
64
|
+
* parsed to nothing, and its JSON lists only sources with findings, so a
|
|
65
|
+
* lockfile rewritten to `{}` beside a healthy one is otherwise
|
|
66
|
+
* indistinguishable from a clean one: listed as scanned, with every advisory
|
|
67
|
+
* it carried gone.
|
|
68
|
+
*
|
|
69
|
+
* Read from osv-scanner's stderr, which is annotation, never a verdict: this
|
|
70
|
+
* only adds a note. `handed` are the repository-relative paths the umbrella
|
|
71
|
+
* passed (the parse-as prefix is not part of them), and `cwd` is where the
|
|
72
|
+
* child ran. A path is compared in its written and its resolved spelling on
|
|
73
|
+
* both sides, so a temp directory reached through a symlink still matches,
|
|
74
|
+
* and by whole path, so two files with one base name never stand in for each
|
|
75
|
+
* other. A file with no count line is not named: that is a limit (a policy
|
|
76
|
+
* that lowers osv-scanner's verbosity hides every line), not a finding.
|
|
77
|
+
*/
|
|
78
|
+
export declare function emptiedLockfiles(stderr: string, handed: readonly string[], cwd: string): string[];
|
|
79
|
+
/** The note when a policy's no-resolve was dropped from an invocation. */
|
|
80
|
+
export declare const NO_RESOLVE_OVERRIDDEN: string;
|