@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/dist/run.d.ts CHANGED
@@ -145,10 +145,23 @@ export interface RunTrustBase {
145
145
  */
146
146
  notGiven?: boolean;
147
147
  }
148
+ /**
149
+ * A gate the policy file declares with `enabled: false`. Listed so an adopter
150
+ * sees what is off; it is not a GateOutcome, nothing was looked for or run.
151
+ */
152
+ export interface DisabledGate {
153
+ role: GateRole;
154
+ product: Product;
155
+ }
148
156
  export interface RunResult {
149
157
  schemaVersion: 1;
150
158
  generatedAt: string;
151
159
  gates: GateOutcome[];
160
+ /**
161
+ * Gates the policy file declares with `enabled: false`. A gate the --gate
162
+ * flag left out is in `excluded` instead. Absent counts as none.
163
+ */
164
+ disabled?: DisabledGate[];
152
165
  /** Enabled gates the requested stage held back. Empty with no --stage. */
153
166
  deferred: DeferredGate[];
154
167
  /** Enabled gates that ran at this stage and found nothing to check. */
@@ -185,6 +198,10 @@ export interface RunOptions {
185
198
  repoRoot: string;
186
199
  staged: boolean;
187
200
  pathValue: string;
201
+ /**
202
+ * A test hook: every gate's time limit, outranking the policy. No CLI path
203
+ * sets it; `resolveTimeLimit` (src/gate-runner.ts) decides the limit.
204
+ */
188
205
  timeoutMs?: number;
189
206
  /**
190
207
  * Which stopping point this run is. Absent means every enabled gate runs,
package/dist/run.js CHANGED
@@ -1,7 +1,7 @@
1
1
  // One run across every enabled gate.
2
2
  import { compareFindings } from './envelope.js';
3
- import { EXIT_COULD_NOT_RUN, composeExitCode } from './exit-codes.js';
4
- import { gateProgramRefused, preparationFailed, refuseHeadControlledBinary, runGate, } from './gate-runner.js';
3
+ import { EXIT_COULD_NOT_RUN, composeExitCode, gateExitBlocks } from './exit-codes.js';
4
+ import { gateProgramRefused, preparationFailed, preparationTimedOut, refuseHeadControlledBinary, resolveTimeLimit, runGate, } from './gate-runner.js';
5
5
  import { resolveBaseRef } from './intent-base.js';
6
6
  import { frozenNativeContractPath, prepareIntent, } from './intent-prepare.js';
7
7
  import { GATE_ROLES, enabledGates, runsAtStage } from './policy.js';
@@ -82,6 +82,12 @@ function partitionGates(policy, requested) {
82
82
  .map((gate) => ({ role: gate.role, product: gate.product }));
83
83
  return { gates, deferred, excluded };
84
84
  }
85
+ /** Declared in the policy file with enabled: false, in role order. */
86
+ function disabledGates(policy) {
87
+ return GATE_ROLES.map((role) => policy.gates[role])
88
+ .filter((gate) => gate !== undefined && !gate.enabled && !gate.excludedByCli)
89
+ .map((gate) => ({ role: gate.role, product: gate.product }));
90
+ }
85
91
  /**
86
92
  * The run that never happened, because the trust base could not be judged
87
93
  * against.
@@ -275,13 +281,17 @@ export function runAll(policy, options) {
275
281
  continue;
276
282
  }
277
283
  }
284
+ const intentLimit = resolveTimeLimit(gate, options.timeoutMs);
278
285
  const prepared = prepareIntent({
279
286
  repoRoot: options.repoRoot,
280
287
  binary,
281
288
  env,
282
289
  ...(options.base === undefined ? {} : { base: options.base }),
283
290
  ...(options.spec === undefined ? {} : { spec: options.spec }),
284
- ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
291
+ // The same resolver runGate uses, so the preparation spawns and
292
+ // the gate's own spawns cannot disagree about its limit; each
293
+ // preparation spawn gets the full limit.
294
+ timeoutMs: intentLimit.ms,
285
295
  ...(options.tempRoot === undefined ? {} : { tempRoot: options.tempRoot }),
286
296
  ...(trustBaseRef === undefined ? {} : { trustBase: trustBaseRef }),
287
297
  });
@@ -302,6 +312,18 @@ export function runAll(policy, options) {
302
312
  });
303
313
  continue;
304
314
  }
315
+ if (prepared.kind === 'timed-out') {
316
+ outcomes.push(preparationTimedOut(
317
+ // The same enforce rule as a failed preparation, below.
318
+ trustBaseRef === undefined ? gate : { ...gate, enforce: true }, {
319
+ step: prepared.step,
320
+ elapsedMs: prepared.elapsedMs,
321
+ signal: prepared.signal,
322
+ limit: intentLimit,
323
+ ...(trustBaseRef === undefined ? {} : { trustBase: trustBaseRef }),
324
+ }));
325
+ continue;
326
+ }
305
327
  if (prepared.kind === 'failed') {
306
328
  outcomes.push(preparationFailed(
307
329
  // ENFORCED under a trust base, by the same argument as
@@ -360,7 +382,7 @@ export function runAll(policy, options) {
360
382
  }
361
383
  const exitCode = composeExitCode(outcomes.map((outcome) => ({
362
384
  couldNotRun: outcome.couldNotRun,
363
- exitCode: outcome.exitCode,
385
+ exitBlocks: gateExitBlocks(outcome),
364
386
  hasBlockingFinding: outcome.findings.some((finding) => finding.blocking),
365
387
  enforce: outcome.enforce,
366
388
  })));
@@ -368,6 +390,9 @@ export function runAll(policy, options) {
368
390
  schemaVersion: 1,
369
391
  generatedAt: (options.now?.() ?? new Date()).toISOString(),
370
392
  gates: outcomes,
393
+ // Absent rather than empty when nothing is disabled, so a run with every
394
+ // gate on serialises exactly as it did before this field existed.
395
+ ...(disabledGates(policy).length === 0 ? {} : { disabled: disabledGates(policy) }),
371
396
  deferred,
372
397
  skipped,
373
398
  excluded,
@@ -185,6 +185,25 @@ export type FileAtRef = {
185
185
  * which is the repository root here.
186
186
  */
187
187
  export declare function readFileAtRef(repoRoot: string, ref: string, relativePath: string): FileAtRef;
188
+ /** One file at a ref as bytes: not there, its exact bytes, or a read this run could not make. */
189
+ export type BytesAtRef = {
190
+ kind: 'absent';
191
+ } | {
192
+ kind: 'file';
193
+ bytes: Buffer;
194
+ } | {
195
+ kind: 'error';
196
+ detail: string;
197
+ };
198
+ /**
199
+ * `readFileAtRef`, byte-exact. The same lookup (the same tree listing, the
200
+ * same refusal of a symlink, directory or submodule at the path or above it,
201
+ * the same blob read by the id the listing named), with the blob kept as
202
+ * bytes rather than decoded as UTF-8. For a file that is copied out and read
203
+ * by another program (the vulnerabilities gate's base copies): decoding would
204
+ * rewrite a lockfile with invalid bytes before that program saw it.
205
+ */
206
+ export declare function readFileAtRefBytes(repoRoot: string, ref: string, relativePath: string): BytesAtRef;
188
207
  /**
189
208
  * Whether two policy files differ in what they SAY.
190
209
  *
@@ -74,7 +74,7 @@
74
74
  import { realpathSync } from 'node:fs';
75
75
  import path from 'node:path';
76
76
  import { parse as parseYaml } from 'yaml';
77
- import { gitComplaint, runGit } from './git.js';
77
+ import { gitComplaint, runGit, runGitBytes } from './git.js';
78
78
  /**
79
79
  * The private, fully spelled ref the composite action fetches the base branch
80
80
  * into (action.yml, gates step). Nothing else writes it and no short name can
@@ -531,6 +531,35 @@ export function readFileAtRef(repoRoot, ref, relativePath) {
531
531
  }
532
532
  return { kind: 'file', text: blob.stdout };
533
533
  }
534
+ /**
535
+ * `readFileAtRef`, byte-exact. The same lookup (the same tree listing, the
536
+ * same refusal of a symlink, directory or submodule at the path or above it,
537
+ * the same blob read by the id the listing named), with the blob kept as
538
+ * bytes rather than decoded as UTF-8. For a file that is copied out and read
539
+ * by another program (the vulnerabilities gate's base copies): decoding would
540
+ * rewrite a lockfile with invalid bytes before that program saw it.
541
+ */
542
+ export function readFileAtRefBytes(repoRoot, ref, relativePath) {
543
+ const listed = treeEntryAt(repoRoot, ref, relativePath);
544
+ if (listed.kind !== 'entry') {
545
+ return listed;
546
+ }
547
+ if (listed.type !== 'blob' || !isRegularFileMode(listed.mode)) {
548
+ return {
549
+ kind: 'error',
550
+ detail: `${relativePath} is not a regular file at "${ref}" (git lists it with mode ${listed.mode}), ` +
551
+ 'so there is no file to read there',
552
+ };
553
+ }
554
+ const blob = runGitBytes(repoRoot, ['cat-file', 'blob', listed.sha]);
555
+ if (blob.error !== undefined || blob.status !== 0) {
556
+ return {
557
+ kind: 'error',
558
+ detail: `${relativePath} is listed at "${ref}" but its contents could not be read: ${gitComplaint({ ...blob, stdout: '' })}`,
559
+ };
560
+ }
561
+ return { kind: 'file', bytes: blob.stdout };
562
+ }
534
563
  /**
535
564
  * Whether two policy files differ in what they SAY.
536
565
  *
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Tracked manifest-like files that were not handed to `product`, sorted, as
3
+ * one sentence fragment, or null when there are none.
4
+ *
5
+ * `handed` are the repository-relative paths the gate was actually handed,
6
+ * so a file it does read is never listed. By path rather than by base name,
7
+ * because the vulnerabilities gate hands a requirements file only when it
8
+ * passes the pin check (src/osv-coverage.ts): an unpinned requirements.txt
9
+ * is not read even when another requirements.txt is, and is listed. go.mod
10
+ * and a pinned requirements file are handed, so they leave this list.
11
+ * Vendored and testdata directories are skipped like node_modules: they are
12
+ * not this repository's own manifests.
13
+ */
14
+ export declare function unreadManifestsNote(tracked: readonly string[], handed: ReadonlySet<string>, product: string): string | null;
@@ -0,0 +1,69 @@
1
+ // Which tracked manifest-like files were NOT handed to the external scanner.
2
+ //
3
+ // This scans nothing and decides nothing, and it claims nothing about what
4
+ // any other gate reads: it measures one thing, the files this gate was not
5
+ // given. A repository whose only manifests are a pyproject.toml, a Dockerfile
6
+ // and a workflow gets a green vulnerabilities gate that looked at none of
7
+ // them, and "treated as clean" on its own reads as a statement about the code.
8
+ const EXACT_NAMES = new Set([
9
+ 'pyproject.toml',
10
+ 'Pipfile',
11
+ 'setup.py',
12
+ 'go.mod',
13
+ 'go.sum',
14
+ 'Cargo.toml',
15
+ 'Gemfile',
16
+ 'composer.json',
17
+ 'pom.xml',
18
+ 'build.gradle',
19
+ 'build.gradle.kts',
20
+ 'Package.swift',
21
+ 'Podfile',
22
+ 'compose.yml',
23
+ 'compose.yaml',
24
+ // Added 2026-10-13 (audit finding F3). Podfile.lock and deno.lock are
25
+ // lockfiles osv-scanner 2.4.0 rejects with --lockfile (exit 127,
26
+ // measured), so they are never handed over and must be named here; mix.exs
27
+ // and pubspec.yaml are the manifests beside two lockfiles it does read
28
+ // (mix.lock, pubspec.lock), named when no lockfile was committed.
29
+ 'Podfile.lock',
30
+ 'deno.lock',
31
+ 'mix.exs',
32
+ 'pubspec.yaml',
33
+ ]);
34
+ const MAX_LISTED = 12;
35
+ const SKIPPED_DIRS = new Set(['node_modules', 'vendor', 'testdata']);
36
+ function isManifest(file) {
37
+ const base = file.slice(file.lastIndexOf('/') + 1);
38
+ return (EXACT_NAMES.has(base) ||
39
+ /^requirements.*\.txt$/.test(base) ||
40
+ /^Dockerfile(\..+)?$/.test(base) ||
41
+ /^docker-compose.*\.ya?ml$/.test(base) ||
42
+ (file.startsWith('.github/workflows/') && /\.ya?ml$/.test(base)));
43
+ }
44
+ /**
45
+ * Tracked manifest-like files that were not handed to `product`, sorted, as
46
+ * one sentence fragment, or null when there are none.
47
+ *
48
+ * `handed` are the repository-relative paths the gate was actually handed,
49
+ * so a file it does read is never listed. By path rather than by base name,
50
+ * because the vulnerabilities gate hands a requirements file only when it
51
+ * passes the pin check (src/osv-coverage.ts): an unpinned requirements.txt
52
+ * is not read even when another requirements.txt is, and is listed. go.mod
53
+ * and a pinned requirements file are handed, so they leave this list.
54
+ * Vendored and testdata directories are skipped like node_modules: they are
55
+ * not this repository's own manifests.
56
+ */
57
+ export function unreadManifestsNote(tracked, handed, product) {
58
+ const unread = tracked
59
+ .filter((file) => !file.split('/').some((segment) => SKIPPED_DIRS.has(segment)))
60
+ .filter((file) => !handed.has(file))
61
+ .filter(isManifest)
62
+ .sort();
63
+ if (unread.length === 0) {
64
+ return null;
65
+ }
66
+ const listed = unread.slice(0, MAX_LISTED).join(', ');
67
+ const more = unread.length > MAX_LISTED ? `, and ${unread.length - MAX_LISTED} more` : '';
68
+ return `Tracked manifests not handed to ${product}: ${listed}${more}.`;
69
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.8.1",
3
+ "version": "0.10.0",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
6
  "keywords": [
@@ -54,6 +54,16 @@
54
54
  "type": "boolean",
55
55
  "default": true
56
56
  },
57
+ "present-on-base": {
58
+ "description": "Only on the vulnerabilities gate. On a pull-request run osv-scanner also scans the base branch copies of the lockfiles that carry findings, and labels each finding introduced or present-on-base. block (the default when the key is absent) blocks on every finding; report reports present-on-base findings without blocking and blocks only on introduced ones. Read from the base branch policy on a pull request, so a pull request cannot set it for itself. Has no effect on a run without a base, where every finding blocks.",
59
+ "enum": ["block", "report"]
60
+ },
61
+ "timeout-seconds": {
62
+ "description": "How long conductor lets this gate run before stopping it, in whole seconds, from 10 to 21600 (six hours, the GitHub-hosted job limit). Every spawn of the gate gets the full limit: the version probe, the scan, the intent gate's preparation steps and osv-scanner's base run. Absent means the default for the product: 120 for dep-guard, vault-guard and intent-guard, 600 for gitleaks, 300 for osv-scanner. A gate stopped at its limit could not run (timed-out). Read from the base branch policy on a pull request, so a pull request cannot change its own limit. Not the same as a gate's own timeout flag under options.",
63
+ "type": "integer",
64
+ "minimum": 10,
65
+ "maximum": 21600
66
+ },
57
67
  "stage": {
58
68
  "description": "When this gate runs. Stages are cumulative in the order commit, push, ci: a gate runs at its own stage and at every later one, so a run at ci runs everything enabled. Defaults to commit for dependencies and secrets, and to ci for intent, secrets-history and vulnerabilities: the intent gate carries per-task ceremony, and a history scan or a registry lookup is pull-request work. A run with no --stage runs every enabled gate whatever its stage.",
59
69
  "enum": ["commit", "push", "ci"]