@vaultcompass/conductor 0.18.0 → 0.19.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 +204 -61
- package/dist/adoption-proposal.d.ts +36 -0
- package/dist/adoption-proposal.js +260 -0
- package/dist/cli.d.ts +25 -7
- package/dist/cli.js +181 -47
- package/dist/escape.d.ts +36 -0
- package/dist/escape.js +49 -0
- package/dist/existing-findings.d.ts +38 -0
- package/dist/existing-findings.js +206 -0
- package/dist/gate-runner.d.ts +13 -9
- package/dist/gate-runner.js +145 -37
- package/dist/git.d.ts +70 -0
- package/dist/git.js +141 -6
- package/dist/init.js +9 -0
- package/dist/intent-prepare.js +4 -0
- package/dist/osv-coverage.js +6 -5
- package/dist/output-sarif.js +52 -8
- package/dist/output-text.d.ts +117 -8
- package/dist/output-text.js +374 -39
- package/dist/policy-diff.d.ts +2 -9
- package/dist/policy-diff.js +4 -11
- package/dist/policy.d.ts +9 -0
- package/dist/policy.js +21 -3
- package/dist/rule-ids.d.ts +42 -0
- package/dist/rule-ids.js +100 -0
- package/dist/run.d.ts +80 -0
- package/dist/run.js +70 -3
- package/package.json +1 -1
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
// When a pull request that adds .guardrails.yaml may be reported as a
|
|
2
|
+
// PROPOSAL, exit 0, instead of the refusal every other policy-less base gets
|
|
3
|
+
// (issue 101).
|
|
4
|
+
//
|
|
5
|
+
// A proposal is a run that enforces nothing and still exits 0, so this file
|
|
6
|
+
// is trust-boundary code and it has one direction: every function here either
|
|
7
|
+
// says "all of this holds" or gives a reason to refuse, and anything it cannot
|
|
8
|
+
// establish is a reason. Nothing here falls back, guesses, or reads a failed
|
|
9
|
+
// git call as "nothing there".
|
|
10
|
+
//
|
|
11
|
+
// What it establishes, beyond what src/cli.ts#policyForRun already has by the
|
|
12
|
+
// time it asks (the flag was given, the trust base passed its own checks, the
|
|
13
|
+
// exact file name is absent in the base tree, and the HEAD blob parses):
|
|
14
|
+
//
|
|
15
|
+
// - git's answers can be taken at their word (`disallowedGitVariables`);
|
|
16
|
+
// - the base has no policy under another spelling either
|
|
17
|
+
// (`policyNameVariants`);
|
|
18
|
+
// - the repository has its history (`refuseAdoptionProposal`, shallow);
|
|
19
|
+
// - this pull request ADDED the policy, rather than inheriting one the
|
|
20
|
+
// base has since dropped: no merge base of the trust base and HEAD
|
|
21
|
+
// carries it;
|
|
22
|
+
// - the base branch never carried one: nothing on its own first-parent
|
|
23
|
+
// history touched the file.
|
|
24
|
+
//
|
|
25
|
+
// Known limit, not closed here: a base branch force-rewound to before the
|
|
26
|
+
// commit that added the policy. A pull request branched from that commit
|
|
27
|
+
// inherits the file, its merge base with the rewound branch lacks it, and the
|
|
28
|
+
// rewound branch's first-parent history never held it. That takes a
|
|
29
|
+
// force-push to the default branch.
|
|
30
|
+
import { escapeNonAscii } from './escape.js';
|
|
31
|
+
import { gitComplaint, runGit } from './git.js';
|
|
32
|
+
import { POLICY_FILE_NAME } from './policy.js';
|
|
33
|
+
import { isFullObjectId, readFileAtRef, resolveRev } from './trust-base.js';
|
|
34
|
+
/**
|
|
35
|
+
* The GIT_ variables a proposal run may have in its environment. AN
|
|
36
|
+
* ALLOWLIST, never a deny list: git reads a long and growing set of GIT_
|
|
37
|
+
* variables, several of them redirect where objects, refs or the work tree
|
|
38
|
+
* are read from (GIT_DIR, GIT_COMMON_DIR, GIT_OBJECT_DIRECTORY,
|
|
39
|
+
* GIT_ALTERNATE_OBJECT_DIRECTORIES, GIT_WORK_TREE, GIT_NAMESPACE,
|
|
40
|
+
* GIT_INDEX_FILE) or how a path is matched (GIT_LITERAL_PATHSPECS,
|
|
41
|
+
* GIT_ICASE_PATHSPECS, GIT_GLOB_PATHSPECS, GIT_NOGLOB_PATHSPECS), and a list
|
|
42
|
+
* of the dangerous ones is wrong the day git adds another. On every other
|
|
43
|
+
* run a redirected git gives a wrong refusal; on this one it would give a
|
|
44
|
+
* green check, because "the base has no policy" is the answer the exit code
|
|
45
|
+
* rests on.
|
|
46
|
+
*
|
|
47
|
+
* Each entry says why that name cannot turn a policy that is there into one
|
|
48
|
+
* that is not.
|
|
49
|
+
*/
|
|
50
|
+
const ALLOWED_GIT_VARIABLES = [
|
|
51
|
+
{
|
|
52
|
+
name: /^GIT_NO_REPLACE_OBJECTS$/,
|
|
53
|
+
why: 'The Action exports it for the gates step, and every git call here sets it anyway ' +
|
|
54
|
+
'(src/git.ts#pinnedGitEnv). git tests it for presence only, so any value turns replace ' +
|
|
55
|
+
'objects off, which is the direction wanted.',
|
|
56
|
+
},
|
|
57
|
+
{
|
|
58
|
+
name: /^GIT_GRAFT_FILE$/,
|
|
59
|
+
why: 'Overwritten on every git call here with a path that cannot exist ' +
|
|
60
|
+
'(src/git.ts#pinnedGitEnv), so the value in the environment is never the one git reads.',
|
|
61
|
+
},
|
|
62
|
+
{
|
|
63
|
+
name: /^GIT_TERMINAL_PROMPT$/,
|
|
64
|
+
why: 'The Action sets it to 0 for the gates step. It only decides whether git may ask for a ' +
|
|
65
|
+
'credential on a terminal; no read of a local object consults it.',
|
|
66
|
+
},
|
|
67
|
+
{
|
|
68
|
+
name: /^GIT_CONFIG_COUNT$|^GIT_CONFIG_(KEY|VALUE)_(0|[1-9][0-9]*)$/,
|
|
69
|
+
why: 'Configuration handed over in the environment, which the Action preserves by design (its ' +
|
|
70
|
+
'fetch step appends to a count already there). Configuration CAN bring replace objects ' +
|
|
71
|
+
'back over GIT_NO_REPLACE_OBJECTS (core.useReplaceRefs=true), here or in any file git ' +
|
|
72
|
+
'reads, which is why every git call conductor makes passes core.useReplaceRefs=false and ' +
|
|
73
|
+
'core.commitGraph=false on the command line (src/git.ts#PINNED_GIT_CONFIG): the command ' +
|
|
74
|
+
'line outranks these entries, GIT_CONFIG_PARAMETERS and every file. A gate conductor ' +
|
|
75
|
+
'starts gets core.useReplaceRefs=false appended after these entries, and that value plus ' +
|
|
76
|
+
'core.commitGraph=false appended to GIT_CONFIG_PARAMETERS (src/git.ts#gateChildEnv), ' +
|
|
77
|
+
'because conductor cannot put that command line on a git call the gate makes. ' +
|
|
78
|
+
'GIT_CONFIG_PARAMETERS is not on this list. Configuration has no key for a graft file or for ' +
|
|
79
|
+
'pathspec matching, and cannot move the object store; the design review tried ' +
|
|
80
|
+
'core.worktree and core.bare against the tree listing and the entry was still listed. It ' +
|
|
81
|
+
'can make a read FAIL, and a failed read is an error here, never absent.',
|
|
82
|
+
},
|
|
83
|
+
{
|
|
84
|
+
name: /^GIT_(AUTHOR|COMMITTER)_(NAME|EMAIL|DATE)$/,
|
|
85
|
+
why: 'The identity and date git writes into a commit or a reflog entry it creates. No read of ' +
|
|
86
|
+
'an object, a tree or a history consults them, and a workflow that sets a bot identity ' +
|
|
87
|
+
'for the whole job would otherwise have a genuine adoption refused.',
|
|
88
|
+
},
|
|
89
|
+
];
|
|
90
|
+
/**
|
|
91
|
+
* Every GIT_ variable in `env` that is not on the allowlist, sorted. Matched
|
|
92
|
+
* on the upper-cased name, so a lower-case spelling (which Windows treats as
|
|
93
|
+
* the same variable) is caught, and present-but-empty counts: git treats
|
|
94
|
+
* several of these as set whatever they hold.
|
|
95
|
+
*/
|
|
96
|
+
export function disallowedGitVariables(env) {
|
|
97
|
+
return Object.keys(env)
|
|
98
|
+
.filter((name) => env[name] !== undefined && name.toUpperCase().startsWith('GIT_'))
|
|
99
|
+
.filter((name) => !ALLOWED_GIT_VARIABLES.some((allowed) => allowed.name.test(name)))
|
|
100
|
+
.sort();
|
|
101
|
+
}
|
|
102
|
+
/**
|
|
103
|
+
* A file name as a case-insensitive, normalization-insensitive file system
|
|
104
|
+
* compares it, near enough to refuse on: compatibility-decomposed, the code
|
|
105
|
+
* points HFS+ ignores removed, upper-cased then lower-cased (so a long s
|
|
106
|
+
* meets s). Errs toward calling two names the same.
|
|
107
|
+
*/
|
|
108
|
+
function foldedName(name) {
|
|
109
|
+
return name
|
|
110
|
+
.normalize('NFKD')
|
|
111
|
+
.replace(/[---]/g, '')
|
|
112
|
+
.toUpperCase()
|
|
113
|
+
.toLowerCase();
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* The entries at the root of `commit`'s tree whose name is the policy file
|
|
117
|
+
* name under another spelling (`.Guardrails.yaml`), or the reason the root
|
|
118
|
+
* could not be listed.
|
|
119
|
+
*
|
|
120
|
+
* `src/policy.ts#loadPolicy` reads the policy from disk by name, so on a
|
|
121
|
+
* case-insensitive file system (the macOS runners) a push run finds and
|
|
122
|
+
* enforces `.Guardrails.yaml`, while every read from a ref here asks git for
|
|
123
|
+
* the exact name and is told there is none. Such a base has a policy.
|
|
124
|
+
*/
|
|
125
|
+
export function policyNameVariants(repoRoot, commit) {
|
|
126
|
+
if (!isFullObjectId(commit)) {
|
|
127
|
+
return { kind: 'error', detail: `"${commit}" is not a full commit id` };
|
|
128
|
+
}
|
|
129
|
+
const listed = runGit(repoRoot, ['ls-tree', '--name-only', '-z', commit]);
|
|
130
|
+
if (listed.error !== undefined || listed.status !== 0) {
|
|
131
|
+
return { kind: 'error', detail: `cannot list the root of ${commit}: ${gitComplaint(listed)}` };
|
|
132
|
+
}
|
|
133
|
+
const wanted = foldedName(POLICY_FILE_NAME);
|
|
134
|
+
return {
|
|
135
|
+
kind: 'listed',
|
|
136
|
+
names: listed.stdout
|
|
137
|
+
.split('\0')
|
|
138
|
+
.filter((name) => name !== '' && name !== POLICY_FILE_NAME && foldedName(name) === wanted),
|
|
139
|
+
};
|
|
140
|
+
}
|
|
141
|
+
/** A name from a tree, quoted and with nothing outside printable ASCII. */
|
|
142
|
+
function shownName(name) {
|
|
143
|
+
return escapeNonAscii(JSON.stringify(name));
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* How a base branch that once had a policy, or lost one, gets one back. A
|
|
147
|
+
* pull request cannot do it as a proposal, by the two history rules below.
|
|
148
|
+
*/
|
|
149
|
+
const LAND_IT_FIRST = `Land ${POLICY_FILE_NAME} on the base branch first: the pull request that adds it is judged ` +
|
|
150
|
+
'against this same base, so it has to be merged by someone allowed to merge without this ' +
|
|
151
|
+
'check passing.';
|
|
152
|
+
/**
|
|
153
|
+
* Why this run is NOT an adoption proposal, or null when every condition
|
|
154
|
+
* holds. Called only after the caller has established that the flag was
|
|
155
|
+
* given, that the trust base passed its own checks, that the exact policy
|
|
156
|
+
* file name is absent in the trust base's tree, and that the HEAD blob
|
|
157
|
+
* parses.
|
|
158
|
+
*
|
|
159
|
+
* The reason is one or two sentences for the refusal the caller reports;
|
|
160
|
+
* every enabled gate is then could-not-run and the run exits 2, exactly as
|
|
161
|
+
* on a base without a policy before this file existed.
|
|
162
|
+
*/
|
|
163
|
+
export function refuseAdoptionProposal(repoRoot, trustBase, env = process.env) {
|
|
164
|
+
// THE ENVIRONMENT FIRST, before any answer from git is believed.
|
|
165
|
+
const unexpected = disallowedGitVariables(env);
|
|
166
|
+
if (unexpected.length > 0) {
|
|
167
|
+
return (`${unexpected.join(', ')} ${unexpected.length === 1 ? 'is' : 'are'} set in the environment of ` +
|
|
168
|
+
'this run. conductor reports a proposal only when it can take git at its word that the base ' +
|
|
169
|
+
'has no policy, and a GIT_ variable can change what git reads. Unset ' +
|
|
170
|
+
`${unexpected.length === 1 ? 'it' : 'them'} for this step.`);
|
|
171
|
+
}
|
|
172
|
+
const base = resolveRev(repoRoot, trustBase, 'commit');
|
|
173
|
+
const head = resolveRev(repoRoot, 'HEAD', 'commit');
|
|
174
|
+
if (base === null || head === null || !isFullObjectId(base) || !isFullObjectId(head)) {
|
|
175
|
+
return `"${trustBase}" and HEAD could not both be resolved to commits, so their history could not be read.`;
|
|
176
|
+
}
|
|
177
|
+
// THE BASE ROOT, UNDER ANY SPELLING.
|
|
178
|
+
const atBase = policyNameVariants(repoRoot, base);
|
|
179
|
+
if (atBase.kind === 'error') {
|
|
180
|
+
return `whether "${trustBase}" holds the policy file under another spelling could not be checked: ${atBase.detail}.`;
|
|
181
|
+
}
|
|
182
|
+
if (atBase.names.length > 0) {
|
|
183
|
+
return (`"${trustBase}" holds ${atBase.names.map(shownName).join(', ')} at its root, which is the policy ` +
|
|
184
|
+
'file name in another spelling, and a run on a case-insensitive file system reads that file ' +
|
|
185
|
+
`as the policy. So this base is not a base without one. Rename it to ${POLICY_FILE_NAME} on ` +
|
|
186
|
+
'the base branch.');
|
|
187
|
+
}
|
|
188
|
+
// A SHALLOW REPOSITORY CANNOT ANSWER THE NEXT TWO QUESTIONS. A commit at
|
|
189
|
+
// the shallow boundary reads as a commit with no parents, so a merge base
|
|
190
|
+
// can be missed and a history that carried a policy reads as one that
|
|
191
|
+
// never did.
|
|
192
|
+
const shallow = runGit(repoRoot, ['rev-parse', '--is-shallow-repository']);
|
|
193
|
+
if (shallow.error !== undefined || shallow.status !== 0 || shallow.stdout.trim() !== 'false') {
|
|
194
|
+
return (shallow.error === undefined && shallow.status === 0 && shallow.stdout.trim() === 'true'
|
|
195
|
+
? 'this is a shallow repository, so the history that would show whether the base branch ' +
|
|
196
|
+
'ever carried a policy is not here.'
|
|
197
|
+
: `whether this repository is shallow could not be checked (${gitComplaint(shallow)}).`) + ' Check out with fetch-depth: 0.';
|
|
198
|
+
}
|
|
199
|
+
// EVERY MERGE BASE. When no commit the pull request shares with the base
|
|
200
|
+
// carries the policy and HEAD does, the pull request added it. When one
|
|
201
|
+
// does, the pull request inherited it and the base has dropped it since:
|
|
202
|
+
// a merge ref built before a deletion landed, or a branch cut before one.
|
|
203
|
+
// --all, and every one of them read: a criss-cross history has more than
|
|
204
|
+
// one merge base. The parents come from the commits themselves, never
|
|
205
|
+
// from a replace ref, a graft or a commit-graph file left in the git
|
|
206
|
+
// directory: runGit pins all three on every call.
|
|
207
|
+
const bases = runGit(repoRoot, ['merge-base', '--all', base, head]);
|
|
208
|
+
const mergeBases = bases.stdout.split('\n').filter((line) => line !== '');
|
|
209
|
+
if (bases.error === undefined && bases.status === 1 && mergeBases.length === 0) {
|
|
210
|
+
return (`"${trustBase}" and HEAD share no history, so nothing shows that this pull request is the one ` +
|
|
211
|
+
'that added the policy.');
|
|
212
|
+
}
|
|
213
|
+
if (bases.error !== undefined ||
|
|
214
|
+
bases.status !== 0 ||
|
|
215
|
+
mergeBases.length === 0 ||
|
|
216
|
+
!mergeBases.every(isFullObjectId)) {
|
|
217
|
+
return `the merge base of "${trustBase}" and HEAD could not be read (${gitComplaint(bases)}).`;
|
|
218
|
+
}
|
|
219
|
+
for (const mergeBase of mergeBases) {
|
|
220
|
+
const read = readFileAtRef(repoRoot, mergeBase, POLICY_FILE_NAME);
|
|
221
|
+
if (read.kind === 'error') {
|
|
222
|
+
return `${POLICY_FILE_NAME} could not be read at the merge base ${mergeBase}: ${read.detail}.`;
|
|
223
|
+
}
|
|
224
|
+
const variants = read.kind === 'file' ? null : policyNameVariants(repoRoot, mergeBase);
|
|
225
|
+
if (variants !== null && variants.kind === 'error') {
|
|
226
|
+
return `the merge base ${mergeBase} could not be listed: ${variants.detail}.`;
|
|
227
|
+
}
|
|
228
|
+
if (variants === null || variants.names.length > 0) {
|
|
229
|
+
return (`the history this pull request shares with "${trustBase}" carries a ${POLICY_FILE_NAME} at ` +
|
|
230
|
+
`the merge base ${mergeBase}, so this pull request did not add the policy: the base branch ` +
|
|
231
|
+
`dropped it after this branch, or its merge ref, was made. ${LAND_IT_FIRST}`);
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
// THE BASE BRANCH'S OWN HISTORY. One commit on its first-parent chain that
|
|
235
|
+
// added, changed or removed the file means the branch has carried a policy
|
|
236
|
+
// and no longer does, and a pull request that adds one after that is the
|
|
237
|
+
// second half of "delete the rules, then propose weaker ones". rev-list,
|
|
238
|
+
// the plumbing form of `git log --first-parent -1 <base> -- <file>`, so no
|
|
239
|
+
// log configuration reaches it. Matched in any case, as the root listing
|
|
240
|
+
// above is. Empty output is the only answer that passes.
|
|
241
|
+
const touched = runGit(repoRoot, [
|
|
242
|
+
'rev-list',
|
|
243
|
+
'--first-parent',
|
|
244
|
+
'-n',
|
|
245
|
+
'1',
|
|
246
|
+
base,
|
|
247
|
+
'--',
|
|
248
|
+
`:(icase)${POLICY_FILE_NAME}`,
|
|
249
|
+
]);
|
|
250
|
+
if (touched.error !== undefined || touched.status !== 0) {
|
|
251
|
+
return `the history of "${trustBase}" could not be read (${gitComplaint(touched)}). Check out with fetch-depth: 0.`;
|
|
252
|
+
}
|
|
253
|
+
const commit = touched.stdout.trim();
|
|
254
|
+
if (commit !== '') {
|
|
255
|
+
return (`the base branch has carried a ${POLICY_FILE_NAME} before: ` +
|
|
256
|
+
`${isFullObjectId(commit) ? `commit ${commit}` : 'a commit'} on the first-parent history of ` +
|
|
257
|
+
`"${trustBase}" added, changed or removed one. So this is not a first adoption. ${LAND_IT_FIRST}`);
|
|
258
|
+
}
|
|
259
|
+
return null;
|
|
260
|
+
}
|
package/dist/cli.d.ts
CHANGED
|
@@ -2,12 +2,6 @@
|
|
|
2
2
|
import { Command } from 'commander';
|
|
3
3
|
import type { CliOverrides, Policy } from './policy.js';
|
|
4
4
|
import type { RunTrustBase } from './run.js';
|
|
5
|
-
/**
|
|
6
|
-
* Whether the text report is rendered for a terminal: only when it goes to
|
|
7
|
-
* stdout (no --output) and stdout is a TTY. A file, a pipe and the
|
|
8
|
-
* --text-report copy never are, so they stay byte for byte as before.
|
|
9
|
-
*/
|
|
10
|
-
export declare function rendersToTerminal(output: string | undefined, stdoutIsTTY: boolean | undefined): boolean;
|
|
11
5
|
/**
|
|
12
6
|
* The policy for one run, and where it came from.
|
|
13
7
|
*
|
|
@@ -28,6 +22,21 @@ type PolicyForRun = {
|
|
|
28
22
|
*/
|
|
29
23
|
previewPolicy: Policy | null;
|
|
30
24
|
}
|
|
25
|
+
/**
|
|
26
|
+
* The policy this pull request ADDS, on a base that has none (issue 101):
|
|
27
|
+
* `enabled`, `stage` and `enforce` from the HEAD blob and nothing else.
|
|
28
|
+
*
|
|
29
|
+
* A SEPARATE VARIANT WITH NO `previewPolicy` FIELD, on purpose. The preview
|
|
30
|
+
* withholds --trust-base from dep-guard and vault-guard, so each reads its
|
|
31
|
+
* own config from the head; on a proposal that would let the pull
|
|
32
|
+
* request's own config hide what it adds. With no field to set, no later
|
|
33
|
+
* edit can attach a preview to a proposal, and --preview is ignored on one.
|
|
34
|
+
*/
|
|
35
|
+
| {
|
|
36
|
+
kind: 'proposal';
|
|
37
|
+
policy: Policy;
|
|
38
|
+
trustBase: RunTrustBase;
|
|
39
|
+
}
|
|
31
40
|
/** The trust base could not be judged against. `inventory` only names gates. */
|
|
32
41
|
| {
|
|
33
42
|
kind: 'refused';
|
|
@@ -35,6 +44,8 @@ type PolicyForRun = {
|
|
|
35
44
|
detail: string;
|
|
36
45
|
inventory: Policy;
|
|
37
46
|
notGiven?: boolean;
|
|
47
|
+
/** Neither the base nor HEAD has a policy file. */
|
|
48
|
+
noPolicy?: boolean;
|
|
38
49
|
};
|
|
39
50
|
/**
|
|
40
51
|
* Exported so a test can see that no preview policy is built unless one was
|
|
@@ -42,6 +53,13 @@ type PolicyForRun = {
|
|
|
42
53
|
*/
|
|
43
54
|
export declare function policyForRun(root: string, trustBase: string | undefined, overrides: CliOverrides, githubBaseRef: string | undefined, githubActions: string | undefined,
|
|
44
55
|
/** Whether this run asked for the preview under the proposed rules. */
|
|
45
|
-
preview?: boolean
|
|
56
|
+
preview?: boolean,
|
|
57
|
+
/**
|
|
58
|
+
* Whether --adoption-proposal was given. Without it a base with no policy
|
|
59
|
+
* is refused exactly as before the flag existed, whoever calls the CLI.
|
|
60
|
+
*/
|
|
61
|
+
adoptionProposal?: boolean,
|
|
62
|
+
/** The environment git will run in, for the proposal's own check of it. */
|
|
63
|
+
env?: NodeJS.ProcessEnv): PolicyForRun;
|
|
46
64
|
export declare function buildProgram(): Command;
|
|
47
65
|
export {};
|