@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.
@@ -0,0 +1,256 @@
1
+ // The pin check for pip requirements files.
2
+ //
3
+ // osv-scanner reads a requirements file as a list of packages at the versions
4
+ // written in it. A line pinned with == names one version, and an advisory
5
+ // against that version is a statement about what this repository installs.
6
+ // Any other line (>=, ~=, a range, no version at all) names a set of versions,
7
+ // and whatever osv-scanner reports for it is a guess: with its default
8
+ // resolution it is the registry's latest, with --no-resolve it is the lower
9
+ // bound. So a requirements file is handed over only when every requirement in
10
+ // it, and in every file it includes with -r, is pinned with ==.
11
+ //
12
+ // This SELECTS what the tool is handed, like the basename list beside it in
13
+ // src/products.ts, and raises no finding of its own: a file left out is named
14
+ // on the coverage line with the line that stopped it (src/gate-runner.ts).
15
+ //
16
+ // Includes are followed here rather than left to osv-scanner, because
17
+ // osv-scanner 2.4.0 follows -r and swallows a missing include (one stderr
18
+ // line, the rest scanned, exit decided by what it did read): a top file whose
19
+ // include is absent would be scanned and silently under-read. It resolves an
20
+ // include relative to the including file's directory and survives a cycle,
21
+ // and so does this.
22
+ import path from 'node:path';
23
+ /** The deepest include chain followed. A deeper one leaves the top file unscanned. */
24
+ export const MAX_INCLUDE_DEPTH = 8;
25
+ /** Options that take a value and say nothing about which packages are installed. */
26
+ const IGNORED_WITH_VALUE = [
27
+ '-c',
28
+ '--constraint',
29
+ '-i',
30
+ '--index-url',
31
+ '--extra-index-url',
32
+ '-f',
33
+ '--find-links',
34
+ '--trusted-host',
35
+ '--only-binary',
36
+ '--no-binary',
37
+ '--use-feature',
38
+ ];
39
+ /** Flags with no value that say nothing about which packages are installed. */
40
+ const IGNORED_FLAGS = ['--pre', '--prefer-binary', '--require-hashes'];
41
+ const NAME = '[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?';
42
+ const EXTRAS = '\\[[^\\]]*\\]';
43
+ const REQUIREMENT = new RegExp(`^(${NAME})\\s*(${EXTRAS})?\\s*(.*)$`);
44
+ const NAME_AT_URL = new RegExp(`^${NAME}\\s*(${EXTRAS})?\\s*@\\s*\\S`);
45
+ const URL = /^[A-Za-z][A-Za-z0-9+.-]*:\/\//;
46
+ const HASH_OPTION = /\s+--hash(?:=|\s+)\S+/g;
47
+ function logicalLines(text) {
48
+ const physical = text.split(/\r?\n/);
49
+ const out = [];
50
+ let buffer = null;
51
+ let start = 0;
52
+ const flush = () => {
53
+ if (buffer === null) {
54
+ return;
55
+ }
56
+ // A # that starts the line or follows whitespace starts a comment; one
57
+ // inside a token (a URL fragment, #egg=) does not.
58
+ const stripped = buffer.replace(/(^|\s)#.*$/, '').trim();
59
+ if (stripped !== '') {
60
+ out.push({ line: start, text: stripped });
61
+ }
62
+ buffer = null;
63
+ };
64
+ for (const [index, raw] of physical.entries()) {
65
+ if (buffer === null) {
66
+ buffer = '';
67
+ start = index + 1;
68
+ }
69
+ if (raw.endsWith('\\')) {
70
+ buffer += `${raw.slice(0, -1)} `;
71
+ continue;
72
+ }
73
+ buffer += raw;
74
+ flush();
75
+ }
76
+ flush();
77
+ return out;
78
+ }
79
+ /** Splits a leading option into its name and value: "-rfoo", "-r foo", "--x=foo", "--x foo". */
80
+ function option(text) {
81
+ const long = /^(--[A-Za-z0-9-]+)(?:=|\s+|$)(.*)$/.exec(text);
82
+ if (long !== null) {
83
+ return { name: long[1], value: long[2].trim() };
84
+ }
85
+ const short = /^(-[A-Za-z])\s*(.*)$/.exec(text);
86
+ if (short !== null) {
87
+ return { name: short[1], value: short[2].trim() };
88
+ }
89
+ return null;
90
+ }
91
+ /** Printable, one line, no double quotes, capped: the line goes into a report. */
92
+ function printable(text) {
93
+ const flat = text.replace(/[^\x20-\x7e]/g, '?').replace(/"/g, "'");
94
+ return flat.length > 120 ? `${flat.slice(0, 117)}...` : flat;
95
+ }
96
+ function isDirectReference(text) {
97
+ if (URL.test(text) || NAME_AT_URL.test(text)) {
98
+ return true;
99
+ }
100
+ // A local path: anything that starts like one or has a path separator in
101
+ // the part before a version specifier, or names an archive.
102
+ const head = text.split(/[\s;=<>!~]/)[0] ?? '';
103
+ return (head.startsWith('.') ||
104
+ head.startsWith('/') ||
105
+ head.startsWith('~') ||
106
+ head.includes('/') ||
107
+ head.includes('\\') ||
108
+ /\.(whl|zip|tar\.gz|tgz|tar\.bz2)$/i.test(head));
109
+ }
110
+ function classify(text) {
111
+ if (text.startsWith('-')) {
112
+ const opt = option(text);
113
+ if (opt === null) {
114
+ return { kind: 'unrecognised' };
115
+ }
116
+ if (opt.name === '-r' || opt.name === '--requirement') {
117
+ return opt.value === '' ? { kind: 'unrecognised' } : { kind: 'include', target: opt.value };
118
+ }
119
+ if (opt.name === '-e' || opt.name === '--editable') {
120
+ return { kind: 'excluded' };
121
+ }
122
+ if (IGNORED_WITH_VALUE.includes(opt.name) && opt.value !== '') {
123
+ return { kind: 'ignored' };
124
+ }
125
+ if (IGNORED_FLAGS.includes(opt.name) && opt.value === '') {
126
+ return { kind: 'ignored' };
127
+ }
128
+ return { kind: 'unrecognised' };
129
+ }
130
+ if (isDirectReference(text)) {
131
+ return { kind: 'excluded' };
132
+ }
133
+ // Hash options may follow a requirement; nothing else may.
134
+ const withoutHashes = text.replace(HASH_OPTION, '');
135
+ const [spec = '', ...marker] = withoutHashes.split(';');
136
+ if (marker.join(';').includes(' --') || /\s--?[A-Za-z]/.test(spec)) {
137
+ return { kind: 'unrecognised' };
138
+ }
139
+ const match = REQUIREMENT.exec(spec.trim());
140
+ if (match === null) {
141
+ return { kind: 'unrecognised' };
142
+ }
143
+ const specifier = match[3].trim();
144
+ if (specifier.startsWith('===')) {
145
+ return { kind: 'arbitrary-equality' };
146
+ }
147
+ if (/^==\s*[^\s,=<>!~*$;]+$/.test(specifier)) {
148
+ return { kind: 'pinned' };
149
+ }
150
+ if (specifier === '' || /^[=<>!~]/.test(specifier)) {
151
+ return { kind: 'unpinned' };
152
+ }
153
+ return { kind: 'unrecognised' };
154
+ }
155
+ /**
156
+ * Checks one requirements file and everything it includes.
157
+ *
158
+ * `read` is asked for each file by repository-relative path and decides what
159
+ * "there" means: on the head, a tracked regular file on disk; on the base,
160
+ * the blob at the trust base. Every problem is collected, not only the first,
161
+ * so the ratchet's diagnostic can name each unpinned line; `pinned` is true
162
+ * only when there are none.
163
+ */
164
+ export function checkRequirementsPins(top, read) {
165
+ const files = [];
166
+ const problems = [];
167
+ let excluded = 0;
168
+ let topMissing = null;
169
+ const visited = new Set();
170
+ const visit = (file, depth, from, written) => {
171
+ if (visited.has(file)) {
172
+ return;
173
+ }
174
+ if (depth > MAX_INCLUDE_DEPTH) {
175
+ problems.push({
176
+ file: from ?? file,
177
+ line: null,
178
+ text: written,
179
+ kind: 'include',
180
+ why: `more than ${MAX_INCLUDE_DEPTH} includes deep`,
181
+ });
182
+ return;
183
+ }
184
+ visited.add(file);
185
+ const got = read(file);
186
+ if (got.kind === 'missing') {
187
+ // For the top file itself the sentence would read "includes
188
+ // requirements.txt, which ...", which no caller prints: the head copy
189
+ // is a tracked file, and callers of a base check read topMissing.
190
+ if (from === null) {
191
+ topMissing = got.why;
192
+ }
193
+ problems.push({ file: from ?? file, line: null, text: written, kind: 'include', why: `which ${got.why}` });
194
+ return;
195
+ }
196
+ files.push(file);
197
+ for (const logical of logicalLines(got.text)) {
198
+ const verdict = classify(logical.text);
199
+ switch (verdict.kind) {
200
+ case 'pinned':
201
+ case 'ignored':
202
+ break;
203
+ case 'excluded':
204
+ excluded += 1;
205
+ break;
206
+ case 'include': {
207
+ const target = verdict.target;
208
+ const fail = (why) => {
209
+ problems.push({ file, line: null, text: printable(target), kind: 'include', why });
210
+ };
211
+ if (URL.test(target)) {
212
+ fail('which is a URL');
213
+ break;
214
+ }
215
+ if (path.posix.isAbsolute(target) || path.win32.isAbsolute(target)) {
216
+ fail('which is an absolute path');
217
+ break;
218
+ }
219
+ const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(file), target));
220
+ if (resolved === '..' || resolved.startsWith('../')) {
221
+ fail('which is outside the repository');
222
+ break;
223
+ }
224
+ visit(resolved, depth + 1, file, printable(target));
225
+ break;
226
+ }
227
+ default:
228
+ problems.push({ file, line: logical.line, text: printable(logical.text), kind: verdict.kind });
229
+ }
230
+ }
231
+ };
232
+ visit(top, 0, null, top);
233
+ return { pinned: problems.length === 0, files, excluded, problems, topMissing };
234
+ }
235
+ /**
236
+ * One problem as the reason clause of a diagnostic about `top`, with no
237
+ * trailing full stop: `line 4 "flask>=2.0" is not pinned with ==, so any
238
+ * version osv-scanner reported would be a guess`.
239
+ */
240
+ export function describePinProblem(top, problem) {
241
+ const guess = 'so any version osv-scanner reported would be a guess';
242
+ const where = problem.file === top ? '' : ` of ${problem.file}`;
243
+ switch (problem.kind) {
244
+ case 'unpinned':
245
+ return `line ${problem.line ?? '?'}${where} "${problem.text}" is not pinned with ==, ${guess}`;
246
+ case 'arbitrary-equality':
247
+ return `line ${problem.line ?? '?'}${where} "${problem.text}" is pinned with ===, not ==, ${guess}`;
248
+ case 'unrecognised':
249
+ return (`line ${problem.line ?? '?'}${where} "${problem.text}" is not a line conductor recognises, ` +
250
+ 'so it cannot tell what osv-scanner would read there');
251
+ case 'include': {
252
+ const from = problem.file === top ? '' : ` (from ${problem.file})`;
253
+ return `includes ${problem.text}${from}, ${problem.why ?? 'which could not be read'}`;
254
+ }
255
+ }
256
+ }
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. */
package/dist/run.js CHANGED
@@ -1,6 +1,6 @@
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';
3
+ import { EXIT_COULD_NOT_RUN, composeExitCode, gateExitBlocks } from './exit-codes.js';
4
4
  import { gateProgramRefused, preparationFailed, refuseHeadControlledBinary, runGate, } from './gate-runner.js';
