@vaultcompass/conductor 0.8.1 → 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 +144 -35
- package/dist/cli.js +1 -1
- 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 +22 -1
- package/dist/gate-runner.js +209 -23
- package/dist/git.d.ts +15 -0
- package/dist/git.js +20 -0
- package/dist/init-policy.js +38 -2
- package/dist/normalize.d.ts +11 -0
- package/dist/normalize.js +54 -2
- 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 +43 -2
- package/dist/output-text.d.ts +5 -2
- package/dist/output-text.js +148 -13
- package/dist/policy.d.ts +10 -0
- package/dist/policy.js +12 -0
- 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/run.d.ts +13 -0
- package/dist/run.js +11 -2
- 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 +4 -0
package/dist/gate-runner.js
CHANGED
|
@@ -23,10 +23,13 @@ import { tmpdir } from 'node:os';
|
|
|
23
23
|
import path from 'node:path';
|
|
24
24
|
import { runGit } from './git.js';
|
|
25
25
|
import { NormalizeError } from './envelope.js';
|
|
26
|
-
import { normalizeDepGuard, normalizeFailedGate, normalizeGitleaks, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeOsvScanner, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
|
|
26
|
+
import { describeLockfiles, normalizeDepGuard, normalizeFailedGate, normalizeGitleaks, normalizeIntentGuard, normalizeMisconfiguredGate, normalizeMissingGate, normalizeOsvScanner, normalizeUnparseableGate, normalizeVaultGuard, } from './normalize.js';
|
|
27
27
|
import { renderOptionFlags } from './policy.js';
|
|
28
|
+
import { NO_RESOLVE_OVERRIDDEN, emptiedLockfiles, noLongerScanned, nothingScannableMessage, notScannedDetail, selectOsvInputs, } from './osv-coverage.js';
|
|
29
|
+
import { compareWithBase, comparisonFailed, } from './osv-baseline.js';
|
|
28
30
|
import { ExternalConfigError, materializeExternalConfig, nestedConfigProposals, } from './external-config.js';
|
|
29
|
-
import { profileFor } from './products.js';
|
|
31
|
+
import { osvLockfileKind, profileFor } from './products.js';
|
|
32
|
+
import { unreadManifestsNote } from './unread-manifests.js';
|
|
30
33
|
import { atLeastVersion, refuseHeadControlledProgram } from './trust-base.js';
|
|
31
34
|
import { ResolveError, candidateNames, nodeModulesCandidate, resolveGateBinary, } from './resolve.js';
|
|
32
35
|
/** The longest excerpt of a gate's own reason that is carried. */
|
|
@@ -542,15 +545,55 @@ intentBase) {
|
|
|
542
545
|
case 'osv-scanner': {
|
|
543
546
|
// JSON goes to stdout and everything else to stderr, so no report
|
|
544
547
|
// file. No directory walk: each tracked lockfile is named with
|
|
545
|
-
// --lockfile (the runner lists them, src/
|
|
546
|
-
//
|
|
547
|
-
//
|
|
548
|
-
//
|
|
548
|
+
// --lockfile (the runner lists them, src/osv-coverage.ts), because
|
|
549
|
+
// osv-scanner's own walk skips anything .gitignore matches, tracked or
|
|
550
|
+
// not. With none there is nothing to hand over, and the runner reports
|
|
551
|
+
// that without spawning the tool.
|
|
549
552
|
if (external.lockfiles === undefined || external.lockfiles.length === 0) {
|
|
550
553
|
throw new Error('osv-scanner needs at least one lockfile: with none, nothing is spawned');
|
|
551
554
|
}
|
|
552
|
-
const
|
|
553
|
-
|
|
555
|
+
const isRequirements = (file) => osvLockfileKind(path.basename(file)) === 'requirements';
|
|
556
|
+
// A requirements variant (requirements-dev.txt) is handed in the
|
|
557
|
+
// parse-as form, because 2.4.0 does not recognise the bare name;
|
|
558
|
+
// requirements.txt itself and every exact lockfile name go bare
|
|
559
|
+
// (npm-shrinkwrap.json is not even a valid parse-as type in 2.4.0).
|
|
560
|
+
// The parse-as form splits on the first colon only, so a variant's own
|
|
561
|
+
// path is safe; a bare path with a colon is split and exits 127, which
|
|
562
|
+
// is a could-not-run, never a silent skip.
|
|
563
|
+
const lockfiles = external.lockfiles.flatMap((file) => [
|
|
564
|
+
'--lockfile',
|
|
565
|
+
isRequirements(file) && path.basename(file) !== 'requirements.txt' ? `requirements.txt:${file}` : file,
|
|
566
|
+
]);
|
|
567
|
+
// --no-resolve on every invocation that carries a requirements file,
|
|
568
|
+
// and on the base run exactly when the head run had it (section 2.4):
|
|
569
|
+
// without a lockfile, a resolved transitive version is the registry's
|
|
570
|
+
// latest, not the installed one. Not overridable: a policy no-resolve
|
|
571
|
+
// is dropped from such an invocation (the runner says so), because
|
|
572
|
+
// no-resolve: false would render --no-no-resolve, which osv rejects.
|
|
573
|
+
const noResolve = external.noResolve ?? external.lockfiles.some(isRequirements);
|
|
574
|
+
const options = { ...gate.options };
|
|
575
|
+
if (noResolve) {
|
|
576
|
+
delete options['no-resolve'];
|
|
577
|
+
}
|
|
578
|
+
// On a pull-request run, call analysis is off for every language
|
|
579
|
+
// unless the base policy says otherwise (section 3.3, open question 6):
|
|
580
|
+
// the base copies carry no source, so call analysis could hide on the
|
|
581
|
+
// head what the base run reports, and the comparison would then not be
|
|
582
|
+
// a dependency fact. Off on both runs makes the head only gain
|
|
583
|
+
// findings. A policy that names either key keeps its own value, on
|
|
584
|
+
// both runs, through the passthrough.
|
|
585
|
+
const callAnalysis = trustBase !== undefined && !('call-analysis' in options) && !('no-call-analysis' in options)
|
|
586
|
+
? ['--no-call-analysis=all']
|
|
587
|
+
: [];
|
|
588
|
+
return [
|
|
589
|
+
'--format',
|
|
590
|
+
'json',
|
|
591
|
+
...config,
|
|
592
|
+
...lockfiles,
|
|
593
|
+
...(noResolve ? ['--no-resolve'] : []),
|
|
594
|
+
...callAnalysis,
|
|
595
|
+
...renderOptionFlags(options),
|
|
596
|
+
];
|
|
554
597
|
}
|
|
555
598
|
}
|
|
556
599
|
}
|
|
@@ -1031,8 +1074,18 @@ function spawnAndRead(ctx) {
|
|
|
1031
1074
|
// removing or renaming one is visible in the diff, so there is nothing for
|
|
1032
1075
|
// a base-ref read to protect. A listing that fails is not "no lockfiles".
|
|
1033
1076
|
const nestedProposals = [];
|
|
1034
|
-
|
|
1035
|
-
|
|
1077
|
+
// What the osv gate's selection said beside the list it handed over: the
|
|
1078
|
+
// umbrella's own diagnostics (a requirements file left out, or scanned
|
|
1079
|
+
// under the ratchet, a passthrough option dropped) and the per-file run
|
|
1080
|
+
// notes. Carried onto every outcome from here on that reports a scan.
|
|
1081
|
+
let selection = null;
|
|
1082
|
+
const selectionDiagnostics = [];
|
|
1083
|
+
// Tracked manifests this gate was NOT handed, when it was handed others
|
|
1084
|
+
// (review of 1b.2, item 5): a run note, so a Podfile.lock beside a scanned
|
|
1085
|
+
// mix.lock is named without pushing a clean run off its one-line summary.
|
|
1086
|
+
// The nothing-to-scan branch below names them in its own diagnostic.
|
|
1087
|
+
let unreadNote = null;
|
|
1088
|
+
if (profile.lockfileMatcher !== null) {
|
|
1036
1089
|
const listing = runGit(options.repoRoot, ['ls-files', '-z'], { maxBuffer: 64 * 1024 * 1024 });
|
|
1037
1090
|
if (listing.error !== undefined || listing.status !== 0) {
|
|
1038
1091
|
const detail = `the repository's tracked files could not be listed, so ${gate.product} had no ` +
|
|
@@ -1071,15 +1124,29 @@ function spawnAndRead(ctx) {
|
|
|
1071
1124
|
};
|
|
1072
1125
|
}
|
|
1073
1126
|
}
|
|
1074
|
-
|
|
1075
|
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1127
|
+
// The pin check reads the head copies on disk and, on a pull request, the
|
|
1128
|
+
// base copies through the one reader; both are selection, not verdicts.
|
|
1129
|
+
selection = selectOsvInputs({
|
|
1130
|
+
repoRoot: options.repoRoot,
|
|
1131
|
+
tracked,
|
|
1132
|
+
...(decidedRef === undefined ? {} : { decidedRef }),
|
|
1133
|
+
});
|
|
1134
|
+
external.lockfiles = selection.handed;
|
|
1135
|
+
selectionDiagnostics.push(...selection.diagnostics);
|
|
1136
|
+
if (decidedRef !== undefined) {
|
|
1137
|
+
selectionDiagnostics.push(...noLongerScanned(options.repoRoot, decidedRef, new Set(tracked)));
|
|
1138
|
+
}
|
|
1139
|
+
if (external.lockfiles.length > 0) {
|
|
1140
|
+
const unread = unreadManifestsNote(tracked, new Set(selection.handed), gate.product);
|
|
1141
|
+
unreadNote = unread === null ? null : { code: 'conductor/manifests-not-handed', message: unread };
|
|
1142
|
+
}
|
|
1080
1143
|
if (external.lockfiles.length === 0) {
|
|
1081
1144
|
// Nothing to scan, reported the same way as osv-scanner's own 128 below,
|
|
1082
|
-
// without spawning it.
|
|
1145
|
+
// without spawning it. The verdict is unchanged (clean); what changes is
|
|
1146
|
+
// what is said: which requirements files the pin check left out, and
|
|
1147
|
+
// which tracked manifests were not handed to this scanner.
|
|
1148
|
+
const unread = unreadManifestsNote(tracked, new Set(selection.handed), gate.product);
|
|
1149
|
+
const cleanBecause = 'the verdict is clean because there was nothing to read, not because a scan found nothing.';
|
|
1083
1150
|
return {
|
|
1084
1151
|
...base,
|
|
1085
1152
|
productVersion: version,
|
|
@@ -1091,13 +1158,21 @@ function spawnAndRead(ctx) {
|
|
|
1091
1158
|
findings: [],
|
|
1092
1159
|
run: EMPTY_RUN,
|
|
1093
1160
|
diagnostics: [
|
|
1161
|
+
...selectionDiagnostics,
|
|
1094
1162
|
{
|
|
1095
1163
|
code: 'conductor/nothing-to-scan',
|
|
1096
|
-
message:
|
|
1164
|
+
message: (selection.notScanned.length > 0
|
|
1165
|
+
? `${nothingScannableMessage(selection.notScanned)} T${cleanBecause.slice(1)}`
|
|
1166
|
+
: `${gate.product} read no lockfile, so nothing was scanned; ${cleanBecause}`) +
|
|
1167
|
+
(unread === null ? '' : ` ${unread}`),
|
|
1097
1168
|
},
|
|
1098
1169
|
],
|
|
1099
1170
|
};
|
|
1100
1171
|
}
|
|
1172
|
+
external.noResolve = external.lockfiles.some((file) => osvLockfileKind(path.posix.basename(file)) === 'requirements');
|
|
1173
|
+
if (external.noResolve && 'no-resolve' in gate.options) {
|
|
1174
|
+
selectionDiagnostics.push({ code: 'conductor/option-overridden', message: NO_RESOLVE_OVERRIDDEN });
|
|
1175
|
+
}
|
|
1101
1176
|
}
|
|
1102
1177
|
// On a pull request, the tool's config and ignore file come from the base
|
|
1103
1178
|
// ref (or a neutral stand-in), never from the head it would otherwise
|
|
@@ -1237,13 +1312,28 @@ function spawnAndRead(ctx) {
|
|
|
1237
1312
|
// request in a docs-only repository; read as a verdict it would claim a
|
|
1238
1313
|
// scan that did not happen. So it is clean, and the report says why.
|
|
1239
1314
|
if (exitCode !== null && profile.exit.nothingToScan.includes(exitCode)) {
|
|
1315
|
+
const handedAll = external.lockfiles ?? [];
|
|
1240
1316
|
return {
|
|
1241
1317
|
...withRun,
|
|
1242
1318
|
exitCode: 0,
|
|
1243
1319
|
couldNotRun: null,
|
|
1244
1320
|
findings: [],
|
|
1245
|
-
|
|
1321
|
+
// Every handed lockfile parsed to nothing: `packages-read 0` is the
|
|
1322
|
+
// marker that this gate read NOTHING (the verdict token's
|
|
1323
|
+
// nothing-checked rule reads it), which the partial-empty note further
|
|
1324
|
+
// down shares a diagnostic code with but never carries.
|
|
1325
|
+
run: handedAll.length === 0
|
|
1326
|
+
? EMPTY_RUN
|
|
1327
|
+
: {
|
|
1328
|
+
...EMPTY_RUN,
|
|
1329
|
+
diagnostics: unreadNote === null ? [] : [unreadNote],
|
|
1330
|
+
details: {
|
|
1331
|
+
lockfiles: describeLockfiles(handedAll, new Set(handedAll)),
|
|
1332
|
+
'packages-read': 0,
|
|
1333
|
+
},
|
|
1334
|
+
},
|
|
1246
1335
|
diagnostics: [
|
|
1336
|
+
...selectionDiagnostics,
|
|
1247
1337
|
// When lockfiles WERE handed over, this exit means they parsed to no
|
|
1248
1338
|
// packages at all, which is different news from "no lockfile": a
|
|
1249
1339
|
// lockfile the tool could not read anything from deserves a look.
|
|
@@ -1255,7 +1345,8 @@ function spawnAndRead(ctx) {
|
|
|
1255
1345
|
}
|
|
1256
1346
|
: {
|
|
1257
1347
|
code: 'conductor/nothing-to-scan',
|
|
1258
|
-
message: `${gate.product}
|
|
1348
|
+
message: `${gate.product} read no lockfile (exit ${exitCode}), so nothing was scanned; the ` +
|
|
1349
|
+
`verdict is clean because there was nothing to read, not because a scan found nothing.`,
|
|
1259
1350
|
},
|
|
1260
1351
|
],
|
|
1261
1352
|
};
|
|
@@ -1369,13 +1460,108 @@ function spawnAndRead(ctx) {
|
|
|
1369
1460
|
online: argv.includes('--online'),
|
|
1370
1461
|
lockfiles: external.lockfiles ?? [],
|
|
1371
1462
|
});
|
|
1463
|
+
// The base comparison (osv design, section 3.1): only on a decided trust
|
|
1464
|
+
// base, only when the head run exited blocked and produced a finding. A
|
|
1465
|
+
// clean head, nothing to scan, empty lockfiles and every could-not-run
|
|
1466
|
+
// returned before this, so none of them costs anything new. Its own
|
|
1467
|
+
// try: a comparison that throws labels every finding introduced and is
|
|
1468
|
+
// never a could-not-run, unlike the normalizer failure the catch below
|
|
1469
|
+
// is for.
|
|
1470
|
+
let findings = normalized.findings;
|
|
1471
|
+
let baseComparison;
|
|
1472
|
+
const comparisonDiagnostics = [];
|
|
1473
|
+
if (gate.product === 'osv-scanner' &&
|
|
1474
|
+
decidedRef !== undefined &&
|
|
1475
|
+
workDir !== null &&
|
|
1476
|
+
blocked &&
|
|
1477
|
+
findings.length > 0) {
|
|
1478
|
+
const compareArgs = {
|
|
1479
|
+
repoRoot: options.repoRoot,
|
|
1480
|
+
ref: decidedRef,
|
|
1481
|
+
workDir,
|
|
1482
|
+
policy: gate.presentOnBase ?? 'block',
|
|
1483
|
+
version,
|
|
1484
|
+
headFindings: findings,
|
|
1485
|
+
headLockfiles: external.lockfiles ?? [],
|
|
1486
|
+
closures: selection?.closures ?? new Map(),
|
|
1487
|
+
otherVerdicts: normalized.otherVerdicts ?? [],
|
|
1488
|
+
headArgv: argv,
|
|
1489
|
+
baseArgv: (copies) => [
|
|
1490
|
+
...binary.argvPrefix,
|
|
1491
|
+
...gateArgs(gate, options.staged, options.intent, decidedRef, { ...external, lockfiles: copies }),
|
|
1492
|
+
],
|
|
1493
|
+
spawn: (baseArgv, cwd) => {
|
|
1494
|
+
const baseChild = spawnSync(binary.command, [...baseArgv], {
|
|
1495
|
+
cwd,
|
|
1496
|
+
encoding: 'utf8',
|
|
1497
|
+
timeout: timeoutMs,
|
|
1498
|
+
maxBuffer: 64 * 1024 * 1024,
|
|
1499
|
+
});
|
|
1500
|
+
return { status: baseChild.status, stdout: baseChild.stdout ?? '', error: baseChild.error };
|
|
1501
|
+
},
|
|
1502
|
+
rootSpellings,
|
|
1503
|
+
};
|
|
1504
|
+
let compared;
|
|
1505
|
+
try {
|
|
1506
|
+
compared = compareWithBase(compareArgs);
|
|
1507
|
+
}
|
|
1508
|
+
catch (err) {
|
|
1509
|
+
compared = comparisonFailed(compareArgs, `the comparison failed (${messageOf(err)})`);
|
|
1510
|
+
}
|
|
1511
|
+
findings = compared.findings;
|
|
1512
|
+
baseComparison = compared.comparison;
|
|
1513
|
+
comparisonDiagnostics.push(...compared.diagnostics);
|
|
1514
|
+
}
|
|
1515
|
+
// A handed lockfile osv-scanner read no packages from, while it read
|
|
1516
|
+
// packages from another (audit finding F2). Exit 128 above covers only
|
|
1517
|
+
// the all-empty case; this is the rest, named on the coverage line and
|
|
1518
|
+
// in a diagnostic, so an emptied lockfile's advisories never vanish
|
|
1519
|
+
// without a word. Annotation only: the verdict is osv-scanner's.
|
|
1520
|
+
const emptied = gate.product === 'osv-scanner'
|
|
1521
|
+
? emptiedLockfiles(withRun.stderr, external.lockfiles ?? [], spawnCwd)
|
|
1522
|
+
: [];
|
|
1523
|
+
const emptyDiagnostics = emptied.length === 0
|
|
1524
|
+
? []
|
|
1525
|
+
: [
|
|
1526
|
+
{
|
|
1527
|
+
code: 'conductor/lockfiles-empty',
|
|
1528
|
+
message: `${gate.product} read no packages from ${emptied.join(', ')} while it read packages ` +
|
|
1529
|
+
'from the other lockfiles, so nothing in the named file(s) was checked. A lockfile ' +
|
|
1530
|
+
'emptied in this change hides every advisory it carried; look at its diff.',
|
|
1531
|
+
},
|
|
1532
|
+
];
|
|
1533
|
+
const run = selection === null
|
|
1534
|
+
? normalized.run
|
|
1535
|
+
: {
|
|
1536
|
+
...normalized.run,
|
|
1537
|
+
diagnostics: [
|
|
1538
|
+
...normalized.run.diagnostics,
|
|
1539
|
+
...selection.notes,
|
|
1540
|
+
...(unreadNote === null ? [] : [unreadNote]),
|
|
1541
|
+
],
|
|
1542
|
+
details: {
|
|
1543
|
+
...normalized.run.details,
|
|
1544
|
+
...(emptied.length === 0
|
|
1545
|
+
? {}
|
|
1546
|
+
: { lockfiles: describeLockfiles(external.lockfiles ?? [], new Set(emptied)) }),
|
|
1547
|
+
...(selection.notScanned.length === 0
|
|
1548
|
+
? {}
|
|
1549
|
+
: { 'not-scanned': notScannedDetail(selection.notScanned) }),
|
|
1550
|
+
},
|
|
1551
|
+
};
|
|
1372
1552
|
return {
|
|
1373
1553
|
...withRun,
|
|
1374
1554
|
exitCode,
|
|
1375
1555
|
couldNotRun: null,
|
|
1376
|
-
findings
|
|
1377
|
-
run
|
|
1378
|
-
diagnostics:
|
|
1556
|
+
findings,
|
|
1557
|
+
run,
|
|
1558
|
+
diagnostics: [
|
|
1559
|
+
...normalized.diagnostics,
|
|
1560
|
+
...selectionDiagnostics,
|
|
1561
|
+
...emptyDiagnostics,
|
|
1562
|
+
...comparisonDiagnostics,
|
|
1563
|
+
],
|
|
1564
|
+
...(baseComparison === undefined ? {} : { baseComparison }),
|
|
1379
1565
|
// The gate's own answer about the control inputs, folded onto the
|
|
1380
1566
|
// decision the umbrella made before spawning it. A gate that was NOT
|
|
1381
1567
|
// put into pull-request mode reports no proposals, and its trustBase
|
package/dist/git.d.ts
CHANGED
|
@@ -15,7 +15,22 @@ export declare function useGitProgram(program: string): void;
|
|
|
15
15
|
/** Runs one git command in `cwd`, reading stdout as UTF-8. Never throws. */
|
|
16
16
|
export declare function runGit(cwd: string, args: readonly string[], options?: {
|
|
17
17
|
maxBuffer?: number;
|
|
18
|
+
input?: string;
|
|
18
19
|
}): GitResult;
|
|
20
|
+
/**
|
|
21
|
+
* Runs one git command in `cwd` and keeps stdout as BYTES. For a blob that is
|
|
22
|
+
* copied out byte for byte (the osv gate's base copies): decoding it as UTF-8
|
|
23
|
+
* would rewrite a file with invalid bytes before anything read it. Same
|
|
24
|
+
* program, same environment and same never-throws contract as runGit.
|
|
25
|
+
*/
|
|
26
|
+
export declare function runGitBytes(cwd: string, args: readonly string[], options?: {
|
|
27
|
+
maxBuffer?: number;
|
|
28
|
+
}): {
|
|
29
|
+
status: number | null;
|
|
30
|
+
stdout: Buffer;
|
|
31
|
+
stderr: string;
|
|
32
|
+
error: Error | undefined;
|
|
33
|
+
};
|
|
19
34
|
/**
|
|
20
35
|
* A PATH with every entry that would resolve against the working directory
|
|
21
36
|
* removed: an empty entry (which means the current directory) and a relative
|
package/dist/git.js
CHANGED
|
@@ -38,6 +38,7 @@ export function runGit(cwd, args, options = {}) {
|
|
|
38
38
|
encoding: 'utf8',
|
|
39
39
|
maxBuffer: options.maxBuffer ?? 32 * 1024 * 1024,
|
|
40
40
|
env: { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' },
|
|
41
|
+
...(options.input === undefined ? {} : { input: options.input }),
|
|
41
42
|
});
|
|
42
43
|
return {
|
|
43
44
|
status: child.status,
|
|
@@ -46,6 +47,25 @@ export function runGit(cwd, args, options = {}) {
|
|
|
46
47
|
error: child.error,
|
|
47
48
|
};
|
|
48
49
|
}
|
|
50
|
+
/**
|
|
51
|
+
* Runs one git command in `cwd` and keeps stdout as BYTES. For a blob that is
|
|
52
|
+
* copied out byte for byte (the osv gate's base copies): decoding it as UTF-8
|
|
53
|
+
* would rewrite a file with invalid bytes before anything read it. Same
|
|
54
|
+
* program, same environment and same never-throws contract as runGit.
|
|
55
|
+
*/
|
|
56
|
+
export function runGitBytes(cwd, args, options = {}) {
|
|
57
|
+
const child = spawnSync(gitProgram, [...args], {
|
|
58
|
+
cwd,
|
|
59
|
+
maxBuffer: options.maxBuffer ?? 64 * 1024 * 1024,
|
|
60
|
+
env: { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' },
|
|
61
|
+
});
|
|
62
|
+
return {
|
|
63
|
+
status: child.status,
|
|
64
|
+
stdout: Buffer.isBuffer(child.stdout) ? child.stdout : Buffer.alloc(0),
|
|
65
|
+
stderr: Buffer.isBuffer(child.stderr) ? child.stderr.toString('utf8') : '',
|
|
66
|
+
error: child.error,
|
|
67
|
+
};
|
|
68
|
+
}
|
|
49
69
|
/**
|
|
50
70
|
* A PATH with every entry that would resolve against the working directory
|
|
51
71
|
* removed: an empty entry (which means the current directory) and a relative
|
package/dist/init-policy.js
CHANGED
|
@@ -112,6 +112,7 @@ export function renderPolicy(detected, frozenContractPath) {
|
|
|
112
112
|
// ramp is already climbed and enforcing from the start is what stops a
|
|
113
113
|
// frozen contract's protected paths from producing findings that never
|
|
114
114
|
// fail the check (issue #57).
|
|
115
|
+
let unfrozenIntent = false;
|
|
115
116
|
if (role === 'intent') {
|
|
116
117
|
if (frozenContractPath !== null) {
|
|
117
118
|
lines.push(` # A frozen contract already exists at ${frozenContractPath}, so this gate`);
|
|
@@ -119,6 +120,7 @@ export function renderPolicy(detected, frozenContractPath) {
|
|
|
119
120
|
lines.push(' enforce: true');
|
|
120
121
|
}
|
|
121
122
|
else {
|
|
123
|
+
unfrozenIntent = true;
|
|
122
124
|
lines.push(` # No frozen contract yet (${NATIVE_CONTRACT_PATH}), so this gate runs`);
|
|
123
125
|
lines.push(' # and reports without failing the run. Once a contract is frozen,');
|
|
124
126
|
lines.push(' # set this to true by hand: conductor init never rewrites this file');
|
|
@@ -129,9 +131,43 @@ export function renderPolicy(detected, frozenContractPath) {
|
|
|
129
131
|
else {
|
|
130
132
|
lines.push(' enforce: true');
|
|
131
133
|
}
|
|
134
|
+
// Only the vulnerabilities gate compares a pull request with its base.
|
|
135
|
+
// Written as report for a fresh repository, so an existing backlog does
|
|
136
|
+
// not block every pull request from the first one; a parser default of
|
|
137
|
+
// block keeps every policy written before the key existed as strict as
|
|
138
|
+
// it was.
|
|
139
|
+
if (role === 'vulnerabilities') {
|
|
140
|
+
lines.push(' # On a pull request, findings already on the base branch are reported');
|
|
141
|
+
lines.push(' # and do not block; only advisories the pull request introduces do.');
|
|
142
|
+
lines.push(' # Set present-on-base: block to block on every known vulnerability.');
|
|
143
|
+
lines.push(' present-on-base: report');
|
|
144
|
+
}
|
|
132
145
|
lines.push(' # Handed to this gate unchanged. Keys are its own long flags,');
|
|
133
|
-
lines.push(' # without the leading dashes.
|
|
134
|
-
|
|
146
|
+
lines.push(' # without the leading dashes.');
|
|
147
|
+
if (role === 'secrets-history') {
|
|
148
|
+
lines.push(' # gitleaks has no severity floor. Tune its rules in .gitleaks.toml and');
|
|
149
|
+
lines.push(' # accept an old finding in .gitleaksignore, not here.');
|
|
150
|
+
}
|
|
151
|
+
else if (role === 'vulnerabilities') {
|
|
152
|
+
lines.push(' # osv-scanner has no severity floor. Tune what it reports in');
|
|
153
|
+
lines.push(' # osv-scanner.toml, not here.');
|
|
154
|
+
}
|
|
155
|
+
else if (role === 'intent') {
|
|
156
|
+
lines.push(' # require-frozen: false lets the gate run and not block when no contract exists.');
|
|
157
|
+
}
|
|
158
|
+
else {
|
|
159
|
+
lines.push(' # Example: fail-on: high');
|
|
160
|
+
}
|
|
161
|
+
if (unfrozenIntent) {
|
|
162
|
+
// intent-guard blocks on a missing contract when require-frozen is true,
|
|
163
|
+
// its default. Without this key a full run prints a BLOCKING critical
|
|
164
|
+
// finding for the very state the unenforced ramp above exists for.
|
|
165
|
+
lines.push(' options:');
|
|
166
|
+
lines.push(' require-frozen: false');
|
|
167
|
+
}
|
|
168
|
+
else {
|
|
169
|
+
lines.push(' options: {}');
|
|
170
|
+
}
|
|
135
171
|
}
|
|
136
172
|
lines.push('', 'report:', ' format: text', '');
|
|
137
173
|
return lines.join('\n');
|
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
|
@@ -943,9 +943,13 @@ function relativeToRoots(file, roots) {
|
|
|
943
943
|
* never osv-scanner's own results[], which 2.x prints only for a source with
|
|
944
944
|
* findings. A clean scan of one lockfile and a run that scanned none both
|
|
945
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.
|
|
946
949
|
*/
|
|
947
|
-
function describeLockfiles(lockfiles) {
|
|
948
|
-
|
|
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(', ')})`;
|
|
949
953
|
}
|
|
950
954
|
export function normalizeOsvScanner(raw, version, blocked,
|
|
951
955
|
/** The scan root as a path osv-scanner may have printed it, in any spelling. */
|
|
@@ -956,6 +960,7 @@ lockfiles = []) {
|
|
|
956
960
|
const top = needRecord(raw, product, 'the output');
|
|
957
961
|
const results = needArray(top.results, product, 'results');
|
|
958
962
|
const findings = [];
|
|
963
|
+
const otherVerdicts = [];
|
|
959
964
|
for (const [ri, rawResult] of results.entries()) {
|
|
960
965
|
const resultWhere = `results[${ri}]`;
|
|
961
966
|
const result = needRecord(rawResult, product, resultWhere);
|
|
@@ -969,6 +974,7 @@ lockfiles = []) {
|
|
|
969
974
|
const name = needString(pkg.name, product, `${packageWhere}.package.name`);
|
|
970
975
|
const installed = optionalString(pkg.version, product, `${packageWhere}.package.version`) ?? '';
|
|
971
976
|
const ecosystem = optionalString(pkg.ecosystem, product, `${packageWhere}.package.ecosystem`);
|
|
977
|
+
otherVerdicts.push(...osvOtherVerdicts(entry, pkg, `${name}@${installed}`));
|
|
972
978
|
const groups = (entry.groups === undefined ? [] : needArray(entry.groups, product, `${packageWhere}.groups`)).filter(isRecord);
|
|
973
979
|
const vulns = entry.vulnerabilities === undefined
|
|
974
980
|
? []
|
|
@@ -1023,8 +1029,54 @@ lockfiles = []) {
|
|
|
1023
1029
|
},
|
|
1024
1030
|
},
|
|
1025
1031
|
diagnostics: [],
|
|
1032
|
+
otherVerdicts,
|
|
1026
1033
|
};
|
|
1027
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
|
+
}
|
|
1028
1080
|
function gateProblem(ruleId, role, product, message, details) {
|
|
1029
1081
|
return {
|
|
1030
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;
|