@vaultcompass/conductor 0.16.0 → 0.18.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 +60 -47
- package/dist/cli.js +5 -5
- package/dist/gate-runner.d.ts +1 -0
- package/dist/gate-runner.js +14 -7
- package/dist/intent-prepare.js +3 -6
- package/dist/normalize.js +42 -2
- package/dist/output-sarif.js +69 -3
- package/dist/output-text.d.ts +35 -2
- package/dist/output-text.js +98 -12
- package/dist/policy.d.ts +21 -1
- package/dist/policy.js +58 -2
- package/dist/resolve.d.ts +23 -4
- package/dist/resolve.js +64 -43
- package/dist/run.d.ts +11 -1
- package/dist/trust-base.d.ts +59 -10
- package/dist/trust-base.js +296 -33
- package/dist/unread-manifests.d.ts +1 -1
- package/dist/unread-manifests.js +25 -3
- package/package.json +1 -1
package/dist/trust-base.d.ts
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The private, fully spelled ref the composite action fetches the base branch
|
|
3
|
-
* into
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
3
|
+
* into, or moves to the merge ref's first parent on issue 159's one shape
|
|
4
|
+
* (action.yml, fetch-base step). Nothing else writes it and no short name can
|
|
5
|
+
* shadow it: git resolves origin/main through refs/tags/ BEFORE refs/remotes/,
|
|
6
|
+
* so a tag pushed by anyone able to push tags would choose the rules' commit.
|
|
7
7
|
*/
|
|
8
8
|
export declare const PRIVATE_TRUST_BASE_REF = "refs/conductor/trust-base";
|
|
9
9
|
/** What a fully spelled ref names: nothing, an object, or an answer git could not give. */
|
|
@@ -120,8 +120,8 @@ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): strin
|
|
|
120
120
|
* else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
|
|
121
121
|
* a platform that never sets it. When it is set, the given ref is accepted
|
|
122
122
|
* only when it is the FULL COMMIT ID the composite action's "Fetch the trust
|
|
123
|
-
* base" step published (
|
|
124
|
-
* authority, or refs/remotes/origin/<githubBaseRef>, both
|
|
123
|
+
* base" step published, the tip or on one shape its first parent (it must equal
|
|
124
|
+
* refs/conductor/trust-base, the authority, or refs/remotes/origin/<githubBaseRef>, both via show-ref),
|
|
125
125
|
* or is that private ref itself, or -- for an explicit trust base -- resolves
|
|
126
126
|
* to the same commit as refs/remotes/origin/<githubBaseRef>. So an ordinary
|
|
127
127
|
* pull-request run through the action returns null here, before
|
|
@@ -253,6 +253,12 @@ export type TreeEntry = {
|
|
|
253
253
|
* decided outside the tree, so it is an error, never absent.
|
|
254
254
|
*/
|
|
255
255
|
export declare function treeEntryAt(repoRoot: string, ref: string, relativePath: string): TreeEntry;
|
|
256
|
+
/**
|
|
257
|
+
* Whether `candidate`, as written, names the working tree or something in it
|
|
258
|
+
* (writtenRelative). For the preview's outright refusals, so a base path
|
|
259
|
+
* written inside the tree is refused there even when a link on it points out.
|
|
260
|
+
*/
|
|
261
|
+
export declare function writtenInsideWorkingTree(repoRoot: string, candidate: string): boolean;
|
|
256
262
|
/**
|
|
257
263
|
* Why this gate's PROGRAM cannot be trusted on a pull-request run, or null.
|
|
258
264
|
*
|
|
@@ -322,10 +328,23 @@ export declare function treeEntryAt(repoRoot: string, ref: string, relativePath:
|
|
|
322
328
|
* or its tree entry is a link rather than a regular file, and either refuses.
|
|
323
329
|
* Vetting the target is what catches a link whose own path is outside the
|
|
324
330
|
* tree pointing into it; it never decides the in-repo case.
|
|
331
|
+
*
|
|
332
|
+
* AND THE PATH AS WRITTEN, for this rule and for both args rules below
|
|
333
|
+
* (audit 2026-11-01, MB2). Both spellings above resolve the directories on
|
|
334
|
+
* the path through the head's disk, so a head that replaced `tools/` with a
|
|
335
|
+
* link to a base-tracked `stub/` had `tools/vault-guard` judged as
|
|
336
|
+
* `stub/vault-guard`, which the base approved. So the path is also judged
|
|
337
|
+
* exactly as written inside the tree (writtenRelative): refused when HEAD's
|
|
338
|
+
* tree holds any directory on it as a link (linkOnWrittenPathAtHead), and
|
|
339
|
+
* the written path is one more candidate, judged by its own entries at both
|
|
340
|
+
* refs like the others. A link the base already had there is refused too:
|
|
341
|
+
* what the gate is handed through it is still decided by the head tree.
|
|
325
342
|
*/
|
|
326
343
|
export declare function refuseHeadControlledProgram(repoRoot: string, trustBase: string, programPath: string,
|
|
327
344
|
/** True when asked for an interpreter's `args:` entry, which words the root refusal for an argument. */
|
|
328
|
-
fromArgs?: boolean
|
|
345
|
+
fromArgs?: boolean,
|
|
346
|
+
/** Which policy list an argument came from, for its refusals: `args:`, or `options:` for a code-extension option value. */
|
|
347
|
+
list?: string): string | null;
|
|
329
348
|
/**
|
|
330
349
|
* Whether a gate's reported version is at least `minimum`.
|
|
331
350
|
*
|
|
@@ -371,13 +390,16 @@ export declare function atLeastVersion(version: string | null, minimum: string):
|
|
|
371
390
|
* read from disk, and a link is never followed for that, so a link is always
|
|
372
391
|
* vetted as a link.
|
|
373
392
|
*/
|
|
374
|
-
export declare function refuseHeadControlledArgument(repoRoot: string, trustBase: string, argumentPath: string
|
|
393
|
+
export declare function refuseHeadControlledArgument(repoRoot: string, trustBase: string, argumentPath: string,
|
|
394
|
+
/** Which policy list the path came from, for the refusals: `args:`, or `options:` for a code-extension option value. */
|
|
395
|
+
list?: string): string | null;
|
|
375
396
|
/**
|
|
376
397
|
* Why a path a gate's own `args:` name cannot be trusted on a pull-request
|
|
377
398
|
* run, or null (audit 2026-10-28, N1, and its review, B1 and N-a).
|
|
378
399
|
*
|
|
379
|
-
* Asked
|
|
380
|
-
* src/resolve.ts),
|
|
400
|
+
* Asked for the args of a `command:` that is the gate itself, and for the
|
|
401
|
+
* `options:` values of every gate (dataArgumentPaths in src/resolve.ts),
|
|
402
|
+
* since both are the gate's own argv: a rules file such as
|
|
381
403
|
* `--config=.gitleaks.toml`, or a rules directory such as dep-guard's
|
|
382
404
|
* `--corpus-dir`, is read as data, not loaded as code. Its contents still
|
|
383
405
|
* decide what the gate reports, so a pull request that rewrote them would
|
|
@@ -406,6 +428,14 @@ export declare function refuseHeadControlledArgument(repoRoot: string, trustBase
|
|
|
406
428
|
* - Absent at the base: accepted only if the head has nothing there either,
|
|
407
429
|
* tracked or on disk (a word that is not a path, `--format=json`);
|
|
408
430
|
* otherwise it is a path this pull request chose, and refused.
|
|
431
|
+
* - AS WRITTEN as well as resolved (audit 2026-11-01, MB2): a directory on
|
|
432
|
+
* the written path that HEAD's tree holds as a link is refused, the
|
|
433
|
+
* written path is judged by the rules above like the resolved ones, and a
|
|
434
|
+
* positional scan target the base tracks as a directory is refused when
|
|
435
|
+
* HEAD holds it as a link, since that one is otherwise not compared.
|
|
436
|
+
* - The same for an `options:` value (audit 2026-11-01, MB1): it is
|
|
437
|
+
* rendered into the gate's argv and read the same way (dataArgumentPaths),
|
|
438
|
+
* and `from: 'options'` only changes which list the refusal names.
|
|
409
439
|
*
|
|
410
440
|
* Only whether something exists on disk at a path the base does not track is
|
|
411
441
|
* read from the working tree; every other answer is a `git ls-tree` listing.
|
|
@@ -414,4 +444,23 @@ export declare function refuseHeadControlledData(repoRoot: string, trustBase: st
|
|
|
414
444
|
path: string;
|
|
415
445
|
positional: boolean;
|
|
416
446
|
entry?: string;
|
|
447
|
+
from?: 'options';
|
|
417
448
|
}): string | null;
|
|
449
|
+
/**
|
|
450
|
+
* The trust base with the base branch's tip to name in the report, when the
|
|
451
|
+
* Action moved the trust base past it. FOR DISPLAY ONLY: nothing that decides
|
|
452
|
+
* anything reads `baseTip`. The value comes from the environment, so it is
|
|
453
|
+
* honored only when the repository bears it out: a full id of a commit that is
|
|
454
|
+
* neither HEAD nor the trust base, with HEAD's tree, and the trust base is HEAD's
|
|
455
|
+
* first parent. Anything else is ignored without a word: the sentence is the only
|
|
456
|
+
* thing it could change, and leaving it out is true.
|
|
457
|
+
*
|
|
458
|
+
* The CLI cannot work this out alone. It sees the private ref at HEAD's first
|
|
459
|
+
* parent, which is also what every ordinary pull-request run looks like, and it
|
|
460
|
+
* never sees the tip the Action moved away from. It can only check what it is told.
|
|
461
|
+
*/
|
|
462
|
+
export declare function withMovedBaseTip<T extends {
|
|
463
|
+
ref: string;
|
|
464
|
+
}>(repoRoot: string, trustBase: T, value: string | undefined): T & {
|
|
465
|
+
baseTip?: string;
|
|
466
|
+
};
|
package/dist/trust-base.js
CHANGED
|
@@ -77,10 +77,10 @@ import { parse as parseYaml } from 'yaml';
|
|
|
77
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
|
-
* into
|
|
81
|
-
*
|
|
82
|
-
*
|
|
83
|
-
*
|
|
80
|
+
* into, or moves to the merge ref's first parent on issue 159's one shape
|
|
81
|
+
* (action.yml, fetch-base step). Nothing else writes it and no short name can
|
|
82
|
+
* shadow it: git resolves origin/main through refs/tags/ BEFORE refs/remotes/,
|
|
83
|
+
* so a tag pushed by anyone able to push tags would choose the rules' commit.
|
|
84
84
|
*/
|
|
85
85
|
export const PRIVATE_TRUST_BASE_REF = 'refs/conductor/trust-base';
|
|
86
86
|
/**
|
|
@@ -332,9 +332,9 @@ export function refuseTrustBaseRef(repoRoot, ref) {
|
|
|
332
332
|
`identical tree (${headTree}), so the policy would come from the tree being judged and ` +
|
|
333
333
|
'there would be nothing for pull-request mode to compare. Likely cause: the base already ' +
|
|
334
334
|
'carries this tree, which usually means the pull request was merged while this job was ' +
|
|
335
|
-
'queued
|
|
336
|
-
|
|
337
|
-
'
|
|
335
|
+
'queued. ' +
|
|
336
|
+
`${EQUAL_TREE_ADVICE} ` +
|
|
337
|
+
'Nothing was checked.');
|
|
338
338
|
}
|
|
339
339
|
return null;
|
|
340
340
|
}
|
|
@@ -360,8 +360,8 @@ export function refuseTrustBaseRef(repoRoot, ref) {
|
|
|
360
360
|
* else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
|
|
361
361
|
* a platform that never sets it. When it is set, the given ref is accepted
|
|
362
362
|
* only when it is the FULL COMMIT ID the composite action's "Fetch the trust
|
|
363
|
-
* base" step published (
|
|
364
|
-
* authority, or refs/remotes/origin/<githubBaseRef>, both
|
|
363
|
+
* base" step published, the tip or on one shape its first parent (it must equal
|
|
364
|
+
* refs/conductor/trust-base, the authority, or refs/remotes/origin/<githubBaseRef>, both via show-ref),
|
|
365
365
|
* or is that private ref itself, or -- for an explicit trust base -- resolves
|
|
366
366
|
* to the same commit as refs/remotes/origin/<githubBaseRef>. So an ordinary
|
|
367
367
|
* pull-request run through the action returns null here, before
|
|
@@ -708,6 +708,132 @@ function withResolvedParent(candidate) {
|
|
|
708
708
|
const parent = path.dirname(candidate);
|
|
709
709
|
return path.join(realOrNull(parent) ?? parent, path.basename(candidate));
|
|
710
710
|
}
|
|
711
|
+
/**
|
|
712
|
+
* A vetted path AS WRITTEN, relative to the repository root with `/`
|
|
713
|
+
* separators: '' for the root itself, null when the path is not in the
|
|
714
|
+
* working tree (audit 2026-11-01, MB2).
|
|
715
|
+
*
|
|
716
|
+
* The resolved spellings above follow every link on the path, and a link
|
|
717
|
+
* inside the tree is the head's to choose: a head that replaces `data/` with
|
|
718
|
+
* a link to a base-approved `alt/` makes `data/corpus` resolve to
|
|
719
|
+
* `alt/corpus`, whose tree is the base's, while the policy named
|
|
720
|
+
* `data/corpus`. So the components INSIDE the tree are kept exactly as
|
|
721
|
+
* written. Only the leading components that reach the tree are resolved: the
|
|
722
|
+
* shortest prefix whose real path is the root or under it, which is how a
|
|
723
|
+
* root spelled through a symlinked mount (a macOS temporary directory) or an
|
|
724
|
+
* outside link into the tree still lands inside. Components above the tree
|
|
725
|
+
* are the machine's, which a pull request cannot write.
|
|
726
|
+
*/
|
|
727
|
+
function writtenRelative(repoReal, candidate) {
|
|
728
|
+
const absolute = path.resolve(candidate);
|
|
729
|
+
const root = path.parse(absolute).root;
|
|
730
|
+
const segments = absolute.slice(root.length).split(path.sep).filter((segment) => segment !== '');
|
|
731
|
+
for (let depth = 0; depth <= segments.length; depth += 1) {
|
|
732
|
+
const real = realOrNull(path.join(root, ...segments.slice(0, depth)));
|
|
733
|
+
if (real === null) {
|
|
734
|
+
// Nothing below a missing component exists either.
|
|
735
|
+
return null;
|
|
736
|
+
}
|
|
737
|
+
if (real === repoReal || insideWorkingTree(repoReal, real)) {
|
|
738
|
+
const reached = path.relative(repoReal, real).split(path.sep).filter((segment) => segment !== '');
|
|
739
|
+
return [...reached, ...segments.slice(depth)].join('/');
|
|
740
|
+
}
|
|
741
|
+
}
|
|
742
|
+
return null;
|
|
743
|
+
}
|
|
744
|
+
/**
|
|
745
|
+
* Whether `candidate`, as written, names the working tree or something in it
|
|
746
|
+
* (writtenRelative). For the preview's outright refusals, so a base path
|
|
747
|
+
* written inside the tree is refused there even when a link on it points out.
|
|
748
|
+
*/
|
|
749
|
+
export function writtenInsideWorkingTree(repoRoot, candidate) {
|
|
750
|
+
const repoReal = realOrNull(repoRoot);
|
|
751
|
+
return repoReal !== null && writtenRelative(repoReal, candidate) !== null;
|
|
752
|
+
}
|
|
753
|
+
/**
|
|
754
|
+
* The first DIRECTORY component above the last one of `relative` that HEAD's
|
|
755
|
+
* tree holds as a symbolic link, or null (audit 2026-11-01, MB2). Read from
|
|
756
|
+
* `git ls-tree`, one component at a time, never from the disk. Stops,
|
|
757
|
+
* answering null, at a component HEAD does not have, cannot list, or holds as
|
|
758
|
+
* a file: what is below it is then absent or unreadable, which the rule
|
|
759
|
+
* asking decides. The last component is each rule's own entry, which every
|
|
760
|
+
* rule already refuses as a link in its own words (a positional scan target
|
|
761
|
+
* included, in refuseHeadControlledData).
|
|
762
|
+
*/
|
|
763
|
+
function linkOnWrittenPathAtHead(repoRoot, relative) {
|
|
764
|
+
const segments = relative.split('/').filter((segment) => segment !== '' && segment !== '.');
|
|
765
|
+
for (let depth = 1; depth < segments.length; depth += 1) {
|
|
766
|
+
const prefix = segments.slice(0, depth).join('/');
|
|
767
|
+
const listed = listOne(repoRoot, 'HEAD', prefix);
|
|
768
|
+
if (listed.kind !== 'entry') {
|
|
769
|
+
return null;
|
|
770
|
+
}
|
|
771
|
+
if (listed.mode === '120000') {
|
|
772
|
+
return prefix;
|
|
773
|
+
}
|
|
774
|
+
if (listed.type !== 'tree') {
|
|
775
|
+
return null;
|
|
776
|
+
}
|
|
777
|
+
}
|
|
778
|
+
return null;
|
|
779
|
+
}
|
|
780
|
+
/**
|
|
781
|
+
* The refusal for a vetted path a link at HEAD redirects, naming the link.
|
|
782
|
+
* `subject` is how the rule asking names the path: "the gate program at X",
|
|
783
|
+
* "in the gate's args:, the path X", "the path X named in the gate's args:".
|
|
784
|
+
*/
|
|
785
|
+
function linkOnWrittenPathRefusal(subject, link, baseName) {
|
|
786
|
+
return (`${subject} goes through ${link}, which is a symbolic link at the head commit, so this pull ` +
|
|
787
|
+
'request changed the path it is judged by: the gate would be handed whatever that link points ' +
|
|
788
|
+
`at, not the path ${baseName} approved. conductor judges every path as written and follows no ` +
|
|
789
|
+
'link inside the repository. Name the directory the link points at, or commit a real directory ' +
|
|
790
|
+
'there on the base branch. Nothing was checked by this gate.');
|
|
791
|
+
}
|
|
792
|
+
/**
|
|
793
|
+
* The first component of `relative`, the last one included, that is a
|
|
794
|
+
* symbolic link ON DISK while HEAD's tree holds no link at that exact
|
|
795
|
+
* spelling, or null (review of the 2026-11-01 fix, item 1).
|
|
796
|
+
*
|
|
797
|
+
* `git ls-tree` matches names exactly, and a case-insensitive disk does not:
|
|
798
|
+
* a head that adds a link entry `data` beside the base's tree `Data` leaves
|
|
799
|
+
* only `data -> alt` on disk after a checkout, so `Data/corpus` reads the
|
|
800
|
+
* link's target while the tree still says `Data` is the base's directory.
|
|
801
|
+
* The disk is therefore asked too, and a link there that the tree does not
|
|
802
|
+
* declare at that spelling refuses: what the gate is handed is decided by
|
|
803
|
+
* something other than the tree conductor judged. A link the tree DOES
|
|
804
|
+
* declare is left to the checks that already refuse it. Stops at the first
|
|
805
|
+
* component that is missing or not a directory. Each rule asks this LAST, so
|
|
806
|
+
* a path its own checks refuse keeps its wording; the exception is the data
|
|
807
|
+
* rule's positional root, which returns early and asks this first (R1).
|
|
808
|
+
*/
|
|
809
|
+
function undeclaredLinkOnDisk(repoRoot, repoReal, relative) {
|
|
810
|
+
const segments = relative.split('/').filter((segment) => segment !== '' && segment !== '.');
|
|
811
|
+
for (let depth = 1; depth <= segments.length; depth += 1) {
|
|
812
|
+
const prefix = segments.slice(0, depth).join('/');
|
|
813
|
+
let stats;
|
|
814
|
+
try {
|
|
815
|
+
stats = lstatSync(path.join(repoReal, prefix));
|
|
816
|
+
}
|
|
817
|
+
catch {
|
|
818
|
+
return null;
|
|
819
|
+
}
|
|
820
|
+
if (stats.isSymbolicLink()) {
|
|
821
|
+
const listed = listOne(repoRoot, 'HEAD', prefix);
|
|
822
|
+
return listed.kind === 'entry' && listed.mode === '120000' ? null : prefix;
|
|
823
|
+
}
|
|
824
|
+
if (!stats.isDirectory()) {
|
|
825
|
+
return null;
|
|
826
|
+
}
|
|
827
|
+
}
|
|
828
|
+
return null;
|
|
829
|
+
}
|
|
830
|
+
/** The refusal for a link on disk the head tree does not declare, naming it. */
|
|
831
|
+
function undeclaredLinkRefusal(subject, link) {
|
|
832
|
+
return (`${subject} goes through ${link}, which is a symbolic link on disk that the pull request's tree does not declare ` +
|
|
833
|
+
'there, so what the gate would be handed is decided by something other than the tree conductor ' +
|
|
834
|
+
'judged. On a case-insensitive filesystem a tree entry spelled with different case is the same ' +
|
|
835
|
+
'path. Nothing was checked by this gate.');
|
|
836
|
+
}
|
|
711
837
|
/**
|
|
712
838
|
* The tree object id of one directory at a ref, or null.
|
|
713
839
|
*
|
|
@@ -792,16 +918,44 @@ function treeShaAt(repoRoot, ref, relativeDir) {
|
|
|
792
918
|
* or its tree entry is a link rather than a regular file, and either refuses.
|
|
793
919
|
* Vetting the target is what catches a link whose own path is outside the
|
|
794
920
|
* tree pointing into it; it never decides the in-repo case.
|
|
921
|
+
*
|
|
922
|
+
* AND THE PATH AS WRITTEN, for this rule and for both args rules below
|
|
923
|
+
* (audit 2026-11-01, MB2). Both spellings above resolve the directories on
|
|
924
|
+
* the path through the head's disk, so a head that replaced `tools/` with a
|
|
925
|
+
* link to a base-tracked `stub/` had `tools/vault-guard` judged as
|
|
926
|
+
* `stub/vault-guard`, which the base approved. So the path is also judged
|
|
927
|
+
* exactly as written inside the tree (writtenRelative): refused when HEAD's
|
|
928
|
+
* tree holds any directory on it as a link (linkOnWrittenPathAtHead), and
|
|
929
|
+
* the written path is one more candidate, judged by its own entries at both
|
|
930
|
+
* refs like the others. A link the base already had there is refused too:
|
|
931
|
+
* what the gate is handed through it is still decided by the head tree.
|
|
795
932
|
*/
|
|
796
933
|
export function refuseHeadControlledProgram(repoRoot, trustBase, programPath,
|
|
797
934
|
/** True when asked for an interpreter's `args:` entry, which words the root refusal for an argument. */
|
|
798
|
-
fromArgs = false
|
|
935
|
+
fromArgs = false,
|
|
936
|
+
/** Which policy list an argument came from, for its refusals: `args:`, or `options:` for a code-extension option value. */
|
|
937
|
+
list = "the gate's args:") {
|
|
799
938
|
const repoReal = realOrNull(repoRoot);
|
|
800
939
|
if (repoReal === null) {
|
|
801
940
|
return `the repository root ${repoRoot} could not be resolved, so the gate program could not be checked against "${trustBase}". Nothing was checked by this gate.`;
|
|
802
941
|
}
|
|
942
|
+
// AS WRITTEN, before either resolved spelling (audit 2026-11-01, MB2): a
|
|
943
|
+
// directory on the written path that HEAD holds as a link redirects the
|
|
944
|
+
// program to wherever the head points it, and the written path is also a
|
|
945
|
+
// candidate below, judged by its own entries at both refs.
|
|
946
|
+
const written = writtenRelative(repoReal, programPath);
|
|
947
|
+
if (written !== null && written !== '') {
|
|
948
|
+
const link = linkOnWrittenPathAtHead(repoRoot, written);
|
|
949
|
+
if (link !== null) {
|
|
950
|
+
return linkOnWrittenPathRefusal(fromArgs ? `in ${list}, the path ${written}` : `the gate program at ${written}`, link, trustBase === '' ? 'the base' : `"${trustBase}"`);
|
|
951
|
+
}
|
|
952
|
+
}
|
|
803
953
|
const candidates = new Set();
|
|
804
|
-
for (const candidate of [
|
|
954
|
+
for (const candidate of [
|
|
955
|
+
withResolvedParent(programPath),
|
|
956
|
+
realOrNull(programPath),
|
|
957
|
+
written === null ? null : path.join(repoReal, written),
|
|
958
|
+
]) {
|
|
805
959
|
if (candidate !== null && insideWorkingTree(repoReal, candidate)) {
|
|
806
960
|
candidates.add(candidate);
|
|
807
961
|
}
|
|
@@ -827,18 +981,18 @@ fromArgs = false) {
|
|
|
827
981
|
// gate program": it may be a script or a file a script reads (review
|
|
828
982
|
// 2026-10-28, N-f, which the first N1 round fixed for the root only).
|
|
829
983
|
if (fromArgs && (base === null || head === null)) {
|
|
830
|
-
return (`in
|
|
984
|
+
return (`in ${list}, the ${trustBase === '' ? 'base' : `"${trustBase}"`} ref does not ` +
|
|
831
985
|
`track ${relative}, a file named there or one an interpreter could load for it, so it is ` +
|
|
832
986
|
'a file this pull request controls, vetted as code. Land it on the base branch first, or ' +
|
|
833
987
|
'name a script outside the repository. Nothing was checked by this gate.');
|
|
834
988
|
}
|
|
835
989
|
if (fromArgs && (!isRegularFileMode(base.mode) || !isRegularFileMode(head.mode))) {
|
|
836
|
-
return (`in
|
|
990
|
+
return (`in ${list}, the file ${relative} is not a regular file at both "${trustBase}" ` +
|
|
837
991
|
'and the head commit, so what an interpreter would load is decided by something other ' +
|
|
838
992
|
'than the approved bytes. Nothing was checked by this gate.');
|
|
839
993
|
}
|
|
840
994
|
if (fromArgs && base.sha !== head.sha) {
|
|
841
|
-
return (`in
|
|
995
|
+
return (`in ${list}, the file ${relative} is not the one "${trustBase}" approved: this ` +
|
|
842
996
|
'pull request changes it, and it is vetted as code an interpreter could load. Land the ' +
|
|
843
997
|
'change on the base branch first. Nothing was checked by this gate.');
|
|
844
998
|
}
|
|
@@ -882,7 +1036,7 @@ fromArgs = false) {
|
|
|
882
1036
|
// the file may be a script or something the script reads, so it is
|
|
883
1037
|
// not called "the gate program", and the remedy is about the
|
|
884
1038
|
// command, not about vendoring (audit 2026-10-28, N1).
|
|
885
|
-
return (`the file ${relative} named in
|
|
1039
|
+
return (`the file ${relative} named in ${list} is at the repository root, and it is ` +
|
|
886
1040
|
'vetted as code an interpreter could load (the command is not the gate itself, or ' +
|
|
887
1041
|
'the entry has a code extension): ' +
|
|
888
1042
|
'the directory that would have to be unchanged is the whole repository, and this pull ' +
|
|
@@ -897,7 +1051,7 @@ fromArgs = false) {
|
|
|
897
1051
|
'its own directory, or install it on PATH. Nothing was checked by this gate.');
|
|
898
1052
|
}
|
|
899
1053
|
if (fromArgs) {
|
|
900
|
-
return (`in
|
|
1054
|
+
return (`in ${list}, a file beside ${relative} in ${directory} is not what ` +
|
|
901
1055
|
`"${trustBase}" approved: ${relative} is unchanged, but the directory around it is not, ` +
|
|
902
1056
|
'and code an interpreter loads can load its neighbours. Land the change on the base ' +
|
|
903
1057
|
'branch first, or name a script outside the repository. Nothing was checked by this gate.');
|
|
@@ -909,6 +1063,13 @@ fromArgs = false) {
|
|
|
909
1063
|
'PATH. Nothing was checked by this gate.');
|
|
910
1064
|
}
|
|
911
1065
|
}
|
|
1066
|
+
// LAST, the disk against the tree (review of the 2026-11-01 fix, item 1).
|
|
1067
|
+
if (written !== null && written !== '') {
|
|
1068
|
+
const undeclared = undeclaredLinkOnDisk(repoRoot, repoReal, written);
|
|
1069
|
+
if (undeclared !== null) {
|
|
1070
|
+
return undeclaredLinkRefusal(fromArgs ? `in ${list}, the path ${written}` : `the gate program at ${written}`, undeclared);
|
|
1071
|
+
}
|
|
1072
|
+
}
|
|
912
1073
|
return null;
|
|
913
1074
|
}
|
|
914
1075
|
/**
|
|
@@ -975,18 +1136,32 @@ export function atLeastVersion(version, minimum) {
|
|
|
975
1136
|
* read from disk, and a link is never followed for that, so a link is always
|
|
976
1137
|
* vetted as a link.
|
|
977
1138
|
*/
|
|
978
|
-
export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath
|
|
1139
|
+
export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath,
|
|
1140
|
+
/** Which policy list the path came from, for the refusals: `args:`, or `options:` for a code-extension option value. */
|
|
1141
|
+
list = "the gate's args:") {
|
|
979
1142
|
const repoReal = realOrNull(repoRoot);
|
|
980
1143
|
if (repoReal === null) {
|
|
981
1144
|
return `the repository root ${repoRoot} could not be resolved, so the gate arguments could not be checked against "${trustBase}". Nothing was checked by this gate.`;
|
|
982
1145
|
}
|
|
983
|
-
|
|
1146
|
+
// The written spelling beside the resolved ones (audit 2026-11-01, MB2).
|
|
1147
|
+
const written = writtenRelative(repoReal, argumentPath);
|
|
1148
|
+
const spellings = [
|
|
1149
|
+
withResolvedParent(argumentPath),
|
|
1150
|
+
realOrNull(argumentPath),
|
|
1151
|
+
written === null ? null : path.join(repoReal, written),
|
|
1152
|
+
].filter((spelling) => spelling !== null);
|
|
984
1153
|
if (spellings.some((spelling) => path.relative(repoReal, spelling) === '')) {
|
|
985
|
-
return (
|
|
1154
|
+
return (`${list} name the repository root (${argumentPath}), so what would run is decided by ` +
|
|
986
1155
|
`the whole working tree, and this pull request differs from "${trustBase}" somewhere in it. ` +
|
|
987
1156
|
'conductor already hands each gate the repository it scans; name a script in its own ' +
|
|
988
1157
|
'directory instead. Nothing was checked by this gate.');
|
|
989
1158
|
}
|
|
1159
|
+
if (written !== null) {
|
|
1160
|
+
const link = linkOnWrittenPathAtHead(repoRoot, written);
|
|
1161
|
+
if (link !== null) {
|
|
1162
|
+
return linkOnWrittenPathRefusal(`in ${list}, the path ${written}`, link, trustBase === '' ? 'the base' : `"${trustBase}"`);
|
|
1163
|
+
}
|
|
1164
|
+
}
|
|
990
1165
|
let isDirectory;
|
|
991
1166
|
try {
|
|
992
1167
|
isDirectory = lstatSync(argumentPath).isDirectory();
|
|
@@ -998,7 +1173,7 @@ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath)
|
|
|
998
1173
|
isDirectory = false;
|
|
999
1174
|
}
|
|
1000
1175
|
if (!isDirectory) {
|
|
1001
|
-
return refuseHeadControlledProgram(repoRoot, trustBase, argumentPath, true);
|
|
1176
|
+
return refuseHeadControlledProgram(repoRoot, trustBase, argumentPath, true, list);
|
|
1002
1177
|
}
|
|
1003
1178
|
for (const spelling of new Set(spellings)) {
|
|
1004
1179
|
if (!insideWorkingTree(repoReal, spelling)) {
|
|
@@ -1009,27 +1184,35 @@ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath)
|
|
|
1009
1184
|
const headEntry = treeEntryAt(repoRoot, 'HEAD', relative);
|
|
1010
1185
|
for (const listed of [baseEntry, headEntry]) {
|
|
1011
1186
|
if (listed.kind === 'error') {
|
|
1012
|
-
return (`the directory ${relative} named in
|
|
1187
|
+
return (`the directory ${relative} named in ${list} could not be checked against ` +
|
|
1013
1188
|
`"${trustBase}": ${listed.detail}. Nothing was checked by this gate.`);
|
|
1014
1189
|
}
|
|
1015
1190
|
}
|
|
1016
1191
|
const base = baseEntry.kind === 'entry' ? baseEntry : null;
|
|
1017
1192
|
const head = headEntry.kind === 'entry' ? headEntry : null;
|
|
1018
1193
|
if (base === null || head === null || base.type !== 'tree' || head.type !== 'tree' || base.sha !== head.sha) {
|
|
1019
|
-
return (`the directory ${relative} named in
|
|
1194
|
+
return (`the directory ${relative} named in ${list} is not what "${trustBase}" approved: ` +
|
|
1020
1195
|
'this pull request adds, removes or changes something in it, and an interpreter handed a ' +
|
|
1021
1196
|
'directory runs what is inside. Land the change on the base branch first, or name a ' +
|
|
1022
1197
|
'script outside the repository. Nothing was checked by this gate.');
|
|
1023
1198
|
}
|
|
1024
1199
|
}
|
|
1200
|
+
// LAST, the disk against the tree (review of the 2026-11-01 fix, item 1).
|
|
1201
|
+
if (written !== null) {
|
|
1202
|
+
const undeclared = undeclaredLinkOnDisk(repoRoot, repoReal, written);
|
|
1203
|
+
if (undeclared !== null) {
|
|
1204
|
+
return undeclaredLinkRefusal(`in ${list}, the path ${written}`, undeclared);
|
|
1205
|
+
}
|
|
1206
|
+
}
|
|
1025
1207
|
return null;
|
|
1026
1208
|
}
|
|
1027
1209
|
/**
|
|
1028
1210
|
* Why a path a gate's own `args:` name cannot be trusted on a pull-request
|
|
1029
1211
|
* run, or null (audit 2026-10-28, N1, and its review, B1 and N-a).
|
|
1030
1212
|
*
|
|
1031
|
-
* Asked
|
|
1032
|
-
* src/resolve.ts),
|
|
1213
|
+
* Asked for the args of a `command:` that is the gate itself, and for the
|
|
1214
|
+
* `options:` values of every gate (dataArgumentPaths in src/resolve.ts),
|
|
1215
|
+
* since both are the gate's own argv: a rules file such as
|
|
1033
1216
|
* `--config=.gitleaks.toml`, or a rules directory such as dep-guard's
|
|
1034
1217
|
* `--corpus-dir`, is read as data, not loaded as code. Its contents still
|
|
1035
1218
|
* decide what the gate reports, so a pull request that rewrote them would
|
|
@@ -1058,26 +1241,67 @@ export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath)
|
|
|
1058
1241
|
* - Absent at the base: accepted only if the head has nothing there either,
|
|
1059
1242
|
* tracked or on disk (a word that is not a path, `--format=json`);
|
|
1060
1243
|
* otherwise it is a path this pull request chose, and refused.
|
|
1244
|
+
* - AS WRITTEN as well as resolved (audit 2026-11-01, MB2): a directory on
|
|
1245
|
+
* the written path that HEAD's tree holds as a link is refused, the
|
|
1246
|
+
* written path is judged by the rules above like the resolved ones, and a
|
|
1247
|
+
* positional scan target the base tracks as a directory is refused when
|
|
1248
|
+
* HEAD holds it as a link, since that one is otherwise not compared.
|
|
1249
|
+
* - The same for an `options:` value (audit 2026-11-01, MB1): it is
|
|
1250
|
+
* rendered into the gate's argv and read the same way (dataArgumentPaths),
|
|
1251
|
+
* and `from: 'options'` only changes which list the refusal names.
|
|
1061
1252
|
*
|
|
1062
1253
|
* Only whether something exists on disk at a path the base does not track is
|
|
1063
1254
|
* read from the working tree; every other answer is a `git ls-tree` listing.
|
|
1064
1255
|
*/
|
|
1065
1256
|
export function refuseHeadControlledData(repoRoot, trustBase, data) {
|
|
1257
|
+
// Which list of the policy the value came from, for every message below:
|
|
1258
|
+
// an `options:` value is rendered into the same argv and vetted the same
|
|
1259
|
+
// way (audit 2026-11-01, MB1).
|
|
1260
|
+
const list = data.from === 'options' ? "the gate's options:" : "the gate's args:";
|
|
1066
1261
|
const repoReal = realOrNull(repoRoot);
|
|
1067
1262
|
if (repoReal === null) {
|
|
1068
|
-
return `the repository root ${repoRoot} could not be resolved, so the files named in
|
|
1263
|
+
return `the repository root ${repoRoot} could not be resolved, so the files named in ${list} could not be checked against "${trustBase}". Nothing was checked by this gate.`;
|
|
1069
1264
|
}
|
|
1070
1265
|
const dataPath = data.path;
|
|
1071
|
-
|
|
1266
|
+
// The written spelling beside the resolved ones (audit 2026-11-01, MB2).
|
|
1267
|
+
const written = writtenRelative(repoReal, dataPath);
|
|
1268
|
+
const spellings = [
|
|
1269
|
+
withResolvedParent(dataPath),
|
|
1270
|
+
realOrNull(dataPath),
|
|
1271
|
+
written === null ? null : path.join(repoReal, written),
|
|
1272
|
+
].filter((spelling) => spelling !== null);
|
|
1072
1273
|
const baseName = trustBase === '' ? 'the base' : `"${trustBase}"`;
|
|
1274
|
+
if (written !== null && written !== '') {
|
|
1275
|
+
const subject = `the path ${written} named in ${list}`;
|
|
1276
|
+
const link = linkOnWrittenPathAtHead(repoRoot, written);
|
|
1277
|
+
if (link !== null) {
|
|
1278
|
+
return linkOnWrittenPathRefusal(subject, link, baseName);
|
|
1279
|
+
}
|
|
1280
|
+
// A positional directory the base tracks is a scan target and is not
|
|
1281
|
+
// compared below, so its own entry is asked here: a link there hands the
|
|
1282
|
+
// gate wherever the head points it, possibly the root, instead of the
|
|
1283
|
+
// target the base named. Every other own-entry link (a file, an option
|
|
1284
|
+
// value) is refused below, in the words of its kind.
|
|
1285
|
+
if (data.positional) {
|
|
1286
|
+
const own = listOne(repoRoot, 'HEAD', written);
|
|
1287
|
+
const approved = treeEntryAt(repoRoot, trustBase, written);
|
|
1288
|
+
if (own.kind === 'entry' && own.mode === '120000' && approved.kind === 'entry' && approved.type === 'tree') {
|
|
1289
|
+
return linkOnWrittenPathRefusal(subject, written, baseName);
|
|
1290
|
+
}
|
|
1291
|
+
}
|
|
1292
|
+
}
|
|
1073
1293
|
if (spellings.some((spelling) => path.relative(repoReal, spelling) === '')) {
|
|
1074
1294
|
if (data.positional) {
|
|
1075
|
-
|
|
1295
|
+
// A scan target that IS the root is accepted, so the disk check that
|
|
1296
|
+
// otherwise runs last runs here first: a link on disk the head tree
|
|
1297
|
+
// does not declare can fold a positional onto the root (review R1).
|
|
1298
|
+
const undeclared = written === null || written === '' ? null : undeclaredLinkOnDisk(repoRoot, repoReal, written);
|
|
1299
|
+
return undeclared === null ? null : undeclaredLinkRefusal(`the path ${written} named in ${list}`, undeclared);
|
|
1076
1300
|
}
|
|
1077
1301
|
// The entry as written, never the absolute checkout path, which would
|
|
1078
1302
|
// reach the pull-request comment and SARIF; and the remedy for the common
|
|
1079
1303
|
// case, a scan target written after a flag, first (re-review R1).
|
|
1080
|
-
return (
|
|
1304
|
+
return (`${list} give the repository root (${data.entry ?? '.'}) as an option's value, so ` +
|
|
1081
1305
|
`the whole working tree would be data the gate reads, and this pull request differs from ` +
|
|
1082
1306
|
`${baseName} somewhere in it. If it is the scan target written after a flag, move it before ` +
|
|
1083
1307
|
'the flags, where it reads as a positional; otherwise give that option a directory of its ' +
|
|
@@ -1095,7 +1319,7 @@ export function refuseHeadControlledData(repoRoot, trustBase, data) {
|
|
|
1095
1319
|
const headEntry = treeEntryAt(repoRoot, 'HEAD', relative);
|
|
1096
1320
|
for (const listed of [baseEntry, headEntry]) {
|
|
1097
1321
|
if (listed.kind === 'error') {
|
|
1098
|
-
return (`the file ${relative} named in
|
|
1322
|
+
return (`the file ${relative} named in ${list} could not be checked against ${baseName}: ` +
|
|
1099
1323
|
`${listed.detail}. Nothing was checked by this gate.`);
|
|
1100
1324
|
}
|
|
1101
1325
|
}
|
|
@@ -1106,7 +1330,7 @@ export function refuseHeadControlledData(repoRoot, trustBase, data) {
|
|
|
1106
1330
|
// Names nothing at either side: a word, not a path.
|
|
1107
1331
|
continue;
|
|
1108
1332
|
}
|
|
1109
|
-
return (`the file ${relative} named in
|
|
1333
|
+
return (`the file ${relative} named in ${list} is not tracked at ${baseName} and the head ` +
|
|
1110
1334
|
'commit both, so the gate would read a path this pull request chose. Commit it on the base ' +
|
|
1111
1335
|
'branch first, or name a file outside the repository. Nothing was checked by this gate.');
|
|
1112
1336
|
}
|
|
@@ -1116,7 +1340,7 @@ export function refuseHeadControlledData(repoRoot, trustBase, data) {
|
|
|
1116
1340
|
continue;
|
|
1117
1341
|
}
|
|
1118
1342
|
if (head === null || head.type !== 'tree' || head.sha !== base.sha) {
|
|
1119
|
-
return (`the directory ${relative} named in
|
|
1343
|
+
return (`the directory ${relative} named in ${list} is not what ${baseName} approved: ` +
|
|
1120
1344
|
'this pull request adds, removes or changes something in it, and it is given as an ' +
|
|
1121
1345
|
"option's value, so the gate reads it as data, such as a rules directory " +
|
|
1122
1346
|
'(dep-guard --corpus-dir). Land the change on the base branch first. If it is a scan ' +
|
|
@@ -1126,16 +1350,55 @@ export function refuseHeadControlledData(repoRoot, trustBase, data) {
|
|
|
1126
1350
|
continue;
|
|
1127
1351
|
}
|
|
1128
1352
|
if (head === null || !isRegularFileMode(base.mode) || !isRegularFileMode(head.mode)) {
|
|
1129
|
-
return (`the file ${relative} named in
|
|
1353
|
+
return (`the file ${relative} named in ${list} is not a regular file at both ${baseName} ` +
|
|
1130
1354
|
'and the head commit, so what the gate would read is decided by something other than the ' +
|
|
1131
1355
|
'approved bytes. Name the file itself. Nothing was checked by this gate.');
|
|
1132
1356
|
}
|
|
1133
1357
|
if (base.sha !== head.sha) {
|
|
1134
|
-
return (`the file ${relative} named in
|
|
1358
|
+
return (`the file ${relative} named in ${list} is not the one ${baseName} approved: this ` +
|
|
1135
1359
|
'pull request changes it, and the gate reads it, so running the gate would let the pull ' +
|
|
1136
1360
|
'request choose the rules that judge it. Land the change on the base branch first. ' +
|
|
1137
1361
|
'Nothing was checked by this gate.');
|
|
1138
1362
|
}
|
|
1139
1363
|
}
|
|
1364
|
+
// LAST, the disk against the tree (review of the 2026-11-01 fix, item 1).
|
|
1365
|
+
if (written !== null && written !== '') {
|
|
1366
|
+
const undeclared = undeclaredLinkOnDisk(repoRoot, repoReal, written);
|
|
1367
|
+
if (undeclared !== null) {
|
|
1368
|
+
return undeclaredLinkRefusal(`the path ${written} named in ${list}`, undeclared);
|
|
1369
|
+
}
|
|
1370
|
+
}
|
|
1140
1371
|
return null;
|
|
1141
1372
|
}
|
|
1373
|
+
/** What a run refused for carrying HEAD's tree tells the reader to do. */
|
|
1374
|
+
const EQUAL_TREE_ADVICE = 'A pull request that landed gets no later push, so nothing re-runs this check: this run stays ' +
|
|
1375
|
+
'red and its changes went unchecked here. One still open re-runs on its next push. The Action judges this shape against the commit the merge ref was ' +
|
|
1376
|
+
'built from only on a full clone (fetch-depth: 0) with the same control files at both commits. ' +
|
|
1377
|
+
'If neither case applies, the trust base names the head or merge commit: pass the base branch ' +
|
|
1378
|
+
'(for example origin/main) instead.';
|
|
1379
|
+
/**
|
|
1380
|
+
* The trust base with the base branch's tip to name in the report, when the
|
|
1381
|
+
* Action moved the trust base past it. FOR DISPLAY ONLY: nothing that decides
|
|
1382
|
+
* anything reads `baseTip`. The value comes from the environment, so it is
|
|
1383
|
+
* honored only when the repository bears it out: a full id of a commit that is
|
|
1384
|
+
* neither HEAD nor the trust base, with HEAD's tree, and the trust base is HEAD's
|
|
1385
|
+
* first parent. Anything else is ignored without a word: the sentence is the only
|
|
1386
|
+
* thing it could change, and leaving it out is true.
|
|
1387
|
+
*
|
|
1388
|
+
* The CLI cannot work this out alone. It sees the private ref at HEAD's first
|
|
1389
|
+
* parent, which is also what every ordinary pull-request run looks like, and it
|
|
1390
|
+
* never sees the tip the Action moved away from. It can only check what it is told.
|
|
1391
|
+
*/
|
|
1392
|
+
export function withMovedBaseTip(repoRoot, trustBase, value) {
|
|
1393
|
+
if (value === undefined || !/^[0-9a-f]{40}([0-9a-f]{24})?$/.test(value)) {
|
|
1394
|
+
return trustBase;
|
|
1395
|
+
}
|
|
1396
|
+
const base = resolveRev(repoRoot, trustBase.ref, 'commit');
|
|
1397
|
+
const borneOut = base !== null &&
|
|
1398
|
+
value !== base &&
|
|
1399
|
+
resolveRev(repoRoot, value, 'commit') === value &&
|
|
1400
|
+
value !== resolveRev(repoRoot, 'HEAD', 'commit') &&
|
|
1401
|
+
headTreeEqualsBase(repoRoot, value) &&
|
|
1402
|
+
headParents(repoRoot)[0] === base;
|
|
1403
|
+
return borneOut ? { ...trustBase, baseTip: value } : trustBase;
|
|
1404
|
+
}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Tracked
|
|
2
|
+
* Tracked dependency files that were not handed to `product`, sorted, as
|
|
3
3
|
* one sentence fragment, or null when there are none.
|
|
4
4
|
*
|
|
5
5
|
* `handed` are the repository-relative paths the gate was actually handed,
|