5
5
  import { resolveBaseRef } from './intent-base.js';
6
6
  import { frozenNativeContractPath, prepareIntent, } from './intent-prepare.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.
@@ -360,7 +366,7 @@ export function runAll(policy, options) {
360
366
  }
361
367
  const exitCode = composeExitCode(outcomes.map((outcome) => ({
362
368
  couldNotRun: outcome.couldNotRun,
363
- exitCode: outcome.exitCode,
369
+ exitBlocks: gateExitBlocks(outcome),
364
370
  hasBlockingFinding: outcome.findings.some((finding) => finding.blocking),
365
371
  enforce: outcome.enforce,
366
372
  })));
@@ -368,6 +374,9 @@ export function runAll(policy, options) {
368
374
  schemaVersion: 1,
369
375
  generatedAt: (options.now?.() ?? new Date()).toISOString(),
370
376
  gates: outcomes,
377
+ // Absent rather than empty when nothing is disabled, so a run with every
378
+ // gate on serialises exactly as it did before this field existed.
379
+ ...(disabledGates(policy).length === 0 ? {} : { disabled: disabledGates(policy) }),
371
380
  deferred,
372
381
  skipped,
373
382
  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.9.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,10 @@
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
+ },
57
61
  "stage": {
58
62
  "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
63
  "enum": ["commit", "push", "ci"]