@vaultcompass/conductor 0.2.3 → 0.3.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 +147 -2
- package/dist/cli.js +96 -15
- package/dist/envelope.d.ts +16 -0
- package/dist/gate-runner.d.ts +118 -2
- package/dist/gate-runner.js +211 -9
- package/dist/init.d.ts +15 -1
- package/dist/init.js +215 -33
- package/dist/intent-prepare.d.ts +16 -0
- package/dist/intent-prepare.js +18 -0
- package/dist/normalize.d.ts +14 -1
- package/dist/normalize.js +76 -0
- package/dist/output-sarif.d.ts +11 -0
- package/dist/output-sarif.js +230 -19
- package/dist/output-text.js +134 -3
- package/dist/policy.js +24 -3
- package/dist/resolve.d.ts +11 -0
- package/dist/resolve.js +4 -0
- package/dist/run.d.ts +92 -0
- package/dist/run.js +119 -5
- package/dist/trust-base.d.ts +142 -0
- package/dist/trust-base.js +414 -0
- package/package.json +1 -1
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Why this ref cannot be a trust base, or null when it can.
|
|
3
|
+
*
|
|
4
|
+
* A string rather than a thrown error, because the caller does not print it
|
|
5
|
+
* and stop: every enabled gate becomes could-not-run carrying this sentence,
|
|
6
|
+
* so the report names the gates that did not run rather than only the ref
|
|
7
|
+
* that was wrong.
|
|
8
|
+
*
|
|
9
|
+
* The four sentences mirror intent-guard's own refusals, which the umbrella
|
|
10
|
+
* would otherwise meet second-hand as a child's exit 2. Refusing here means
|
|
11
|
+
* the umbrella never spawns a child at all on a base it has already decided
|
|
12
|
+
* it cannot judge against, and it means the two gates give a user the same
|
|
13
|
+
* answer to the same mistake.
|
|
14
|
+
*/
|
|
15
|
+
export declare function refuseTrustBaseRef(repoRoot: string, ref: string): string | null;
|
|
16
|
+
/**
|
|
17
|
+
* The policy file's contents at a ref, or null when that ref carries none.
|
|
18
|
+
*
|
|
19
|
+
* `git show`, never a checkout switch and never a read from the working
|
|
20
|
+
* tree. The `./` is load-bearing for the same reason it is in intent-guard:
|
|
21
|
+
* it makes git resolve the path relative to the working directory, which is
|
|
22
|
+
* the repository root here, rather than to wherever the repository root would
|
|
23
|
+
* be from somewhere else.
|
|
24
|
+
*/
|
|
25
|
+
export declare function readPolicyAtRef(repoRoot: string, ref: string): string | null;
|
|
26
|
+
/**
|
|
27
|
+
* Whether two policy files differ in what they SAY.
|
|
28
|
+
*
|
|
29
|
+
* Compared as parsed documents rather than as bytes, so a reflowed list, a
|
|
30
|
+
* changed quote style or an edited comment is not reported as a proposal to
|
|
31
|
+
* change the rules; a report that cries wolf on whitespace is a report
|
|
32
|
+
* reviewers learn to skip. When either side will not parse, the raw text is
|
|
33
|
+
* compared instead, which is the fail-closed direction: an unparseable head
|
|
34
|
+
* policy is reported as a change rather than quietly matching.
|
|
35
|
+
*
|
|
36
|
+
* BOTH SIDES COME FROM `git show`, base and head alike, and that is not an
|
|
37
|
+
* accident of implementation. intent-guard read its head side from the
|
|
38
|
+
* working tree with a call that follows symlinks, so a pull request that
|
|
39
|
+
* replaced a control file with a link compared equal to the base and was
|
|
40
|
+
* reported as changing nothing. One reader for both sides is the only way the
|
|
41
|
+
* two can be compared on equal terms, and it also means an uncommitted local
|
|
42
|
+
* edit is not reported as something the pull request proposes.
|
|
43
|
+
*/
|
|
44
|
+
export declare function policyDiffers(base: string | null, head: string | null): boolean;
|
|
45
|
+
/** The one line the report prints when the head proposes a different policy. */
|
|
46
|
+
export declare const POLICY_PROPOSAL_LINE = "policy changed in this pull request";
|
|
47
|
+
/**
|
|
48
|
+
* One path's tree entry at a ref, or null when the ref has no such path.
|
|
49
|
+
*
|
|
50
|
+
* `ls-tree` rather than `git show`, because the BLOB ID is the thing being
|
|
51
|
+
* compared and `show` prints contents without telling you what kind of entry
|
|
52
|
+
* produced them. The mode comes with it, so a regular file can be told from a
|
|
53
|
+
* symlink, a submodule or a directory in the same read.
|
|
54
|
+
*/
|
|
55
|
+
export declare function treeEntryAt(repoRoot: string, ref: string, relativePath: string): {
|
|
56
|
+
mode: string;
|
|
57
|
+
type: string;
|
|
58
|
+
sha: string;
|
|
59
|
+
} | null;
|
|
60
|
+
/**
|
|
61
|
+
* Why this gate's PROGRAM cannot be trusted on a pull-request run, or null.
|
|
62
|
+
*
|
|
63
|
+
* Reading the rules from the base ref is worth nothing if the pull request
|
|
64
|
+
* chooses the program that applies them, and it can, three ways that all look
|
|
65
|
+
* ordinary in a diff:
|
|
66
|
+
*
|
|
67
|
+
* - A base policy whose `command:` points INSIDE the repository, at
|
|
68
|
+
* something like `vendor/vault-guard`. The path came from the base and is
|
|
69
|
+
* therefore approved; the FILE AT THAT PATH is whatever the head commit
|
|
70
|
+
* put there. The umbrella then runs the pull request's own program, is
|
|
71
|
+
* told the scan was clean, and reports a clean scan.
|
|
72
|
+
*
|
|
73
|
+
* - No `command:` at all. Resolution prefers the repository's own
|
|
74
|
+
* `node_modules/.bin` over PATH, deliberately, so that a project pin beats
|
|
75
|
+
* a global install. A head that commits `node_modules/.bin/vault-guard`
|
|
76
|
+
* shadows the real gate, and a stub that answers `--version` with a
|
|
77
|
+
* plausible number passes every check the umbrella makes. The composite
|
|
78
|
+
* action installs nothing, so the plant survives an install step.
|
|
79
|
+
*
|
|
80
|
+
* - A base-approved WRAPPER. `vendor/vault-guard` is byte for byte what the
|
|
81
|
+
* base approved and is the path the policy names; it execs
|
|
82
|
+
* `vendor/impl.sh`, which the head rewrote. Nothing in the diff touches
|
|
83
|
+
* the path the policy names, so a per-file check waves it through. This
|
|
84
|
+
* one was found by a reviewer after the first two were closed, and it is
|
|
85
|
+
* why the unit of approval is a directory rather than a file.
|
|
86
|
+
*
|
|
87
|
+
* THE RULE. A program is acceptable when it is outside the working tree
|
|
88
|
+
* entirely: on PATH, or an absolute `command:` somewhere else on the machine.
|
|
89
|
+
* A pull request cannot write those. A program INSIDE the working tree is
|
|
90
|
+
* acceptable only when BOTH hold: it is a tracked regular file whose blob is
|
|
91
|
+
* IDENTICAL at the trust base and at HEAD, AND the tree object id of its
|
|
92
|
+
* CONTAINING DIRECTORY is identical at those two refs. The first is the same
|
|
93
|
+
* base-versus-head test the rules themselves get, applied to the thing that
|
|
94
|
+
* enforces them; the second extends it to everything beside the program,
|
|
95
|
+
* which is what the wrapper shape needs and what a per-file test cannot give.
|
|
96
|
+
*
|
|
97
|
+
* A tree object id covers a whole subtree in one comparison, so this needs no
|
|
98
|
+
* knowledge of what a wrapper calls. WHAT IS VETTED IS THE PROGRAM FILE AND
|
|
99
|
+
* ITS DIRECTORY SUBTREE AND NOTHING ELSE: anything the program reaches
|
|
100
|
+
* outside that directory is not vetted, so an in-repo gate has to be
|
|
101
|
+
* self-contained within its own directory. That limit is stated in the README
|
|
102
|
+
* in those words, because an adopter has to be able to satisfy it.
|
|
103
|
+
*
|
|
104
|
+
* A PROGRAM AT THE REPOSITORY ROOT IS REFUSED. There the containing directory
|
|
105
|
+
* is the whole repository, so the comparison is the root tree and every pull
|
|
106
|
+
* request that changed anything differs, which is every pull request.
|
|
107
|
+
* Refusing with the remedy in the message beats a rule that silently means
|
|
108
|
+
* "no pull request may change anything".
|
|
109
|
+
*
|
|
110
|
+
* NOTHING HERE READS THE WORKING TREE. Both sides come from `git ls-tree`, so
|
|
111
|
+
* an uncommitted local edit cannot make a file look approved and a tracked
|
|
112
|
+
* file cannot be vouched for by a copy on disk that git has never seen.
|
|
113
|
+
*
|
|
114
|
+
* NODE_MODULES IS NEVER BASE-APPROVED, and the reason is worth stating
|
|
115
|
+
* because "but the lockfile is committed" is the obvious objection. What is
|
|
116
|
+
* under `node_modules` is chosen by the head's own manifest and lockfile and
|
|
117
|
+
* installed by a step that runs before this one; git has no record of those
|
|
118
|
+
* bytes at either ref, so `ls-tree` finds nothing and the rule refuses. That
|
|
119
|
+
* is the correct answer rather than a limitation: a pull request that edits
|
|
120
|
+
* its lockfile to pull a different build of a gate has chosen its own judge
|
|
121
|
+
* just as surely as one that commits a stub.
|
|
122
|
+
*
|
|
123
|
+
* BOTH THE PROGRAM'S OWN PATH AND ITS REALPATH ARE VETTED, because a
|
|
124
|
+
* head-committed symlink is a choice of program too. An in-repo symlink is
|
|
125
|
+
* refused on its OWN entry, before its target matters: it is either untracked
|
|
126
|
+
* or its tree entry is a link rather than a regular file, and either refuses.
|
|
127
|
+
* Vetting the target is what catches a link whose own path is outside the
|
|
128
|
+
* tree pointing into it; it never decides the in-repo case.
|
|
129
|
+
*/
|
|
130
|
+
export declare function refuseHeadControlledProgram(repoRoot: string, trustBase: string, programPath: string): string | null;
|
|
131
|
+
/**
|
|
132
|
+
* Whether a gate's reported version is at least `minimum`.
|
|
133
|
+
*
|
|
134
|
+
* Numeric per component, not a string comparison, or "1.10.0" would sort
|
|
135
|
+
* below "1.4.0". A version that cannot be read at all answers FALSE, which is
|
|
136
|
+
* the safe direction for the one thing this decides: whether to hand a child
|
|
137
|
+
* a flag an older build of it would reject outright. A gate that refused an
|
|
138
|
+
* unknown flag would exit non-zero with no JSON, which the umbrella reports
|
|
139
|
+
* as could-not-run, so guessing high turns a working run into a broken one
|
|
140
|
+
* for every repository pinning an older gate.
|
|
141
|
+
*/
|
|
142
|
+
export declare function atLeastVersion(version: string | null, minimum: string): boolean;
|
|
@@ -0,0 +1,414 @@
|
|
|
1
|
+
// Pull-request mode for the umbrella: the policy comes from the base ref.
|
|
2
|
+
//
|
|
3
|
+
// The hole this closes is the umbrella's own, and it is the sharpest one in
|
|
4
|
+
// the family because the policy file can name a program to run. On a
|
|
5
|
+
// pull-request run the author controls every file in the tree being judged,
|
|
6
|
+
// `.guardrails.yaml` included, so one commit could point a gate's `command:`
|
|
7
|
+
// at a script the same commit added, or set `enabled: false` on the gate
|
|
8
|
+
// that would have caught what else is in it, and the report would say the
|
|
9
|
+
// run was clean. The gate ran. It just ran the pull request's own program,
|
|
10
|
+
// under the pull request's own rules.
|
|
11
|
+
//
|
|
12
|
+
// The fix is not a heuristic about which policy edits look suspicious. It is
|
|
13
|
+
// base versus head, and it is plain git: with `--trust-base <ref>` the
|
|
14
|
+
// umbrella reads its policy from that ref and judges the head tree. A policy
|
|
15
|
+
// difference never takes effect for the run, and the report says it was
|
|
16
|
+
// proposed. Outside pull-request mode nothing changes, because a pre-commit
|
|
17
|
+
// hook and a direct run on your own checkout are already inside the trust
|
|
18
|
+
// boundary.
|
|
19
|
+
//
|
|
20
|
+
// Three rules hold this file together, and all three are intent-guard's,
|
|
21
|
+
// mirrored on purpose so the two gates cannot disagree about what a trust
|
|
22
|
+
// base is:
|
|
23
|
+
//
|
|
24
|
+
// - READS ONLY, AND NEVER INTO THE REPOSITORY. `git rev-parse` and
|
|
25
|
+
// `git show`, both of which only read. No checkout switch, no worktree, no
|
|
26
|
+
// stash, no write of any kind. An umbrella that moved somebody's HEAD to
|
|
27
|
+
// do its job would be a worse bug than the one it fixes.
|
|
28
|
+
//
|
|
29
|
+
// - FAIL CLOSED ON THE REF. A ref that will not resolve is could-not-run for
|
|
30
|
+
// every enabled gate. It is never a reason to fall back to the head,
|
|
31
|
+
// because falling back to the head is exactly the behaviour being removed,
|
|
32
|
+
// and it would be reachable by anyone who could make the base ref
|
|
33
|
+
// unfetchable.
|
|
34
|
+
//
|
|
35
|
+
// - THE BASE MUST NOT BE THE HEAD, by commit AND by tree. A trust base that
|
|
36
|
+
// resolves to the head commit puts the boundary back where it started
|
|
37
|
+
// while still reporting as on, and two different commits can carry one
|
|
38
|
+
// identical tree, which has the same effect and passes a commit
|
|
39
|
+
// comparison. Both are real misconfigurations rather than curiosities:
|
|
40
|
+
// on a pull_request event `github.sha` IS the merge commit, and what
|
|
41
|
+
// GitHub publishes as the merge ref carries the head branch's tree
|
|
42
|
+
// whenever the base has not moved since the fork.
|
|
43
|
+
import { spawnSync } from 'node:child_process';
|
|
44
|
+
import { realpathSync } from 'node:fs';
|
|
45
|
+
import path from 'node:path';
|
|
46
|
+
import { parse as parseYaml } from 'yaml';
|
|
47
|
+
import { POLICY_FILE_NAME } from './policy.js';
|
|
48
|
+
/**
|
|
49
|
+
* What a rev resolves to at this repository, or null when it does not.
|
|
50
|
+
*
|
|
51
|
+
* `--quiet` suppresses git's own explanation, so there is nothing worth
|
|
52
|
+
* forwarding on failure: the caller writes a sentence a reader can act on
|
|
53
|
+
* rather than repeating the command line that failed.
|
|
54
|
+
*/
|
|
55
|
+
function resolveRev(repoRoot, rev, kind) {
|
|
56
|
+
const child = spawnSync('git', ['rev-parse', '--verify', '--quiet', `${rev}^{${kind}}`], {
|
|
57
|
+
cwd: repoRoot,
|
|
58
|
+
encoding: 'utf8',
|
|
59
|
+
});
|
|
60
|
+
if (child.error !== undefined || child.status !== 0) {
|
|
61
|
+
return null;
|
|
62
|
+
}
|
|
63
|
+
const value = (child.stdout ?? '').trim();
|
|
64
|
+
return value === '' ? null : value;
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* Why this ref cannot be a trust base, or null when it can.
|
|
68
|
+
*
|
|
69
|
+
* A string rather than a thrown error, because the caller does not print it
|
|
70
|
+
* and stop: every enabled gate becomes could-not-run carrying this sentence,
|
|
71
|
+
* so the report names the gates that did not run rather than only the ref
|
|
72
|
+
* that was wrong.
|
|
73
|
+
*
|
|
74
|
+
* The four sentences mirror intent-guard's own refusals, which the umbrella
|
|
75
|
+
* would otherwise meet second-hand as a child's exit 2. Refusing here means
|
|
76
|
+
* the umbrella never spawns a child at all on a base it has already decided
|
|
77
|
+
* it cannot judge against, and it means the two gates give a user the same
|
|
78
|
+
* answer to the same mistake.
|
|
79
|
+
*/
|
|
80
|
+
export function refuseTrustBaseRef(repoRoot, ref) {
|
|
81
|
+
const base = resolveRev(repoRoot, ref, 'commit');
|
|
82
|
+
if (base === null) {
|
|
83
|
+
return (`cannot read the policy from base ref "${ref}": it does not resolve to a commit in ` +
|
|
84
|
+
'this repository. Nothing was checked. In CI, fetch the base branch (actions/checkout ' +
|
|
85
|
+
'with fetch-depth: 0) before running the gates.');
|
|
86
|
+
}
|
|
87
|
+
const head = resolveRev(repoRoot, 'HEAD', 'commit');
|
|
88
|
+
if (head === null) {
|
|
89
|
+
return (`cannot resolve HEAD to compare against base ref "${ref}": this is not a repository ` +
|
|
90
|
+
'with any commits. Pull-request mode needs both a base commit and a head commit. ' +
|
|
91
|
+
'Nothing was checked.');
|
|
92
|
+
}
|
|
93
|
+
if (base === head) {
|
|
94
|
+
return (`refusing "${ref}" as the trust base: it resolves to ${head}, the same commit as HEAD, ` +
|
|
95
|
+
'so the policy would come from the tree being judged and pull-request mode would be off ' +
|
|
96
|
+
'while still reporting as on. Pass the base branch (for example origin/main), not the ' +
|
|
97
|
+
'head commit: on a pull_request event github.sha is the merge commit, which is HEAD. ' +
|
|
98
|
+
'Nothing was checked.');
|
|
99
|
+
}
|
|
100
|
+
const baseTree = resolveRev(repoRoot, ref, 'tree');
|
|
101
|
+
const headTree = resolveRev(repoRoot, 'HEAD', 'tree');
|
|
102
|
+
if (baseTree !== null && headTree !== null && baseTree === headTree) {
|
|
103
|
+
return (`refusing "${ref}" as the trust base: it is a different commit from HEAD but carries an ` +
|
|
104
|
+
`identical tree (${headTree}), so the policy would come from the tree being judged and ` +
|
|
105
|
+
'there would be nothing for pull-request mode to compare. A pull request merge ref looks ' +
|
|
106
|
+
'exactly like this when the base has not moved. Pass the base branch (for example ' +
|
|
107
|
+
'origin/main), not the head or merge commit. Nothing was checked.');
|
|
108
|
+
}
|
|
109
|
+
return null;
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* The policy file's contents at a ref, or null when that ref carries none.
|
|
113
|
+
*
|
|
114
|
+
* `git show`, never a checkout switch and never a read from the working
|
|
115
|
+
* tree. The `./` is load-bearing for the same reason it is in intent-guard:
|
|
116
|
+
* it makes git resolve the path relative to the working directory, which is
|
|
117
|
+
* the repository root here, rather than to wherever the repository root would
|
|
118
|
+
* be from somewhere else.
|
|
119
|
+
*/
|
|
120
|
+
export function readPolicyAtRef(repoRoot, ref) {
|
|
121
|
+
const child = spawnSync('git', ['show', `${ref}:./${POLICY_FILE_NAME}`], {
|
|
122
|
+
cwd: repoRoot,
|
|
123
|
+
encoding: 'utf8',
|
|
124
|
+
maxBuffer: 32 * 1024 * 1024,
|
|
125
|
+
});
|
|
126
|
+
if (child.error !== undefined || child.status !== 0) {
|
|
127
|
+
return null;
|
|
128
|
+
}
|
|
129
|
+
return child.stdout ?? '';
|
|
130
|
+
}
|
|
131
|
+
/**
|
|
132
|
+
* Whether two policy files differ in what they SAY.
|
|
133
|
+
*
|
|
134
|
+
* Compared as parsed documents rather than as bytes, so a reflowed list, a
|
|
135
|
+
* changed quote style or an edited comment is not reported as a proposal to
|
|
136
|
+
* change the rules; a report that cries wolf on whitespace is a report
|
|
137
|
+
* reviewers learn to skip. When either side will not parse, the raw text is
|
|
138
|
+
* compared instead, which is the fail-closed direction: an unparseable head
|
|
139
|
+
* policy is reported as a change rather than quietly matching.
|
|
140
|
+
*
|
|
141
|
+
* BOTH SIDES COME FROM `git show`, base and head alike, and that is not an
|
|
142
|
+
* accident of implementation. intent-guard read its head side from the
|
|
143
|
+
* working tree with a call that follows symlinks, so a pull request that
|
|
144
|
+
* replaced a control file with a link compared equal to the base and was
|
|
145
|
+
* reported as changing nothing. One reader for both sides is the only way the
|
|
146
|
+
* two can be compared on equal terms, and it also means an uncommitted local
|
|
147
|
+
* edit is not reported as something the pull request proposes.
|
|
148
|
+
*/
|
|
149
|
+
export function policyDiffers(base, head) {
|
|
150
|
+
if (base === null && head === null) {
|
|
151
|
+
return false;
|
|
152
|
+
}
|
|
153
|
+
if (base === null || head === null) {
|
|
154
|
+
return true;
|
|
155
|
+
}
|
|
156
|
+
try {
|
|
157
|
+
return JSON.stringify(parseYaml(base) ?? null) !== JSON.stringify(parseYaml(head) ?? null);
|
|
158
|
+
}
|
|
159
|
+
catch {
|
|
160
|
+
return base !== head;
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
/** The one line the report prints when the head proposes a different policy. */
|
|
164
|
+
export const POLICY_PROPOSAL_LINE = 'policy changed in this pull request';
|
|
165
|
+
/**
|
|
166
|
+
* One path's tree entry at a ref, or null when the ref has no such path.
|
|
167
|
+
*
|
|
168
|
+
* `ls-tree` rather than `git show`, because the BLOB ID is the thing being
|
|
169
|
+
* compared and `show` prints contents without telling you what kind of entry
|
|
170
|
+
* produced them. The mode comes with it, so a regular file can be told from a
|
|
171
|
+
* symlink, a submodule or a directory in the same read.
|
|
172
|
+
*/
|
|
173
|
+
export function treeEntryAt(repoRoot, ref, relativePath) {
|
|
174
|
+
const child = spawnSync('git', ['ls-tree', ref, '--', `./${relativePath}`], {
|
|
175
|
+
cwd: repoRoot,
|
|
176
|
+
encoding: 'utf8',
|
|
177
|
+
});
|
|
178
|
+
if (child.error !== undefined || child.status !== 0) {
|
|
179
|
+
return null;
|
|
180
|
+
}
|
|
181
|
+
const line = (child.stdout ?? '').split('\n').find((entry) => entry.trim().length > 0);
|
|
182
|
+
if (line === undefined) {
|
|
183
|
+
return null;
|
|
184
|
+
}
|
|
185
|
+
const [mode, type, sha] = line.split(/\s+/);
|
|
186
|
+
if (mode === undefined || type === undefined || sha === undefined) {
|
|
187
|
+
return null;
|
|
188
|
+
}
|
|
189
|
+
return { mode, type, sha };
|
|
190
|
+
}
|
|
191
|
+
/** The two modes that mean an ordinary file git will hand back. */
|
|
192
|
+
function isRegularFileMode(mode) {
|
|
193
|
+
return mode === '100644' || mode === '100755';
|
|
194
|
+
}
|
|
195
|
+
/**
|
|
196
|
+
* The working-tree root, resolved through symlinks, or null.
|
|
197
|
+
*
|
|
198
|
+
* realpath on BOTH sides of every comparison below. On macOS the temporary
|
|
199
|
+
* directory is reached through a symlink, so one repository root has two
|
|
200
|
+
* spellings, one of them with an extra leading segment, and a prefix test on
|
|
201
|
+
* the raw strings answers "outside" for a file that is plainly inside.
|
|
202
|
+
*/
|
|
203
|
+
function realOrNull(candidate) {
|
|
204
|
+
try {
|
|
205
|
+
return realpathSync(candidate);
|
|
206
|
+
}
|
|
207
|
+
catch {
|
|
208
|
+
return null;
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
/** Whether `candidate` is the working tree or something under it. */
|
|
212
|
+
function insideWorkingTree(repoReal, candidate) {
|
|
213
|
+
const relative = path.relative(repoReal, candidate);
|
|
214
|
+
return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
|
|
215
|
+
}
|
|
216
|
+
/**
|
|
217
|
+
* A path with its PARENT resolved through symlinks but its own last component
|
|
218
|
+
* left alone.
|
|
219
|
+
*
|
|
220
|
+
* Resolving the whole path would follow the program's own symlink, which is a
|
|
221
|
+
* different question and is asked separately below. Resolving nothing at all
|
|
222
|
+
* was a bug: the repository root arrives here realpath'd, so on a machine
|
|
223
|
+
* where the working tree sits under a symlinked mount (a macOS temporary
|
|
224
|
+
* directory, for one) the unresolved spelling of a file plainly inside the
|
|
225
|
+
* tree compares as OUTSIDE it, and the entry was quietly skipped. Only the
|
|
226
|
+
* link's target was then vetted, and the link's own entry never was.
|
|
227
|
+
*/
|
|
228
|
+
function withResolvedParent(candidate) {
|
|
229
|
+
const parent = path.dirname(candidate);
|
|
230
|
+
return path.join(realOrNull(parent) ?? parent, path.basename(candidate));
|
|
231
|
+
}
|
|
232
|
+
/**
|
|
233
|
+
* The tree object id of one directory at a ref, or null.
|
|
234
|
+
*
|
|
235
|
+
* The repository root is its own case: it has no containing directory, so the
|
|
236
|
+
* comparison is the whole root tree, which `rev-parse` gives directly.
|
|
237
|
+
*/
|
|
238
|
+
function treeShaAt(repoRoot, ref, relativeDir) {
|
|
239
|
+
if (relativeDir === '' || relativeDir === '.') {
|
|
240
|
+
return resolveRev(repoRoot, ref, 'tree');
|
|
241
|
+
}
|
|
242
|
+
const entry = treeEntryAt(repoRoot, ref, relativeDir);
|
|
243
|
+
return entry === null || entry.type !== 'tree' ? null : entry.sha;
|
|
244
|
+
}
|
|
245
|
+
/**
|
|
246
|
+
* Why this gate's PROGRAM cannot be trusted on a pull-request run, or null.
|
|
247
|
+
*
|
|
248
|
+
* Reading the rules from the base ref is worth nothing if the pull request
|
|
249
|
+
* chooses the program that applies them, and it can, three ways that all look
|
|
250
|
+
* ordinary in a diff:
|
|
251
|
+
*
|
|
252
|
+
* - A base policy whose `command:` points INSIDE the repository, at
|
|
253
|
+
* something like `vendor/vault-guard`. The path came from the base and is
|
|
254
|
+
* therefore approved; the FILE AT THAT PATH is whatever the head commit
|
|
255
|
+
* put there. The umbrella then runs the pull request's own program, is
|
|
256
|
+
* told the scan was clean, and reports a clean scan.
|
|
257
|
+
*
|
|
258
|
+
* - No `command:` at all. Resolution prefers the repository's own
|
|
259
|
+
* `node_modules/.bin` over PATH, deliberately, so that a project pin beats
|
|
260
|
+
* a global install. A head that commits `node_modules/.bin/vault-guard`
|
|
261
|
+
* shadows the real gate, and a stub that answers `--version` with a
|
|
262
|
+
* plausible number passes every check the umbrella makes. The composite
|
|
263
|
+
* action installs nothing, so the plant survives an install step.
|
|
264
|
+
*
|
|
265
|
+
* - A base-approved WRAPPER. `vendor/vault-guard` is byte for byte what the
|
|
266
|
+
* base approved and is the path the policy names; it execs
|
|
267
|
+
* `vendor/impl.sh`, which the head rewrote. Nothing in the diff touches
|
|
268
|
+
* the path the policy names, so a per-file check waves it through. This
|
|
269
|
+
* one was found by a reviewer after the first two were closed, and it is
|
|
270
|
+
* why the unit of approval is a directory rather than a file.
|
|
271
|
+
*
|
|
272
|
+
* THE RULE. A program is acceptable when it is outside the working tree
|
|
273
|
+
* entirely: on PATH, or an absolute `command:` somewhere else on the machine.
|
|
274
|
+
* A pull request cannot write those. A program INSIDE the working tree is
|
|
275
|
+
* acceptable only when BOTH hold: it is a tracked regular file whose blob is
|
|
276
|
+
* IDENTICAL at the trust base and at HEAD, AND the tree object id of its
|
|
277
|
+
* CONTAINING DIRECTORY is identical at those two refs. The first is the same
|
|
278
|
+
* base-versus-head test the rules themselves get, applied to the thing that
|
|
279
|
+
* enforces them; the second extends it to everything beside the program,
|
|
280
|
+
* which is what the wrapper shape needs and what a per-file test cannot give.
|
|
281
|
+
*
|
|
282
|
+
* A tree object id covers a whole subtree in one comparison, so this needs no
|
|
283
|
+
* knowledge of what a wrapper calls. WHAT IS VETTED IS THE PROGRAM FILE AND
|
|
284
|
+
* ITS DIRECTORY SUBTREE AND NOTHING ELSE: anything the program reaches
|
|
285
|
+
* outside that directory is not vetted, so an in-repo gate has to be
|
|
286
|
+
* self-contained within its own directory. That limit is stated in the README
|
|
287
|
+
* in those words, because an adopter has to be able to satisfy it.
|
|
288
|
+
*
|
|
289
|
+
* A PROGRAM AT THE REPOSITORY ROOT IS REFUSED. There the containing directory
|
|
290
|
+
* is the whole repository, so the comparison is the root tree and every pull
|
|
291
|
+
* request that changed anything differs, which is every pull request.
|
|
292
|
+
* Refusing with the remedy in the message beats a rule that silently means
|
|
293
|
+
* "no pull request may change anything".
|
|
294
|
+
*
|
|
295
|
+
* NOTHING HERE READS THE WORKING TREE. Both sides come from `git ls-tree`, so
|
|
296
|
+
* an uncommitted local edit cannot make a file look approved and a tracked
|
|
297
|
+
* file cannot be vouched for by a copy on disk that git has never seen.
|
|
298
|
+
*
|
|
299
|
+
* NODE_MODULES IS NEVER BASE-APPROVED, and the reason is worth stating
|
|
300
|
+
* because "but the lockfile is committed" is the obvious objection. What is
|
|
301
|
+
* under `node_modules` is chosen by the head's own manifest and lockfile and
|
|
302
|
+
* installed by a step that runs before this one; git has no record of those
|
|
303
|
+
* bytes at either ref, so `ls-tree` finds nothing and the rule refuses. That
|
|
304
|
+
* is the correct answer rather than a limitation: a pull request that edits
|
|
305
|
+
* its lockfile to pull a different build of a gate has chosen its own judge
|
|
306
|
+
* just as surely as one that commits a stub.
|
|
307
|
+
*
|
|
308
|
+
* BOTH THE PROGRAM'S OWN PATH AND ITS REALPATH ARE VETTED, because a
|
|
309
|
+
* head-committed symlink is a choice of program too. An in-repo symlink is
|
|
310
|
+
* refused on its OWN entry, before its target matters: it is either untracked
|
|
311
|
+
* or its tree entry is a link rather than a regular file, and either refuses.
|
|
312
|
+
* Vetting the target is what catches a link whose own path is outside the
|
|
313
|
+
* tree pointing into it; it never decides the in-repo case.
|
|
314
|
+
*/
|
|
315
|
+
export function refuseHeadControlledProgram(repoRoot, trustBase, programPath) {
|
|
316
|
+
const repoReal = realOrNull(repoRoot);
|
|
317
|
+
if (repoReal === null) {
|
|
318
|
+
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.`;
|
|
319
|
+
}
|
|
320
|
+
const candidates = new Set();
|
|
321
|
+
for (const candidate of [withResolvedParent(programPath), realOrNull(programPath)]) {
|
|
322
|
+
if (candidate !== null && insideWorkingTree(repoReal, candidate)) {
|
|
323
|
+
candidates.add(candidate);
|
|
324
|
+
}
|
|
325
|
+
}
|
|
326
|
+
if (candidates.size === 0) {
|
|
327
|
+
// Outside the working tree: on PATH, or an absolute path elsewhere on the
|
|
328
|
+
// machine. A pull request cannot write either.
|
|
329
|
+
return null;
|
|
330
|
+
}
|
|
331
|
+
for (const candidate of candidates) {
|
|
332
|
+
const relative = path.relative(repoReal, candidate).split(path.sep).join('/');
|
|
333
|
+
const base = treeEntryAt(repoRoot, trustBase, relative);
|
|
334
|
+
const head = treeEntryAt(repoRoot, 'HEAD', relative);
|
|
335
|
+
if (base === null || head === null) {
|
|
336
|
+
return (`the ${trustBase === '' ? 'base' : `"${trustBase}"`} ref does not track the gate program ` +
|
|
337
|
+
`at ${relative}, so it is a file this pull request controls and running it would let the ` +
|
|
338
|
+
'pull request choose the program that judges it. Nothing under node_modules is ever ' +
|
|
339
|
+
'base-approved: what is there is chosen by the head own manifest and lockfile, and git ' +
|
|
340
|
+
'has no record of those bytes at either ref. Install the gate on PATH, or point ' +
|
|
341
|
+
'command: at a path outside the repository. Nothing was checked by this gate.');
|
|
342
|
+
}
|
|
343
|
+
if (!isRegularFileMode(base.mode) || !isRegularFileMode(head.mode)) {
|
|
344
|
+
return (`the gate program at ${relative} is not a regular file at both "${trustBase}" and the ` +
|
|
345
|
+
'head commit, so what would actually run is decided by something other than the ' +
|
|
346
|
+
'approved bytes. Nothing was checked by this gate.');
|
|
347
|
+
}
|
|
348
|
+
if (base.sha !== head.sha) {
|
|
349
|
+
return (`the gate program at ${relative} is not the one "${trustBase}" approved: this pull ` +
|
|
350
|
+
'request changes it, so running it would let the pull request choose the program that ' +
|
|
351
|
+
'judges it. Land the change on the base branch first. Nothing was checked by this gate.');
|
|
352
|
+
}
|
|
353
|
+
// AND THE DIRECTORY AROUND IT. The file check alone is defeated by a
|
|
354
|
+
// wrapper: `vendor/vault-guard` execs `vendor/impl.sh`, the pull request
|
|
355
|
+
// leaves the wrapper byte for byte alone and rewrites the helper beside
|
|
356
|
+
// it, and nothing in the diff touches the path the policy names. So the
|
|
357
|
+
// unit of approval is the program's DIRECTORY SUBTREE, compared as one
|
|
358
|
+
// tree object id, which covers every file under it at once without this
|
|
359
|
+
// package having to know what a wrapper calls.
|
|
360
|
+
const directory = path.posix.dirname(relative);
|
|
361
|
+
const baseTree = treeShaAt(repoRoot, trustBase, directory);
|
|
362
|
+
const headTree = treeShaAt(repoRoot, 'HEAD', directory);
|
|
363
|
+
if (baseTree === null || headTree === null || baseTree !== headTree) {
|
|
364
|
+
if (directory === '' || directory === '.') {
|
|
365
|
+
// At the root the containing directory IS the whole repository, so
|
|
366
|
+
// this compares root trees and any pull request that changed anything
|
|
367
|
+
// differs, which is every pull request. Refusing with the remedy
|
|
368
|
+
// beats a rule that silently means "no pull request may change
|
|
369
|
+
// anything".
|
|
370
|
+
return (`the gate program at ${relative} is at the repository root, so the directory that ` +
|
|
371
|
+
'would have to be unchanged for it to be trusted is the whole repository, and this ' +
|
|
372
|
+
`pull request differs from "${trustBase}" somewhere in it. Move a vendored gate into ` +
|
|
373
|
+
'its own directory, or install it on PATH. Nothing was checked by this gate.');
|
|
374
|
+
}
|
|
375
|
+
return (`a file beside the gate program in ${directory} is not what "${trustBase}" approved: the ` +
|
|
376
|
+
`program at ${relative} is unchanged, but the directory around it is not, and a gate is ` +
|
|
377
|
+
'rarely one file. A wrapper that execs a helper beside it runs whatever this pull ' +
|
|
378
|
+
'request put there. Land the change on the base branch first, or install the gate on ' +
|
|
379
|
+
'PATH. Nothing was checked by this gate.');
|
|
380
|
+
}
|
|
381
|
+
}
|
|
382
|
+
return null;
|
|
383
|
+
}
|
|
384
|
+
/**
|
|
385
|
+
* Whether a gate's reported version is at least `minimum`.
|
|
386
|
+
*
|
|
387
|
+
* Numeric per component, not a string comparison, or "1.10.0" would sort
|
|
388
|
+
* below "1.4.0". A version that cannot be read at all answers FALSE, which is
|
|
389
|
+
* the safe direction for the one thing this decides: whether to hand a child
|
|
390
|
+
* a flag an older build of it would reject outright. A gate that refused an
|
|
391
|
+
* unknown flag would exit non-zero with no JSON, which the umbrella reports
|
|
392
|
+
* as could-not-run, so guessing high turns a working run into a broken one
|
|
393
|
+
* for every repository pinning an older gate.
|
|
394
|
+
*/
|
|
395
|
+
export function atLeastVersion(version, minimum) {
|
|
396
|
+
if (version === null) {
|
|
397
|
+
return false;
|
|
398
|
+
}
|
|
399
|
+
const parse = (value) => {
|
|
400
|
+
const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(value.trim());
|
|
401
|
+
return match === null ? [] : [Number(match[1]), Number(match[2]), Number(match[3])];
|
|
402
|
+
};
|
|
403
|
+
const actual = parse(version);
|
|
404
|
+
const wanted = parse(minimum);
|
|
405
|
+
if (actual.length !== 3 || wanted.length !== 3) {
|
|
406
|
+
return false;
|
|
407
|
+
}
|
|
408
|
+
for (let index = 0; index < 3; index += 1) {
|
|
409
|
+
if (actual[index] !== wanted[index]) {
|
|
410
|
+
return actual[index] > wanted[index];
|
|
411
|
+
}
|
|
412
|
+
}
|
|
413
|
+
return true;
|
|
414
|
+
}
|