@vaultcompass/conductor 0.14.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 +159 -1123
- package/dist/gate-runner.d.ts +20 -0
- package/dist/gate-runner.js +64 -2
- package/dist/output-sarif.js +2 -2
- package/dist/output-text.js +24 -8
- package/dist/policy-diff.d.ts +9 -0
- package/dist/policy-diff.js +12 -4
- package/dist/resolve.d.ts +131 -0
- package/dist/resolve.js +287 -2
- package/dist/trust-base.d.ts +80 -1
- package/dist/trust-base.js +258 -5
- package/package.json +1 -1
package/dist/resolve.js
CHANGED
|
@@ -59,7 +59,7 @@
|
|
|
59
59
|
// depend on a package cache the report cannot describe, and a gate that
|
|
60
60
|
// "ran" from an unknown version is worse than one that is honestly
|
|
61
61
|
// reported missing.
|
|
62
|
-
import { accessSync, constants, statSync } from 'node:fs';
|
|
62
|
+
import { accessSync, constants, lstatSync, statSync } from 'node:fs';
|
|
63
63
|
import path from 'node:path';
|
|
64
64
|
import { profileFor } from './products.js';
|
|
65
65
|
export const CANDIDATES = {
|
|
@@ -220,6 +220,8 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
220
220
|
const prefix = gate.args ?? inferred?.prefix ?? table[0].prefix;
|
|
221
221
|
const candidateName = inferred?.name ?? baseName(gate.command);
|
|
222
222
|
const candidate = inferred ?? table[0];
|
|
223
|
+
const argumentPaths = argumentPathsOf(gate, repoRoot);
|
|
224
|
+
const dataArguments = dataArgumentPaths(gate, repoRoot);
|
|
223
225
|
// A build directory holds plain .js files with a shebang but no
|
|
224
226
|
// executable bit surprisingly often (a fresh tsc output, a file copied
|
|
225
227
|
// out of a tarball). Running it through this same Node is exactly what
|
|
@@ -231,6 +233,8 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
231
233
|
// Node is the command; the script is what actually decides anything.
|
|
232
234
|
program: gate.command,
|
|
233
235
|
argvPrefix: [gate.command, ...prefix],
|
|
236
|
+
argumentPaths,
|
|
237
|
+
dataArguments,
|
|
234
238
|
source: 'policy',
|
|
235
239
|
candidate: candidateName,
|
|
236
240
|
versionProbe: candidate.versionSafe && profileFor(gate.product).versionProbe !== null
|
|
@@ -241,13 +245,21 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
241
245
|
: versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
|
|
242
246
|
};
|
|
243
247
|
}
|
|
248
|
+
// A command that is not itself a gate name (an interpreter, typically)
|
|
249
|
+
// and whose args hand it a script is asked through the script, or the
|
|
250
|
+
// version reported is the interpreter's (audit 2026-10-27, N4). A
|
|
251
|
+
// version-unsafe candidate keeps its sibling lookup: rule 2 above.
|
|
252
|
+
const viaScript = inferred === undefined && candidate.versionSafe ? scriptVersionProbe(gate, repoRoot) : null;
|
|
244
253
|
return {
|
|
245
254
|
command: gate.command,
|
|
246
255
|
program: gate.command,
|
|
247
256
|
argvPrefix: prefix,
|
|
257
|
+
argumentPaths,
|
|
258
|
+
dataArguments,
|
|
248
259
|
source: 'policy',
|
|
249
260
|
candidate: candidateName,
|
|
250
|
-
versionProbe:
|
|
261
|
+
versionProbe: viaScript ??
|
|
262
|
+
versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
|
|
251
263
|
};
|
|
252
264
|
}
|
|
253
265
|
for (const candidate of table) {
|
|
@@ -259,6 +271,8 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
259
271
|
command: found.command,
|
|
260
272
|
program: found.command,
|
|
261
273
|
argvPrefix: [...candidate.prefix],
|
|
274
|
+
argumentPaths: [],
|
|
275
|
+
dataArguments: [],
|
|
262
276
|
source: found.source,
|
|
263
277
|
candidate: candidate.name,
|
|
264
278
|
versionProbe: versionProbeFor(gate.product, candidate, found.command, repoRoot, pathValue, skipNodeModules),
|
|
@@ -270,3 +284,274 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
270
284
|
export function candidateNames(product) {
|
|
271
285
|
return CANDIDATES[product].map((candidate) => candidate.name);
|
|
272
286
|
}
|
|
287
|
+
/**
|
|
288
|
+
* The extensions an interpreter can add to an entry before it looks at the
|
|
289
|
+
* entry as written: Node's main-entry resolution tries `.js`, `.json` and
|
|
290
|
+
* `.node` BEFORE a directory of the same name (`node tools/gate` runs
|
|
291
|
+
* `tools/gate.js` over `tools/gate/index.js`, measured on Node 22), and the
|
|
292
|
+
* ES module forms are listed too, so a sibling a loader might take is vetted
|
|
293
|
+
* whether or not this Node takes it (audit 2026-10-27 fix round, MB1 and
|
|
294
|
+
* MB2).
|
|
295
|
+
*/
|
|
296
|
+
const LOADABLE_EXTENSIONS = ['.js', '.mjs', '.cjs', '.json', '.node'];
|
|
297
|
+
function existsAtAll(candidate) {
|
|
298
|
+
try {
|
|
299
|
+
lstatSync(candidate);
|
|
300
|
+
return true;
|
|
301
|
+
}
|
|
302
|
+
catch {
|
|
303
|
+
return false;
|
|
304
|
+
}
|
|
305
|
+
}
|
|
306
|
+
/**
|
|
307
|
+
* Whether the policy's `command:` is itself the gate program, so its `args:`
|
|
308
|
+
* are that gate's own argv rather than something an interpreter will load.
|
|
309
|
+
*
|
|
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).
|
|
326
|
+
*/
|
|
327
|
+
export function commandIsGateProgram(gate) {
|
|
328
|
+
if (gate.command === undefined) {
|
|
329
|
+
return true;
|
|
330
|
+
}
|
|
331
|
+
const name = baseName(gate.command);
|
|
332
|
+
return CANDIDATES[gate.product].some((candidate) => candidate.name === name);
|
|
333
|
+
}
|
|
334
|
+
/**
|
|
335
|
+
* Every path an interpreter could load for one `args:` entry, as absolute
|
|
336
|
+
* paths, in the order checked; empty when the entry names nothing on disk
|
|
337
|
+
* (audit 2026-10-27, B1, and its fix round).
|
|
338
|
+
*
|
|
339
|
+
* Relative entries are resolved against `repoRoot`. That is the working
|
|
340
|
+
* directory of the version probe and of the gate's own spawn for every
|
|
341
|
+
* product except one whose base config can name further files
|
|
342
|
+
* (`followsConfigExtend`): on a pull request that gate runs from a temporary
|
|
343
|
+
* directory holding the base ref's copies (src/gate-runner.ts, spawnCwd), so
|
|
344
|
+
* a relative script there resolves against base copies or not at all, never
|
|
345
|
+
* against the head tree. The rules, in order:
|
|
346
|
+
*
|
|
347
|
+
* - An option with no `=` (`--json`, `-r`) names nothing. An option with one
|
|
348
|
+
* (`--config=tools/cfg.json`, `--import=./hook.mjs`) is read for the value
|
|
349
|
+
* after the first `=`, since that is where an interpreter takes a file to
|
|
350
|
+
* load and a gate takes a file to read its rules from.
|
|
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).
|
|
356
|
+
* - The entry as written, when it exists as a file, a directory or a
|
|
357
|
+
* symlink, without following the symlink, so the caller can refuse an
|
|
358
|
+
* in-tree link on its own entry.
|
|
359
|
+
* - Then every `<entry>.js`, `.mjs`, `.cjs`, `.json` and `.node` that exists,
|
|
360
|
+
* slash or not, and whether or not the entry itself exists: Node tries
|
|
361
|
+
* those before a directory of the same name, and a bare `run` runs
|
|
362
|
+
* `run.js`. A sibling the head ADDED is listed too, which is what refuses
|
|
363
|
+
* it: the base does not track it.
|
|
364
|
+
*
|
|
365
|
+
* A directory's contents are covered by the caller's tree comparison, so
|
|
366
|
+
* `index.js` and `package.json` inside it are not listed separately; a
|
|
367
|
+
* `main` that points outside the directory is not vetted, the same limit as
|
|
368
|
+
* a program's directory. Everything else, a Python `-m` module name, a bare
|
|
369
|
+
* package specifier an interpreter resolves for itself, code passed as a
|
|
370
|
+
* string (`node -e`, `bash -c`), is not recognised as a path. The README says
|
|
371
|
+
* so.
|
|
372
|
+
*/
|
|
373
|
+
export function argumentCandidates(arg, repoRoot) {
|
|
374
|
+
let value = arg;
|
|
375
|
+
if (arg.startsWith('-')) {
|
|
376
|
+
const equals = arg.indexOf('=');
|
|
377
|
+
if (equals < 0) {
|
|
378
|
+
return [];
|
|
379
|
+
}
|
|
380
|
+
value = arg.slice(equals + 1);
|
|
381
|
+
}
|
|
382
|
+
if (value === '') {
|
|
383
|
+
return [];
|
|
384
|
+
}
|
|
385
|
+
const absolute = path.resolve(repoRoot, value);
|
|
386
|
+
return [absolute, ...LOADABLE_EXTENSIONS.map((extension) => absolute + extension)].filter(existsAtAll);
|
|
387
|
+
}
|
|
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. */
|
|
486
|
+
function argumentPathsOf(gate, repoRoot) {
|
|
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 }));
|
|
517
|
+
}
|
|
518
|
+
/**
|
|
519
|
+
* The version probe for a policy `command:` that is not itself a gate name,
|
|
520
|
+
* when its `args:` hand it a script: the args up to and including the first
|
|
521
|
+
* non-option entry, when that entry names something the interpreter can load
|
|
522
|
+
* (argumentCandidates: a file, a directory, or a bare or extension-less name
|
|
523
|
+
* with a loadable sibling), then the product's own probe argv. The entry is
|
|
524
|
+
* passed as written, so the interpreter resolves it exactly as it will for
|
|
525
|
+
* the scan. So `node tools/gate/run.mjs scan` is asked `node
|
|
526
|
+
* tools/gate/run.mjs --version`, `node tools/gate` is asked `node tools/gate
|
|
527
|
+
* --version`, and the version reported is the script's, not Node's (audit
|
|
528
|
+
* 2026-10-27, N4). Null when the first non-option entry names nothing, or
|
|
529
|
+
* there is none, and the caller keeps the probe it would have made anyway.
|
|
530
|
+
*
|
|
531
|
+
* Only the first: everything after the script is the script's own argv, and
|
|
532
|
+
* carrying a subcommand or a target into a probe would make it do work,
|
|
533
|
+
* which is the one thing a probe must not do.
|
|
534
|
+
* An interpreter flag that takes a file as a separate entry (`-r
|
|
535
|
+
* ./setup.js`) makes that file the first, so the probe asks the interpreter
|
|
536
|
+
* and reports its version, as it did before; under an expected-version pin
|
|
537
|
+
* that is could-not-run, the fail-closed direction.
|
|
538
|
+
*/
|
|
539
|
+
function scriptVersionProbe(gate, repoRoot) {
|
|
540
|
+
const spec = profileFor(gate.product).versionProbe;
|
|
541
|
+
if (spec === null || gate.command === undefined || gate.args === undefined) {
|
|
542
|
+
return null;
|
|
543
|
+
}
|
|
544
|
+
for (let index = 0; index < gate.args.length; index += 1) {
|
|
545
|
+
const arg = gate.args[index];
|
|
546
|
+
if (arg.startsWith('-')) {
|
|
547
|
+
continue;
|
|
548
|
+
}
|
|
549
|
+
// Only the FIRST non-option entry can be the script. A later file is the
|
|
550
|
+
// script's own argument (`my-build check rules.json`), and a probe that
|
|
551
|
+
// carried the subcommand before it would make the gate do work.
|
|
552
|
+
return argumentCandidates(arg, repoRoot).length > 0
|
|
553
|
+
? { command: gate.command, argv: [...gate.args.slice(0, index + 1), ...spec.argv] }
|
|
554
|
+
: null;
|
|
555
|
+
}
|
|
556
|
+
return null;
|
|
557
|
+
}
|
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
|
*
|
|
@@ -336,3 +338,80 @@ export declare function refuseHeadControlledProgram(repoRoot: string, trustBase:
|
|
|
336
338
|
* for every repository pinning an older gate.
|
|
337
339
|
*/
|
|
338
340
|
export declare function atLeastVersion(version: string | null, minimum: string): boolean;
|
|
341
|
+
/**
|
|
342
|
+
* Why a path named in a gate's `args:` cannot be trusted on a pull-request
|
|
343
|
+
* run, or null (audit 2026-10-27, B1).
|
|
344
|
+
*
|
|
345
|
+
* An interpreter `command:` takes the program as an argument: with
|
|
346
|
+
* `command: /usr/bin/node` and `args: [tools/gate/run.mjs, scan]` the script
|
|
347
|
+
* judges and Node only runs it, so vetting `command:` alone let a pull request
|
|
348
|
+
* rewrite the script and choose its own judge. `argumentCandidates`
|
|
349
|
+
* (src/resolve.ts) lists every path an interpreter could load for an entry,
|
|
350
|
+
* the entry and each of its loadable siblings (`tools/gate.js` beside
|
|
351
|
+
* `tools/gate/`), and each one is asked here separately; this decides
|
|
352
|
+
* whether that one path is the base's.
|
|
353
|
+
*
|
|
354
|
+
* - A FILE, or a symlink of any kind, goes through refuseHeadControlledProgram
|
|
355
|
+
* unchanged: blob and containing directory identical at both refs, an
|
|
356
|
+
* in-tree link refused on its own entry, the root refused, anything outside
|
|
357
|
+
* the tree accepted. The same rule as a `command:`, because it is the same
|
|
358
|
+
* question.
|
|
359
|
+
* - A DIRECTORY inside the tree is accepted only when it is a tracked tree
|
|
360
|
+
* at both refs with the same tree object id: when no sibling file wins,
|
|
361
|
+
* an interpreter handed a directory (`node tools/gate`) runs what is
|
|
362
|
+
* inside it, so the whole subtree is the unit, as it is beside a program.
|
|
363
|
+
* A sibling file that would win is a separate candidate, vetted as a file.
|
|
364
|
+
* - THE REPOSITORY ROOT ITSELF is refused (`node .` runs the head's own
|
|
365
|
+
* package.json main). Approving it would mean comparing the whole tree,
|
|
366
|
+
* which differs on every pull request; conductor already hands every gate
|
|
367
|
+
* the repository it scans, so no gate needs the root in `args:`.
|
|
368
|
+
*
|
|
369
|
+
* NOTHING HERE READS THE WORKING TREE's CONTENTS, as for the program: both
|
|
370
|
+
* sides are `git ls-tree` listings. Only whether the entry is a directory is
|
|
371
|
+
* read from disk, and a link is never followed for that, so a link is always
|
|
372
|
+
* vetted as a link.
|
|
373
|
+
*/
|
|
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;
|