@vaultcompass/conductor 0.8.1 → 0.10.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 +261 -46
- package/dist/cli.d.ts +6 -0
- package/dist/cli.js +20 -5
- package/dist/envelope.d.ts +8 -0
- package/dist/exit-codes.d.ts +52 -2
- package/dist/exit-codes.js +64 -14
- package/dist/gate-runner.d.ts +124 -11
- package/dist/gate-runner.js +491 -60
- package/dist/git.d.ts +15 -0
- package/dist/git.js +20 -0
- package/dist/init-hook-detect.d.ts +1 -0
- package/dist/init-hook-detect.js +45 -0
- package/dist/init-policy.js +51 -2
- package/dist/init.d.ts +8 -0
- package/dist/init.js +166 -20
- package/dist/intent-prepare.d.ts +18 -1
- package/dist/intent-prepare.js +23 -2
- package/dist/normalize.d.ts +43 -2
- package/dist/normalize.js +168 -10
- 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 +61 -2
- package/dist/output-text.d.ts +31 -3
- package/dist/output-text.js +354 -26
- package/dist/policy.d.ts +18 -0
- package/dist/policy.js +45 -6
- package/dist/products.d.ts +40 -11
- package/dist/products.js +87 -9
- package/dist/requirements-pin.d.ts +47 -0
- package/dist/requirements-pin.js +256 -0
- package/dist/run.d.ts +17 -0
- package/dist/run.js +29 -4
- package/dist/trust-base.d.ts +19 -0
- package/dist/trust-base.js +30 -1
- 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 +10 -0
|
@@ -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;
|
|
@@ -0,0 +1,223 @@
|
|
|
1
|
+
// Which tracked files the vulnerabilities gate hands osv-scanner (osv design,
|
|
2
|
+
// item 1.1, sections 2.1 to 2.4).
|
|
3
|
+
//
|
|
4
|
+
// Selection only. Nothing here raises a finding: a file left out is named in
|
|
5
|
+
// a diagnostic, the way the basename list has always decided what is handed
|
|
6
|
+
// over without judging anything. The verdict is still osv-scanner's own.
|
|
7
|
+
import { lstatSync, readFileSync, realpathSync } from 'node:fs';
|
|
8
|
+
import path from 'node:path';
|
|
9
|
+
import { runGit } from './git.js';
|
|
10
|
+
import { osvLockfileKind } from './products.js';
|
|
11
|
+
import { checkRequirementsPins, describePinProblem, } from './requirements-pin.js';
|
|
12
|
+
import { readFileAtRefBytes } from './trust-base.js';
|
|
13
|
+
/**
|
|
14
|
+
* A reader over the head: a TRACKED regular file on disk. On disk because
|
|
15
|
+
* that is the copy osv-scanner reads; tracked because an untracked file is
|
|
16
|
+
* not part of what is being judged.
|
|
17
|
+
*/
|
|
18
|
+
export function headReader(repoRoot, tracked) {
|
|
19
|
+
return (file) => {
|
|
20
|
+
const full = path.join(repoRoot, file);
|
|
21
|
+
let stats;
|
|
22
|
+
try {
|
|
23
|
+
stats = lstatSync(full);
|
|
24
|
+
}
|
|
25
|
+
catch {
|
|
26
|
+
return { kind: 'missing', why: tracked.has(file) ? 'is tracked but not on disk' : 'does not exist' };
|
|
27
|
+
}
|
|
28
|
+
if (!tracked.has(file)) {
|
|
29
|
+
return { kind: 'missing', why: 'is not tracked' };
|
|
30
|
+
}
|
|
31
|
+
if (!stats.isFile()) {
|
|
32
|
+
return { kind: 'missing', why: 'is not a regular file' };
|
|
33
|
+
}
|
|
34
|
+
return { kind: 'file', text: readFileSync(full, 'utf8') };
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
/** Why a base reader found nothing: the base tree has no such path. */
|
|
38
|
+
export const ABSENT_ON_BASE = 'does not exist on the base';
|
|
39
|
+
/**
|
|
40
|
+
* A reader over the trust base, through the one reader (readFileAtRef's byte
|
|
41
|
+
* variant). Every byte it hands out is kept in `bytes`, so a base copy that is
|
|
42
|
+
* written out later is exactly the blob that was checked, never a re-read.
|
|
43
|
+
*/
|
|
44
|
+
export function baseReader(repoRoot, ref, bytes = new Map()) {
|
|
45
|
+
return (file) => {
|
|
46
|
+
const read = readFileAtRefBytes(repoRoot, ref, file);
|
|
47
|
+
if (read.kind === 'absent') {
|
|
48
|
+
return { kind: 'missing', why: ABSENT_ON_BASE };
|
|
49
|
+
}
|
|
50
|
+
if (read.kind === 'error') {
|
|
51
|
+
return { kind: 'missing', why: `could not be read from the base (${read.detail})` };
|
|
52
|
+
}
|
|
53
|
+
bytes.set(file, read.bytes);
|
|
54
|
+
return { kind: 'file', text: read.bytes.toString('utf8') };
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
const DIRECT_ONLY = 'direct requirements only; no lockfile, so transitive packages are not scanned.';
|
|
58
|
+
/** The not-scanned sentence for one requirements file. */
|
|
59
|
+
function notScannedMessage(file, check) {
|
|
60
|
+
return `${file} not scanned: ${describePinProblem(file, check.problems[0])}.`;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* Picks what osv-scanner is handed from the tracked files.
|
|
64
|
+
*
|
|
65
|
+
* `decidedRef` is the trust base on a pull-request run, and switches the
|
|
66
|
+
* ratchet on (section 2.3): a requirements file whose head copy fails the pin
|
|
67
|
+
* check is still handed over when its base copy, and the base include
|
|
68
|
+
* closure, passes. A base copy that exists and cannot be read is handed over
|
|
69
|
+
* too: leaving it out would let an unreadable base drop a file from the scan,
|
|
70
|
+
* which is the direction this gate does not fail in.
|
|
71
|
+
*/
|
|
72
|
+
export function selectOsvInputs(args) {
|
|
73
|
+
const trackedSet = new Set(args.tracked);
|
|
74
|
+
const candidates = args.tracked
|
|
75
|
+
// Never a vendored copy under node_modules: that is a dependency's own
|
|
76
|
+
// lockfile, not a statement about what this repository resolves.
|
|
77
|
+
.filter((file) => !file.split('/').includes('node_modules'))
|
|
78
|
+
// The whole repository-relative path, not the base name: one format
|
|
79
|
+
// (gradle's verification-metadata.xml) is matched on its parent too.
|
|
80
|
+
.filter((file) => osvLockfileKind(file) !== null)
|
|
81
|
+
.sort();
|
|
82
|
+
const head = headReader(args.repoRoot, trackedSet);
|
|
83
|
+
const base = args.decidedRef === undefined ? null : baseReader(args.repoRoot, args.decidedRef);
|
|
84
|
+
const handed = [];
|
|
85
|
+
const notScanned = [];
|
|
86
|
+
const diagnostics = [];
|
|
87
|
+
const notes = [];
|
|
88
|
+
const closures = new Map();
|
|
89
|
+
for (const file of candidates) {
|
|
90
|
+
if (osvLockfileKind(file) === 'bare') {
|
|
91
|
+
handed.push(file);
|
|
92
|
+
continue;
|
|
93
|
+
}
|
|
94
|
+
const headCheck = checkRequirementsPins(file, head);
|
|
95
|
+
if (headCheck.pinned) {
|
|
96
|
+
handed.push(file);
|
|
97
|
+
closures.set(file, headCheck.files);
|
|
98
|
+
let suffix = '';
|
|
99
|
+
if (base !== null) {
|
|
100
|
+
const baseCheck = checkRequirementsPins(file, base);
|
|
101
|
+
if (!baseCheck.pinned && baseCheck.topMissing !== ABSENT_ON_BASE) {
|
|
102
|
+
suffix = ' Newly pinned in this pull request.';
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
notes.push({ code: 'conductor/requirements-direct-only', message: `${file}: ${DIRECT_ONLY}${suffix}` });
|
|
106
|
+
continue;
|
|
107
|
+
}
|
|
108
|
+
if (base !== null) {
|
|
109
|
+
const baseCheck = checkRequirementsPins(file, base);
|
|
110
|
+
const topUnreadable = baseCheck.topMissing !== null && baseCheck.topMissing !== ABSENT_ON_BASE;
|
|
111
|
+
if (baseCheck.pinned || topUnreadable) {
|
|
112
|
+
handed.push(file);
|
|
113
|
+
closures.set(file, null);
|
|
114
|
+
const lines = headCheck.problems.map((problem) => describePinProblem(file, problem)).join('; ');
|
|
115
|
+
const why = baseCheck.pinned
|
|
116
|
+
? 'Its copy on the base is pinned, so the file stays scanned under the ratchet; the lines named are read as written.'
|
|
117
|
+
: 'Its copy on the base could not be read, so the file stays scanned; the lines named are read as written.';
|
|
118
|
+
diagnostics.push({
|
|
119
|
+
code: 'conductor/requirements-not-pinned',
|
|
120
|
+
message: `${file} is scanned although ${lines}. ${why}`,
|
|
121
|
+
});
|
|
122
|
+
notes.push({
|
|
123
|
+
code: 'conductor/requirements-direct-only',
|
|
124
|
+
message: `${file}: ${DIRECT_ONLY} ${baseCheck.pinned ? 'Pinned on the base; scanned under the ratchet.' : 'Base copy unreadable; scanned under the ratchet.'}`,
|
|
125
|
+
});
|
|
126
|
+
continue;
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
notScanned.push(file);
|
|
130
|
+
diagnostics.push({ code: 'conductor/requirements-not-scanned', message: notScannedMessage(file, headCheck) });
|
|
131
|
+
}
|
|
132
|
+
return { handed: handed.sort(), notScanned, diagnostics, notes, closures };
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* Notes for every basename-matched file tracked on the base and absent from
|
|
136
|
+
* the head (section 3.2): deleted, moved, or renamed to a name the matcher
|
|
137
|
+
* does not take. Such a file is not scanned on either side, and saying so is
|
|
138
|
+
* all this does: it never blocks. A base listing git could not make yields no
|
|
139
|
+
* note rather than a guess.
|
|
140
|
+
*/
|
|
141
|
+
export function noLongerScanned(repoRoot, ref, tracked) {
|
|
142
|
+
if (ref.startsWith('-')) {
|
|
143
|
+
return [];
|
|
144
|
+
}
|
|
145
|
+
const listing = runGit(repoRoot, ['ls-tree', '-r', '-z', '--name-only', ref], { maxBuffer: 64 * 1024 * 1024 });
|
|
146
|
+
if (listing.error !== undefined || listing.status !== 0) {
|
|
147
|
+
return [];
|
|
148
|
+
}
|
|
149
|
+
return listing.stdout
|
|
150
|
+
.split('\0')
|
|
151
|
+
.filter((file) => file !== '' && !file.split('/').includes('node_modules'))
|
|
152
|
+
.filter((file) => osvLockfileKind(file) !== null && !tracked.has(file))
|
|
153
|
+
.sort()
|
|
154
|
+
.map((file) => ({
|
|
155
|
+
code: 'conductor/lockfile-no-longer-scanned',
|
|
156
|
+
message: `${file} is tracked on the base and not in this pull request, so it is no longer scanned ` +
|
|
157
|
+
'(by either run). Its removal is visible in the diff.',
|
|
158
|
+
}));
|
|
159
|
+
}
|
|
160
|
+
/** The nothing-to-scan sentence when every candidate was a requirements file left out. */
|
|
161
|
+
export function nothingScannableMessage(notScanned) {
|
|
162
|
+
return (`osv-scanner had nothing it could scan: ${notScanned.length} requirements file(s) not pinned ` +
|
|
163
|
+
`(${notScanned.join(', ')}).`);
|
|
164
|
+
}
|
|
165
|
+
/** The run detail beside `lockfiles`: how many requirements files were left out, and which. */
|
|
166
|
+
export function notScannedDetail(notScanned) {
|
|
167
|
+
return `${notScanned.length} (${notScanned.join(', ')})`;
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* osv-scanner 2.4.0's per-file count line on stderr, at its default
|
|
171
|
+
* verbosity (measured): "Scanned <absolute path> file and found N packages",
|
|
172
|
+
* with "package" for one.
|
|
173
|
+
*/
|
|
174
|
+
const SCANNED_LINE = /^Scanned (.+) file and found (\d+) packages?$/;
|
|
175
|
+
/** A path in both spellings worth comparing: as written and, when it exists, resolved. */
|
|
176
|
+
function spellings(file) {
|
|
177
|
+
const out = [file];
|
|
178
|
+
try {
|
|
179
|
+
const real = realpathSync(file);
|
|
180
|
+
if (real !== file) {
|
|
181
|
+
out.push(real);
|
|
182
|
+
}
|
|
183
|
+
}
|
|
184
|
+
catch {
|
|
185
|
+
// Not on disk under this spelling: the written form is all there is.
|
|
186
|
+
}
|
|
187
|
+
return out;
|
|
188
|
+
}
|
|
189
|
+
/**
|
|
190
|
+
* The handed lockfiles osv-scanner said it found 0 packages in (audit
|
|
191
|
+
* finding F2). Its exit 128 covers only the case where EVERY handed file
|
|
192
|
+
* parsed to nothing, and its JSON lists only sources with findings, so a
|
|
193
|
+
* lockfile rewritten to `{}` beside a healthy one is otherwise
|
|
194
|
+
* indistinguishable from a clean one: listed as scanned, with every advisory
|
|
195
|
+
* it carried gone.
|
|
196
|
+
*
|
|
197
|
+
* Read from osv-scanner's stderr, which is annotation, never a verdict: this
|
|
198
|
+
* only adds a note. `handed` are the repository-relative paths the umbrella
|
|
199
|
+
* passed (the parse-as prefix is not part of them), and `cwd` is where the
|
|
200
|
+
* child ran. A path is compared in its written and its resolved spelling on
|
|
201
|
+
* both sides, so a temp directory reached through a symlink still matches,
|
|
202
|
+
* and by whole path, so two files with one base name never stand in for each
|
|
203
|
+
* other. A file with no count line is not named: that is a limit (a policy
|
|
204
|
+
* that lowers osv-scanner's verbosity hides every line), not a finding.
|
|
205
|
+
*/
|
|
206
|
+
export function emptiedLockfiles(stderr, handed, cwd) {
|
|
207
|
+
const empty = new Set();
|
|
208
|
+
for (const raw of stderr.split('\n')) {
|
|
209
|
+
const match = SCANNED_LINE.exec(raw.trim());
|
|
210
|
+
if (match !== null && Number(match[2]) === 0) {
|
|
211
|
+
for (const spelling of spellings(match[1])) {
|
|
212
|
+
empty.add(spelling);
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
if (empty.size === 0) {
|
|
217
|
+
return [];
|
|
218
|
+
}
|
|
219
|
+
return handed.filter((file) => spellings(path.resolve(cwd, file)).some((spelling) => empty.has(spelling)));
|
|
220
|
+
}
|
|
221
|
+
/** The note when a policy's no-resolve was dropped from an invocation. */
|
|
222
|
+
export const NO_RESOLVE_OVERRIDDEN = 'options.no-resolve in .guardrails.yaml was not passed: requirements files are always scanned ' +
|
|
223
|
+
'with --no-resolve (direct requirements only).';
|