@vaultcompass/conductor 0.7.0 → 0.8.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 +109 -41
- package/dist/cli.js +53 -8
- package/dist/external-config.js +7 -1
- package/dist/gate-runner.d.ts +9 -1
- package/dist/gate-runner.js +49 -5
- package/dist/init-policy.js +2 -1
- package/dist/intent-base.d.ts +29 -0
- package/dist/intent-base.js +96 -2
- package/dist/intent-prepare.js +6 -2
- package/dist/normalize.d.ts +9 -0
- package/dist/normalize.js +13 -1
- package/dist/output-text.d.ts +4 -2
- package/dist/output-text.js +11 -2
- package/dist/products.js +1 -1
- package/dist/trust-base.d.ts +57 -10
- package/dist/trust-base.js +194 -18
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -167,7 +167,7 @@ required.
|
|
|
167
167
|
A commit with a staged credential in it prints the full report and exits 1:
|
|
168
168
|
|
|
169
169
|
```
|
|
170
|
-
conductor 0.
|
|
170
|
+
conductor 0.8.0
|
|
171
171
|
verdict-token: blocked (1)
|
|
172
172
|
conductor run: 2 gate(s), 1 finding(s)
|
|
173
173
|
|
|
@@ -473,7 +473,8 @@ proceeds normally without mentioning them.
|
|
|
473
473
|
pull-request run passes both: `--base` decides which paths are judged,
|
|
474
474
|
`--trust-base` decides what they are judged by. When `GITHUB_BASE_REF` is
|
|
475
475
|
set, an explicit `--trust-base` is accepted only when it resolves to the
|
|
476
|
-
same commit as `origin/$GITHUB_BASE_REF
|
|
476
|
+
same commit as `refs/remotes/origin/$GITHUB_BASE_REF`, or is the Action's
|
|
477
|
+
private `refs/conductor/trust-base` (issue #58); anyone invoking the
|
|
477
478
|
CLI directly on a pull request, rather than through the Action, gets this
|
|
478
479
|
as its own refusal, named below.
|
|
479
480
|
- `--spec <path>` names the spec the intent gate imports its contract from.
|
|
@@ -571,6 +572,11 @@ code and the `enforce` flags the run already had.
|
|
|
571
572
|
|
|
572
573
|
- `pass`: exit 0, and no gate, enforced or not, has a blocking finding or
|
|
573
574
|
could not run.
|
|
575
|
+
- `nothing-checked`: exit 0, but no gate ran at all (none is enabled, or
|
|
576
|
+
every enabled one was deferred to a later stage, had nothing to judge, or
|
|
577
|
+
was skipped). The exit status is unchanged, since nothing failed, but this
|
|
578
|
+
is not a pass: nothing was verified. In the Action the `verdict` output
|
|
579
|
+
carries this token, so a workflow can tell it apart from `pass`.
|
|
574
580
|
- `advisory-blocked (N)`: the run would have exited 1, and `--advisory` made
|
|
575
581
|
it exit 0. N is the blocking findings on enforced gates.
|
|
576
582
|
- `unenforced-findings (N)`: exit 0, but a gate with `enforce: false` had
|
|
@@ -580,11 +586,13 @@ code and the `enforce` flags the run already had.
|
|
|
580
586
|
- `could-not-run`: exit 2, a refused trust base included.
|
|
581
587
|
|
|
582
588
|
When several apply the order is `could-not-run`, then `blocked` or
|
|
583
|
-
`advisory-blocked`, then `unenforced-findings`, then `
|
|
589
|
+
`advisory-blocked`, then `unenforced-findings`, then `nothing-checked` (no gate
|
|
590
|
+
ran) or `pass`. A run with
|
|
584
591
|
`--advisory` whose only blocking findings sit on an unenforced gate is
|
|
585
592
|
`unenforced-findings`, not `advisory-blocked`, because the flag did nothing
|
|
586
593
|
there. A gate skipped for want of a contract does not by itself move the token
|
|
587
|
-
off `pass
|
|
594
|
+
off `pass` when another gate ran; when no gate ran, the token is
|
|
595
|
+
`nothing-checked` and the verdict sentence says "nothing was checked". A
|
|
588
596
|
gate that exited non-zero with no finding marked blocking counts as one in N,
|
|
589
597
|
so a state that is not a pass never prints a count of zero. The one-line
|
|
590
598
|
summary of a clean, non-verbose run has no token line, since it is one line by
|
|
@@ -737,15 +745,19 @@ to remove the input; see "The Action" below.
|
|
|
737
745
|
|
|
738
746
|
**The CLI check catches a misconfigured or innocent-looking redirect when
|
|
739
747
|
`GITHUB_BASE_REF` is set**, for anyone invoking the CLI directly in CI. When
|
|
740
|
-
that variable is set, an explicit `--trust-base` is accepted only when it
|
|
741
|
-
|
|
742
|
-
|
|
748
|
+
that variable is set, an explicit `--trust-base` is accepted only when it is
|
|
749
|
+
`refs/conductor/trust-base`, the private ref the Action fetches the base
|
|
750
|
+
branch into and always passes (that ref is the authority and is not compared
|
|
751
|
+
with anything), or resolves to the same commit as
|
|
752
|
+
`refs/remotes/origin/$GITHUB_BASE_REF`. So an ordinary pull-request run is
|
|
743
753
|
unaffected. A ref naming the pull request's own branch, or anything else that
|
|
744
754
|
disagrees, is refused with both refs and both commits named, through the same
|
|
745
755
|
could-not-run path as every other trust-base refusal: exit 2, the report
|
|
746
|
-
leads with the reason, and nothing is checked.
|
|
747
|
-
|
|
748
|
-
|
|
756
|
+
leads with the reason, and nothing is checked. A short name that matches both
|
|
757
|
+
a tag and a branch or remote-tracking ref (a tag named `origin/main`) is
|
|
758
|
+
refused as ambiguous: spell the ref in full. When neither resolves, this fails
|
|
759
|
+
closed too, naming it, for the same reason the fetch-depth remedy below
|
|
760
|
+
exists.
|
|
749
761
|
|
|
750
762
|
**Neither layer closes anything against a pull request that edits its own
|
|
751
763
|
workflow file.** A CLI invocation on a pull request can simply omit
|
|
@@ -899,8 +911,11 @@ human step. That step is exactly what a pull request cannot carry, so at the
|
|
|
899
911
|
branch changed since it forked, from
|
|
900
912
|
`git diff --name-only --no-renames <base>...HEAD` in the repository root.
|
|
901
913
|
|
|
902
|
-
With no `--base`, `GITHUB_BASE_REF` is used
|
|
903
|
-
|
|
914
|
+
With no `--base`, `GITHUB_BASE_REF` is used when it is set, spelled in full:
|
|
915
|
+
`refs/conductor/trust-base` (the Action's private fetch of the base) if that
|
|
916
|
+
exists, else `refs/remotes/origin/<value>`, so a tag of that name cannot
|
|
917
|
+
shadow it. The text report says which. An explicit `--base` that matches both
|
|
918
|
+
a tag and a branch is refused as ambiguous. With neither, the intent gate runs the way
|
|
904
919
|
it does at a commit: against the staged index, or the paths you name.
|
|
905
920
|
|
|
906
921
|
**This is why a local preview and a pull-request run can disagree about a
|
|
@@ -1098,8 +1113,11 @@ provenance even though all four packages publish it.
|
|
|
1098
1113
|
umbrella reads `GITHUB_BASE_REF` itself and treats an empty value as "not a
|
|
1099
1114
|
pull request", which is what a push build wants.
|
|
1100
1115
|
|
|
1101
|
-
On a `pull_request` event the
|
|
1102
|
-
|
|
1116
|
+
On a `pull_request` event a dedicated step fetches the base branch into a
|
|
1117
|
+
private ref and the action passes **`--trust-base <the fetched commit id>`**
|
|
1118
|
+
of its own accord (the job needs `contents: read`; a failed fetch fails the job
|
|
1119
|
+
rather than running without a trust base; the token exists only in that fetch
|
|
1120
|
+
step and never in the gates), so the run takes
|
|
1103
1121
|
its configuration from the base branch and the pull request cannot change the
|
|
1104
1122
|
rules it is judged by; a change to the rules shows as a proposal line and
|
|
1105
1123
|
takes effect after merge. See "The pull-request trust boundary" above. On any
|
|
@@ -1113,7 +1131,8 @@ workflow file is the *base* branch's own instead, but the input is refused
|
|
|
1113
1131
|
there too, because pull-request mode already derives the trust base on both
|
|
1114
1132
|
events and an explicit redirect has no legitimate use on either. The refusal
|
|
1115
1133
|
names the value that was given and the fix, which is to remove the input: the
|
|
1116
|
-
action already derives `
|
|
1134
|
+
action already derives the private `refs/conductor/trust-base` itself on that
|
|
1135
|
+
event.
|
|
1117
1136
|
|
|
1118
1137
|
There is deliberately **no input that turns pull-request mode off**.
|
|
1119
1138
|
Base-ref judging is the floor rather than a knob, and on a `pull_request`
|
|
@@ -1148,7 +1167,7 @@ jobs:
|
|
|
1148
1167
|
with:
|
|
1149
1168
|
node-version: '22.11.0'
|
|
1150
1169
|
- id: conductor
|
|
1151
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1170
|
+
uses: vaultcompasshq/conductor@v0.8.0
|
|
1152
1171
|
with:
|
|
1153
1172
|
output: conductor.sarif
|
|
1154
1173
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -1191,7 +1210,6 @@ jobs:
|
|
|
1191
1210
|
# clone, because on a pull request the rules are read from it: a
|
|
1192
1211
|
# base ref that will not resolve is exit 2 for every enabled gate.
|
|
1193
1212
|
fetch-depth: 0
|
|
1194
|
-
- uses: pnpm/action-setup@v4
|
|
1195
1213
|
- uses: actions/setup-node@v7
|
|
1196
1214
|
with:
|
|
1197
1215
|
# Not a bare major: Node 22.0.0 ships npm 10.5.1, which the action
|
|
@@ -1199,13 +1217,16 @@ jobs:
|
|
|
1199
1217
|
# with. 22.1.0 or later, or 20.13.0 or later, carries an npm that
|
|
1200
1218
|
# can verify.
|
|
1201
1219
|
node-version: '22.11.0'
|
|
1202
|
-
|
|
1203
|
-
#
|
|
1204
|
-
#
|
|
1205
|
-
#
|
|
1206
|
-
|
|
1220
|
+
# NOTHING FROM THE PULL REQUEST RUNS BEFORE THE ACTION IN THIS JOB.
|
|
1221
|
+
# No `pnpm install`, `npm ci`, build or test step: an install runs the
|
|
1222
|
+
# repository's own lifecycle scripts (a root postinstall), and that code
|
|
1223
|
+
# could write the PATH the gates are resolved from, or the refs the
|
|
1224
|
+
# policy is read from, before the gates ever start. Your own
|
|
1225
|
+
# dependencies, build and tests belong in a separate job (see below).
|
|
1226
|
+
# The gates are not among the things that job has to install: the action
|
|
1227
|
+
# installs those itself, globally, at the versions pinned below.
|
|
1207
1228
|
- id: conductor
|
|
1208
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1229
|
+
uses: vaultcompasshq/conductor@v0.8.0
|
|
1209
1230
|
with:
|
|
1210
1231
|
output: conductor.sarif
|
|
1211
1232
|
# Exact versions, never a range and never "latest". These four
|
|
@@ -1216,10 +1237,10 @@ jobs:
|
|
|
1216
1237
|
# request of their own. Forward only on a pull request: the action
|
|
1217
1238
|
# refuses a pin below what its tag ships, and the four lines can be
|
|
1218
1239
|
# left out entirely to take that tag's own versions.
|
|
1219
|
-
conductor-version: 0.
|
|
1220
|
-
dep-guard-version: 0.
|
|
1221
|
-
vault-guard-version: 1.
|
|
1222
|
-
intent-guard-version: 1.
|
|
1240
|
+
conductor-version: 0.8.0
|
|
1241
|
+
dep-guard-version: 0.10.0
|
|
1242
|
+
vault-guard-version: 1.9.0
|
|
1243
|
+
intent-guard-version: 1.8.0
|
|
1223
1244
|
- uses: github/codeql-action/upload-sarif@v3
|
|
1224
1245
|
# Always: the log is most worth having on the run that failed.
|
|
1225
1246
|
if: always()
|
|
@@ -1233,8 +1254,49 @@ jobs:
|
|
|
1233
1254
|
continue-on-error: true
|
|
1234
1255
|
with:
|
|
1235
1256
|
sarif_file: ${{ steps.conductor.outputs.sarif }}
|
|
1257
|
+
|
|
1258
|
+
# Your own dependencies, build and tests: a different job, so the code they
|
|
1259
|
+
# run shares no runner, PATH or workspace with the gates.
|
|
1260
|
+
build:
|
|
1261
|
+
runs-on: ubuntu-latest
|
|
1262
|
+
steps:
|
|
1263
|
+
- uses: actions/checkout@v7
|
|
1264
|
+
- uses: pnpm/action-setup@v4
|
|
1265
|
+
- uses: actions/setup-node@v7
|
|
1266
|
+
with:
|
|
1267
|
+
node-version: '22.11.0'
|
|
1268
|
+
cache: pnpm
|
|
1269
|
+
- run: pnpm install --frozen-lockfile
|
|
1270
|
+
- run: pnpm test
|
|
1236
1271
|
```
|
|
1237
1272
|
|
|
1273
|
+
**Run the gates in a job that runs no code from the pull request.** Do not
|
|
1274
|
+
run `pnpm install`, `npm ci`, a build or a test step before the conductor
|
|
1275
|
+
action in the same job, and do not put the action in a job whose earlier steps
|
|
1276
|
+
run the repository's own scripts. Anything that runs first shares the runner
|
|
1277
|
+
with the gates: it can write to `GITHUB_PATH`, to the runner's temp directory
|
|
1278
|
+
where the action installs the gates, or to the git refs the base policy is
|
|
1279
|
+
read from, and then it is the pull request choosing the program that judges
|
|
1280
|
+
it. The action fetches the base branch into its own private ref and judges by
|
|
1281
|
+
that, which closes a moved or tag-shadowed base ref and nothing else. Only
|
|
1282
|
+
keeping pull-request code out of the job covers the rest: `GITHUB_ENV`
|
|
1283
|
+
(`NODE_OPTIONS=--require`, `GIT_CONFIG_*`, `GIT_DIR`), `GITHUB_PATH`,
|
|
1284
|
+
`.git/config` changes (a remote URL, `url.insteadOf`, `core.fsmonitor`,
|
|
1285
|
+
credential helpers, `core.sshCommand`), git hooks such as
|
|
1286
|
+
`reference-transaction`, and replace refs or grafts. Say it plainly:
|
|
1287
|
+
package.json lifecycle scripts (`preinstall`, `install`, `postinstall`,
|
|
1288
|
+
`prepare`) run by an install bypass "require review on `.github/workflows`",
|
|
1289
|
+
because the pull request supplies them, not the workflow file. Branch
|
|
1290
|
+
protection on the workflow directory does not stop them, so the gates must
|
|
1291
|
+
not share a job with head code that runs first.
|
|
1292
|
+
|
|
1293
|
+
**With gitleaks enabled the checkout must be `fetch-depth: 0`.** At the default
|
|
1294
|
+
depth of 1 the checkout is shallow, the range from the base to HEAD holds one
|
|
1295
|
+
grafted commit, and a secret added and then removed inside the pull request
|
|
1296
|
+
would never be seen. conductor detects a shallow checkout and reports the
|
|
1297
|
+
history gate as could-not-run, naming `fetch-depth: 0` (exit 2 on a pull
|
|
1298
|
+
request, whatever `enforce` says). It does not deepen the checkout for you.
|
|
1299
|
+
|
|
1238
1300
|
**The two external gates are installed by your workflow, not by the
|
|
1239
1301
|
Action.** The Action still installs exactly its four npm packages and has no
|
|
1240
1302
|
input for gitleaks or osv-scanner; conductor downloads, pins and checksums
|
|
@@ -1259,12 +1321,15 @@ checksum, the same way you would for a standalone security job:
|
|
|
1259
1321
|
echo "$bin" >> "$GITHUB_PATH"
|
|
1260
1322
|
```
|
|
1261
1323
|
|
|
1262
|
-
`fetch-depth: 0` on the checkout
|
|
1263
|
-
pull request conductor scans `<base>..HEAD
|
|
1264
|
-
|
|
1265
|
-
|
|
1266
|
-
|
|
1267
|
-
|
|
1324
|
+
`fetch-depth: 0` on the checkout is required with gitleaks enabled: on a
|
|
1325
|
+
pull request conductor scans `<base>..HEAD`. At depth 1 the checkout is
|
|
1326
|
+
shallow and that range holds a single commit, so a secret added and removed
|
|
1327
|
+
inside the pull request would go unseen; conductor detects the shallow
|
|
1328
|
+
checkout and reports the gate as could-not-run instead of scanning it. (A
|
|
1329
|
+
base that was never fetched at all is a git error gitleaks itself would
|
|
1330
|
+
report as a clean scan of nothing; conductor reads that error off gitleaks'
|
|
1331
|
+
log and reports the gate as could-not-run too.) A missing tool is
|
|
1332
|
+
could-not-run as well, with the install step named in the report.
|
|
1268
1333
|
|
|
1269
1334
|
The `@v4` pins there are readable, not safe: a tag moves, so pinning by one
|
|
1270
1335
|
runs whatever its author pushes to it next. Pin every third-party action by
|
|
@@ -1311,15 +1376,16 @@ jobs:
|
|
|
1311
1376
|
node-version: '22.11.0'
|
|
1312
1377
|
- id: conductor
|
|
1313
1378
|
timeout-minutes: 5
|
|
1314
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1379
|
+
uses: vaultcompasshq/conductor@v0.8.0
|
|
1315
1380
|
with:
|
|
1316
1381
|
pr-comment: true
|
|
1317
1382
|
advisory: true
|
|
1318
1383
|
```
|
|
1319
1384
|
|
|
1320
|
-
`action.yml`
|
|
1321
|
-
|
|
1322
|
-
|
|
1385
|
+
`action.yml` fetches the trust base itself on every pull-request run, into its
|
|
1386
|
+
own private ref (depth 1 only when the checkout is already shallow, and always,
|
|
1387
|
+
whether or not the checkout carries the base), so this recipe needs no separate
|
|
1388
|
+
"fetch the base ref" step. None of
|
|
1323
1389
|
the three steps above swallows its own exit code: a checkout or setup-node
|
|
1324
1390
|
failure is an infrastructure problem this recipe should still surface, and
|
|
1325
1391
|
the `conductor` step's own advisory behaviour comes from `advisory: true`
|
|
@@ -1442,9 +1508,11 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1442
1508
|
security-events: write
|
|
1443
1509
|
pull-requests: write
|
|
1444
1510
|
steps:
|
|
1445
|
-
# ... checkout
|
|
1511
|
+
# ... checkout and setup-node, as in the example above. Nothing from
|
|
1512
|
+
# the pull request runs before the action in this job: no install, build
|
|
1513
|
+
# or test step here; those belong in a separate job. ...
|
|
1446
1514
|
- id: conductor
|
|
1447
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1515
|
+
uses: vaultcompasshq/conductor@v0.8.0
|
|
1448
1516
|
with:
|
|
1449
1517
|
output: conductor.sarif
|
|
1450
1518
|
pr-comment: true
|
|
@@ -1516,12 +1584,12 @@ per pull request.
|
|
|
1516
1584
|
|
|
1517
1585
|
```yaml
|
|
1518
1586
|
- id: conductor-package-a
|
|
1519
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1587
|
+
uses: vaultcompasshq/conductor@v0.8.0
|
|
1520
1588
|
with:
|
|
1521
1589
|
pr-comment: true
|
|
1522
1590
|
pr-comment-marker: 'package-a'
|
|
1523
1591
|
- id: conductor-package-b
|
|
1524
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1592
|
+
uses: vaultcompasshq/conductor@v0.8.0
|
|
1525
1593
|
with:
|
|
1526
1594
|
pr-comment: true
|
|
1527
1595
|
pr-comment-marker: 'package-b'
|
package/dist/cli.js
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
// decisions be tested without a subprocess.
|
|
8
8
|
import { Command, CommanderError } from 'commander';
|
|
9
9
|
import { execFileSync } from 'node:child_process';
|
|
10
|
-
import { readFileSync, realpathSync, statSync, unlinkSync,
|
|
10
|
+
import { closeSync, constants as fsConstants, lstatSync, openSync, readFileSync, realpathSync, statSync, unlinkSync, writeSync, } from 'node:fs';
|
|
11
11
|
import path from 'node:path';
|
|
12
12
|
import { fileURLToPath } from 'node:url';
|
|
13
13
|
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, EXIT_OK } from './exit-codes.js';
|
|
@@ -19,6 +19,48 @@ import { refusedTrustBase, runAll } from './run.js';
|
|
|
19
19
|
import { headTreeEqualsBase, policyDiffers, readPolicyAtRef, refuseTrustBaseForPullRequest, refuseTrustBaseRef, } from './trust-base.js';
|
|
20
20
|
const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
|
|
21
21
|
const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
|
|
22
|
+
/**
|
|
23
|
+
* Refuses a report path that is a symbolic link, dangling or not.
|
|
24
|
+
*
|
|
25
|
+
* --output defaults to conductor.sarif in the checkout, and a pull request can
|
|
26
|
+
* commit a symlink by that name. writeFileSync follows it, so the run would
|
|
27
|
+
* overwrite whatever it points at (a hook, .git/config, a runner file) with
|
|
28
|
+
* report text. lstat, never stat: stat follows the link and reports the
|
|
29
|
+
* target. A missing path is fine, and so is an ordinary file.
|
|
30
|
+
*/
|
|
31
|
+
function refuseSymlinkReportPath(target, what) {
|
|
32
|
+
let info;
|
|
33
|
+
try {
|
|
34
|
+
info = lstatSync(target);
|
|
35
|
+
}
|
|
36
|
+
catch (err) {
|
|
37
|
+
if (err.code === 'ENOENT') {
|
|
38
|
+
return;
|
|
39
|
+
}
|
|
40
|
+
throw err;
|
|
41
|
+
}
|
|
42
|
+
if (info.isSymbolicLink()) {
|
|
43
|
+
throw new PolicyError(`refusing to write ${what} to ${target}: it is a symbolic link, and writing would follow it ` +
|
|
44
|
+
'to whatever it points at. Remove the link or choose another path.');
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Writes a report file without ever following a symbolic link at the final
|
|
49
|
+
* path: the lstat refusal above for the message, plus O_NOFOLLOW where the
|
|
50
|
+
* platform has it so a link swapped in between the check and the open is
|
|
51
|
+
* refused by the kernel rather than followed.
|
|
52
|
+
*/
|
|
53
|
+
function writeReportFile(target, what, body) {
|
|
54
|
+
refuseSymlinkReportPath(target, what);
|
|
55
|
+
const noFollow = fsConstants.O_NOFOLLOW ?? 0;
|
|
56
|
+
const fd = openSync(target, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_TRUNC | noFollow, 0o666);
|
|
57
|
+
try {
|
|
58
|
+
writeSync(fd, body);
|
|
59
|
+
}
|
|
60
|
+
finally {
|
|
61
|
+
closeSync(fd);
|
|
62
|
+
}
|
|
63
|
+
}
|
|
22
64
|
/**
|
|
23
65
|
* The working-tree root, or a thrown one-line diagnosis of why there is none.
|
|
24
66
|
*
|
|
@@ -212,8 +254,8 @@ function policyForRun(root, trustBase, overrides, githubBaseRef) {
|
|
|
212
254
|
// the same rule for anyone invoking the CLI directly in CI, bypassing that
|
|
213
255
|
// step. Checked BEFORE refuseTrustBaseRef and deliberately narrower than
|
|
214
256
|
// it: it says nothing about HEAD or about tree equality, only about
|
|
215
|
-
// whether the given ref agrees with
|
|
216
|
-
//
|
|
257
|
+
// whether the given ref agrees with the base branch (the full commit id the
|
|
258
|
+
// composite action's fetch step published). So on an
|
|
217
259
|
// ordinary pull-request run this returns null immediately and
|
|
218
260
|
// refuseTrustBaseRef runs its own checks unchanged, the equal-tree
|
|
219
261
|
// first-parent exception (issue #69/#73) included.
|
|
@@ -432,10 +474,10 @@ export function buildProgram() {
|
|
|
432
474
|
.option('--staged', 'gate the git index against HEAD, the way the pre-commit hook does')
|
|
433
475
|
.option('--format <format>', 'output format: text or sarif')
|
|
434
476
|
.option('--stage <stage>', `which stopping point this run is: ${GATE_STAGES.join(', ')}. Stages are cumulative, so a gate runs at its own stage and every later one. Omit it to run every enabled gate.`)
|
|
435
|
-
.option('--base <ref>', 'measure the intent gate against what this branch changed since <ref>, rather than against the index. In Actions this defaults to origin/<GITHUB_BASE_REF
|
|
436
|
-
.option('--trust-base <ref>', 'pull-request mode: read .guardrails.yaml from this ref instead of from the tree being judged, and pass the same ref to every gate that supports it. A policy change in the pull request is reported as a proposal and never takes effect for the run, so a pull request cannot change the rules it is judged by. In Actions the composite action passes
|
|
477
|
+
.option('--base <ref>', 'measure the intent gate against what this branch changed since <ref>, rather than against the index. In Actions this defaults to the base branch (refs/conductor/trust-base, else refs/remotes/origin/<GITHUB_BASE_REF>, as a commit id) when GITHUB_BASE_REF is set.')
|
|
478
|
+
.option('--trust-base <ref>', 'pull-request mode: read .guardrails.yaml from this ref instead of from the tree being judged, and pass the same ref to every gate that supports it. A policy change in the pull request is reported as a proposal and never takes effect for the run, so a pull request cannot change the rules it is judged by. In Actions the composite action fetches the base branch and passes its full commit id on a pull_request event.')
|
|
437
479
|
.option('--output <path>', 'write the report to this file instead of to stdout, for a CI step that uploads it')
|
|
438
|
-
.option('--text-report <path>', 'with --format sarif, also write the text report to this file, from the same run: exactly what --format text would have rendered for this result, --verbose, --compact-on-refusal and --advisory respected, and no gate is run a second time. In a full report (any run that is not fully clean, or any run with --verbose) the second line is "verdict-token: <token>"; the one-line summary of a clean run without --verbose has none. The token is a label for this run\'s own exit decision: pass, advisory-blocked (N), unenforced-findings (N), blocked (N) or could-not-run. Only meaningful with --format sarif: with --format text the text report is already the output, so the combination is a usage error (exit 2).')
|
|
480
|
+
.option('--text-report <path>', 'with --format sarif, also write the text report to this file, from the same run: exactly what --format text would have rendered for this result, --verbose, --compact-on-refusal and --advisory respected, and no gate is run a second time. In a full report (any run that is not fully clean, or any run with --verbose) the second line is "verdict-token: <token>"; the one-line summary of a clean run without --verbose has none. The token is a label for this run\'s own exit decision: pass, nothing-checked (exit 0 but no gate ran), advisory-blocked (N), unenforced-findings (N), blocked (N) or could-not-run. Only meaningful with --format sarif: with --format text the text report is already the output, so the combination is a usage error (exit 2).')
|
|
439
481
|
.option('--spec <path>', 'the spec the intent gate imports its contract from, outranking a Spec: line in the pull request body and the branch-name convention')
|
|
440
482
|
.option('--verbose', 'print the full per-gate report even when the run is clean. A clean run prints one summary line by default, because a pre-commit hook that prints a screenful on every commit is a hook a team switches off. Text output only; SARIF is unaffected.')
|
|
441
483
|
.option('--compact-on-refusal', 'when the trust base was refused and no gate ran, print a short body instead of the full refusal report: the version, the verdict, and the refusal reason (with its remedy, when one applies), never the full per-gate report. Built for the pull-request-comment step; every other run is unaffected, whatever --verbose says. Text output only; SARIF is unaffected.')
|
|
@@ -507,7 +549,7 @@ export function buildProgram() {
|
|
|
507
549
|
// own. Reporting exit 0 next to a report nobody can read is the
|
|
508
550
|
// worst of the available answers: the upload step downstream would
|
|
509
551
|
// fail on a missing file with no explanation here.
|
|
510
|
-
|
|
552
|
+
writeReportFile(options.output, 'the report', rendered);
|
|
511
553
|
}
|
|
512
554
|
// WRITTEN LAST, after the SARIF log or stdout, and removed again in
|
|
513
555
|
// the catch below if anything after it throws. A run that exits 2
|
|
@@ -516,8 +558,11 @@ export function buildProgram() {
|
|
|
516
558
|
// post it as a comment, beside a red job. A text report that cannot
|
|
517
559
|
// be written takes the could-not-run code, like an unwritable --output.
|
|
518
560
|
if (options.textReport !== undefined && textReport !== undefined) {
|
|
561
|
+
// Checked BEFORE textReportPath is set, so the catch below never
|
|
562
|
+
// unlinks a path this run refused to touch.
|
|
563
|
+
refuseSymlinkReportPath(options.textReport, 'the text report');
|
|
519
564
|
textReportPath = options.textReport;
|
|
520
|
-
|
|
565
|
+
writeReportFile(options.textReport, 'the text report', textReport);
|
|
521
566
|
}
|
|
522
567
|
if (options.output !== undefined) {
|
|
523
568
|
// One line, so a CI job whose only product is an uploaded artifact
|
package/dist/external-config.js
CHANGED
|
@@ -62,7 +62,13 @@ export function extendPath(config) {
|
|
|
62
62
|
}
|
|
63
63
|
/** A file's contents at a ref, or null when the ref does not have it. */
|
|
64
64
|
function showAtRef(repoRoot, ref, file) {
|
|
65
|
-
|
|
65
|
+
if (ref.startsWith('-')) {
|
|
66
|
+
return null;
|
|
67
|
+
}
|
|
68
|
+
const child = spawnSync('git', ['show', '--end-of-options', `${ref}:${file}`], {
|
|
69
|
+
cwd: repoRoot,
|
|
70
|
+
encoding: 'utf8',
|
|
71
|
+
});
|
|
66
72
|
return child.status === 0 && typeof child.stdout === 'string' ? child.stdout : null;
|
|
67
73
|
}
|
|
68
74
|
function headCopy(repoRoot, file) {
|
package/dist/gate-runner.d.ts
CHANGED
|
@@ -36,7 +36,15 @@ export type CouldNotRunReason = 'binary-missing' | 'configured-command-missing'
|
|
|
36
36
|
* verdict to is not there. Only a tool whose output is a report file can
|
|
37
37
|
* land here.
|
|
38
38
|
*/
|
|
39
|
-
| 'report-missing'
|
|
39
|
+
| 'report-missing'
|
|
40
|
+
/**
|
|
41
|
+
* The gate reads git history and the checkout is shallow, so the history it
|
|
42
|
+
* would read is truncated (at depth 1 the pull request's merge commit is
|
|
43
|
+
* grafted, and base..HEAD holds one commit: a secret added and removed
|
|
44
|
+
* inside the pull request is never seen). Never unshallowed automatically:
|
|
45
|
+
* the remedy is a checkout setting, fetch-depth: 0.
|
|
46
|
+
*/
|
|
47
|
+
| 'history-shallow';
|
|
40
48
|
export interface CouldNotRun {
|
|
41
49
|
reason: CouldNotRunReason;
|
|
42
50
|
detail: string;
|
package/dist/gate-runner.js
CHANGED
|
@@ -274,9 +274,10 @@ external = {}) {
|
|
|
274
274
|
// with cwd at the repository root anyway. Passing one would also risk
|
|
275
275
|
// a passthrough value being read as the positional.
|
|
276
276
|
//
|
|
277
|
-
// `scan` takes --trust-base from 1.7.0
|
|
278
|
-
//
|
|
279
|
-
//
|
|
277
|
+
// `scan` takes --trust-base from 1.7.0. On exit 2 it prints a line on
|
|
278
|
+
// stderr and may also write a JSON document (it can on a staged run);
|
|
279
|
+
// conductor never parses stdout on exit 2, so the could-not-run path
|
|
280
|
+
// above handles both before JSON.parse is reached.
|
|
280
281
|
return [...(staged ? ['--staged'] : []), '-f', 'json', ...trust, ...passthrough];
|
|
281
282
|
case 'intent-guard': {
|
|
282
283
|
if (intent === undefined) {
|
|
@@ -484,7 +485,10 @@ function missingGateRemedy(product, skipNodeModules, skipped) {
|
|
|
484
485
|
return ` ${profile.remedy(skipNodeModules)}`;
|
|
485
486
|
}
|
|
486
487
|
if (!skipNodeModules) {
|
|
487
|
-
|
|
488
|
+
// Named on a local run too: the scoped package is the only correct
|
|
489
|
+
// install target, and the finding's own sentence must not be the only
|
|
490
|
+
// place a reader could take a bare name from.
|
|
491
|
+
return ` ${profile.remedy(false)}`;
|
|
488
492
|
}
|
|
489
493
|
return (' On a pull-request run node_modules/.bin is not consulted at all: what is installed there ' +
|
|
490
494
|
'is chosen by the head own manifest and lockfile, so no ref approves it.' +
|
|
@@ -559,6 +563,18 @@ export function runGate(gate, options) {
|
|
|
559
563
|
};
|
|
560
564
|
}
|
|
561
565
|
}
|
|
566
|
+
/**
|
|
567
|
+
* Whether git says the repository at `repoRoot` is shallow. Anything other
|
|
568
|
+
* than a clear "true" (no git, an old git that does not know the flag) is
|
|
569
|
+
* not shallow: those runs have their own failure paths.
|
|
570
|
+
*/
|
|
571
|
+
function isShallowRepository(repoRoot) {
|
|
572
|
+
const probe = spawnSync('git', ['rev-parse', '--is-shallow-repository'], {
|
|
573
|
+
cwd: repoRoot,
|
|
574
|
+
encoding: 'utf8',
|
|
575
|
+
});
|
|
576
|
+
return probe.status === 0 && typeof probe.stdout === 'string' && probe.stdout.trim() === 'true';
|
|
577
|
+
}
|
|
562
578
|
function runGateInner(gate, options, started, progress) {
|
|
563
579
|
const timeoutMs = options.timeoutMs ?? profileFor(gate.product).timeoutMs;
|
|
564
580
|
// ONE PLACE DECIDES WHAT PULL-REQUEST MODE IS, and it is the presence of a
|
|
@@ -611,7 +627,9 @@ function runGateInner(gate, options, started, progress) {
|
|
|
611
627
|
// not a location this run has.
|
|
612
628
|
detail: (skipNodeModules
|
|
613
629
|
? `no ${gate.product} binary on PATH`
|
|
614
|
-
: `no ${gate.product} binary in node_modules/.bin or on PATH`) +
|
|
630
|
+
: `no ${gate.product} binary in node_modules/.bin or on PATH`) +
|
|
631
|
+
(remedy === '' ? '' : '.') +
|
|
632
|
+
remedy,
|
|
615
633
|
},
|
|
616
634
|
// A missing enabled gate is a finding of the umbrella's own, never a
|
|
617
635
|
// silent skip. Skipping is how a gate ends up switched on in the
|
|
@@ -642,6 +660,27 @@ function runGateInner(gate, options, started, progress) {
|
|
|
642
660
|
};
|
|
643
661
|
}
|
|
644
662
|
}
|
|
663
|
+
// A history gate cannot vouch for history it was not given. Checked before
|
|
664
|
+
// the version probe so nothing is executed for a run that cannot be honest.
|
|
665
|
+
if (profileFor(gate.product).readsHistory && isShallowRepository(options.repoRoot)) {
|
|
666
|
+
const detail = `this checkout is shallow, so the git history ${gate.product} reads is truncated: ` +
|
|
667
|
+
'with the default actions/checkout depth of 1 the range from the base to HEAD holds a ' +
|
|
668
|
+
'single grafted commit, and a secret added and then removed inside the pull request ' +
|
|
669
|
+
'would never be seen. Check out with fetch-depth: 0 (actions/checkout) or run ' +
|
|
670
|
+
'git fetch --unshallow, then run again. conductor does not deepen the checkout itself.';
|
|
671
|
+
return {
|
|
672
|
+
...base,
|
|
673
|
+
// Under a trust base this is enforced whatever the policy says: the
|
|
674
|
+
// gate produced nothing for `enforce: false` to be a decision about.
|
|
675
|
+
// A local run keeps the policy's own value.
|
|
676
|
+
enforce: options.trustBase !== undefined ? true : gate.enforce,
|
|
677
|
+
durationMs: Date.now() - started,
|
|
678
|
+
couldNotRun: { reason: 'history-shallow', detail },
|
|
679
|
+
findings: [normalizeFailedGate(gate.role, gate.product, detail)],
|
|
680
|
+
run: EMPTY_RUN,
|
|
681
|
+
diagnostics: [],
|
|
682
|
+
};
|
|
683
|
+
}
|
|
645
684
|
const version = probeVersion(binary, gate.product, options.repoRoot, timeoutMs);
|
|
646
685
|
// The command-line floor. Only the external tools have one: the umbrella
|
|
647
686
|
// writes flags they grew at a known release (gitleaks' git subcommand,
|
|
@@ -895,6 +934,11 @@ function spawnAndRead(ctx) {
|
|
|
895
934
|
encoding: 'utf8',
|
|
896
935
|
timeout: timeoutMs,
|
|
897
936
|
maxBuffer: 64 * 1024 * 1024,
|
|
937
|
+
// A history gate reads git history, and replace refs or grafts can cut
|
|
938
|
+
// that history without making the repository shallow. Ignoring replace
|
|
939
|
+
// objects makes it read the real commits. Other gates keep the
|
|
940
|
+
// inherited environment untouched.
|
|
941
|
+
...(profile.readsHistory ? { env: { ...process.env, GIT_NO_REPLACE_OBJECTS: '1' } } : {}),
|
|
898
942
|
});
|
|
899
943
|
const withRun = {
|
|
900
944
|
...base,
|
package/dist/init-policy.js
CHANGED
|
@@ -2,6 +2,7 @@ import { statSync } from 'node:fs';
|
|
|
2
2
|
import path from 'node:path';
|
|
3
3
|
import { NATIVE_CONTRACT_PATH } from './intent-prepare.js';
|
|
4
4
|
import { DEFAULT_STAGE_FOR_ROLE, GATE_ROLES, POLICY_FILE_NAME, PRODUCT_FOR_ROLE } from './policy.js';
|
|
5
|
+
import { installName } from './normalize.js';
|
|
5
6
|
import { CANDIDATES } from './resolve.js';
|
|
6
7
|
export { POLICY_FILE_NAME };
|
|
7
8
|
/** Names of the gates whose binary resolves right now. */
|
|
@@ -96,7 +97,7 @@ export function renderPolicy(detected, frozenContractPath) {
|
|
|
96
97
|
const enabled = detected.has(role);
|
|
97
98
|
lines.push(` # ${ROLE_DESCRIPTION[role]}`);
|
|
98
99
|
if (!enabled) {
|
|
99
|
-
lines.push(` # not found in node_modules/.bin or on PATH. Install ${product}, then set enabled: true.`);
|
|
100
|
+
lines.push(` # not found in node_modules/.bin or on PATH. Install ${installName(product)}, then set enabled: true.`);
|
|
100
101
|
}
|
|
101
102
|
lines.push(` ${role}:`);
|
|
102
103
|
lines.push(` product: ${product}`);
|
package/dist/intent-base.d.ts
CHANGED
|
@@ -23,6 +23,35 @@ export declare function resolveBaseRef(options: {
|
|
|
23
23
|
base?: string;
|
|
24
24
|
env: NodeJS.ProcessEnv;
|
|
25
25
|
}): BaseResolution | null;
|
|
26
|
+
export type ResolvedBase = {
|
|
27
|
+
ok: true;
|
|
28
|
+
base: BaseResolution | null;
|
|
29
|
+
} | {
|
|
30
|
+
ok: false;
|
|
31
|
+
detail: string;
|
|
32
|
+
};
|
|
33
|
+
/**
|
|
34
|
+
* The base to diff against, resolved against the repository and always
|
|
35
|
+
* spelled so a tag cannot shadow it (the same class as the trust base: git
|
|
36
|
+
* resolves a short origin/<base> through refs/tags/ first, so a tag at
|
|
37
|
+
* HEAD~1 would narrow the change set to the last commit).
|
|
38
|
+
*
|
|
39
|
+
* - An explicit --base keeps its meaning, but a short name that matches
|
|
40
|
+
* more than one kind of ref is refused (refuseAmbiguousRef).
|
|
41
|
+
* - Otherwise, on a pull request: refs/conductor/trust-base (the composite
|
|
42
|
+
* action's private fetch) when it exists, else refs/remotes/origin/<base>,
|
|
43
|
+
* both in full. The private ref wins and is not compared against the
|
|
44
|
+
* remote-tracking ref. If neither exists the spelled remote ref is returned and the
|
|
45
|
+
* diff fails closed, naming fetch-depth: 0.
|
|
46
|
+
* - Null outside a pull request.
|
|
47
|
+
*
|
|
48
|
+
* Nothing is deepened here: a depth-1 private ref has no merge base and the
|
|
49
|
+
* diff fails closed, the same outcome as a depth-1 origin/<base> always had.
|
|
50
|
+
*/
|
|
51
|
+
export declare function resolveBaseRefInRepo(repoRoot: string, options: {
|
|
52
|
+
base?: string;
|
|
53
|
+
env: NodeJS.ProcessEnv;
|
|
54
|
+
}): ResolvedBase;
|
|
26
55
|
/**
|
|
27
56
|
* The branch this run is about.
|
|
28
57
|
*
|
package/dist/intent-base.js
CHANGED
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
// the flags below are copied from intent-guard 1.2.1 so the two agree on what
|
|
17
17
|
// "changed" means rather than agreeing by coincidence.
|
|
18
18
|
import { spawnSync } from 'node:child_process';
|
|
19
|
+
import { PRIVATE_TRUST_BASE_REF, exactRefObject, refuseAmbiguousRef } from './trust-base.js';
|
|
19
20
|
/**
|
|
20
21
|
* The ref to diff against, or null for a run that is not a pull request.
|
|
21
22
|
*
|
|
@@ -35,6 +36,77 @@ export function resolveBaseRef(options) {
|
|
|
35
36
|
}
|
|
36
37
|
return null;
|
|
37
38
|
}
|
|
39
|
+
/**
|
|
40
|
+
* The base to diff against, resolved against the repository and always
|
|
41
|
+
* spelled so a tag cannot shadow it (the same class as the trust base: git
|
|
42
|
+
* resolves a short origin/<base> through refs/tags/ first, so a tag at
|
|
43
|
+
* HEAD~1 would narrow the change set to the last commit).
|
|
44
|
+
*
|
|
45
|
+
* - An explicit --base keeps its meaning, but a short name that matches
|
|
46
|
+
* more than one kind of ref is refused (refuseAmbiguousRef).
|
|
47
|
+
* - Otherwise, on a pull request: refs/conductor/trust-base (the composite
|
|
48
|
+
* action's private fetch) when it exists, else refs/remotes/origin/<base>,
|
|
49
|
+
* both in full. The private ref wins and is not compared against the
|
|
50
|
+
* remote-tracking ref. If neither exists the spelled remote ref is returned and the
|
|
51
|
+
* diff fails closed, naming fetch-depth: 0.
|
|
52
|
+
* - Null outside a pull request.
|
|
53
|
+
*
|
|
54
|
+
* Nothing is deepened here: a depth-1 private ref has no merge base and the
|
|
55
|
+
* diff fails closed, the same outcome as a depth-1 origin/<base> always had.
|
|
56
|
+
*/
|
|
57
|
+
export function resolveBaseRefInRepo(repoRoot, options) {
|
|
58
|
+
if (options.base !== undefined && options.base !== '') {
|
|
59
|
+
// A base that starts with a dash is an OPTION to git, not a ref:
|
|
60
|
+
// "--output=/x" made "git diff --output=/x...HEAD" write that file and
|
|
61
|
+
// print nothing, an empty change set the intent gate then judged as clean.
|
|
62
|
+
// Refused here, and changedPathsSince passes --end-of-options as well.
|
|
63
|
+
if (options.base.startsWith('-')) {
|
|
64
|
+
return {
|
|
65
|
+
ok: false,
|
|
66
|
+
detail: `refusing "${options.base}" as the intent gate base: it starts with a dash, so git would ` +
|
|
67
|
+
'read it as an option rather than a ref. Nothing was checked.',
|
|
68
|
+
};
|
|
69
|
+
}
|
|
70
|
+
const ambiguous = refuseAmbiguousRef(repoRoot, options.base, 'the intent gate base');
|
|
71
|
+
if (ambiguous !== null) {
|
|
72
|
+
return { ok: false, detail: ambiguous };
|
|
73
|
+
}
|
|
74
|
+
// A refs/ name is checked with show-ref: git's name resolution would
|
|
75
|
+
// otherwise fall back to refs/tags/<that name> when the ref is absent.
|
|
76
|
+
if (options.base.startsWith('refs/') && exactRefObject(repoRoot, options.base) === null) {
|
|
77
|
+
return {
|
|
78
|
+
ok: false,
|
|
79
|
+
detail: `refusing "${options.base}" as the intent gate base: no such ref exists in this ` +
|
|
80
|
+
'repository (a tag of that name does not count). Nothing was checked.',
|
|
81
|
+
};
|
|
82
|
+
}
|
|
83
|
+
return { ok: true, base: { ref: options.base, source: 'flag' } };
|
|
84
|
+
}
|
|
85
|
+
const fromGithub = options.env.GITHUB_BASE_REF;
|
|
86
|
+
if (fromGithub === undefined || fromGithub === '') {
|
|
87
|
+
return { ok: true, base: null };
|
|
88
|
+
}
|
|
89
|
+
const remoteRef = `refs/remotes/origin/${fromGithub}`;
|
|
90
|
+
// The private ref is the authority when it exists; refs/remotes/origin/<base>
|
|
91
|
+
// is fixed at checkout time, is the side pull-request code can move, and is
|
|
92
|
+
// not compared against it (a merge to the base in between would be a false
|
|
93
|
+
// refusal). It is the base only when the private ref is absent. Both are
|
|
94
|
+
// read with show-ref (the EXACT ref, never git's name resolution, which
|
|
95
|
+
// would take a tag of that name) and the base handed on is the commit id.
|
|
96
|
+
const priv = exactRefObject(repoRoot, PRIVATE_TRUST_BASE_REF);
|
|
97
|
+
const remote = exactRefObject(repoRoot, remoteRef);
|
|
98
|
+
const chosen = priv ?? remote;
|
|
99
|
+
if (chosen === null) {
|
|
100
|
+
return {
|
|
101
|
+
ok: false,
|
|
102
|
+
detail: `neither ${PRIVATE_TRUST_BASE_REF} (the composite action's fetch of the base branch) nor ` +
|
|
103
|
+
`${remoteRef} exists in this repository, so there is no base to measure the intent gate ` +
|
|
104
|
+
'against. Nothing was checked. In CI, check out with fetch-depth: 0, or fetch the base ' +
|
|
105
|
+
'ref before the run.',
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
return { ok: true, base: { ref: chosen, source: 'github' } };
|
|
109
|
+
}
|
|
38
110
|
/**
|
|
39
111
|
* The branch this run is about.
|
|
40
112
|
*
|
|
@@ -83,7 +155,15 @@ export function changedPathsSince(repoRoot, base) {
|
|
|
83
155
|
'core.quotePath=false',
|
|
84
156
|
'diff',
|
|
85
157
|
'--name-only',
|
|
158
|
+
// NUL-terminated, so a name with a quote, a backslash, a tab or a
|
|
159
|
+
// newline arrives byte for byte instead of C-quoted ("a\"b.txt"), which
|
|
160
|
+
// names no file and which intent-guard refuses outright (backslash).
|
|
161
|
+
'-z',
|
|
86
162
|
'--no-renames',
|
|
163
|
+
// Everything after this is a revision, never an option, whatever the
|
|
164
|
+
// caller-given base looks like (the second line of defence behind the
|
|
165
|
+
// dash refusal in resolveBaseRefInRepo).
|
|
166
|
+
'--end-of-options',
|
|
87
167
|
`${base}...HEAD`,
|
|
88
168
|
], { cwd: repoRoot, encoding: 'utf8' });
|
|
89
169
|
if (child.error !== undefined) {
|
|
@@ -102,11 +182,11 @@ export function changedPathsSince(repoRoot, base) {
|
|
|
102
182
|
'check out with fetch-depth: 0, or fetch the base ref before the run.',
|
|
103
183
|
};
|
|
104
184
|
}
|
|
105
|
-
// Split on
|
|
185
|
+
// Split on NUL and NOTHING else. Trimming each entry was corrupting a
|
|
106
186
|
// filename with leading or trailing whitespace into a different filename,
|
|
107
187
|
// which is worse than refusing it: the gate would then check a path that
|
|
108
188
|
// does not exist and never check the one that changed.
|
|
109
|
-
const paths = (child.stdout ?? '').split('\
|
|
189
|
+
const paths = (child.stdout ?? '').split('\0').filter((line) => line.length > 0);
|
|
110
190
|
for (const entry of paths) {
|
|
111
191
|
// Fail closed rather than hand over a path the encoding cannot carry.
|
|
112
192
|
// `--paths` is comma-joined, which is the only shape intent-guard 1.2.1
|
|
@@ -122,6 +202,20 @@ export function changedPathsSince(repoRoot, base) {
|
|
|
122
202
|
'Nothing was checked, rather than checking a path that does not exist.',
|
|
123
203
|
};
|
|
124
204
|
}
|
|
205
|
+
// intent-guard refuses ANY explicit --paths entry containing a backslash
|
|
206
|
+
// (skill/src/changed-paths.ts, explicitPathIssue: "it contains a
|
|
207
|
+
// backslash"), and exits 2 with a message that names the flag rather than
|
|
208
|
+
// the file. Said here instead, naming the file. A newline, tab or quote
|
|
209
|
+
// inside a path is accepted by intent-guard (it splits on commas only) and
|
|
210
|
+
// passes through intact.
|
|
211
|
+
if (entry.includes('\\')) {
|
|
212
|
+
return {
|
|
213
|
+
ok: false,
|
|
214
|
+
detail: `the changed path "${entry}" contains a backslash, and intent-guard refuses an explicit ` +
|
|
215
|
+
'path list entry with one (--paths), so it cannot judge this change. Nothing was ' +
|
|
216
|
+
'checked. Rename the file, or run the intent gate against the index instead.',
|
|
217
|
+
};
|
|
218
|
+
}
|
|
125
219
|
if (entry !== entry.trim()) {
|
|
126
220
|
return {
|
|
127
221
|
ok: false,
|
package/dist/intent-prepare.js
CHANGED
|
@@ -34,7 +34,7 @@ import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, st
|
|
|
34
34
|
import os from 'node:os';
|
|
35
35
|
import path from 'node:path';
|
|
36
36
|
import { parse as parseYaml } from 'yaml';
|
|
37
|
-
import { changedPathsSince, currentBranch,
|
|
37
|
+
import { changedPathsSince, currentBranch, resolveBaseRefInRepo } from './intent-base.js';
|
|
38
38
|
import { summariseStderr } from './normalize.js';
|
|
39
39
|
import { SPEC_DIR, discoverSpec, prBodyFromEvent } from './intent-spec.js';
|
|
40
40
|
/** Prefix of the per-run directory, exported so a test can count leaks. */
|
|
@@ -383,10 +383,14 @@ export function prepareIntent(options) {
|
|
|
383
383
|
'Name one with a "Spec: <path>" line in the pull request body, or pass --spec.',
|
|
384
384
|
};
|
|
385
385
|
}
|
|
386
|
-
const
|
|
386
|
+
const resolvedBase = resolveBaseRefInRepo(repoRoot, {
|
|
387
387
|
...(options.base === undefined ? {} : { base: options.base }),
|
|
388
388
|
env,
|
|
389
389
|
});
|
|
390
|
+
if (!resolvedBase.ok) {
|
|
391
|
+
return { kind: 'failed', step: 'base', detail: resolvedBase.detail };
|
|
392
|
+
}
|
|
393
|
+
const base = resolvedBase.base;
|
|
390
394
|
let paths = null;
|
|
391
395
|
if (base !== null) {
|
|
392
396
|
const changed = changedPathsSince(repoRoot, base.ref);
|
package/dist/normalize.d.ts
CHANGED
|
@@ -54,6 +54,15 @@ roots?: readonly string[],
|
|
|
54
54
|
/** The lockfiles the umbrella passed with --lockfile, repository-relative. */
|
|
55
55
|
lockfiles?: readonly string[]): NormalizedGateOutput;
|
|
56
56
|
export type GateProblemRule = 'conductor/gate-missing' | 'conductor/gate-output-unparseable' | 'conductor/gate-failed';
|
|
57
|
+
/**
|
|
58
|
+
* What to install for a product, spelled so it cannot be mistaken for
|
|
59
|
+
* another package. The three npm gates are published under the
|
|
60
|
+
* @vaultcompass scope only: the unscoped dep-guard and intent-guard names are
|
|
61
|
+
* unclaimed on npm, so a reader (or an agent) told to install the bare name
|
|
62
|
+
* could install a squatted package. The external tools are not npm packages
|
|
63
|
+
* of this family and keep their own names.
|
|
64
|
+
*/
|
|
65
|
+
export declare function installName(product: Product): string;
|
|
57
66
|
/**
|
|
58
67
|
* The finding raised when an ENABLED gate's binary cannot be found.
|
|
59
68
|
*
|
package/dist/normalize.js
CHANGED
|
@@ -14,6 +14,7 @@
|
|
|
14
14
|
// own reported count says otherwise.
|
|
15
15
|
import { createHash } from 'node:crypto';
|
|
16
16
|
import { NormalizeError, atOrAboveThreshold, } from './envelope.js';
|
|
17
|
+
import { profileFor } from './products.js';
|
|
17
18
|
const BLOCKING_MISMATCH = 'conductor/blocking-count-mismatch';
|
|
18
19
|
const THRESHOLD_UNKNOWN = 'conductor/blocking-threshold-unknown';
|
|
19
20
|
function isRecord(value) {
|
|
@@ -1045,6 +1046,17 @@ function gateProblem(ruleId, role, product, message, details) {
|
|
|
1045
1046
|
details: { role, product, ...details },
|
|
1046
1047
|
};
|
|
1047
1048
|
}
|
|
1049
|
+
/**
|
|
1050
|
+
* What to install for a product, spelled so it cannot be mistaken for
|
|
1051
|
+
* another package. The three npm gates are published under the
|
|
1052
|
+
* @vaultcompass scope only: the unscoped dep-guard and intent-guard names are
|
|
1053
|
+
* unclaimed on npm, so a reader (or an agent) told to install the bare name
|
|
1054
|
+
* could install a squatted package. The external tools are not npm packages
|
|
1055
|
+
* of this family and keep their own names.
|
|
1056
|
+
*/
|
|
1057
|
+
export function installName(product) {
|
|
1058
|
+
return profileFor(product).managed ? `@vaultcompass/${product}` : product;
|
|
1059
|
+
}
|
|
1048
1060
|
/**
|
|
1049
1061
|
* The finding raised when an ENABLED gate's binary cannot be found.
|
|
1050
1062
|
*
|
|
@@ -1066,7 +1078,7 @@ export function normalizeMissingGate(role, product, candidates,
|
|
|
1066
1078
|
*/
|
|
1067
1079
|
remedy = '') {
|
|
1068
1080
|
return gateProblem('conductor/gate-missing', role, product, `The "${role}" gate is enabled but no ${product} binary was found. ` +
|
|
1069
|
-
`Looked for: ${candidates.join(', ')}. Install
|
|
1081
|
+
`Looked for: ${candidates.join(', ')}. Install ${installName(product)}, point the gate at a build with an ` +
|
|
1070
1082
|
`absolute "command:", or set enabled: false to switch the gate off on purpose.${remedy}`, { candidates });
|
|
1071
1083
|
}
|
|
1072
1084
|
/**
|
package/dist/output-text.d.ts
CHANGED
|
@@ -31,6 +31,8 @@ export declare function jobLogSummary(result: RunResult): string;
|
|
|
31
31
|
* the state without parsing the verdict sentence.
|
|
32
32
|
*
|
|
33
33
|
* pass exit 0 and nothing was hidden by it
|
|
34
|
+
* nothing-checked exit 0, but no gate ran at all (none enabled,
|
|
35
|
+
* or every one deferred, tree-unchanged or skipped)
|
|
34
36
|
* advisory-blocked (N) exit 1 that --advisory turned into exit 0
|
|
35
37
|
* unenforced-findings (N) exit 0, but enforce: false gates blocked or
|
|
36
38
|
* could not run
|
|
@@ -51,8 +53,8 @@ export declare function jobLogSummary(result: RunResult): string;
|
|
|
51
53
|
*
|
|
52
54
|
* A SKIPPED gate (no contract, or a waived spec) is in result.skipped rather
|
|
53
55
|
* than result.gates, is neither a blocking finding nor a could-not-run, and
|
|
54
|
-
* so does not by itself move the token off pass
|
|
55
|
-
*
|
|
56
|
+
* so does not by itself move the token off pass when another gate ran. When
|
|
57
|
+
* NO gate ran, the token is nothing-checked, matching the verdict sentence.
|
|
56
58
|
*
|
|
57
59
|
* Any exit code outside 0, 1 and 2 is could-not-run: an unknown state is
|
|
58
60
|
* not a pass.
|
package/dist/output-text.js
CHANGED
|
@@ -405,6 +405,8 @@ function blockingCount(gate) {
|
|
|
405
405
|
* the state without parsing the verdict sentence.
|
|
406
406
|
*
|
|
407
407
|
* pass exit 0 and nothing was hidden by it
|
|
408
|
+
* nothing-checked exit 0, but no gate ran at all (none enabled,
|
|
409
|
+
* or every one deferred, tree-unchanged or skipped)
|
|
408
410
|
* advisory-blocked (N) exit 1 that --advisory turned into exit 0
|
|
409
411
|
* unenforced-findings (N) exit 0, but enforce: false gates blocked or
|
|
410
412
|
* could not run
|
|
@@ -425,8 +427,8 @@ function blockingCount(gate) {
|
|
|
425
427
|
*
|
|
426
428
|
* A SKIPPED gate (no contract, or a waived spec) is in result.skipped rather
|
|
427
429
|
* than result.gates, is neither a blocking finding nor a could-not-run, and
|
|
428
|
-
* so does not by itself move the token off pass
|
|
429
|
-
*
|
|
430
|
+
* so does not by itself move the token off pass when another gate ran. When
|
|
431
|
+
* NO gate ran, the token is nothing-checked, matching the verdict sentence.
|
|
430
432
|
*
|
|
431
433
|
* Any exit code outside 0, 1 and 2 is could-not-run: an unknown state is
|
|
432
434
|
* not a pass.
|
|
@@ -443,6 +445,13 @@ export function verdictToken(result, advisory) {
|
|
|
443
445
|
.reduce((total, gate) => total + blockingCount(gate), 0);
|
|
444
446
|
return advisory ? `advisory-blocked (${count})` : `blocked (${count})`;
|
|
445
447
|
}
|
|
448
|
+
// Exit 0 with no gate having run at all (none enabled, every one deferred,
|
|
449
|
+
// tree-unchanged or skipped): the exit code stays 0, since nothing failed,
|
|
450
|
+
// but the label must not say pass. It is the same condition the verdict
|
|
451
|
+
// sentence words as "nothing was checked".
|
|
452
|
+
if (result.gates.length === 0) {
|
|
453
|
+
return 'nothing-checked';
|
|
454
|
+
}
|
|
446
455
|
const unenforced = result.gates
|
|
447
456
|
.filter((gate) => !gate.enforce)
|
|
448
457
|
.reduce((total, gate) => total + (gate.couldNotRun !== null ? 1 : blockingCount(gate)), 0);
|
package/dist/products.js
CHANGED
|
@@ -39,7 +39,7 @@ function managedRemedy(product) {
|
|
|
39
39
|
? `Install the gate outside the tree with npm install -g @vaultcompass/${product}. The ` +
|
|
40
40
|
`conductor Action does exactly that, at the version its ${product}-version input pins, and ` +
|
|
41
41
|
'that pin lives in the workflow file on the base branch.'
|
|
42
|
-
: `
|
|
42
|
+
: `The package is @vaultcompass/${product}, never the unscoped name: install it with npm install -g @vaultcompass/${product}, or add @vaultcompass/${product} to the repository's devDependencies.`;
|
|
43
43
|
}
|
|
44
44
|
function managedProfile(product) {
|
|
45
45
|
return {
|
package/dist/trust-base.d.ts
CHANGED
|
@@ -1,3 +1,49 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The private, fully spelled ref the composite action fetches the base branch
|
|
3
|
+
* into (action.yml, gates step). Nothing else writes it and no short name can
|
|
4
|
+
* shadow it: git resolves a short name like origin/main through refs/tags/
|
|
5
|
+
* BEFORE refs/remotes/, so a tag pushed by anyone able to push tags would
|
|
6
|
+
* otherwise choose the commit the rules are read from.
|
|
7
|
+
*/
|
|
8
|
+
export declare const PRIVATE_TRUST_BASE_REF = "refs/conductor/trust-base";
|
|
9
|
+
/**
|
|
10
|
+
* The object id a fully spelled ref EXACTLY names, or null when there is no
|
|
11
|
+
* such ref. `show-ref --verify` looks at that ref and nothing else: it does
|
|
12
|
+
* not run git's name-resolution rules, so a tag stored as
|
|
13
|
+
* refs/tags/refs/conductor/trust-base is never taken for
|
|
14
|
+
* refs/conductor/trust-base.
|
|
15
|
+
*/
|
|
16
|
+
export declare function exactRefObject(repoRoot: string, fullRef: string): string | null;
|
|
17
|
+
/**
|
|
18
|
+
* A caller-given trust base that starts with "-", or null. Git allows a tag
|
|
19
|
+
* named refs/tags/--output=x, and such a name handed to git as an argument is
|
|
20
|
+
* read as an option, not a revision. Refused before any git call sees it; the
|
|
21
|
+
* git calls below also pass --end-of-options as a second line of defence.
|
|
22
|
+
*/
|
|
23
|
+
export declare function refuseDashLeadingRef(ref: string): string | null;
|
|
24
|
+
/** A full 40- or 64-hex object id: never subject to ref name resolution. */
|
|
25
|
+
export declare function isFullObjectId(value: string): boolean;
|
|
26
|
+
/**
|
|
27
|
+
* Why a SHORT ref name cannot be trusted as spelled, or null.
|
|
28
|
+
*
|
|
29
|
+
* A name that matches more than one kind of ref (a tag and a remote-tracking
|
|
30
|
+
* ref or a branch) is resolved by git in its own precedence order, tags
|
|
31
|
+
* first, with no warning under --quiet. That is a choice made by whoever can
|
|
32
|
+
* create the tag, so it is refused rather than resolved. A ref already spelled
|
|
33
|
+
* from refs/ is unambiguous, and revision expressions (HEAD, HEAD~1, a sha) are
|
|
34
|
+
* not names and are left to the callers' own checks.
|
|
35
|
+
*/
|
|
36
|
+
export declare function refuseAmbiguousRef(repoRoot: string, ref: string,
|
|
37
|
+
/** What the ref is used as, for the message: "the trust base", "the intent base". */
|
|
38
|
+
noun?: string): string | null;
|
|
39
|
+
/**
|
|
40
|
+
* What a rev resolves to at this repository, or null when it does not.
|
|
41
|
+
*
|
|
42
|
+
* `--quiet` suppresses git's own explanation, so there is nothing worth
|
|
43
|
+
* forwarding on failure: the caller writes a sentence a reader can act on
|
|
44
|
+
* rather than repeating the command line that failed.
|
|
45
|
+
*/
|
|
46
|
+
export declare function resolveRev(repoRoot: string, rev: string, kind: 'commit' | 'tree'): string | null;
|
|
1
47
|
/**
|
|
2
48
|
* Whether HEAD's tree is byte-identical to the trust base's tree.
|
|
3
49
|
*
|
|
@@ -54,11 +100,12 @@ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): strin
|
|
|
54
100
|
* NAME on a pull_request or pull_request_target event, and empty everywhere
|
|
55
101
|
* else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
|
|
56
102
|
* a platform that never sets it. When it is set, the given ref is accepted
|
|
57
|
-
* only when it
|
|
58
|
-
*
|
|
59
|
-
*
|
|
60
|
-
*
|
|
61
|
-
*
|
|
103
|
+
* only when it is the FULL COMMIT ID the composite action's "Fetch the trust
|
|
104
|
+
* base" step published (which must equal refs/conductor/trust-base, the
|
|
105
|
+
* authority, or refs/remotes/origin/<githubBaseRef>, both read with show-ref),
|
|
106
|
+
* or is that private ref itself, or -- for an explicit trust base -- resolves
|
|
107
|
+
* to the same commit as refs/remotes/origin/<githubBaseRef>. So an ordinary
|
|
108
|
+
* pull-request run through the action returns null here, before
|
|
62
109
|
* refuseTrustBaseRef's own checks -- HEAD, and the equal-tree exception from
|
|
63
110
|
* issue #69/#73 -- ever run: this check is narrower than those and says
|
|
64
111
|
* nothing about HEAD or about tree equality, only about whether the given ref
|
|
@@ -66,11 +113,11 @@ export declare function refuseTrustBaseRef(repoRoot: string, ref: string): strin
|
|
|
66
113
|
* request's own branch, or anything else that disagrees, is refused with both
|
|
67
114
|
* refs and both commits named.
|
|
68
115
|
*
|
|
69
|
-
* FAILS CLOSED when
|
|
70
|
-
*
|
|
71
|
-
*
|
|
72
|
-
* fetch-depth: 0, and a checkout
|
|
73
|
-
* reason to skip the comparison.
|
|
116
|
+
* FAILS CLOSED when neither the private ref nor refs/remotes/origin/
|
|
117
|
+
* <githubBaseRef> exists, naming them: reachable through the CLI on the
|
|
118
|
+
* default actions/checkout (fetch-depth: 1), which does not carry the base
|
|
119
|
+
* branch at all. The README already asks for fetch-depth: 0, and a checkout
|
|
120
|
+
* that does not carry the base branch is not a reason to skip the comparison.
|
|
74
121
|
*
|
|
75
122
|
* When the GIVEN ref does not resolve at all, this returns null rather than
|
|
76
123
|
* refusing: refuseTrustBaseRef is the function with its own sentence for an
|
package/dist/trust-base.js
CHANGED
|
@@ -69,6 +69,93 @@ import { realpathSync } from 'node:fs';
|
|
|
69
69
|
import path from 'node:path';
|
|
70
70
|
import { parse as parseYaml } from 'yaml';
|
|
71
71
|
import { POLICY_FILE_NAME } from './policy.js';
|
|
72
|
+
/**
|
|
73
|
+
* The private, fully spelled ref the composite action fetches the base branch
|
|
74
|
+
* into (action.yml, gates step). Nothing else writes it and no short name can
|
|
75
|
+
* shadow it: git resolves a short name like origin/main through refs/tags/
|
|
76
|
+
* BEFORE refs/remotes/, so a tag pushed by anyone able to push tags would
|
|
77
|
+
* otherwise choose the commit the rules are read from.
|
|
78
|
+
*/
|
|
79
|
+
export const PRIVATE_TRUST_BASE_REF = 'refs/conductor/trust-base';
|
|
80
|
+
function refExists(repoRoot, fullRef) {
|
|
81
|
+
const child = spawnSync('git', ['show-ref', '--verify', '--quiet', fullRef], {
|
|
82
|
+
cwd: repoRoot,
|
|
83
|
+
encoding: 'utf8',
|
|
84
|
+
});
|
|
85
|
+
return child.error === undefined && child.status === 0;
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* The object id a fully spelled ref EXACTLY names, or null when there is no
|
|
89
|
+
* such ref. `show-ref --verify` looks at that ref and nothing else: it does
|
|
90
|
+
* not run git's name-resolution rules, so a tag stored as
|
|
91
|
+
* refs/tags/refs/conductor/trust-base is never taken for
|
|
92
|
+
* refs/conductor/trust-base.
|
|
93
|
+
*/
|
|
94
|
+
export function exactRefObject(repoRoot, fullRef) {
|
|
95
|
+
const child = spawnSync('git', ['show-ref', '--verify', '--hash', fullRef], {
|
|
96
|
+
cwd: repoRoot,
|
|
97
|
+
encoding: 'utf8',
|
|
98
|
+
});
|
|
99
|
+
if (child.error !== undefined || child.status !== 0) {
|
|
100
|
+
return null;
|
|
101
|
+
}
|
|
102
|
+
const value = (child.stdout ?? '').trim();
|
|
103
|
+
return /^[0-9a-f]{40}([0-9a-f]{24})?$/.test(value) ? value : null;
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* A caller-given trust base that starts with "-", or null. Git allows a tag
|
|
107
|
+
* named refs/tags/--output=x, and such a name handed to git as an argument is
|
|
108
|
+
* read as an option, not a revision. Refused before any git call sees it; the
|
|
109
|
+
* git calls below also pass --end-of-options as a second line of defence.
|
|
110
|
+
*/
|
|
111
|
+
export function refuseDashLeadingRef(ref) {
|
|
112
|
+
if (!ref.startsWith('-')) {
|
|
113
|
+
return null;
|
|
114
|
+
}
|
|
115
|
+
return (`refusing "${ref}" as the trust base: it starts with "-", which git would read as an ` +
|
|
116
|
+
'option rather than a revision. Pass a ref name or a full commit id. Nothing was checked.');
|
|
117
|
+
}
|
|
118
|
+
/** A full 40- or 64-hex object id: never subject to ref name resolution. */
|
|
119
|
+
export function isFullObjectId(value) {
|
|
120
|
+
return /^([0-9a-f]{40}|[0-9a-f]{64})$/i.test(value);
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* Why a SHORT ref name cannot be trusted as spelled, or null.
|
|
124
|
+
*
|
|
125
|
+
* A name that matches more than one kind of ref (a tag and a remote-tracking
|
|
126
|
+
* ref or a branch) is resolved by git in its own precedence order, tags
|
|
127
|
+
* first, with no warning under --quiet. That is a choice made by whoever can
|
|
128
|
+
* create the tag, so it is refused rather than resolved. A ref already spelled
|
|
129
|
+
* from refs/ is unambiguous, and revision expressions (HEAD, HEAD~1, a sha) are
|
|
130
|
+
* not names and are left to the callers' own checks.
|
|
131
|
+
*/
|
|
132
|
+
export function refuseAmbiguousRef(repoRoot, ref,
|
|
133
|
+
/** What the ref is used as, for the message: "the trust base", "the intent base". */
|
|
134
|
+
noun = 'the trust base') {
|
|
135
|
+
// The NAME part only: origin/main~0, origin/main^{commit} and origin/main@{0}
|
|
136
|
+
// resolve through the same tag-first rules as origin/main, so a revision
|
|
137
|
+
// suffix is cut off (from the first ~ ^ : or @{) before the check. A bare @
|
|
138
|
+
// is HEAD and is NOT a cut: a name may carry a literal @ (a branch and a tag
|
|
139
|
+
// both named feature@x, where git picks the tag), and cutting there hid it.
|
|
140
|
+
const cut = ref.search(/[~^:]|@\{/);
|
|
141
|
+
const name = cut === -1 ? ref : ref.slice(0, cut);
|
|
142
|
+
if (name === '' ||
|
|
143
|
+
name === 'HEAD' ||
|
|
144
|
+
name === '@' ||
|
|
145
|
+
name.startsWith('refs/') ||
|
|
146
|
+
/[\s{}\\]/.test(name) ||
|
|
147
|
+
isFullObjectId(name)) {
|
|
148
|
+
return null;
|
|
149
|
+
}
|
|
150
|
+
const matches = [`refs/tags/${name}`, `refs/heads/${name}`, `refs/remotes/${name}`].filter((full) => refExists(repoRoot, full));
|
|
151
|
+
if (matches.length <= 1) {
|
|
152
|
+
return null;
|
|
153
|
+
}
|
|
154
|
+
return (`refusing "${ref}" as ${noun}: the name "${name}" is ambiguous, it matches ${matches.join(' and ')}, ` +
|
|
155
|
+
'and git would pick one of them by its own precedence (tags first). Whoever can push a tag ' +
|
|
156
|
+
'could choose the base this way. Pass the ref spelled in full, for example ' +
|
|
157
|
+
'refs/remotes/origin/main. Nothing was checked.');
|
|
158
|
+
}
|
|
72
159
|
/**
|
|
73
160
|
* What a rev resolves to at this repository, or null when it does not.
|
|
74
161
|
*
|
|
@@ -76,8 +163,21 @@ import { POLICY_FILE_NAME } from './policy.js';
|
|
|
76
163
|
* forwarding on failure: the caller writes a sentence a reader can act on
|
|
77
164
|
* rather than repeating the command line that failed.
|
|
78
165
|
*/
|
|
79
|
-
function resolveRev(repoRoot, rev, kind) {
|
|
80
|
-
|
|
166
|
+
export function resolveRev(repoRoot, rev, kind) {
|
|
167
|
+
// A refs/ name is NEVER handed to git's name resolution: rev-parse would
|
|
168
|
+
// try refs/tags/<name> when the ref itself is absent, so a pushed tag named
|
|
169
|
+
// refs/conductor/trust-base would stand in for the private ref. The exact
|
|
170
|
+
// ref is read with show-ref and its object id is what gets resolved (a full
|
|
171
|
+
// object id is not subject to name resolution).
|
|
172
|
+
let target = rev;
|
|
173
|
+
if (rev.startsWith('refs/')) {
|
|
174
|
+
const exact = exactRefObject(repoRoot, rev);
|
|
175
|
+
if (exact === null) {
|
|
176
|
+
return null;
|
|
177
|
+
}
|
|
178
|
+
target = exact;
|
|
179
|
+
}
|
|
180
|
+
const child = spawnSync('git', ['rev-parse', '--verify', '--quiet', '--end-of-options', `${target}^{${kind}}`], {
|
|
81
181
|
cwd: repoRoot,
|
|
82
182
|
encoding: 'utf8',
|
|
83
183
|
});
|
|
@@ -150,6 +250,14 @@ export function headTreeEqualsBase(repoRoot, ref) {
|
|
|
150
250
|
* learns the trees matched even on this accepted path.
|
|
151
251
|
*/
|
|
152
252
|
export function refuseTrustBaseRef(repoRoot, ref) {
|
|
253
|
+
const dashed = refuseDashLeadingRef(ref);
|
|
254
|
+
if (dashed !== null) {
|
|
255
|
+
return dashed;
|
|
256
|
+
}
|
|
257
|
+
const ambiguous = refuseAmbiguousRef(repoRoot, ref);
|
|
258
|
+
if (ambiguous !== null) {
|
|
259
|
+
return ambiguous;
|
|
260
|
+
}
|
|
153
261
|
const base = resolveRev(repoRoot, ref, 'commit');
|
|
154
262
|
if (base === null) {
|
|
155
263
|
return (`cannot read the policy from base ref "${ref}": it does not resolve to a commit in ` +
|
|
@@ -211,11 +319,12 @@ export function refuseTrustBaseRef(repoRoot, ref) {
|
|
|
211
319
|
* NAME on a pull_request or pull_request_target event, and empty everywhere
|
|
212
320
|
* else -- a push, a schedule, workflow_dispatch, merge_group, a local run, or
|
|
213
321
|
* a platform that never sets it. When it is set, the given ref is accepted
|
|
214
|
-
* only when it
|
|
215
|
-
*
|
|
216
|
-
*
|
|
217
|
-
*
|
|
218
|
-
*
|
|
322
|
+
* only when it is the FULL COMMIT ID the composite action's "Fetch the trust
|
|
323
|
+
* base" step published (which must equal refs/conductor/trust-base, the
|
|
324
|
+
* authority, or refs/remotes/origin/<githubBaseRef>, both read with show-ref),
|
|
325
|
+
* or is that private ref itself, or -- for an explicit trust base -- resolves
|
|
326
|
+
* to the same commit as refs/remotes/origin/<githubBaseRef>. So an ordinary
|
|
327
|
+
* pull-request run through the action returns null here, before
|
|
219
328
|
* refuseTrustBaseRef's own checks -- HEAD, and the equal-tree exception from
|
|
220
329
|
* issue #69/#73 -- ever run: this check is narrower than those and says
|
|
221
330
|
* nothing about HEAD or about tree equality, only about whether the given ref
|
|
@@ -223,11 +332,11 @@ export function refuseTrustBaseRef(repoRoot, ref) {
|
|
|
223
332
|
* request's own branch, or anything else that disagrees, is refused with both
|
|
224
333
|
* refs and both commits named.
|
|
225
334
|
*
|
|
226
|
-
* FAILS CLOSED when
|
|
227
|
-
*
|
|
228
|
-
*
|
|
229
|
-
* fetch-depth: 0, and a checkout
|
|
230
|
-
* reason to skip the comparison.
|
|
335
|
+
* FAILS CLOSED when neither the private ref nor refs/remotes/origin/
|
|
336
|
+
* <githubBaseRef> exists, naming them: reachable through the CLI on the
|
|
337
|
+
* default actions/checkout (fetch-depth: 1), which does not carry the base
|
|
338
|
+
* branch at all. The README already asks for fetch-depth: 0, and a checkout
|
|
339
|
+
* that does not carry the base branch is not a reason to skip the comparison.
|
|
231
340
|
*
|
|
232
341
|
* When the GIVEN ref does not resolve at all, this returns null rather than
|
|
233
342
|
* refusing: refuseTrustBaseRef is the function with its own sentence for an
|
|
@@ -241,24 +350,85 @@ export function refuseTrustBaseForPullRequest(repoRoot, ref, githubBaseRef) {
|
|
|
241
350
|
if (githubBaseRef === undefined || githubBaseRef === '') {
|
|
242
351
|
return null;
|
|
243
352
|
}
|
|
244
|
-
const
|
|
353
|
+
const dashed = refuseDashLeadingRef(ref);
|
|
354
|
+
if (dashed !== null) {
|
|
355
|
+
return dashed;
|
|
356
|
+
}
|
|
357
|
+
const ambiguous = refuseAmbiguousRef(repoRoot, ref);
|
|
358
|
+
if (ambiguous !== null) {
|
|
359
|
+
return ambiguous;
|
|
360
|
+
}
|
|
361
|
+
// SPELLED IN FULL, and read with show-ref (resolveRev does that for every
|
|
362
|
+
// refs/ name): a short origin/<base> would resolve through
|
|
363
|
+
// refs/tags/origin/<base> first, and a refs/ name through a tag of that
|
|
364
|
+
// name when the ref is absent.
|
|
365
|
+
const expectedRef = `refs/remotes/origin/${githubBaseRef}`;
|
|
245
366
|
const expectedCommit = resolveRev(repoRoot, expectedRef, 'commit');
|
|
367
|
+
const privateCommit = resolveRev(repoRoot, PRIVATE_TRUST_BASE_REF, 'commit');
|
|
368
|
+
// THE ACTION PASSES A FULL COMMIT ID, never a ref name (a full object id is
|
|
369
|
+
// not subject to name resolution). It is accepted only when it IS the
|
|
370
|
+
// private ref's commit (the authority, fetched and verified by the action's
|
|
371
|
+
// fetch step) or, ONLY when the private ref does not exist, the commit of
|
|
372
|
+
// refs/remotes/origin/<base> (both read with show-ref).
|
|
373
|
+
if (isFullObjectId(ref)) {
|
|
374
|
+
const given = resolveRev(repoRoot, ref, 'commit');
|
|
375
|
+
if (given === null) {
|
|
376
|
+
return null;
|
|
377
|
+
}
|
|
378
|
+
// The private ref is the ONLY acceptable answer when it exists: pull-request
|
|
379
|
+
// code can move refs/remotes/origin/<base>, so an id that matches only that
|
|
380
|
+
// ref is the attack, not a second answer. The remote-tracking ref is the
|
|
381
|
+
// reference only when the private ref is absent.
|
|
382
|
+
if (privateCommit !== null ? given === privateCommit : given === expectedCommit) {
|
|
383
|
+
return null;
|
|
384
|
+
}
|
|
385
|
+
if (privateCommit === null && expectedCommit === null) {
|
|
386
|
+
return (`cannot verify "${ref}" as the trust base: neither ${PRIVATE_TRUST_BASE_REF} (the ` +
|
|
387
|
+
`composite action's fetch of the base branch) nor "${expectedRef}" exists in this ` +
|
|
388
|
+
'repository, so there is nothing to compare it against. Nothing was checked. In CI, fetch ' +
|
|
389
|
+
'the base branch (actions/checkout with fetch-depth: 0) before running the gates.');
|
|
390
|
+
}
|
|
391
|
+
return (`refusing "${ref}" as the trust base: GITHUB_BASE_REF is set to "${githubBaseRef}", so this ` +
|
|
392
|
+
'run is a pull request, and on a pull request the trust base must be the base branch and ' +
|
|
393
|
+
`nothing else. It equals neither ${PRIVATE_TRUST_BASE_REF} (${privateCommit ?? 'absent'}) ` +
|
|
394
|
+
`nor ${expectedRef} (${expectedCommit ?? 'absent'}). Nothing was checked.`);
|
|
395
|
+
}
|
|
396
|
+
// THE PRIVATE REF IS THE AUTHORITY, and nothing reads
|
|
397
|
+
// refs/remotes/origin/<base> for trust. That ref is fixed at checkout time
|
|
398
|
+
// and is the side pull-request code can move, while the private ref is
|
|
399
|
+
// fetched later by the action: comparing them adds a false refusal whenever
|
|
400
|
+
// the base branch advances in between, and no protection. Only an explicit
|
|
401
|
+
// trust base (below) has the remote-tracking ref as its one reference.
|
|
402
|
+
if (ref === PRIVATE_TRUST_BASE_REF) {
|
|
403
|
+
if (privateCommit !== null) {
|
|
404
|
+
return null;
|
|
405
|
+
}
|
|
406
|
+
return (`refusing "${ref}" as the trust base: no such ref exists in this repository (a tag or ` +
|
|
407
|
+
'branch of that name does not count: only the exact ref the action fetched does). The ' +
|
|
408
|
+
'action\'s fetch of the base branch did not run or did not succeed. Nothing was checked.');
|
|
409
|
+
}
|
|
246
410
|
if (expectedCommit === null) {
|
|
247
411
|
return (`cannot verify "${ref}" as the trust base: "${expectedRef}" does not resolve to a commit ` +
|
|
248
|
-
|
|
249
|
-
|
|
412
|
+
`in this repository, so there is nothing to compare it against, and only ` +
|
|
413
|
+
`${PRIVATE_TRUST_BASE_REF} (fetched by the composite action) is accepted without it. ` +
|
|
414
|
+
'Nothing was checked. In CI, fetch the base branch (actions/checkout with ' +
|
|
415
|
+
'fetch-depth: 0) before running the gates.');
|
|
250
416
|
}
|
|
251
417
|
const givenCommit = resolveRev(repoRoot, ref, 'commit');
|
|
252
418
|
if (givenCommit === null) {
|
|
253
419
|
return null;
|
|
254
420
|
}
|
|
421
|
+
// A NAMED explicit trust base may equal refs/remotes/origin/<base> even
|
|
422
|
+
// while the private ref exists: the full-id rule above applies to the
|
|
423
|
+
// action's own id, not to a name the caller typed.
|
|
255
424
|
if (givenCommit === expectedCommit) {
|
|
256
425
|
return null;
|
|
257
426
|
}
|
|
258
427
|
return (`refusing "${ref}" as the trust base: GITHUB_BASE_REF is set to "${githubBaseRef}", so this ` +
|
|
259
428
|
'run is a pull request, and on a pull request the trust base must be the base branch and ' +
|
|
260
429
|
`nothing else. "${ref}" resolves to ${givenCommit}, and "${expectedRef}" resolves to ` +
|
|
261
|
-
`${expectedCommit}, a different commit
|
|
430
|
+
`${expectedCommit}, a different commit: something moved one of them, so neither can be ` +
|
|
431
|
+
`trusted. Pass ${expectedRef} or ${PRIVATE_TRUST_BASE_REF} instead. Nothing was checked.`);
|
|
262
432
|
}
|
|
263
433
|
/**
|
|
264
434
|
* The policy file's contents at a ref, or null when that ref carries none.
|
|
@@ -270,7 +440,10 @@ export function refuseTrustBaseForPullRequest(repoRoot, ref, githubBaseRef) {
|
|
|
270
440
|
* be from somewhere else.
|
|
271
441
|
*/
|
|
272
442
|
export function readPolicyAtRef(repoRoot, ref) {
|
|
273
|
-
|
|
443
|
+
if (ref.startsWith('-')) {
|
|
444
|
+
return null;
|
|
445
|
+
}
|
|
446
|
+
const child = spawnSync('git', ['show', '--end-of-options', `${ref}:./${POLICY_FILE_NAME}`], {
|
|
274
447
|
cwd: repoRoot,
|
|
275
448
|
encoding: 'utf8',
|
|
276
449
|
maxBuffer: 32 * 1024 * 1024,
|
|
@@ -323,7 +496,10 @@ export const POLICY_PROPOSAL_LINE = 'policy changed in this pull request';
|
|
|
323
496
|
* symlink, a submodule or a directory in the same read.
|
|
324
497
|
*/
|
|
325
498
|
export function treeEntryAt(repoRoot, ref, relativePath) {
|
|
326
|
-
|
|
499
|
+
if (ref.startsWith('-')) {
|
|
500
|
+
return null;
|
|
501
|
+
}
|
|
502
|
+
const child = spawnSync('git', ['ls-tree', '--end-of-options', ref, '--', `./${relativePath}`], {
|
|
327
503
|
cwd: repoRoot,
|
|
328
504
|
encoding: 'utf8',
|
|
329
505
|
});
|