@vaultcompass/conductor 0.9.0 → 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 +127 -21
- package/dist/cli.d.ts +6 -0
- package/dist/cli.js +19 -4
- package/dist/gate-runner.d.ts +102 -10
- package/dist/gate-runner.js +282 -37
- package/dist/init-hook-detect.d.ts +1 -0
- package/dist/init-hook-detect.js +45 -0
- package/dist/init-policy.js +13 -0
- 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 +32 -2
- package/dist/normalize.js +117 -11
- package/dist/output-sarif.js +18 -0
- package/dist/output-text.d.ts +26 -1
- package/dist/output-text.js +206 -13
- package/dist/policy.d.ts +8 -0
- package/dist/policy.js +33 -6
- package/dist/products.d.ts +8 -1
- package/dist/products.js +14 -0
- package/dist/run.d.ts +4 -0
- package/dist/run.js +18 -2
- package/package.json +1 -1
- package/schema/guardrails.schema.json +6 -0
package/dist/init.js
CHANGED
|
@@ -64,14 +64,14 @@
|
|
|
64
64
|
// repositories in a dogfood run: both would have taken the umbrella hook
|
|
65
65
|
// and lost it at the next install, with the manifest still recording it
|
|
66
66
|
// as installed. See detectManagedHook and declaredManagedHooks.
|
|
67
|
-
import { execFileSync } from 'node:child_process';
|
|
68
|
-
import { chmodSync, closeSync, constants as fsConstants, existsSync, mkdirSync, openSync, readdirSync, realpathSync, rmSync, rmdirSync, statSync, writeFileSync, writeSync, } from 'node:fs';
|
|
67
|
+
import { execFileSync, spawnSync } from 'node:child_process';
|
|
68
|
+
import { chmodSync, closeSync, constants as fsConstants, existsSync, lstatSync, mkdirSync, openSync, readdirSync, realpathSync, rmSync, rmdirSync, statSync, writeFileSync, writeSync, } from 'node:fs';
|
|
69
69
|
import path from 'node:path';
|
|
70
|
-
import { DEP_GUARD_HOOK_MARKER, INTENT_GUARD_HOOK_MARKER, MANAGED_HOOK_MARKER, declaredManagedHooks, detectGateHook, detectGeneratedHook, detectManagedHook, editedManagedGuidance, foreignGuidance, gateHookGuidance, generatedHookGuidance, huskyDirectoryFor, huskyShimPresent, managedHooksGuidance, } from './init-hook-detect.js';
|
|
70
|
+
import { DEP_GUARD_HOOK_MARKER, INTENT_GUARD_HOOK_MARKER, MANAGED_HOOK_MARKER, declaredHusky, declaredManagedHooks, detectGateHook, detectGeneratedHook, detectManagedHook, editedManagedGuidance, foreignGuidance, gateHookGuidance, generatedHookGuidance, huskyDirectoryFor, huskyShimPresent, managedHooksGuidance, } from './init-hook-detect.js';
|
|
71
71
|
import { MANIFEST_RELATIVE_PATH, manifestPathInsideRepo, readIfExists, readManifest, recordedHookSha, sha256, } from './init-manifest.js';
|
|
72
72
|
import { POLICY_FILE_NAME, detectGates, renderPolicy } from './init-policy.js';
|
|
73
73
|
import { frozenNativeContractPath } from './intent-prepare.js';
|
|
74
|
-
import { GATE_ROLES, PRODUCT_FOR_ROLE } from './policy.js';
|
|
74
|
+
import { GATE_ROLES, PRODUCT_FOR_ROLE, parsePolicy } from './policy.js';
|
|
75
75
|
import { profileFor } from './products.js';
|
|
76
76
|
export { MANAGED_HOOK_MARKER, MANIFEST_RELATIVE_PATH, DEP_GUARD_HOOK_MARKER, INTENT_GUARD_HOOK_MARKER, POLICY_FILE_NAME, renderPolicy, };
|
|
77
77
|
const HOOK = `#!/bin/sh
|
|
@@ -178,6 +178,11 @@ function gitOutput(cwd, args) {
|
|
|
178
178
|
function repoRootOf(cwd) {
|
|
179
179
|
return gitOutput(cwd, ['rev-parse', '--show-toplevel']);
|
|
180
180
|
}
|
|
181
|
+
/** Whether git tracks anything under .husky/ at the repository root. */
|
|
182
|
+
function trackedHuskyDirectory(cwd) {
|
|
183
|
+
const listed = gitOutput(cwd, ['ls-files', '--full-name', '--', ':/.husky']);
|
|
184
|
+
return listed !== null && listed.length > 0;
|
|
185
|
+
}
|
|
181
186
|
function effectiveHooksDir(cwd, root) {
|
|
182
187
|
const gitDir = gitOutput(cwd, ['rev-parse', '--git-dir']);
|
|
183
188
|
const hooksPath = gitOutput(cwd, ['config', '--get', 'core.hooksPath']) ?? '';
|
|
@@ -186,7 +191,7 @@ function effectiveHooksDir(cwd, root) {
|
|
|
186
191
|
// somewhere else entirely, so this one resolves against gitDir.
|
|
187
192
|
const defaultDir = path.join(path.resolve(cwd, gitDir ?? '.git'), 'hooks');
|
|
188
193
|
if (hooksPath.length === 0) {
|
|
189
|
-
return { dir: defaultDir, outside: false, isDefault: true };
|
|
194
|
+
return { dir: defaultDir, outside: false, isDefault: true, configured: false };
|
|
190
195
|
}
|
|
191
196
|
// A RELATIVE core.hooksPath resolves against the WORKING-TREE ROOT.
|
|
192
197
|
// Verified by experiment rather than by reading the documentation that
|
|
@@ -194,7 +199,7 @@ function effectiveHooksDir(cwd, root) {
|
|
|
194
199
|
const dir = path.isAbsolute(hooksPath) ? hooksPath : path.join(root, hooksPath);
|
|
195
200
|
const relative = path.relative(root, dir);
|
|
196
201
|
const outside = relative.startsWith('..') || path.isAbsolute(relative);
|
|
197
|
-
return { dir, outside, isDefault: samePath(dir, defaultDir) };
|
|
202
|
+
return { dir, outside, isDefault: samePath(dir, defaultDir), configured: true };
|
|
198
203
|
}
|
|
199
204
|
/**
|
|
200
205
|
* Whether two paths name the same directory.
|
|
@@ -300,9 +305,11 @@ export function planInit(options) {
|
|
|
300
305
|
// executes (on husky 8 that file IS the tracked hook), and never
|
|
301
306
|
// conditional on husky's shim being present (a clean deletes it, and the
|
|
302
307
|
// repository is still husky's).
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
308
|
+
let huskyDir = huskyDirectoryFor(hooks.dir);
|
|
309
|
+
// Where husky was recognised from when core.hooksPath does not say so yet:
|
|
310
|
+
// a fresh clone of a husky repository, before its install has run.
|
|
311
|
+
let huskyDeclaredIn = null;
|
|
312
|
+
if (huskyDir === null) {
|
|
306
313
|
const rel = path.relative(root, executedHookPath).split(path.sep).join('/');
|
|
307
314
|
if (executedHook !== undefined) {
|
|
308
315
|
const generatedBy = detectGeneratedHook(executedHook);
|
|
@@ -348,7 +355,25 @@ export function planInit(options) {
|
|
|
348
355
|
hookManager: managedBy.manager,
|
|
349
356
|
};
|
|
350
357
|
}
|
|
358
|
+
// HUSKY ON A FRESH CLONE. core.hooksPath is set by husky's own install
|
|
359
|
+
// (its prepare script), so a clone that has not run it yet looks native,
|
|
360
|
+
// and a hook written to .git/hooks then goes dark the moment the install
|
|
361
|
+
// points git at .husky/_. The declaration is the signal that exists
|
|
362
|
+
// before the install: husky in package.json, or a tracked .husky/
|
|
363
|
+
// directory. Same rule as simple-git-hooks above, the declaration counts
|
|
364
|
+
// on its own, but the answer differs: husky HAS a tracked hook file, and
|
|
365
|
+
// that file is what both husky 8 and husky 9 end up running, so init
|
|
366
|
+
// writes there and says the install still has to run, rather than
|
|
367
|
+
// refusing. Only where git runs .git/hooks: a hooks directory somebody
|
|
368
|
+
// configured is their decision, not a fresh clone.
|
|
369
|
+
if (!hooks.configured) {
|
|
370
|
+
huskyDeclaredIn = declaredHusky(root) ?? (trackedHuskyDirectory(options.cwd) ? 'a tracked .husky/ directory' : null);
|
|
371
|
+
if (huskyDeclaredIn !== null) {
|
|
372
|
+
huskyDir = path.join(root, '.husky');
|
|
373
|
+
}
|
|
374
|
+
}
|
|
351
375
|
}
|
|
376
|
+
const husky = huskyDir !== null;
|
|
352
377
|
const hookManager = husky ? 'husky' : 'native';
|
|
353
378
|
const hookPath = huskyDir === null ? executedHookPath : path.join(huskyDir, 'pre-commit');
|
|
354
379
|
const relHook = path.relative(root, hookPath).split(path.sep).join('/');
|
|
@@ -427,7 +452,16 @@ export function planInit(options) {
|
|
|
427
452
|
else if (existingHook !== undefined && existingHook.trim().length > 0) {
|
|
428
453
|
const gateProduct = detectGateHook(existingHook);
|
|
429
454
|
if (gateProduct === null) {
|
|
430
|
-
conflicts.push({
|
|
455
|
+
conflicts.push({
|
|
456
|
+
path: relHook,
|
|
457
|
+
reason: 'foreign-hook',
|
|
458
|
+
guidance: foreignGuidance(relHook) +
|
|
459
|
+
// On a fresh husky clone the tracked hook is not run by anything yet.
|
|
460
|
+
(huskyDeclaredIn === null
|
|
461
|
+
? ''
|
|
462
|
+
: ' Note that husky is not installed in this clone (core.hooksPath is not set), so that hook ' +
|
|
463
|
+
"does not run at all until the install (husky's prepare script) has run."),
|
|
464
|
+
});
|
|
431
465
|
return { ...base, repoRoot: root, hookPath, hookManager };
|
|
432
466
|
}
|
|
433
467
|
if (!options.adopt) {
|
|
@@ -456,14 +490,18 @@ export function planInit(options) {
|
|
|
456
490
|
// the one core.hooksPath points at. The shim's state is reported
|
|
457
491
|
// here, where it informs, rather than tested in the rule, where it
|
|
458
492
|
// would send a cleaned repository back into the trap.
|
|
459
|
-
detail:
|
|
460
|
-
? `${created}: husky
|
|
461
|
-
.
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
?
|
|
465
|
-
|
|
466
|
-
|
|
493
|
+
detail: huskyDeclaredIn !== null
|
|
494
|
+
? `${created}: husky is declared in ${huskyDeclaredIn} but has not been installed in this ` +
|
|
495
|
+
'clone (core.hooksPath is not set), so git runs nothing from here yet. Run your install ' +
|
|
496
|
+
"(husky's prepare script) and husky will run this tracked file; .git/hooks would be bypassed then"
|
|
497
|
+
: husky
|
|
498
|
+
? `${created}: husky runs ${path
|
|
499
|
+
.relative(root, executedHookPath)
|
|
500
|
+
.split(path.sep)
|
|
501
|
+
.join('/')}, which execs this tracked file${huskyShimPresent(hooks.dir)
|
|
502
|
+
? ''
|
|
503
|
+
: ' (husky is not installed right now: its generated directory is empty or gone, and the next install restores it)'}`
|
|
504
|
+
: created,
|
|
467
505
|
});
|
|
468
506
|
writes.push({ path: hookPath, content: HOOK, executable: true, kind: 'hook' });
|
|
469
507
|
}
|
|
@@ -498,9 +536,11 @@ function finishPlan(options, root, policyPath, base, actions, writes, records, h
|
|
|
498
536
|
const external = GATE_ROLES.filter((role) => detected.has(role) && !profileFor(PRODUCT_FOR_ROLE[role]).managed).map((role) => `${role} (${PRODUCT_FOR_ROLE[role]})`);
|
|
499
537
|
if (external.length > 0) {
|
|
500
538
|
const one = external.length === 1;
|
|
501
|
-
notes.push(`
|
|
539
|
+
notes.push(`WARNING: ${external.join(' and ')} ${one ? 'is' : 'are'} enabled only because ` +
|
|
502
540
|
`${one ? 'its tool was' : 'their tools were'} found on this machine's PATH; your CI ` +
|
|
503
|
-
`workflow must install ${one ? 'it' : 'them'} too, conductor does not
|
|
541
|
+
`workflow must install ${one ? 'it' : 'them'} too, conductor does not. A teammate or a CI ` +
|
|
542
|
+
`job without ${one ? 'it' : 'them'} gets conductor/gate-missing and exit 2; set enabled: ` +
|
|
543
|
+
`false in ${POLICY_FILE_NAME} if that is not wanted.`);
|
|
504
544
|
}
|
|
505
545
|
}
|
|
506
546
|
else {
|
|
@@ -511,6 +551,7 @@ function finishPlan(options, root, policyPath, base, actions, writes, records, h
|
|
|
511
551
|
path: POLICY_FILE_NAME,
|
|
512
552
|
detail: 'already present, left exactly as it is',
|
|
513
553
|
});
|
|
554
|
+
notes.push(...missingRoleNotes(existingPolicy));
|
|
514
555
|
}
|
|
515
556
|
// A record with nothing to write is still work: the manifest has to be
|
|
516
557
|
// rebuilt, so this is not an "already installed, nothing to do" run.
|
|
@@ -518,10 +559,27 @@ function finishPlan(options, root, policyPath, base, actions, writes, records, h
|
|
|
518
559
|
if (!alreadyInstalled) {
|
|
519
560
|
actions.push({ kind: 'write', path: MANIFEST_RELATIVE_PATH, detail: 'record what init wrote' });
|
|
520
561
|
}
|
|
562
|
+
// The manifest names absolute paths on this machine, so it is never meant
|
|
563
|
+
// to be committed. Appended to .gitignore when that can be done without
|
|
564
|
+
// touching a single existing line; otherwise the line to add is printed.
|
|
565
|
+
const ignore = alreadyInstalled ? null : planGitignore(root);
|
|
566
|
+
if (ignore !== null && ignore.kind === 'append') {
|
|
567
|
+
actions.push({
|
|
568
|
+
kind: 'write',
|
|
569
|
+
path: '.gitignore',
|
|
570
|
+
detail: `append "${GITIGNORE_LINE}" (the per-machine manifest); no other line is changed, and --revert leaves it`,
|
|
571
|
+
});
|
|
572
|
+
}
|
|
573
|
+
else if (ignore !== null) {
|
|
574
|
+
notes.push(`Note: ${MANIFEST_RELATIVE_PATH} is not ignored by git and init did not change .gitignore ` +
|
|
575
|
+
`(${ignore.why}). Add the line "${GITIGNORE_LINE}" to it yourself: the manifest records ` +
|
|
576
|
+
'paths on this machine and is not meant to be committed.');
|
|
577
|
+
}
|
|
521
578
|
return {
|
|
522
579
|
...base,
|
|
523
580
|
ok: true,
|
|
524
581
|
alreadyInstalled,
|
|
582
|
+
...(ignore !== null && ignore.kind === 'append' ? { gitignoreAppend: ignore.path } : {}),
|
|
525
583
|
hookPath: hook.hookPath,
|
|
526
584
|
hookManager: hook.hookManager,
|
|
527
585
|
repoRoot: root,
|
|
@@ -531,6 +589,89 @@ function finishPlan(options, root, policyPath, base, actions, writes, records, h
|
|
|
531
589
|
notes,
|
|
532
590
|
};
|
|
533
591
|
}
|
|
592
|
+
/** The line init adds to .gitignore for the per-machine manifest. */
|
|
593
|
+
export const GITIGNORE_LINE = '.guardrails/';
|
|
594
|
+
/**
|
|
595
|
+
* Whether init can append GITIGNORE_LINE to .gitignore, or why not, or null
|
|
596
|
+
* when git already ignores the manifest (by any rule, in any ignore file).
|
|
597
|
+
*
|
|
598
|
+
* APPEND ONLY. Init never rewrites a file it did not write: the line goes at
|
|
599
|
+
* the end of an existing .gitignore, after a newline if the file lacks a
|
|
600
|
+
* final one, or into a new .gitignore. A .gitignore that is a symbolic link,
|
|
601
|
+
* not a regular file, or resolves outside the repository is left alone and
|
|
602
|
+
* the line is printed instead. Not recorded in the manifest, so --revert
|
|
603
|
+
* never removes or rewrites .gitignore.
|
|
604
|
+
*/
|
|
605
|
+
function planGitignore(root) {
|
|
606
|
+
const probe = spawnSync('git', ['check-ignore', '-q', '--no-index', MANIFEST_RELATIVE_PATH], {
|
|
607
|
+
cwd: root,
|
|
608
|
+
stdio: 'ignore',
|
|
609
|
+
});
|
|
610
|
+
if (probe.status === 0) {
|
|
611
|
+
return null;
|
|
612
|
+
}
|
|
613
|
+
if (probe.status !== 1) {
|
|
614
|
+
return { kind: 'print', why: 'git could not say whether it is already ignored' };
|
|
615
|
+
}
|
|
616
|
+
const target = path.join(root, '.gitignore');
|
|
617
|
+
let info;
|
|
618
|
+
try {
|
|
619
|
+
info = lstatSync(target);
|
|
620
|
+
}
|
|
621
|
+
catch (err) {
|
|
622
|
+
if (err.code === 'ENOENT') {
|
|
623
|
+
return { kind: 'append', path: target };
|
|
624
|
+
}
|
|
625
|
+
return { kind: 'print', why: '.gitignore could not be read' };
|
|
626
|
+
}
|
|
627
|
+
if (info.isSymbolicLink()) {
|
|
628
|
+
return { kind: 'print', why: '.gitignore is a symbolic link' };
|
|
629
|
+
}
|
|
630
|
+
if (!info.isFile()) {
|
|
631
|
+
return { kind: 'print', why: '.gitignore is not a regular file' };
|
|
632
|
+
}
|
|
633
|
+
return { kind: 'append', path: target };
|
|
634
|
+
}
|
|
635
|
+
/** Appends the line without following a link swapped in after planning. */
|
|
636
|
+
function appendGitignore(target) {
|
|
637
|
+
const existing = readIfExists(target);
|
|
638
|
+
const lead = existing !== undefined && existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
|
|
639
|
+
const noFollow = fsConstants.O_NOFOLLOW ?? 0;
|
|
640
|
+
const fd = openSync(target, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_APPEND | noFollow, 0o666);
|
|
641
|
+
try {
|
|
642
|
+
writeSync(fd, `${lead}${GITIGNORE_LINE}\n`);
|
|
643
|
+
}
|
|
644
|
+
finally {
|
|
645
|
+
closeSync(fd);
|
|
646
|
+
}
|
|
647
|
+
}
|
|
648
|
+
/**
|
|
649
|
+
* On an existing policy file, the roles it has no entry for, with the two
|
|
650
|
+
* lines that add each. The file itself is never touched; this only says what
|
|
651
|
+
* a newer conductor knows about that an older init did not write.
|
|
652
|
+
*/
|
|
653
|
+
function missingRoleNotes(text) {
|
|
654
|
+
let policy;
|
|
655
|
+
try {
|
|
656
|
+
policy = parsePolicy(text, POLICY_FILE_NAME);
|
|
657
|
+
}
|
|
658
|
+
catch {
|
|
659
|
+
return [
|
|
660
|
+
`Note: ${POLICY_FILE_NAME} does not parse, so init could not list the gate roles it lacks. ` +
|
|
661
|
+
'"conductor run" says why.',
|
|
662
|
+
];
|
|
663
|
+
}
|
|
664
|
+
const missing = GATE_ROLES.filter((role) => policy.gates[role] === undefined);
|
|
665
|
+
if (missing.length === 0) {
|
|
666
|
+
return [];
|
|
667
|
+
}
|
|
668
|
+
return [
|
|
669
|
+
`Note: ${POLICY_FILE_NAME} has no entry for ${missing.length} gate role(s): ${missing.join(', ')}. ` +
|
|
670
|
+
'To add one, put its two lines under "gates:" (a role listed is enabled unless it also says ' +
|
|
671
|
+
'enabled: false):',
|
|
672
|
+
...missing.flatMap((role) => [` ${role}:`, ` product: ${PRODUCT_FOR_ROLE[role]}`]),
|
|
673
|
+
];
|
|
674
|
+
}
|
|
534
675
|
/**
|
|
535
676
|
* The whole plan when --hook was not given: no hook is detected, no hook
|
|
536
677
|
* manager is consulted, and no hook conflict can block the policy file from
|
|
@@ -658,6 +799,11 @@ export function applyInit(plan, options) {
|
|
|
658
799
|
const manifestPath = path.join(plan.repoRoot, MANIFEST_RELATIVE_PATH);
|
|
659
800
|
mkdirSync(path.dirname(manifestPath), { recursive: true });
|
|
660
801
|
writeManifestFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
|
|
802
|
+
// Last, and contained like every other write: a .gitignore resolving
|
|
803
|
+
// outside the repository is never appended to.
|
|
804
|
+
if (plan.gitignoreAppend !== undefined && manifestPathInsideRepo(plan.repoRoot, plan.gitignoreAppend)) {
|
|
805
|
+
appendGitignore(plan.gitignoreAppend);
|
|
806
|
+
}
|
|
661
807
|
}
|
|
662
808
|
catch (err) {
|
|
663
809
|
return {
|
package/dist/intent-prepare.d.ts
CHANGED
|
@@ -120,6 +120,17 @@ export type IntentPrepareResult = {
|
|
|
120
120
|
kind: 'failed';
|
|
121
121
|
step: PrepareStep;
|
|
122
122
|
detail: string;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* A preparation spawn was stopped at the intent gate's time limit (spawn
|
|
126
|
+
* error ETIMEDOUT, checked before the status). Not `failed`: the caller
|
|
127
|
+
* reports it as the timed-out could-not-run reason.
|
|
128
|
+
*/
|
|
129
|
+
| {
|
|
130
|
+
kind: 'timed-out';
|
|
131
|
+
step: 'import-spec' | 'freeze';
|
|
132
|
+
elapsedMs: number;
|
|
133
|
+
signal: string | null;
|
|
123
134
|
};
|
|
124
135
|
export interface IntentPrepareOptions {
|
|
125
136
|
repoRoot: string;
|
|
@@ -133,7 +144,13 @@ export interface IntentPrepareOptions {
|
|
|
133
144
|
* it when no --base and no GITHUB_BASE_REF names another base.
|
|
134
145
|
*/
|
|
135
146
|
trustBase?: string;
|
|
136
|
-
|
|
147
|
+
/**
|
|
148
|
+
* The intent gate's resolved time limit (`resolveTimeLimit` in
|
|
149
|
+
* src/gate-runner.ts), given in full to each preparation spawn. REQUIRED,
|
|
150
|
+
* with no fallback here, so the type checker holds the preparation to the
|
|
151
|
+
* one resolver.
|
|
152
|
+
*/
|
|
153
|
+
timeoutMs: number;
|
|
137
154
|
/**
|
|
138
155
|
* The directory the per-run temporary project is created under.
|
|
139
156
|
*
|
package/dist/intent-prepare.js
CHANGED
|
@@ -274,6 +274,7 @@ function subcommand(binary, name) {
|
|
|
274
274
|
return { command: binary.command, argv: [...prefix.slice(0, -1), name] };
|
|
275
275
|
}
|
|
276
276
|
function run(command, argv, cwd, timeoutMs) {
|
|
277
|
+
const started = Date.now();
|
|
277
278
|
const child = spawnSync(command, argv, {
|
|
278
279
|
cwd,
|
|
279
280
|
encoding: 'utf8',
|
|
@@ -285,8 +286,17 @@ function run(command, argv, cwd, timeoutMs) {
|
|
|
285
286
|
stdout: child.stdout ?? '',
|
|
286
287
|
stderr: child.stderr ?? '',
|
|
287
288
|
errorMessage: child.error === undefined ? null : child.error.message,
|
|
289
|
+
errorCode: child.error === undefined ? null : (child.error.code ?? null),
|
|
290
|
+
signal: child.signal ?? null,
|
|
291
|
+
elapsedMs: Date.now() - started,
|
|
288
292
|
};
|
|
289
293
|
}
|
|
294
|
+
/** A preparation spawn stopped at the limit, as a result; null for any other outcome. */
|
|
295
|
+
function timedOutStep(result, step) {
|
|
296
|
+
return result.errorCode === 'ETIMEDOUT'
|
|
297
|
+
? { kind: 'timed-out', step, elapsedMs: result.elapsedMs, signal: result.signal }
|
|
298
|
+
: null;
|
|
299
|
+
}
|
|
290
300
|
/**
|
|
291
301
|
* Everything the child complained with, trimmed and capped.
|
|
292
302
|
*
|
|
@@ -403,8 +413,7 @@ export function prepareIntent(options) {
|
|
|
403
413
|
* so the change set and the chain cannot differ between them.
|
|
404
414
|
*/
|
|
405
415
|
function finishPreparation(options, source, importInput, proposals, note) {
|
|
406
|
-
const { repoRoot, env } = options;
|
|
407
|
-
const timeoutMs = options.timeoutMs ?? 120_000;
|
|
416
|
+
const { repoRoot, env, timeoutMs } = options;
|
|
408
417
|
const resolvedBase = resolveBaseRefInRepo(repoRoot, {
|
|
409
418
|
...(options.base === undefined ? {} : { base: options.base }),
|
|
410
419
|
...(options.trustBase === undefined ? {} : { trustBase: options.trustBase }),
|
|
@@ -510,6 +519,13 @@ function finishPreparation(options, source, importInput, proposals, note) {
|
|
|
510
519
|
...(source.plan === null ? [] : ['--plan', path.join(readRoot, source.plan)]),
|
|
511
520
|
'--dry-run',
|
|
512
521
|
], readRoot, timeoutMs);
|
|
522
|
+
// The time limit first, before the status, as in the runner: a stopped
|
|
523
|
+
// child's status is not an answer.
|
|
524
|
+
const importStopped = timedOutStep(importResult, 'import-spec');
|
|
525
|
+
if (importStopped !== null) {
|
|
526
|
+
discard();
|
|
527
|
+
return importStopped;
|
|
528
|
+
}
|
|
513
529
|
if (importResult.errorMessage !== null) {
|
|
514
530
|
discard();
|
|
515
531
|
return { kind: 'failed', step: 'import-spec', detail: importResult.errorMessage };
|
|
@@ -588,6 +604,11 @@ function finishPreparation(options, source, importInput, proposals, note) {
|
|
|
588
604
|
'--yes',
|
|
589
605
|
'--json',
|
|
590
606
|
], readRoot, timeoutMs);
|
|
607
|
+
const freezeStopped = timedOutStep(freezeResult, 'freeze');
|
|
608
|
+
if (freezeStopped !== null) {
|
|
609
|
+
cleanup();
|
|
610
|
+
return freezeStopped;
|
|
611
|
+
}
|
|
591
612
|
if (freezeResult.errorMessage !== null || freezeResult.status !== 0) {
|
|
592
613
|
cleanup();
|
|
593
614
|
return {
|
package/dist/normalize.d.ts
CHANGED
|
@@ -59,11 +59,39 @@ export declare function cvssToSeverity(score: number | null): Severity;
|
|
|
59
59
|
* F2) is marked in place, so the count never reads as that many files read.
|
|
60
60
|
*/
|
|
61
61
|
export declare function describeLockfiles(lockfiles: readonly string[], emptied?: ReadonlySet<string>): string;
|
|
62
|
+
/**
|
|
63
|
+
* The advisories osv-scanner.toml filtered out of this run, read from
|
|
64
|
+
* osv-scanner's stderr, the only place it says so.
|
|
65
|
+
*
|
|
66
|
+
* Measured on 2.4.0 (tests/fixtures/osv-scanner-2.4.0-filtered.stderr.txt):
|
|
67
|
+
* the JSON carries no trace of a filtered advisory at all, while stderr
|
|
68
|
+
* prints one "<id> and N alias(es) have been filtered out because: <reason>"
|
|
69
|
+
* line per advisory PER LOCKFILE, then "Filtered N vulnerabilities from
|
|
70
|
+
* output", where N counts the same way (two ignored advisories in two
|
|
71
|
+
* lockfiles print 4). The ignoreUntil expiry is printed nowhere, so it is
|
|
72
|
+
* never claimed here.
|
|
73
|
+
*
|
|
74
|
+
* Annotation only, never a verdict: the count and the ids feed the report's
|
|
75
|
+
* suppressed number and one run fact, and nothing reads them for a decision.
|
|
76
|
+
* A stderr without the count line (a policy that lowers osv-scanner's
|
|
77
|
+
* verbosity) gives null, and the caller keeps the old 0.
|
|
78
|
+
*/
|
|
79
|
+
export interface OsvSuppressions {
|
|
80
|
+
count: number;
|
|
81
|
+
/** Distinct ids in first-seen order, each with the reason osv printed. */
|
|
82
|
+
ids: Array<{
|
|
83
|
+
id: string;
|
|
84
|
+
reason: string;
|
|
85
|
+
}>;
|
|
86
|
+
}
|
|
87
|
+
export declare function osvSuppressions(stderr: string): OsvSuppressions | null;
|
|
62
88
|
export declare function normalizeOsvScanner(raw: unknown, version: string | null, blocked: boolean,
|
|
63
89
|
/** The scan root as a path osv-scanner may have printed it, in any spelling. */
|
|
64
90
|
roots?: readonly string[],
|
|
65
91
|
/** The lockfiles the umbrella passed with --lockfile, repository-relative. */
|
|
66
|
-
lockfiles?: readonly string[]
|
|
92
|
+
lockfiles?: readonly string[],
|
|
93
|
+
/** osv-scanner's stderr, read only for the osv-scanner.toml suppressions it names. */
|
|
94
|
+
stderr?: string): NormalizedGateOutput;
|
|
67
95
|
export type GateProblemRule = 'conductor/gate-missing' | 'conductor/gate-output-unparseable' | 'conductor/gate-failed';
|
|
68
96
|
/**
|
|
69
97
|
* What to install for a product, spelled so it cannot be mistaken for
|
|
@@ -144,4 +172,6 @@ export declare function summariseStderr(stderr: string | null | undefined): stri
|
|
|
144
172
|
* the product and never over the message, so a gate that reworded its error
|
|
145
173
|
* is the same alert rather than a new one every run.
|
|
146
174
|
*/
|
|
147
|
-
export declare function normalizeFailedGate(role: GateRole, product: Product, detail: string, stderr?: string | null
|
|
175
|
+
export declare function normalizeFailedGate(role: GateRole, product: Product, detail: string, stderr?: string | null,
|
|
176
|
+
/** Structured facts beside the detail, such as a timed-out gate's limit and elapsed time. */
|
|
177
|
+
extra?: Record<string, unknown>): Finding;
|
package/dist/normalize.js
CHANGED
|
@@ -797,7 +797,36 @@ export function normalizeGitleaks(raw, version, blocked) {
|
|
|
797
797
|
seen.alsoIn.push(droppedCommit);
|
|
798
798
|
}
|
|
799
799
|
});
|
|
800
|
-
const
|
|
800
|
+
const kept = [...byPlace.values()].map(({ finding, alsoIn }) => alsoIn.length === 0 ? finding : { ...finding, details: { ...finding.details, alsoIn } });
|
|
801
|
+
// THE MERGE COPY ON A MOVED LINE IS NOT COLLAPSED, and that is deliberate
|
|
802
|
+
// (tests/fixtures/gitleaks-8.30.1-merge-doubled.json, measured on 8.30.1).
|
|
803
|
+
// When the base branch moved the lines above a pull request's secret, the
|
|
804
|
+
// merge's first-parent diff reports it at a different StartLine, so the two
|
|
805
|
+
// records differ in StartLine, Commit, Date, Message and Fingerprint and
|
|
806
|
+
// agree on RuleID, File, StartColumn, EndColumn and Entropy. Under --redact
|
|
807
|
+
// nothing in the record identifies the secret itself: Entropy is a
|
|
808
|
+
// character-frequency score, the same for any two secrets that are
|
|
809
|
+
// anagrams, so collapsing on it could fold two different leaks into one
|
|
810
|
+
// SARIF result. Each record is kept, and each names the other here, so a
|
|
811
|
+
// reader sees the likely pair without the report hiding either of them.
|
|
812
|
+
const shape = (finding) => {
|
|
813
|
+
const subject = finding.subject;
|
|
814
|
+
return subject.kind === 'location' && typeof finding.details.entropy === 'number'
|
|
815
|
+
? JSON.stringify([finding.ruleId, subject.file, subject.column, subject.endColumn ?? null, finding.details.entropy])
|
|
816
|
+
: null;
|
|
817
|
+
};
|
|
818
|
+
const findings = kept.map((finding) => {
|
|
819
|
+
const key = shape(finding);
|
|
820
|
+
const twins = key === null
|
|
821
|
+
? []
|
|
822
|
+
: kept
|
|
823
|
+
// A merge re-report is by definition another commit: two records
|
|
824
|
+
// of one shape in the same commit are two places, not a pair.
|
|
825
|
+
.filter((other) => other !== finding && shape(other) === key && other.details.commit !== finding.details.commit)
|
|
826
|
+
.map((other) => other.fingerprint?.value)
|
|
827
|
+
.filter((value) => value !== undefined);
|
|
828
|
+
return twins.length === 0 ? finding : { ...finding, details: { ...finding.details, possiblySameSecretAs: twins } };
|
|
829
|
+
});
|
|
801
830
|
return {
|
|
802
831
|
findings,
|
|
803
832
|
run: {
|
|
@@ -806,7 +835,10 @@ export function normalizeGitleaks(raw, version, blocked) {
|
|
|
806
835
|
suppressed: 0,
|
|
807
836
|
ignored: 0,
|
|
808
837
|
diagnostics: [],
|
|
809
|
-
|
|
838
|
+
// Both counts, labelled: the raw number of records in gitleaks' report,
|
|
839
|
+
// and the distinct places left after the merge collapse above. One
|
|
840
|
+
// unlabelled `entries` read as the finding count when it was not.
|
|
841
|
+
details: { 'entries-raw': entries.length, 'entries-distinct': findings.length },
|
|
810
842
|
},
|
|
811
843
|
diagnostics: [],
|
|
812
844
|
};
|
|
@@ -951,11 +983,55 @@ export function describeLockfiles(lockfiles, emptied = new Set()) {
|
|
|
951
983
|
const named = lockfiles.map((file) => (emptied.has(file) ? `${file} [no packages read]` : file));
|
|
952
984
|
return lockfiles.length === 0 ? '0' : `${lockfiles.length} (${named.join(', ')})`;
|
|
953
985
|
}
|
|
986
|
+
const OSV_FILTERED_COUNT = /^Filtered (\d+) vulnerabilit(?:y|ies) from output$/;
|
|
987
|
+
// The id is restricted to an advisory id's shape. osv-scanner prints a
|
|
988
|
+
// reason from osv-scanner.toml verbatim, newlines and escape bytes included
|
|
989
|
+
// (measured on 2.4.0), so a reason can forge what looks like a second line;
|
|
990
|
+
// an id that is not id-shaped is not read at all, and every id that is still
|
|
991
|
+
// goes through the same cleaner as the reason.
|
|
992
|
+
const OSV_FILTERED_ID = /^([A-Za-z0-9._:-]+) and \d+ alias(?:es)? ha(?:s|ve) been filtered out because: (.*)$/;
|
|
993
|
+
/** Printable ASCII only, capped: the reason is text from the repository's own config. */
|
|
994
|
+
function cleanReason(reason) {
|
|
995
|
+
const printable = reason.replace(/[^\x20-\x7e]/g, '').trim();
|
|
996
|
+
return printable.length <= 80 ? printable : `${printable.slice(0, 80)}...`;
|
|
997
|
+
}
|
|
998
|
+
export function osvSuppressions(stderr) {
|
|
999
|
+
let count = null;
|
|
1000
|
+
const ids = [];
|
|
1001
|
+
for (const raw of stderr.split('\n')) {
|
|
1002
|
+
const line = raw.trim();
|
|
1003
|
+
const total = OSV_FILTERED_COUNT.exec(line);
|
|
1004
|
+
if (total !== null) {
|
|
1005
|
+
// A count that is not a safe integer is not a count (a 400-digit one
|
|
1006
|
+
// printed as "suppressed Infinity"); it is ignored like a missing one.
|
|
1007
|
+
const value = Number(total[1]);
|
|
1008
|
+
if (Number.isSafeInteger(value)) {
|
|
1009
|
+
count = value;
|
|
1010
|
+
}
|
|
1011
|
+
continue;
|
|
1012
|
+
}
|
|
1013
|
+
const one = OSV_FILTERED_ID.exec(line);
|
|
1014
|
+
const id = one === null ? '' : cleanReason(one[1]);
|
|
1015
|
+
if (one !== null && id !== '' && !ids.some((entry) => entry.id === id)) {
|
|
1016
|
+
ids.push({ id, reason: cleanReason(one[2]) });
|
|
1017
|
+
}
|
|
1018
|
+
}
|
|
1019
|
+
return count === null ? null : { count, ids };
|
|
1020
|
+
}
|
|
1021
|
+
/** osv-scanner's `dependency_groups` on a package (2.4.0 writes ["dev"]), read leniently. */
|
|
1022
|
+
function osvDependencyGroups(entry) {
|
|
1023
|
+
const groups = entry.dependency_groups;
|
|
1024
|
+
return Array.isArray(groups) && groups.every((group) => typeof group === 'string')
|
|
1025
|
+
? groups
|
|
1026
|
+
: undefined;
|
|
1027
|
+
}
|
|
954
1028
|
export function normalizeOsvScanner(raw, version, blocked,
|
|
955
1029
|
/** The scan root as a path osv-scanner may have printed it, in any spelling. */
|
|
956
1030
|
roots = [],
|
|
957
1031
|
/** The lockfiles the umbrella passed with --lockfile, repository-relative. */
|
|
958
|
-
lockfiles = []
|
|
1032
|
+
lockfiles = [],
|
|
1033
|
+
/** osv-scanner's stderr, read only for the osv-scanner.toml suppressions it names. */
|
|
1034
|
+
stderr = '') {
|
|
959
1035
|
const product = 'osv-scanner';
|
|
960
1036
|
const top = needRecord(raw, product, 'the output');
|
|
961
1037
|
const results = needArray(top.results, product, 'results');
|
|
@@ -974,6 +1050,7 @@ lockfiles = []) {
|
|
|
974
1050
|
const name = needString(pkg.name, product, `${packageWhere}.package.name`);
|
|
975
1051
|
const installed = optionalString(pkg.version, product, `${packageWhere}.package.version`) ?? '';
|
|
976
1052
|
const ecosystem = optionalString(pkg.ecosystem, product, `${packageWhere}.package.ecosystem`);
|
|
1053
|
+
const dependencyGroups = osvDependencyGroups(entry);
|
|
977
1054
|
otherVerdicts.push(...osvOtherVerdicts(entry, pkg, `${name}@${installed}`));
|
|
978
1055
|
const groups = (entry.groups === undefined ? [] : needArray(entry.groups, product, `${packageWhere}.groups`)).filter(isRecord);
|
|
979
1056
|
const vulns = entry.vulnerabilities === undefined
|
|
@@ -1006,26 +1083,45 @@ lockfiles = []) {
|
|
|
1006
1083
|
aliases: Array.isArray(vuln.aliases) ? vuln.aliases : [],
|
|
1007
1084
|
...(score === null ? {} : { cvss: score }),
|
|
1008
1085
|
...(fixedVersion === undefined ? {} : { fixedVersion }),
|
|
1086
|
+
// Carried, never mapped: whether a dev-only dependency carries
|
|
1087
|
+
// the advisory is for the reader, and changes no verdict.
|
|
1088
|
+
...(dependencyGroups === undefined ? {} : { dependencyGroups }),
|
|
1009
1089
|
},
|
|
1010
1090
|
});
|
|
1011
1091
|
}
|
|
1012
1092
|
}
|
|
1013
1093
|
}
|
|
1094
|
+
const suppressions = osvSuppressions(stderr);
|
|
1014
1095
|
return {
|
|
1015
1096
|
findings,
|
|
1016
1097
|
run: {
|
|
1017
1098
|
// Any known vulnerability fails the gate; a threshold, when an adopter
|
|
1018
1099
|
// wants one, lives in osv-scanner.toml.
|
|
1019
1100
|
failOn: 'any',
|
|
1020
|
-
|
|
1101
|
+
// osv-scanner's own count of what osv-scanner.toml filtered, from its
|
|
1102
|
+
// stderr (osvSuppressions): one per advisory per lockfile. 0 when it
|
|
1103
|
+
// printed no count, which was the only value this ever had before.
|
|
1104
|
+
suppressed: suppressions?.count ?? 0,
|
|
1021
1105
|
ignored: 0,
|
|
1022
1106
|
diagnostics: [],
|
|
1023
1107
|
details: {
|
|
1024
1108
|
lockfiles: describeLockfiles(lockfiles),
|
|
1025
1109
|
// Distinct from the old "sources" name on purpose: this counts only
|
|
1026
1110
|
// the sources osv-scanner reported findings for, never how many were
|
|
1027
|
-
// scanned
|
|
1028
|
-
|
|
1111
|
+
// scanned. Counted as the distinct lockfiles the FINDINGS name rather
|
|
1112
|
+
// than results.length: osv-scanner 2.4.0 prints one result per
|
|
1113
|
+
// lockfile handed with --lockfile (measured,
|
|
1114
|
+
// tests/fixtures/osv-scanner-2.4.0-two-lockfiles.json), but a result
|
|
1115
|
+
// carrying only a non-advisory verdict (a licence, a deprecation) has
|
|
1116
|
+
// no finding, and counting it said a lockfile had findings that the
|
|
1117
|
+
// report then showed none for.
|
|
1118
|
+
'sources-with-findings': new Set(findings.map((finding) => (finding.subject.kind === 'package' ? finding.subject.manifest : ''))).size,
|
|
1119
|
+
...(suppressions === null || suppressions.ids.length === 0
|
|
1120
|
+
? {}
|
|
1121
|
+
: {
|
|
1122
|
+
'suppressed-by-osv-scanner.toml': `${suppressions.ids.map((entry) => `${entry.id} (${entry.reason})`).join(', ')}; ` +
|
|
1123
|
+
'counted by osv-scanner once per advisory per lockfile; expiry not reported by osv-scanner',
|
|
1124
|
+
}),
|
|
1029
1125
|
},
|
|
1030
1126
|
},
|
|
1031
1127
|
diagnostics: [],
|
|
@@ -1035,10 +1131,18 @@ lockfiles = []) {
|
|
|
1035
1131
|
/**
|
|
1036
1132
|
* The package-level keys of an osv-scanner result this normalizer knows:
|
|
1037
1133
|
* the package itself, its advisories, their groups, and the licences it was
|
|
1038
|
-
* found to carry
|
|
1039
|
-
*
|
|
1134
|
+
* found to carry, and `dependency_groups`, the dev marker osvDependencyGroups
|
|
1135
|
+
* reads (2.4.0 writes ["dev"]; a marker, not a verdict). `license_violations`
|
|
1136
|
+
* is deliberately NOT here: it is a verdict (osv-scanner exits 1 for it,
|
|
1137
|
+
* measured on 2.4.0 with --licenses).
|
|
1040
1138
|
*/
|
|
1041
|
-
const OSV_KNOWN_PACKAGE_KEYS = new Set([
|
|
1139
|
+
const OSV_KNOWN_PACKAGE_KEYS = new Set([
|
|
1140
|
+
'package',
|
|
1141
|
+
'vulnerabilities',
|
|
1142
|
+
'groups',
|
|
1143
|
+
'licenses',
|
|
1144
|
+
'dependency_groups',
|
|
1145
|
+
]);
|
|
1042
1146
|
function isEmptyValue(value) {
|
|
1043
1147
|
if (value === undefined || value === null || value === false || value === '') {
|
|
1044
1148
|
return true;
|
|
@@ -1219,8 +1323,10 @@ export function summariseStderr(stderr) {
|
|
|
1219
1323
|
* the product and never over the message, so a gate that reworded its error
|
|
1220
1324
|
* is the same alert rather than a new one every run.
|
|
1221
1325
|
*/
|
|
1222
|
-
export function normalizeFailedGate(role, product, detail, stderr
|
|
1326
|
+
export function normalizeFailedGate(role, product, detail, stderr,
|
|
1327
|
+
/** Structured facts beside the detail, such as a timed-out gate's limit and elapsed time. */
|
|
1328
|
+
extra = {}) {
|
|
1223
1329
|
const said = summariseStderr(stderr);
|
|
1224
1330
|
return gateProblem('conductor/gate-failed', role, product, `The "${role}" gate did not complete: ${detail} Nothing was verified by this gate.` +
|
|
1225
|
-
(said === null ? '' : ` The gate wrote to stderr: ${said}`), { detail, stderr: said });
|
|
1331
|
+
(said === null ? '' : ` The gate wrote to stderr: ${said}`), { detail, stderr: said, ...extra });
|
|
1226
1332
|
}
|
package/dist/output-sarif.js
CHANGED
|
@@ -784,6 +784,23 @@ function nodeModulesSkippedNotifications(result) {
|
|
|
784
784
|
},
|
|
785
785
|
];
|
|
786
786
|
}
|
|
787
|
+
/**
|
|
788
|
+
* A passthrough option that is a gate's own setting under a name conductor
|
|
789
|
+
* also uses (gitleaks' `options.timeout`), as notifications. A NOTE: nothing
|
|
790
|
+
* went wrong, and the gate's own outcome, whatever it was, is reported on its
|
|
791
|
+
* own. It says which deadline is whose.
|
|
792
|
+
*/
|
|
793
|
+
function gateOwnOptionNotifications(result) {
|
|
794
|
+
return result.gates.flatMap((gate) => gate.gateOwnOption === undefined
|
|
795
|
+
? []
|
|
796
|
+
: [
|
|
797
|
+
{
|
|
798
|
+
id: 'conductor/option-is-gate-own',
|
|
799
|
+
message: gate.gateOwnOption,
|
|
800
|
+
details: { role: gate.role, product: gate.product, option: 'timeout' },
|
|
801
|
+
},
|
|
802
|
+
]);
|
|
803
|
+
}
|
|
787
804
|
/**
|
|
788
805
|
* The gates the policy file told not to decide anything, as notifications.
|
|
789
806
|
*
|
|
@@ -934,6 +951,7 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
934
951
|
...trustBaseWithheldNotifications(result),
|
|
935
952
|
...nodeModulesSkippedNotifications(result),
|
|
936
953
|
...intentWarningNotifications(result),
|
|
954
|
+
...gateOwnOptionNotifications(result),
|
|
937
955
|
];
|
|
938
956
|
// Notifications earn the run on their own. Before this, the umbrella run
|
|
939
957
|
// existed only when it had findings and a deferred gate was one; without
|