@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
package/dist/git.js
CHANGED
|
@@ -9,8 +9,15 @@
|
|
|
9
9
|
// other. Outside pull-request mode this is plain `git`, found the way a
|
|
10
10
|
// shell finds it.
|
|
11
11
|
//
|
|
12
|
-
// - REPLACE OBJECTS ARE IGNORED.
|
|
13
|
-
//
|
|
12
|
+
// - REPLACE OBJECTS, GRAFTS AND A COMMIT-GRAPH FILE ARE IGNORED. Every call
|
|
13
|
+
// passes core.useReplaceRefs=false and core.commitGraph=false on the
|
|
14
|
+
// command line (`PINNED_GIT_CONFIG`), where no configuration file and no
|
|
15
|
+
// GIT_CONFIG_COUNT entry can outrank them, and sets GIT_NO_REPLACE_OBJECTS
|
|
16
|
+
// as well, so every read here sees the commit's own objects. The variable
|
|
17
|
+
// alone is not enough: configuration can turn replacement back on over
|
|
18
|
+
// it. GIT_GRAFT_FILE names a path that cannot exist, so every read of a
|
|
19
|
+
// commit's parents sees the parents the commit itself records
|
|
20
|
+
// (`pinnedGitEnv`); git has no configuration key for a graft file.
|
|
14
21
|
//
|
|
15
22
|
// - NOTHING HERE DECIDES WHAT A FAILURE MEANS. The result carries the exit
|
|
16
23
|
// status and the error, and each caller keeps "git said there is nothing
|
|
@@ -31,13 +38,141 @@ export function currentGitProgram() {
|
|
|
31
38
|
export function useGitProgram(program) {
|
|
32
39
|
gitProgram = program;
|
|
33
40
|
}
|
|
41
|
+
/**
|
|
42
|
+
* A graft file path that cannot exist: /dev/null is not a directory, so
|
|
43
|
+
* nothing can be created under it. The same value the Action's fetch step
|
|
44
|
+
* exports (action.yml, "Fetch the trust base"). git reads a missing graft
|
|
45
|
+
* file as no grafts, without a warning.
|
|
46
|
+
*/
|
|
47
|
+
export const NO_GRAFT_FILE = '/dev/null/conductor-no-grafts';
|
|
48
|
+
/**
|
|
49
|
+
* git loads a commit-graph file when GIT_TEST_COMMIT_GRAPH is true, over
|
|
50
|
+
* core.commitGraph=false on the command line and in GIT_CONFIG_PARAMETERS.
|
|
51
|
+
* The environments conductor builds do not pass the variable on. A value
|
|
52
|
+
* that is absent stays absent. The caller's object is never changed.
|
|
53
|
+
*/
|
|
54
|
+
function withoutCommitGraphTestVariable(env) {
|
|
55
|
+
if (!Object.prototype.hasOwnProperty.call(env, 'GIT_TEST_COMMIT_GRAPH')) {
|
|
56
|
+
return env;
|
|
57
|
+
}
|
|
58
|
+
const copy = { ...env };
|
|
59
|
+
delete copy.GIT_TEST_COMMIT_GRAPH;
|
|
60
|
+
return copy;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* The environment of every git call conductor makes itself: the caller's
|
|
64
|
+
* own, with replace objects off and the graft file pointed at nothing.
|
|
65
|
+
*
|
|
66
|
+
* A replace ref swaps one object for another and a graft gives a commit
|
|
67
|
+
* other parents, both from files in the git directory that no commit
|
|
68
|
+
* records. The trees were always read without the first. The second matters
|
|
69
|
+
* since the adoption proposal (issue 101), which asks what the merge bases
|
|
70
|
+
* of two commits are and what the base branch's own first-parent history
|
|
71
|
+
* touched: both answers are read from parents, and a graft would rewrite
|
|
72
|
+
* them. Set last, so a value already in the environment never wins.
|
|
73
|
+
*/
|
|
74
|
+
export function pinnedGitEnv(env = process.env) {
|
|
75
|
+
return { ...withoutCommitGraphTestVariable(env), GIT_NO_REPLACE_OBJECTS: '1', GIT_GRAFT_FILE: NO_GRAFT_FILE };
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Configuration set on the command line of every git call conductor makes
|
|
79
|
+
* itself, ahead of the subcommand. The command line outranks every other
|
|
80
|
+
* place git reads configuration from: the system, global and repository
|
|
81
|
+
* files, anything they include, and GIT_CONFIG_COUNT in the environment.
|
|
82
|
+
*
|
|
83
|
+
* - core.useReplaceRefs=false. GIT_NO_REPLACE_OBJECTS is NOT enough on its
|
|
84
|
+
* own: the same key set to true in any configuration git reads turns
|
|
85
|
+
* replacement back on over the variable (seen on git 2.39.3), and a
|
|
86
|
+
* replace ref can then swap the base commit for one with another tree and
|
|
87
|
+
* other parents. The variable stays as well, for a git where it is the
|
|
88
|
+
* one that counts.
|
|
89
|
+
* - core.commitGraph=false. A commit-graph file in the git directory holds
|
|
90
|
+
* each commit's parents and root tree, and no commit records it, so every
|
|
91
|
+
* read takes both from the commit object itself.
|
|
92
|
+
*/
|
|
93
|
+
export const PINNED_GIT_CONFIG = [
|
|
94
|
+
'-c',
|
|
95
|
+
'core.useReplaceRefs=false',
|
|
96
|
+
'-c',
|
|
97
|
+
'core.commitGraph=false',
|
|
98
|
+
];
|
|
99
|
+
/**
|
|
100
|
+
* GIT_CONFIG_COUNT as git reads it (strtoul, base 10): leading white space,
|
|
101
|
+
* an optional sign, then digits and nothing after them. The number of
|
|
102
|
+
* entries, or null when git itself refuses the value: something after the
|
|
103
|
+
* digits, a negative number other than zero, or more than a 32-bit int
|
|
104
|
+
* holds. Unset and empty are both zero entries.
|
|
105
|
+
*/
|
|
106
|
+
function configCountAsGitReadsIt(raw) {
|
|
107
|
+
if (raw === undefined || raw === '') {
|
|
108
|
+
return 0;
|
|
109
|
+
}
|
|
110
|
+
const read = raw.match(/^[ \t\n\v\f\r]*([+-]?)([0-9]+)$/);
|
|
111
|
+
if (read === null) {
|
|
112
|
+
return null;
|
|
113
|
+
}
|
|
114
|
+
const count = Number(read[2]);
|
|
115
|
+
if (!Number.isSafeInteger(count) || count > 2147483646 || (read[1] === '-' && count !== 0)) {
|
|
116
|
+
return null;
|
|
117
|
+
}
|
|
118
|
+
return count;
|
|
119
|
+
}
|
|
120
|
+
/**
|
|
121
|
+
* The environment of a gate conductor starts: `env`, plus the pins below.
|
|
122
|
+
* GIT_TEST_COMMIT_GRAPH is not passed on. A `-c` the gate itself adds is
|
|
123
|
+
* not something this function can outrank.
|
|
124
|
+
*
|
|
125
|
+
* conductor cannot put anything on the command line of a git call a gate
|
|
126
|
+
* makes itself. What it can give the gate is the two environment channels
|
|
127
|
+
* git reads configuration from. Numbered GIT_CONFIG_COUNT pairs are read
|
|
128
|
+
* after every configuration file, so an entry there outranks
|
|
129
|
+
* core.useReplaceRefs=true in the repository's configuration or a global
|
|
130
|
+
* one. GIT_CONFIG_PARAMETERS is read after those numbered entries, so it
|
|
131
|
+
* outranks them and the files. GIT_NO_REPLACE_OBJECTS does not: such a
|
|
132
|
+
* setting turns replacement back on over it. A -c the gate passes on its
|
|
133
|
+
* own git command line is read after GIT_CONFIG_PARAMETERS and still wins;
|
|
134
|
+
* none of the spawns here pass one.
|
|
135
|
+
*
|
|
136
|
+
* The numbered entry is APPENDED, at the index the caller's own count ends
|
|
137
|
+
* on, never written at index 0: the caller's entries are kept (an Action's
|
|
138
|
+
* authentication header is one), and of two entries for one key git takes
|
|
139
|
+
* the later. It is core.useReplaceRefs=false only. The same value, and
|
|
140
|
+
* core.commitGraph=false, are appended to GIT_CONFIG_PARAMETERS after
|
|
141
|
+
* exactly one space. When the caller's value is unset or the empty string
|
|
142
|
+
* the two pins are the whole value, with no leading space. The caller's
|
|
143
|
+
* value is not trimmed, parsed or repaired.
|
|
144
|
+
*
|
|
145
|
+
* A count git refuses is left exactly as it is and nothing is appended to
|
|
146
|
+
* the numbered entries. The parameters pins are still set on that branch,
|
|
147
|
+
* so there is no branch where they are absent. With a count git refuses,
|
|
148
|
+
* every git call fails, and a failed read is a refusal everywhere here;
|
|
149
|
+
* rewriting the count to make git work again would be conductor deciding
|
|
150
|
+
* what the caller meant. Returns a new object and never changes `env`.
|
|
151
|
+
*/
|
|
152
|
+
export function gateChildEnv(env = process.env) {
|
|
153
|
+
const source = withoutCommitGraphTestVariable(env);
|
|
154
|
+
const pins = "'core.useReplaceRefs=false' 'core.commitGraph=false'";
|
|
155
|
+
const caller = source.GIT_CONFIG_PARAMETERS;
|
|
156
|
+
const parameters = caller === undefined || caller === '' ? pins : `${caller} ${pins}`;
|
|
157
|
+
const count = configCountAsGitReadsIt(source.GIT_CONFIG_COUNT);
|
|
158
|
+
if (count === null) {
|
|
159
|
+
return { ...source, GIT_CONFIG_PARAMETERS: parameters };
|
|
160
|
+
}
|
|
161
|
+
return {
|
|
162
|
+
...source,
|
|
163
|
+
GIT_CONFIG_COUNT: String(count + 1),
|
|
164
|
+
[`GIT_CONFIG_KEY_${count}`]: 'core.useReplaceRefs',
|
|
165
|
+
[`GIT_CONFIG_VALUE_${count}`]: 'false',
|
|
166
|
+
GIT_CONFIG_PARAMETERS: parameters,
|
|
167
|
+
};
|
|
168
|
+
}
|
|
34
169
|
/** Runs one git command in `cwd`, reading stdout as UTF-8. Never throws. */
|
|
35
170
|
export function runGit(cwd, args, options = {}) {
|
|
36
|
-
const child = spawnSync(gitProgram, [...args], {
|
|
171
|
+
const child = spawnSync(gitProgram, [...PINNED_GIT_CONFIG, ...args], {
|
|
37
172
|
cwd,
|
|
38
173
|
encoding: 'utf8',
|
|
39
174
|
maxBuffer: options.maxBuffer ?? 32 * 1024 * 1024,
|
|
40
|
-
env:
|
|
175
|
+
env: pinnedGitEnv(),
|
|
41
176
|
...(options.input === undefined ? {} : { input: options.input }),
|
|
42
177
|
});
|
|
43
178
|
return {
|
|
@@ -54,10 +189,10 @@ export function runGit(cwd, args, options = {}) {
|
|
|
54
189
|
* program, same environment and same never-throws contract as runGit.
|
|
55
190
|
*/
|
|
56
191
|
export function runGitBytes(cwd, args, options = {}) {
|
|
57
|
-
const child = spawnSync(gitProgram, [...args], {
|
|
192
|
+
const child = spawnSync(gitProgram, [...PINNED_GIT_CONFIG, ...args], {
|
|
58
193
|
cwd,
|
|
59
194
|
maxBuffer: options.maxBuffer ?? 64 * 1024 * 1024,
|
|
60
|
-
env:
|
|
195
|
+
env: pinnedGitEnv(),
|
|
61
196
|
});
|
|
62
197
|
return {
|
|
63
198
|
status: child.status,
|
package/dist/init.js
CHANGED
|
@@ -542,6 +542,15 @@ function finishPlan(options, root, policyPath, base, actions, writes, records, h
|
|
|
542
542
|
`job without ${one ? 'it' : 'them'} gets conductor/gate-missing and exit 2; set enabled: ` +
|
|
543
543
|
`false in ${POLICY_FILE_NAME} if that is not wanted.`);
|
|
544
544
|
}
|
|
545
|
+
// What the first run will show, said once at the point the history gate is
|
|
546
|
+
// switched on. Words only: it changes no policy key and no verdict.
|
|
547
|
+
if (detected.has('secrets-history')) {
|
|
548
|
+
notes.push(`Note: the first conductor run with no base judges all of git history${detected.has('vulnerabilities') ? ' and every lockfile' : ''}; a pull request judges only its own change.`);
|
|
549
|
+
if (gitOutput(root, ['rev-parse', '--is-shallow-repository']) === 'true') {
|
|
550
|
+
notes.push('Note: this checkout is shallow, so the history gate will not run here until it is unshallowed ' +
|
|
551
|
+
'(git fetch --unshallow), and CI needs fetch-depth: 0 on actions/checkout. The gate stays enabled.');
|
|
552
|
+
}
|
|
553
|
+
}
|
|
545
554
|
}
|
|
546
555
|
else {
|
|
547
556
|
// Never rewritten. The policy file is the one artifact a user edits by
|
package/dist/intent-prepare.js
CHANGED
|
@@ -30,6 +30,7 @@
|
|
|
30
30
|
// distinguishes a shallow checkout from a spec the importer choked on is the
|
|
31
31
|
// sentence in the report.
|
|
32
32
|
import { spawnSync } from 'node:child_process';
|
|
33
|
+
import { gateChildEnv } from './git.js';
|
|
33
34
|
import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync, } from 'node:fs';
|
|
34
35
|
import os from 'node:os';
|
|
35
36
|
import path from 'node:path';
|
|
@@ -356,6 +357,9 @@ function run(command, argv, cwd, timeoutMs) {
|
|
|
356
357
|
encoding: 'utf8',
|
|
357
358
|
timeout: timeoutMs,
|
|
358
359
|
maxBuffer: 64 * 1024 * 1024,
|
|
360
|
+
// The same pin as every other gate spawn. conductor cannot put it on
|
|
361
|
+
// the command line of a git call this binary makes itself.
|
|
362
|
+
env: gateChildEnv(process.env),
|
|
359
363
|
});
|
|
360
364
|
return {
|
|
361
365
|
status: child.status,
|
package/dist/osv-coverage.js
CHANGED
|
@@ -9,6 +9,7 @@ import path from 'node:path';
|
|
|
9
9
|
import { runGit } from './git.js';
|
|
10
10
|
import { osvLockfileKind } from './products.js';
|
|
11
11
|
import { checkRequirementsPins, describePinProblem, } from './requirements-pin.js';
|
|
12
|
+
import { LOCKFILE_NO_LONGER_SCANNED, REQUIREMENTS_DIRECT_ONLY, REQUIREMENTS_NOT_PINNED, REQUIREMENTS_NOT_SCANNED, } from './rule-ids.js';
|
|
12
13
|
import { readFileAtRefBytes } from './trust-base.js';
|
|
13
14
|
/**
|
|
14
15
|
* A reader over the head: a TRACKED regular file on disk. On disk because
|
|
@@ -102,7 +103,7 @@ export function selectOsvInputs(args) {
|
|
|
102
103
|
suffix = ' Newly pinned in this pull request.';
|
|
103
104
|
}
|
|
104
105
|
}
|
|
105
|
-
notes.push({ code:
|
|
106
|
+
notes.push({ code: REQUIREMENTS_DIRECT_ONLY, message: `${file}: ${DIRECT_ONLY}${suffix}` });
|
|
106
107
|
continue;
|
|
107
108
|
}
|
|
108
109
|
if (base !== null) {
|
|
@@ -116,18 +117,18 @@ export function selectOsvInputs(args) {
|
|
|
116
117
|
? 'Its copy on the base is pinned, so the file stays scanned under the ratchet; the lines named are read as written.'
|
|
117
118
|
: 'Its copy on the base could not be read, so the file stays scanned; the lines named are read as written.';
|
|
118
119
|
diagnostics.push({
|
|
119
|
-
code:
|
|
120
|
+
code: REQUIREMENTS_NOT_PINNED,
|
|
120
121
|
message: `${file} is scanned although ${lines}. ${why}`,
|
|
121
122
|
});
|
|
122
123
|
notes.push({
|
|
123
|
-
code:
|
|
124
|
+
code: REQUIREMENTS_DIRECT_ONLY,
|
|
124
125
|
message: `${file}: ${DIRECT_ONLY} ${baseCheck.pinned ? 'Pinned on the base; scanned under the ratchet.' : 'Base copy unreadable; scanned under the ratchet.'}`,
|
|
125
126
|
});
|
|
126
127
|
continue;
|
|
127
128
|
}
|
|
128
129
|
}
|
|
129
130
|
notScanned.push(file);
|
|
130
|
-
diagnostics.push({ code:
|
|
131
|
+
diagnostics.push({ code: REQUIREMENTS_NOT_SCANNED, message: notScannedMessage(file, headCheck) });
|
|
131
132
|
}
|
|
132
133
|
return { handed: handed.sort(), notScanned, diagnostics, notes, closures };
|
|
133
134
|
}
|
|
@@ -142,7 +143,7 @@ export function selectOsvInputs(args) {
|
|
|
142
143
|
*/
|
|
143
144
|
export function noLongerScanned(repoRoot, ref, tracked) {
|
|
144
145
|
return (noLongerScannedFiles(repoRoot, ref, tracked) ?? []).map((file) => ({
|
|
145
|
-
code:
|
|
146
|
+
code: LOCKFILE_NO_LONGER_SCANNED,
|
|
146
147
|
message: `${file} is tracked on the base and not in this pull request, so it is no longer scanned ` +
|
|
147
148
|
'(by either run). Its removal is visible in the diff.',
|
|
148
149
|
}));
|
package/dist/output-sarif.js
CHANGED
|
@@ -124,7 +124,7 @@ import { INTENT_WARNING } from './normalize.js';
|
|
|
124
124
|
import { baseMovedSentences, gateOutcomeWords, intentEmptyChangeSet, intentNothingWording, intentCheckedNothing, intentSkipReason, skewFound, skewPlace, } from './output-text.js';
|
|
125
125
|
import { POLICY_FILE_NAME } from './policy.js';
|
|
126
126
|
import { policyChangeLine } from './policy-diff.js';
|
|
127
|
-
import { guardPreview } from './run.js';
|
|
127
|
+
import { guardPreview, isProposal, ranProposedPolicy } from './run.js';
|
|
128
128
|
const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json';
|
|
129
129
|
export const UMBRELLA_DRIVER_NAME = 'conductor';
|
|
130
130
|
/**
|
|
@@ -302,7 +302,7 @@ function withFallbackLocation(locations, fallbackUri) {
|
|
|
302
302
|
}
|
|
303
303
|
return locations.map((location) => location.physicalLocation === undefined ? { ...location, physicalLocation } : location);
|
|
304
304
|
}
|
|
305
|
-
function toResult(finding, fallbackUri) {
|
|
305
|
+
function toResult(finding, fallbackUri, proposal = false) {
|
|
306
306
|
// A path that escapes the source root gets no physical location, so the
|
|
307
307
|
// path itself is carried here instead. Dropping a location is honest;
|
|
308
308
|
// dropping the information as well would just lose the finding's subject.
|
|
@@ -316,6 +316,11 @@ function toResult(finding, fallbackUri) {
|
|
|
316
316
|
severity: finding.severity,
|
|
317
317
|
severityIsDerived: finding.severityIsDerived,
|
|
318
318
|
fingerprintStability: finding.fingerprint?.stability ?? 'none',
|
|
319
|
+
// On a run of the policy a pull request adds (issue 101): `blocking`
|
|
320
|
+
// above is what the proposed policy WOULD do, and nothing was enforced.
|
|
321
|
+
// On the result itself, so a consumer that reads results and never the
|
|
322
|
+
// run's properties still cannot take it for an enforced verdict.
|
|
323
|
+
...(proposal ? { proposal: true } : {}),
|
|
319
324
|
...(unplaceable.length === 0 ? {} : { unresolvablePaths: unplaceable }),
|
|
320
325
|
// The details bag verbatim. Not reshaped, not filtered: it is where
|
|
321
326
|
// each gate puts what it actually established.
|
|
@@ -378,7 +383,9 @@ function sarifTrustBase(trustBase) {
|
|
|
378
383
|
}
|
|
379
384
|
function makeRun(name, version, findings,
|
|
380
385
|
/** The artifact a result with no location of its own is filed against. */
|
|
381
|
-
fallbackUri, properties, invocation
|
|
386
|
+
fallbackUri, properties, invocation,
|
|
387
|
+
/** Whether this is a run of the policy a pull request adds (issue 101). */
|
|
388
|
+
proposal = false) {
|
|
382
389
|
const notifications = invocation?.notifications ?? [];
|
|
383
390
|
return {
|
|
384
391
|
tool: {
|
|
@@ -396,7 +403,7 @@ fallbackUri, properties, invocation) {
|
|
|
396
403
|
: { notifications: notificationDeclarations(notifications) }),
|
|
397
404
|
},
|
|
398
405
|
},
|
|
399
|
-
results: findings.map((finding) => toResult(finding, fallbackUri)),
|
|
406
|
+
results: findings.map((finding) => toResult(finding, fallbackUri, proposal)),
|
|
400
407
|
...(invocation === undefined
|
|
401
408
|
? {}
|
|
402
409
|
: {
|
|
@@ -715,11 +722,16 @@ function intentWarningNotifications(result) {
|
|
|
715
722
|
* gate that raised each line is in the details.
|
|
716
723
|
*/
|
|
717
724
|
function proposalNotifications(result) {
|
|
725
|
+
// On a run of the policy the pull request adds, no rule came from the ref:
|
|
726
|
+
// it has no policy. What did not take effect is said without that claim.
|
|
727
|
+
const source = ranProposedPolicy(result)
|
|
728
|
+
? `There is no policy on ${result.trustBase?.ref ?? 'the base ref'}, and this run took only ` +
|
|
729
|
+
'enabled, stage and enforce from the policy this pull request adds'
|
|
730
|
+
: `The rules came from ${result.trustBase?.ref ?? 'the base ref'}`;
|
|
718
731
|
return result.proposals.map((proposal) => ({
|
|
719
732
|
id: 'conductor/control-change-proposed',
|
|
720
733
|
message: `This pull request proposes a control change that did NOT take effect for this run: ` +
|
|
721
|
-
`${proposal.line} (${proposal.product}).
|
|
722
|
-
`${result.trustBase?.ref ?? 'the base ref'}; the proposed change decides what runs once ` +
|
|
734
|
+
`${proposal.line} (${proposal.product}). ${source}; the proposed change decides what runs once ` +
|
|
723
735
|
'it is on the base branch.',
|
|
724
736
|
details: {
|
|
725
737
|
product: proposal.product,
|
|
@@ -769,6 +781,37 @@ function previewNotifications(result) {
|
|
|
769
781
|
* inventory named sit beside it in the same run and carry the same sentence,
|
|
770
782
|
* so a consumer that reads only results still learns that nothing ran.
|
|
771
783
|
*/
|
|
784
|
+
/**
|
|
785
|
+
* A run of the policy a pull request adds to a base that has none (issue
|
|
786
|
+
* 101), said once on the umbrella's run.
|
|
787
|
+
*
|
|
788
|
+
* WARNING level, between the notes and the refusal's error: this is not a
|
|
789
|
+
* coverage statement about one gate, it is that NOTHING in this log was
|
|
790
|
+
* enforced, and a consumer reading only the log has to be able to tell that
|
|
791
|
+
* from an enforced run. Not an error, because nothing failed. It always
|
|
792
|
+
* exists on such a run, so the umbrella's run, and with it
|
|
793
|
+
* `properties.trustBase.proposal`, is always written.
|
|
794
|
+
*/
|
|
795
|
+
function proposalRunNotifications(result) {
|
|
796
|
+
if (!ranProposedPolicy(result)) {
|
|
797
|
+
return [];
|
|
798
|
+
}
|
|
799
|
+
const ref = result.trustBase?.ref ?? '';
|
|
800
|
+
return [
|
|
801
|
+
{
|
|
802
|
+
id: 'conductor/proposal-run',
|
|
803
|
+
level: 'warning',
|
|
804
|
+
message: `There is no ${POLICY_FILE_NAME} on "${ref}", so NOTHING IN THIS LOG WAS ENFORCED. This run ` +
|
|
805
|
+
'took enabled, stage and enforce from the policy this pull request adds and every other ' +
|
|
806
|
+
'setting from the product defaults. Each result is what would be reported once that policy ' +
|
|
807
|
+
'is on the base branch' +
|
|
808
|
+
(isProposal(result)
|
|
809
|
+
? ', and the run exits 0 whatever they say.'
|
|
810
|
+
: '. A gate the proposed policy enforces could not run, so the run is could-not-run.'),
|
|
811
|
+
details: { ref, reason: 'no-policy-on-base', exitCode: result.exitCode },
|
|
812
|
+
},
|
|
813
|
+
];
|
|
814
|
+
}
|
|
772
815
|
function trustBaseRefusedNotifications(result) {
|
|
773
816
|
const refusal = result.trustBase?.refusal;
|
|
774
817
|
if (refusal === undefined || refusal === null) {
|
|
@@ -1070,7 +1113,7 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
1070
1113
|
// only when there is something in it, so a gate that reports none of
|
|
1071
1114
|
// this keeps the properties shape it had before.
|
|
1072
1115
|
...(Object.keys(runDetails(gate)).length === 0 ? {} : { details: runDetails(gate) }),
|
|
1073
|
-
}));
|
|
1116
|
+
}, undefined, ranProposedPolicy(result)));
|
|
1074
1117
|
}
|
|
1075
1118
|
// Still RESULTS, deliberately, and the asymmetry with the three above is
|
|
1076
1119
|
// the point. gate-missing and gate-failed are the fail-closed posture made
|
|
@@ -1094,6 +1137,7 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
1094
1137
|
...legacyStateDirNotifications(result),
|
|
1095
1138
|
...weakMatchNotifications(result),
|
|
1096
1139
|
...trustBaseRefusedNotifications(result),
|
|
1140
|
+
...proposalRunNotifications(result),
|
|
1097
1141
|
...programRefusedNotifications(result),
|
|
1098
1142
|
...proposalNotifications(result),
|
|
1099
1143
|
...trustBaseWithheldNotifications(result),
|
|
@@ -1142,7 +1186,7 @@ export function renderSarif(result, umbrellaVersion) {
|
|
|
1142
1186
|
executionSuccessful: (result.trustBase?.refusal ?? null) === null &&
|
|
1143
1187
|
result.gates.every((gate) => gate.couldNotRun === null),
|
|
1144
1188
|
notifications,
|
|
1145
|
-
}));
|
|
1189
|
+
}, ranProposedPolicy(result)));
|
|
1146
1190
|
}
|
|
1147
1191
|
return JSON.stringify({ $schema: SARIF_SCHEMA, version: '2.1.0', runs }, null, 2);
|
|
1148
1192
|
}
|
package/dist/output-text.d.ts
CHANGED
|
@@ -113,6 +113,123 @@ export declare function previewLogLines(result: RunResult): string[];
|
|
|
113
113
|
export declare function gateLogLines(result: RunResult, options?: {
|
|
114
114
|
terminal?: boolean;
|
|
115
115
|
}): string[];
|
|
116
|
+
/**
|
|
117
|
+
* ONE LINE FOR ONE GATE, from its outcome alone (issue 105): ran, with the
|
|
118
|
+
* gate version, the exit code and the blocking count, or did not run, with
|
|
119
|
+
* the reason. The line the step summary and the pull request comment lead
|
|
120
|
+
* with, so a gate that did not run can never read as one that passed.
|
|
121
|
+
*
|
|
122
|
+
* A CLOSED SHAPE. Every word is conductor's own (a role, a product, a
|
|
123
|
+
* could-not-run reason) and every other field is a number or a version cut
|
|
124
|
+
* to version characters, so nothing a pull request or a gate printed reaches
|
|
125
|
+
* the line. action.yml and scripts/lib/pr-comment.mjs copy a line only when
|
|
126
|
+
* it matches that shape whole.
|
|
127
|
+
*
|
|
128
|
+
* The blocking count is the findings the report marks blocking, not the
|
|
129
|
+
* token's count: a gate that exited non-zero with none marked says "exit 1,
|
|
130
|
+
* 0 blocking", which is what happened. A gate whose resolved version is not
|
|
131
|
+
* the one the run expected is could-not-run (version-skew) since 0.13.0, so
|
|
132
|
+
* that line is the one that prints both versions.
|
|
133
|
+
*
|
|
134
|
+
* Describes, decides nothing: the exit code was composed before this is read.
|
|
135
|
+
*/
|
|
136
|
+
export declare function gateSummaryLine(gate: GateOutcome): string;
|
|
137
|
+
/**
|
|
138
|
+
* The per-gate lines of a run: one per gate that has an outcome, then one per
|
|
139
|
+
* enabled gate that was never spawned (in the job log's own words for why),
|
|
140
|
+
* then one per gate the policy file switches off. The same closed shape.
|
|
141
|
+
*/
|
|
142
|
+
export declare function gateSummaryLines(result: RunResult): string[];
|
|
143
|
+
/**
|
|
144
|
+
* The two fixed lines for a run whose trust base gave no rules. They name no
|
|
145
|
+
* ref and carry none of the refusal's own text, which is printed once in the
|
|
146
|
+
* report under them.
|
|
147
|
+
*/
|
|
148
|
+
export declare const TRUST_BASE_LINES: readonly ["trust-base: refused, no rules were read and no gate ran", "trust-base: not given on a pull-request job, no rules were read and no gate ran"];
|
|
149
|
+
/**
|
|
150
|
+
* The fixed line of a PROPOSAL (issue 101): a run of the policy a pull
|
|
151
|
+
* request adds to a base that has none, which exits 0 and enforced nothing.
|
|
152
|
+
* One number and no other text that varies: no ref, no branch, no file. The
|
|
153
|
+
* number is the verdict token's, `wouldBlock`.
|
|
154
|
+
*/
|
|
155
|
+
export declare function proposalLine(wouldBlockCount: number): string;
|
|
156
|
+
/**
|
|
157
|
+
* The fixed line of a refused pull-request run where neither the base nor
|
|
158
|
+
* the pull request has a policy file, and of a run with no trust base that
|
|
159
|
+
* found no policy file at all (the CLI appends it to the Actions step
|
|
160
|
+
* summary there). The workflow is present and checks nothing: said in so
|
|
161
|
+
* many words, since a red step alone was read as a broken tool.
|
|
162
|
+
*/
|
|
163
|
+
export declare const NO_POLICY_LINE: string;
|
|
164
|
+
/**
|
|
165
|
+
* The fixed line of a pull request that deletes the policy file from a base
|
|
166
|
+
* that has one. That run is the ordinary one under the base's rules, so
|
|
167
|
+
* without this line the deletion is one "proposed" line among gate output.
|
|
168
|
+
* What it says about afterwards is what the code does: with no policy on the
|
|
169
|
+
* base every pull-request run is refused, and a pull request that adds one
|
|
170
|
+
* back is refused too (src/adoption-proposal.ts#refuseAdoptionProposal, the
|
|
171
|
+
* first-parent history rule).
|
|
172
|
+
*/
|
|
173
|
+
export declare const POLICY_REMOVED_LINE: string;
|
|
174
|
+
/** The heading of the named findings on a proposal, in place of "findings". */
|
|
175
|
+
export declare const PROPOSAL_FINDINGS_HEADING = "would block once the policy is on the base";
|
|
176
|
+
/** The headings `findingSummaryLines` is ever given: a closed set the two readers spell too. */
|
|
177
|
+
export declare const FINDINGS_HEADINGS: readonly ["findings", "would block once the policy is on the base"];
|
|
178
|
+
/**
|
|
179
|
+
* THE RUN-LEVEL SLOT: the fixed lines about the run as a whole, printed
|
|
180
|
+
* directly under the verdict token and above the per-gate lines. Each is a
|
|
181
|
+
* closed shape (a fixed sentence, or one with numbers in it), so the Action
|
|
182
|
+
* and the comment poster can copy them without reading anything a pull
|
|
183
|
+
* request wrote. A later line about the run is added here and to the two
|
|
184
|
+
* closed sets that read it, and nowhere else.
|
|
185
|
+
*
|
|
186
|
+
* The present-on-base line stays first and the intent-spec line second, the
|
|
187
|
+
* two positions an Action older than this slot reads, on every run such an
|
|
188
|
+
* Action can be handed. The proposal line and the no-policy line go above
|
|
189
|
+
* them, because each is the first thing to know about its run: an older
|
|
190
|
+
* Action never passes --adoption-proposal, so it never sees a proposal, and
|
|
191
|
+
* a refused run has neither of the two older lines. The policy-removed line
|
|
192
|
+
* is on an ordinary run, so it goes below them.
|
|
193
|
+
*/
|
|
194
|
+
export declare function runLevelLines(result: RunResult): string[];
|
|
195
|
+
/** How many findings the head block and the job log name before "and M more". */
|
|
196
|
+
export declare const FINDINGS_NAMED = 10;
|
|
197
|
+
/** The longest a named-finding line can be: its fixed words plus the four field caps below. */
|
|
198
|
+
export declare const FINDING_LINE_MAX = 520;
|
|
199
|
+
/**
|
|
200
|
+
* THE BLOCKING FINDINGS, NAMED (issue 144): a count line over every finding,
|
|
201
|
+
* then the first `limit` BLOCKING entries as gate, rule, where and the
|
|
202
|
+
* reason, then "and M more blocking". A finding that does not block is
|
|
203
|
+
* counted and not named: it is in the gate's section. When none blocks the
|
|
204
|
+
* count line stands alone, with no colon and no list. "Blocking" is the
|
|
205
|
+
* gate's own mark on the finding, whatever --advisory or enforce: false
|
|
206
|
+
* then does with the exit code. For the head block of the text report, which the Action copies to
|
|
207
|
+
* the step summary and the comment poster lifts above the collapsed report,
|
|
208
|
+
* and for the job log. Empty when no gate that ran reported one.
|
|
209
|
+
*
|
|
210
|
+
* EVERY FIELD IS TEXT A PULL REQUEST CAN CHOOSE (a path, a package name, a
|
|
211
|
+
* rule a user pattern named, a message), so each goes through summaryField
|
|
212
|
+
* (src/escape.ts) and nothing else writes one: a line is one printable ASCII
|
|
213
|
+
* line with no backtick, tag or workflow command, at most FINDING_LINE_MAX
|
|
214
|
+
* long, and always starts with the fixed word "finding: ", so it can never
|
|
215
|
+
* be read as a per-gate line or a verdict.
|
|
216
|
+
*
|
|
217
|
+
* Only gates that RAN are named. A gate that could not run carries the
|
|
218
|
+
* umbrella's own finding about the gate, and its per-gate line already says
|
|
219
|
+
* it did not run. An osv-scanner advisory is one entry however many lockfiles
|
|
220
|
+
* carry it, as in the gate's section. The heading is a parameter because a
|
|
221
|
+
* later run mode lists the same findings under different words.
|
|
222
|
+
*/
|
|
223
|
+
export declare function findingSummaryLines(result: RunResult, options?: {
|
|
224
|
+
heading?: string;
|
|
225
|
+
limit?: number;
|
|
226
|
+
}): string[];
|
|
227
|
+
/**
|
|
228
|
+
* The same lines for the job log, so a run whose report went to a file still
|
|
229
|
+
* says what was found where its log is read (issue 144: a blocked run's log
|
|
230
|
+
* said only "findings (36, 36 blocking)").
|
|
231
|
+
*/
|
|
232
|
+
export declare function findingLogLines(result: RunResult): string[];
|
|
116
233
|
type VersionSkew = NonNullable<GateOutcome['versionSkew']>;
|
|
117
234
|
/** Where a skewed binary came from, in words. Never a machine path. */
|
|
118
235
|
export declare function skewPlace(skew: VersionSkew): string;
|
|
@@ -244,14 +361,6 @@ export interface TextOptions {
|
|
|
244
361
|
* that did not block, never about a gate that did not run.
|
|
245
362
|
*/
|
|
246
363
|
advisory?: boolean;
|
|
247
|
-
/**
|
|
248
|
-
* The report is going straight to a terminal (cli.ts: stdout is a TTY and
|
|
249
|
-
* no --output). Only one thing reads it: a refused trust base prints its
|
|
250
|
-
* refusal once at the top and one line per gate, rather than the refusal
|
|
251
|
-
* again in every gate's section and again in every gate's finding. A file,
|
|
252
|
-
* a pipe and a pull request comment never set it and are unchanged.
|
|
253
|
-
*/
|
|
254
|
-
terminal?: boolean;
|
|
255
364
|
}
|
|
256
365
|
/**
|
|
257
366
|
* The intent-spec header line: a CLOSED SET of four strings, in precedence
|