@vaultcompass/conductor 0.15.0 → 0.16.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 +152 -1184
- package/dist/gate-runner.js +19 -6
- package/dist/output-text.js +8 -0
- package/dist/resolve.d.ts +77 -14
- package/dist/resolve.js +155 -24
- package/dist/trust-base.d.ts +46 -1
- package/dist/trust-base.js +176 -5
- package/package.json +1 -1
package/dist/gate-runner.js
CHANGED
|
@@ -31,8 +31,8 @@ import { ExternalConfigError, materializeExternalConfig, nestedConfigProposals,
|
|
|
31
31
|
import { osvLockfileKind, profileFor } from './products.js';
|
|
32
32
|
import { unreadManifestsNote } from './unread-manifests.js';
|
|
33
33
|
import { escapeNonAscii } from './policy-diff.js';
|
|
34
|
-
import { atLeastVersion, refuseHeadControlledArgument, refuseHeadControlledProgram } from './trust-base.js';
|
|
35
|
-
import { ResolveError, argumentCandidates, candidateNames,
|
|
34
|
+
import { atLeastVersion, refuseHeadControlledArgument, refuseHeadControlledData, refuseHeadControlledProgram, } from './trust-base.js';
|
|
35
|
+
import { ResolveError, argumentCandidates, candidateNames, codeArguments, nodeModulesCandidate, resolveGateBinary, } from './resolve.js';
|
|
36
36
|
/** The longest excerpt of a gate's own reason that is carried. */
|
|
37
37
|
export const GATE_SAID_MAX_CHARS = 160;
|
|
38
38
|
/**
|
|
@@ -681,6 +681,15 @@ export function refuseHeadControlledBinary(repoRoot, trustBase, binary) {
|
|
|
681
681
|
return refusal;
|
|
682
682
|
}
|
|
683
683
|
}
|
|
684
|
+
// A command that is the gate itself reads the rest of its args as data
|
|
685
|
+
// (audit 2026-10-28, N1, and its review): what each path is comes from the
|
|
686
|
+
// base tree, and a file or an option-value directory must be the base's.
|
|
687
|
+
for (const data of binary.dataArguments) {
|
|
688
|
+
const refusal = refuseHeadControlledData(repoRoot, trustBase, data);
|
|
689
|
+
if (refusal !== null) {
|
|
690
|
+
return refusal;
|
|
691
|
+
}
|
|
692
|
+
}
|
|
684
693
|
return null;
|
|
685
694
|
}
|
|
686
695
|
/**
|
|
@@ -1310,10 +1319,14 @@ function previewRefusal(gate, repoRoot) {
|
|
|
1310
1319
|
// own entry is in the tree, wherever it points (its directory is checked).
|
|
1311
1320
|
// The candidate set is the primary run's (argumentCandidates): the entry and
|
|
1312
1321
|
// every loadable sibling of it, so a head-added tools/gate.js beside a base
|
|
1313
|
-
// tools/gate/ is refused here too.
|
|
1314
|
-
|
|
1315
|
-
for
|
|
1316
|
-
|
|
1322
|
+
// tools/gate/ is refused here too. The entries are the primary run's code
|
|
1323
|
+
// arguments (codeArguments): every entry for a command that is not the gate
|
|
1324
|
+
// itself, and only the code-extension ones for one that is. The gate's
|
|
1325
|
+
// other args are data it reads (audit 2026-10-28, N1), and runGate's data
|
|
1326
|
+
// check (refuseHeadControlledData, through refuseHeadControlledBinary) runs
|
|
1327
|
+
// on every preview spawn, an option-value directory included (review B1).
|
|
1328
|
+
for (const arg of codeArguments(gate)) {
|
|
1329
|
+
const candidates = argumentCandidates(arg, repoRoot);
|
|
1317
1330
|
if (candidates.some((named) => realPathInside(repoRoot, named) || realPathInside(repoRoot, path.dirname(named)))) {
|
|
1318
1331
|
return {
|
|
1319
1332
|
reason: 'gate-program-refused',
|
package/dist/output-text.js
CHANGED
|
@@ -235,6 +235,14 @@ function enforcementNote(gate) {
|
|
|
235
235
|
`${gate.exitCode ?? '?'}, and enforce is false for it in .guardrails.yaml, so the commit ` +
|
|
236
236
|
'proceeds. Set enforce: true there to make it block.');
|
|
237
237
|
}
|
|
238
|
+
// A gate that ran and checked nothing (an intent gate with no contract, a
|
|
239
|
+
// scanner with nothing to scan) found nothing because it looked at nothing,
|
|
240
|
+
// and "found nothing to block on" reads as a clean result (audit
|
|
241
|
+
// 2026-10-28, N5). The same predicate and words as the verdict's list.
|
|
242
|
+
if (gateCheckedNothing(gate)) {
|
|
243
|
+
return (' not enforced: enforce is false for this gate in .guardrails.yaml, and it checked ' +
|
|
244
|
+
`nothing here: ${checkedNothingWording(gate)}. This is not a clean result.`);
|
|
245
|
+
}
|
|
238
246
|
return ' not enforced: enforce is false for this gate in .guardrails.yaml. It found nothing to block on here.';
|
|
239
247
|
}
|
|
240
248
|
/**
|
package/dist/resolve.d.ts
CHANGED
|
@@ -18,6 +18,15 @@ export interface VersionProbe {
|
|
|
18
18
|
command: string;
|
|
19
19
|
argv: string[];
|
|
20
20
|
}
|
|
21
|
+
/** One args entry of a gate-named command that could name a path (`dataArgumentPaths`). */
|
|
22
|
+
export interface DataArgument {
|
|
23
|
+
/** Absolute, resolved against the repository root. */
|
|
24
|
+
path: string;
|
|
25
|
+
/** False for an option's value (`--x=v`, the word after `--x`, `-xv`): data the gate reads. */
|
|
26
|
+
positional: boolean;
|
|
27
|
+
/** The args entry as written, for the refusal message. */
|
|
28
|
+
entry: string;
|
|
29
|
+
}
|
|
21
30
|
export interface ResolvedBinary {
|
|
22
31
|
/** What to spawn. */
|
|
23
32
|
command: string;
|
|
@@ -46,8 +55,26 @@ export interface ResolvedBinary {
|
|
|
46
55
|
* policy's args, never a candidate's built-in prefix (`scan`, `source`):
|
|
47
56
|
* those are subcommands this package wrote, and a directory of the same
|
|
48
57
|
* name in somebody's repository is not a program.
|
|
58
|
+
*
|
|
59
|
+
* When `command:` is the gate itself (commandIsGateProgram) only the args
|
|
60
|
+
* entries with a code extension are listed here (`codeArguments`); the
|
|
61
|
+
* rest of its args are its own argv, read as data, and land in
|
|
62
|
+
* `dataArguments` instead.
|
|
49
63
|
*/
|
|
50
64
|
argumentPaths: string[];
|
|
65
|
+
/**
|
|
66
|
+
* Every args entry that could name a path, when `command:` is the gate
|
|
67
|
+
* itself (`dataArgumentPaths`), in args order, by POSITION and never by
|
|
68
|
+
* what the head's disk holds. Empty for every other command, and when
|
|
69
|
+
* resolution found the gate.
|
|
70
|
+
*
|
|
71
|
+
* The pull-request check (refuseHeadControlledData) decides from the BASE
|
|
72
|
+
* tree what each one is: a file must be the base's blob, a directory given
|
|
73
|
+
* as an option's value must be the base's tree, and a positional directory
|
|
74
|
+
* is a scan target and is not compared (audit 2026-10-28, N1, and its
|
|
75
|
+
* review, B1 and N-a).
|
|
76
|
+
*/
|
|
77
|
+
dataArguments: DataArgument[];
|
|
51
78
|
source: ResolutionSource;
|
|
52
79
|
/** The candidate name this matched, for the report's gate header. */
|
|
53
80
|
candidate: string;
|
|
@@ -107,14 +134,22 @@ export declare function candidateNames(product: Product): string[];
|
|
|
107
134
|
* Whether the policy's `command:` is itself the gate program, so its `args:`
|
|
108
135
|
* are that gate's own argv rather than something an interpreter will load.
|
|
109
136
|
*
|
|
110
|
-
* True when the command's
|
|
111
|
-
* `intent-guard.js
|
|
112
|
-
*
|
|
113
|
-
*
|
|
114
|
-
* Only
|
|
115
|
-
* from being read as paths
|
|
116
|
-
*
|
|
117
|
-
*
|
|
137
|
+
* True only when the command's NAME is a candidate name (`vault-guard`,
|
|
138
|
+
* `intent-guard.js`, executable or not). False for anything else: an
|
|
139
|
+
* interpreter such as `node` or `python3`, a renamed gate binary, and any
|
|
140
|
+
* wrapper or dispatcher whose name is not a gate name, a non-executable
|
|
141
|
+
* `my-build.js` included. Only when true are the product's subcommand words
|
|
142
|
+
* (`scan`, `source`) exempt from being read as paths, and the args read as
|
|
143
|
+
* the gate's own data rather than as code (`dataArgumentPaths`): an
|
|
144
|
+
* interpreter handed `scan` runs `scan.js` or `scan/index.js`, so for it the
|
|
145
|
+
* word is a path like any other (audit 2026-10-27 fix round, MB3).
|
|
146
|
+
*
|
|
147
|
+
* The name is the only test. An earlier version also counted every
|
|
148
|
+
* non-executable `.js` command, because this package runs one through its own
|
|
149
|
+
* Node with the script as the program; but how a file is RUN says nothing
|
|
150
|
+
* about what it LOADS, and a dispatcher that requires the script its first
|
|
151
|
+
* argument names let a pull request rewrite `scan.js` and pass (audit
|
|
152
|
+
* 2026-10-28, MB1).
|
|
118
153
|
*/
|
|
119
154
|
export declare function commandIsGateProgram(gate: GatePolicy): boolean;
|
|
120
155
|
/**
|
|
@@ -134,11 +169,11 @@ export declare function commandIsGateProgram(gate: GatePolicy): boolean;
|
|
|
134
169
|
* (`--config=tools/cfg.json`, `--import=./hook.mjs`) is read for the value
|
|
135
170
|
* after the first `=`, since that is where an interpreter takes a file to
|
|
136
171
|
* load and a gate takes a file to read its rules from.
|
|
137
|
-
* -
|
|
138
|
-
*
|
|
139
|
-
*
|
|
140
|
-
*
|
|
141
|
-
*
|
|
172
|
+
* - Nothing else is exempt, the product's own subcommand words (`scan`,
|
|
173
|
+
* `source`) included: this is only ever asked for a command that is not
|
|
174
|
+
* the gate itself (commandIsGateProgram), and an interpreter handed `scan`
|
|
175
|
+
* runs `scan.js` or `scan/index.js`. The gate itself has no code args;
|
|
176
|
+
* its args are data (dataArgumentPaths).
|
|
142
177
|
* - The entry as written, when it exists as a file, a directory or a
|
|
143
178
|
* symlink, without following the symlink, so the caller can refuse an
|
|
144
179
|
* in-tree link on its own entry.
|
|
@@ -156,4 +191,32 @@ export declare function commandIsGateProgram(gate: GatePolicy): boolean;
|
|
|
156
191
|
* string (`node -e`, `bash -c`), is not recognised as a path. The README says
|
|
157
192
|
* so.
|
|
158
193
|
*/
|
|
159
|
-
export declare function argumentCandidates(arg: string, repoRoot: string
|
|
194
|
+
export declare function argumentCandidates(arg: string, repoRoot: string): string[];
|
|
195
|
+
/**
|
|
196
|
+
* The args entries vetted as CODE: every entry when the command is not the
|
|
197
|
+
* gate itself, and only the code-extension values (`hasCodeExtension`) when
|
|
198
|
+
* it is. Each goes through `argumentCandidates`, here and in the preview.
|
|
199
|
+
*/
|
|
200
|
+
export declare function codeArguments(gate: GatePolicy): string[];
|
|
201
|
+
/**
|
|
202
|
+
* The args entries of a gate-named command that are its own DATA, when
|
|
203
|
+
* `command:` is the gate itself (commandIsGateProgram), in args order; empty
|
|
204
|
+
* for every other command (audit 2026-10-28, N1, and its review, B1, N-a,
|
|
205
|
+
* N-b, N-e).
|
|
206
|
+
*
|
|
207
|
+
* Every non-code entry (`gateArgEntries`, less the code-extension ones in
|
|
208
|
+
* `codeArguments`) is listed with its position, resolved against the
|
|
209
|
+
* repository root, WHETHER OR NOT the head's disk has it and whatever kind of
|
|
210
|
+
* thing the disk holds there: a head must not be able to delete a path or
|
|
211
|
+
* change it from a file to a directory to move it out of vetting. What each
|
|
212
|
+
* one is, and so which rule applies, is decided from the base tree by
|
|
213
|
+
* refuseHeadControlledData. No `<entry>.js` sibling is tried: that is how an
|
|
214
|
+
* interpreter resolves a name, and this command is not one.
|
|
215
|
+
*
|
|
216
|
+
* What this trusts is the NAME: a program named like a gate is taken to be
|
|
217
|
+
* that gate, except that a code-extension entry keeps the code rule. A
|
|
218
|
+
* wrapper given a gate's name that hands an extension-less entry to an
|
|
219
|
+
* interpreter is a wrapper, vetted no further than this (README,
|
|
220
|
+
* pull-request trust boundary).
|
|
221
|
+
*/
|
|
222
|
+
export declare function dataArgumentPaths(gate: GatePolicy, repoRoot: string): DataArgument[];
|
package/dist/resolve.js
CHANGED
|
@@ -221,6 +221,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
221
221
|
const candidateName = inferred?.name ?? baseName(gate.command);
|
|
222
222
|
const candidate = inferred ?? table[0];
|
|
223
223
|
const argumentPaths = argumentPathsOf(gate, repoRoot);
|
|
224
|
+
const dataArguments = dataArgumentPaths(gate, repoRoot);
|
|
224
225
|
// A build directory holds plain .js files with a shebang but no
|
|
225
226
|
// executable bit surprisingly often (a fresh tsc output, a file copied
|
|
226
227
|
// out of a tarball). Running it through this same Node is exactly what
|
|
@@ -233,6 +234,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
233
234
|
program: gate.command,
|
|
234
235
|
argvPrefix: [gate.command, ...prefix],
|
|
235
236
|
argumentPaths,
|
|
237
|
+
dataArguments,
|
|
236
238
|
source: 'policy',
|
|
237
239
|
candidate: candidateName,
|
|
238
240
|
versionProbe: candidate.versionSafe && profileFor(gate.product).versionProbe !== null
|
|
@@ -253,6 +255,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
253
255
|
program: gate.command,
|
|
254
256
|
argvPrefix: prefix,
|
|
255
257
|
argumentPaths,
|
|
258
|
+
dataArguments,
|
|
256
259
|
source: 'policy',
|
|
257
260
|
candidate: candidateName,
|
|
258
261
|
versionProbe: viaScript ??
|
|
@@ -269,6 +272,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
269
272
|
program: found.command,
|
|
270
273
|
argvPrefix: [...candidate.prefix],
|
|
271
274
|
argumentPaths: [],
|
|
275
|
+
dataArguments: [],
|
|
272
276
|
source: found.source,
|
|
273
277
|
candidate: candidate.name,
|
|
274
278
|
versionProbe: versionProbeFor(gate.product, candidate, found.command, repoRoot, pathValue, skipNodeModules),
|
|
@@ -303,22 +307,27 @@ function existsAtAll(candidate) {
|
|
|
303
307
|
* Whether the policy's `command:` is itself the gate program, so its `args:`
|
|
304
308
|
* are that gate's own argv rather than something an interpreter will load.
|
|
305
309
|
*
|
|
306
|
-
* True when the command's
|
|
307
|
-
* `intent-guard.js
|
|
308
|
-
*
|
|
309
|
-
*
|
|
310
|
-
* Only
|
|
311
|
-
* from being read as paths
|
|
312
|
-
*
|
|
313
|
-
*
|
|
310
|
+
* True only when the command's NAME is a candidate name (`vault-guard`,
|
|
311
|
+
* `intent-guard.js`, executable or not). False for anything else: an
|
|
312
|
+
* interpreter such as `node` or `python3`, a renamed gate binary, and any
|
|
313
|
+
* wrapper or dispatcher whose name is not a gate name, a non-executable
|
|
314
|
+
* `my-build.js` included. Only when true are the product's subcommand words
|
|
315
|
+
* (`scan`, `source`) exempt from being read as paths, and the args read as
|
|
316
|
+
* the gate's own data rather than as code (`dataArgumentPaths`): an
|
|
317
|
+
* interpreter handed `scan` runs `scan.js` or `scan/index.js`, so for it the
|
|
318
|
+
* word is a path like any other (audit 2026-10-27 fix round, MB3).
|
|
319
|
+
*
|
|
320
|
+
* The name is the only test. An earlier version also counted every
|
|
321
|
+
* non-executable `.js` command, because this package runs one through its own
|
|
322
|
+
* Node with the script as the program; but how a file is RUN says nothing
|
|
323
|
+
* about what it LOADS, and a dispatcher that requires the script its first
|
|
324
|
+
* argument names let a pull request rewrite `scan.js` and pass (audit
|
|
325
|
+
* 2026-10-28, MB1).
|
|
314
326
|
*/
|
|
315
327
|
export function commandIsGateProgram(gate) {
|
|
316
328
|
if (gate.command === undefined) {
|
|
317
329
|
return true;
|
|
318
330
|
}
|
|
319
|
-
if (!isExecutableFile(gate.command) && /\.(?:js|mjs|cjs)$/.test(gate.command)) {
|
|
320
|
-
return true;
|
|
321
|
-
}
|
|
322
331
|
const name = baseName(gate.command);
|
|
323
332
|
return CANDIDATES[gate.product].some((candidate) => candidate.name === name);
|
|
324
333
|
}
|
|
@@ -339,11 +348,11 @@ export function commandIsGateProgram(gate) {
|
|
|
339
348
|
* (`--config=tools/cfg.json`, `--import=./hook.mjs`) is read for the value
|
|
340
349
|
* after the first `=`, since that is where an interpreter takes a file to
|
|
341
350
|
* load and a gate takes a file to read its rules from.
|
|
342
|
-
* -
|
|
343
|
-
*
|
|
344
|
-
*
|
|
345
|
-
*
|
|
346
|
-
*
|
|
351
|
+
* - Nothing else is exempt, the product's own subcommand words (`scan`,
|
|
352
|
+
* `source`) included: this is only ever asked for a command that is not
|
|
353
|
+
* the gate itself (commandIsGateProgram), and an interpreter handed `scan`
|
|
354
|
+
* runs `scan.js` or `scan/index.js`. The gate itself has no code args;
|
|
355
|
+
* its args are data (dataArgumentPaths).
|
|
347
356
|
* - The entry as written, when it exists as a file, a directory or a
|
|
348
357
|
* symlink, without following the symlink, so the caller can refuse an
|
|
349
358
|
* in-tree link on its own entry.
|
|
@@ -361,7 +370,7 @@ export function commandIsGateProgram(gate) {
|
|
|
361
370
|
* string (`node -e`, `bash -c`), is not recognised as a path. The README says
|
|
362
371
|
* so.
|
|
363
372
|
*/
|
|
364
|
-
export function argumentCandidates(arg, repoRoot
|
|
373
|
+
export function argumentCandidates(arg, repoRoot) {
|
|
365
374
|
let value = arg;
|
|
366
375
|
if (arg.startsWith('-')) {
|
|
367
376
|
const equals = arg.indexOf('=');
|
|
@@ -370,19 +379,141 @@ export function argumentCandidates(arg, repoRoot, product, exemptSubcommands) {
|
|
|
370
379
|
}
|
|
371
380
|
value = arg.slice(equals + 1);
|
|
372
381
|
}
|
|
373
|
-
else if (exemptSubcommands && CANDIDATES[product].some((candidate) => candidate.prefix.includes(arg))) {
|
|
374
|
-
return [];
|
|
375
|
-
}
|
|
376
382
|
if (value === '') {
|
|
377
383
|
return [];
|
|
378
384
|
}
|
|
379
385
|
const absolute = path.resolve(repoRoot, value);
|
|
380
386
|
return [absolute, ...LOADABLE_EXTENSIONS.map((extension) => absolute + extension)].filter(existsAtAll);
|
|
381
387
|
}
|
|
382
|
-
/**
|
|
388
|
+
/**
|
|
389
|
+
* Extensions that mark an args entry as CODE whatever the command is named
|
|
390
|
+
* (review 2026-10-28, N-e). None of the five gates reads such a file as data,
|
|
391
|
+
* so a gate-named command losing the code rule for them buys nothing, while a
|
|
392
|
+
* wrapper carrying a gate's name that hands `tools/run.js` to an interpreter
|
|
393
|
+
* would otherwise be vetted by that file's bytes alone, weaker than v0.15.0.
|
|
394
|
+
*/
|
|
395
|
+
const CODE_EXTENSIONS = ['.js', '.mjs', '.cjs', '.node', '.ts', '.mts', '.cts', '.py', '.sh', '.bash', '.rb', '.pl'];
|
|
396
|
+
function hasCodeExtension(value) {
|
|
397
|
+
return CODE_EXTENSIONS.some((extension) => value.endsWith(extension));
|
|
398
|
+
}
|
|
399
|
+
/**
|
|
400
|
+
* A gate-named command's args entries, read by POSITION as that gate's own
|
|
401
|
+
* argv (review 2026-10-28, B1 and N-b):
|
|
402
|
+
*
|
|
403
|
+
* - `--name=value` and `-x=value`: the value, an option value;
|
|
404
|
+
* - `--name` or `-x` with no `=`: the NEXT entry is its value, unless that
|
|
405
|
+
* entry is itself an option. Which options take a value is the gate's
|
|
406
|
+
* business and not known here, so a word after any such option is read
|
|
407
|
+
* as one; that is the fail-closed direction (a positional written after a
|
|
408
|
+
* flag is vetted as data, and the refusal says to write it first);
|
|
409
|
+
* - `-xvalue`, a short option joined to its value (pflag shorthand): the
|
|
410
|
+
* rest of the word, an option value. Bundled flags (`-rv`) read the same
|
|
411
|
+
* way name nothing on disk, so they cost one lookup and refuse nothing;
|
|
412
|
+
* - a bare word that is one of the product's subcommands: nothing;
|
|
413
|
+
* - any other word: a positional.
|
|
414
|
+
*/
|
|
415
|
+
/**
|
|
416
|
+
* Flags that take NO value, per product, read from each gate's own `--help`
|
|
417
|
+
* (osv-scanner 2.4.0 `scan source`, gitleaks 8.30.1 `git`, dep-guard 0.17.0
|
|
418
|
+
* and vault-guard 1.12.1 `scan`, intent-guard 1.10.2 `check`). The word after
|
|
419
|
+
* one of these is NOT its value, so `osv-scanner scan source -r .` keeps `.`
|
|
420
|
+
* as a positional scan target (re-review 2026-10-28, R1). Any flag not listed
|
|
421
|
+
* stays fail-closed: the word after it is read as its value. A wrong entry
|
|
422
|
+
* would let a value be read as a positional, which leaves a directory
|
|
423
|
+
* unvetted, so entries come only from a gate's own help text.
|
|
424
|
+
*/
|
|
425
|
+
const NO_VALUE_FLAGS = {
|
|
426
|
+
'osv-scanner': [
|
|
427
|
+
'-r', '--recursive', '--no-ignore', '--include-git-root', '--serve', '--offline',
|
|
428
|
+
'--offline-vulnerabilities', '--download-offline-databases', '--no-resolve',
|
|
429
|
+
'--allow-no-lockfiles', '--all-packages', '--all-vulns',
|
|
430
|
+
'--experimental-flag-deprecated-packages', '--experimental-no-default-plugins', '-h', '--help',
|
|
431
|
+
],
|
|
432
|
+
gitleaks: [
|
|
433
|
+
'-v', '--verbose', '--pre-commit', '--staged', '--ignore-gitleaks-allow', '--no-banner',
|
|
434
|
+
'--no-color', '--redact', '-h', '--help',
|
|
435
|
+
],
|
|
436
|
+
'dep-guard': ['--staged', '--online', '--no-online', '-h', '--help'],
|
|
437
|
+
'vault-guard': ['--staged', '-h', '--help'],
|
|
438
|
+
'intent-guard': ['--staged', '--no-require-frozen', '--log', '--json', '-h', '--help', '-v', '--version'],
|
|
439
|
+
};
|
|
440
|
+
function gateArgEntries(gate) {
|
|
441
|
+
const entries = [];
|
|
442
|
+
let pendingOption = false;
|
|
443
|
+
for (const arg of gate.args ?? []) {
|
|
444
|
+
if (arg.startsWith('-') && arg !== '-') {
|
|
445
|
+
pendingOption = false;
|
|
446
|
+
const equals = arg.indexOf('=');
|
|
447
|
+
if (equals >= 0) {
|
|
448
|
+
entries.push({ value: arg.slice(equals + 1), positional: false, entry: arg });
|
|
449
|
+
}
|
|
450
|
+
else if (!arg.startsWith('--') && arg.length > 2) {
|
|
451
|
+
entries.push({ value: arg.slice(2), positional: false, entry: arg });
|
|
452
|
+
}
|
|
453
|
+
else {
|
|
454
|
+
// A flag the gate's own help says takes no value leaves the next word
|
|
455
|
+
// a positional (NO_VALUE_FLAGS); any other flag claims it.
|
|
456
|
+
pendingOption = !NO_VALUE_FLAGS[gate.product].includes(arg);
|
|
457
|
+
}
|
|
458
|
+
continue;
|
|
459
|
+
}
|
|
460
|
+
if (pendingOption) {
|
|
461
|
+
pendingOption = false;
|
|
462
|
+
entries.push({ value: arg, positional: false, entry: arg });
|
|
463
|
+
continue;
|
|
464
|
+
}
|
|
465
|
+
if (CANDIDATES[gate.product].some((candidate) => candidate.prefix.includes(arg))) {
|
|
466
|
+
continue;
|
|
467
|
+
}
|
|
468
|
+
entries.push({ value: arg, positional: true, entry: arg });
|
|
469
|
+
}
|
|
470
|
+
return entries.filter((each) => each.value !== '');
|
|
471
|
+
}
|
|
472
|
+
/**
|
|
473
|
+
* The args entries vetted as CODE: every entry when the command is not the
|
|
474
|
+
* gate itself, and only the code-extension values (`hasCodeExtension`) when
|
|
475
|
+
* it is. Each goes through `argumentCandidates`, here and in the preview.
|
|
476
|
+
*/
|
|
477
|
+
export function codeArguments(gate) {
|
|
478
|
+
if (!commandIsGateProgram(gate)) {
|
|
479
|
+
return gate.args ?? [];
|
|
480
|
+
}
|
|
481
|
+
return gateArgEntries(gate)
|
|
482
|
+
.filter((each) => hasCodeExtension(each.value))
|
|
483
|
+
.map((each) => each.value);
|
|
484
|
+
}
|
|
485
|
+
/** `argumentCandidates` for every code argument (`codeArguments`), flattened. */
|
|
383
486
|
function argumentPathsOf(gate, repoRoot) {
|
|
384
|
-
|
|
385
|
-
|
|
487
|
+
return codeArguments(gate).flatMap((arg) => argumentCandidates(arg, repoRoot));
|
|
488
|
+
}
|
|
489
|
+
/**
|
|
490
|
+
* The args entries of a gate-named command that are its own DATA, when
|
|
491
|
+
* `command:` is the gate itself (commandIsGateProgram), in args order; empty
|
|
492
|
+
* for every other command (audit 2026-10-28, N1, and its review, B1, N-a,
|
|
493
|
+
* N-b, N-e).
|
|
494
|
+
*
|
|
495
|
+
* Every non-code entry (`gateArgEntries`, less the code-extension ones in
|
|
496
|
+
* `codeArguments`) is listed with its position, resolved against the
|
|
497
|
+
* repository root, WHETHER OR NOT the head's disk has it and whatever kind of
|
|
498
|
+
* thing the disk holds there: a head must not be able to delete a path or
|
|
499
|
+
* change it from a file to a directory to move it out of vetting. What each
|
|
500
|
+
* one is, and so which rule applies, is decided from the base tree by
|
|
501
|
+
* refuseHeadControlledData. No `<entry>.js` sibling is tried: that is how an
|
|
502
|
+
* interpreter resolves a name, and this command is not one.
|
|
503
|
+
*
|
|
504
|
+
* What this trusts is the NAME: a program named like a gate is taken to be
|
|
505
|
+
* that gate, except that a code-extension entry keeps the code rule. A
|
|
506
|
+
* wrapper given a gate's name that hands an extension-less entry to an
|
|
507
|
+
* interpreter is a wrapper, vetted no further than this (README,
|
|
508
|
+
* pull-request trust boundary).
|
|
509
|
+
*/
|
|
510
|
+
export function dataArgumentPaths(gate, repoRoot) {
|
|
511
|
+
if (gate.command === undefined || !commandIsGateProgram(gate)) {
|
|
512
|
+
return [];
|
|
513
|
+
}
|
|
514
|
+
return gateArgEntries(gate)
|
|
515
|
+
.filter((each) => !hasCodeExtension(each.value))
|
|
516
|
+
.map((each) => ({ path: path.resolve(repoRoot, each.value), positional: each.positional, entry: each.entry }));
|
|
386
517
|
}
|
|
387
518
|
/**
|
|
388
519
|
* The version probe for a policy `command:` that is not itself a gate name,
|
|
@@ -418,7 +549,7 @@ function scriptVersionProbe(gate, repoRoot) {
|
|
|
418
549
|
// Only the FIRST non-option entry can be the script. A later file is the
|
|
419
550
|
// script's own argument (`my-build check rules.json`), and a probe that
|
|
420
551
|
// carried the subcommand before it would make the gate do work.
|
|
421
|
-
return argumentCandidates(arg, repoRoot
|
|
552
|
+
return argumentCandidates(arg, repoRoot).length > 0
|
|
422
553
|
? { command: gate.command, argv: [...gate.args.slice(0, index + 1), ...spec.argv] }
|
|
423
554
|
: null;
|
|
424
555
|
}
|
package/dist/trust-base.d.ts
CHANGED
|
@@ -323,7 +323,9 @@ export declare function treeEntryAt(repoRoot: string, ref: string, relativePath:
|
|
|
323
323
|
* Vetting the target is what catches a link whose own path is outside the
|
|
324
324
|
* tree pointing into it; it never decides the in-repo case.
|
|
325
325
|
*/
|
|
326
|
-
export declare function refuseHeadControlledProgram(repoRoot: string, trustBase: string, programPath: string
|
|
326
|
+
export declare function refuseHeadControlledProgram(repoRoot: string, trustBase: string, programPath: string,
|
|
327
|
+
/** True when asked for an interpreter's `args:` entry, which words the root refusal for an argument. */
|
|
328
|
+
fromArgs?: boolean): string | null;
|
|
327
329
|
/**
|
|
328
330
|
* Whether a gate's reported version is at least `minimum`.
|
|
329
331
|
*
|
|
@@ -370,3 +372,46 @@ export declare function atLeastVersion(version: string | null, minimum: string):
|
|
|
370
372
|
* vetted as a link.
|
|
371
373
|
*/
|
|
372
374
|
export declare function refuseHeadControlledArgument(repoRoot: string, trustBase: string, argumentPath: string): string | null;
|
|
375
|
+
/**
|
|
376
|
+
* Why a path a gate's own `args:` name cannot be trusted on a pull-request
|
|
377
|
+
* run, or null (audit 2026-10-28, N1, and its review, B1 and N-a).
|
|
378
|
+
*
|
|
379
|
+
* Asked only when `command:` is the gate itself (dataArgumentPaths in
|
|
380
|
+
* src/resolve.ts), whose args are its own argv: a rules file such as
|
|
381
|
+
* `--config=.gitleaks.toml`, or a rules directory such as dep-guard's
|
|
382
|
+
* `--corpus-dir`, is read as data, not loaded as code. Its contents still
|
|
383
|
+
* decide what the gate reports, so a pull request that rewrote them would
|
|
384
|
+
* choose the rules that judge it; but nothing beside a file runs, so a
|
|
385
|
+
* file's directory is not compared and a file at the repository root is
|
|
386
|
+
* fine.
|
|
387
|
+
*
|
|
388
|
+
* WHAT THE PATH IS COMES FROM THE BASE TREE, never from the head's disk, so a
|
|
389
|
+
* head cannot delete a path or turn a file into a directory to change which
|
|
390
|
+
* rule applies:
|
|
391
|
+
*
|
|
392
|
+
* - Outside the working tree, by its own spelling and by its realpath:
|
|
393
|
+
* accepted, as for a program.
|
|
394
|
+
* - The repository root: accepted as a POSITIONAL entry (`scan .`, the
|
|
395
|
+
* repository the gate is handed anyway, which is the thing being judged
|
|
396
|
+
* and cannot be the base's on any pull request), refused as an OPTION
|
|
397
|
+
* VALUE (`--corpus-dir=.` would make the whole head tree the rules).
|
|
398
|
+
* - A tree at the base: a positional entry is a scan target and is not
|
|
399
|
+
* compared (the head's version of it is what the gate is there to judge).
|
|
400
|
+
* An option value is data: the head must hold a tree with the same tree
|
|
401
|
+
* object id, or it is refused.
|
|
402
|
+
* - A blob at the base: a tracked regular file at both refs with the same
|
|
403
|
+
* blob, whatever its position. An in-tree link is refused on its own entry
|
|
404
|
+
* (a link entry), as everywhere else, because what it points at is the
|
|
405
|
+
* head's choice. A head that deleted it or replaced it is refused.
|
|
406
|
+
* - Absent at the base: accepted only if the head has nothing there either,
|
|
407
|
+
* tracked or on disk (a word that is not a path, `--format=json`);
|
|
408
|
+
* otherwise it is a path this pull request chose, and refused.
|
|
409
|
+
*
|
|
410
|
+
* Only whether something exists on disk at a path the base does not track is
|
|
411
|
+
* read from the working tree; every other answer is a `git ls-tree` listing.
|
|
412
|
+
*/
|
|
413
|
+
export declare function refuseHeadControlledData(repoRoot: string, trustBase: string, data: {
|
|
414
|
+
path: string;
|
|
415
|
+
positional: boolean;
|
|
416
|
+
entry?: string;
|
|
417
|
+
}): string | null;
|