@vaultcompass/conductor 0.6.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 +200 -48
- package/dist/cli.js +96 -16
- 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 +35 -0
- package/dist/output-text.js +89 -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,8 @@ 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
|
+
verdict-token: blocked (1)
|
|
171
172
|
conductor run: 2 gate(s), 1 finding(s)
|
|
172
173
|
|
|
173
174
|
dependencies dep-guard 0.7.0 exit 0 153ms via dep-guard on path
|
|
@@ -222,7 +223,9 @@ required.
|
|
|
222
223
|
exit code, only a blocking finding's. Leaving the check out of branch
|
|
223
224
|
protection is what keeps that expected exit 2 from blocking the merge;
|
|
224
225
|
the step posts a comment saying so with the remedy on it, which is the
|
|
225
|
-
honest report of an unfinished adoption, not a broken tool.
|
|
226
|
+
honest report of an unfinished adoption, not a broken tool. The same
|
|
227
|
+
refusal recurs once on every new base branch; see "Why the first pull
|
|
228
|
+
request still exits 2 under `advisory: true`" below.
|
|
226
229
|
|
|
227
230
|
3. **Merge.** Every pull request after that is judged by the policy on the
|
|
228
231
|
base branch, and a change to that policy shows up as a proposal line and
|
|
@@ -470,7 +473,8 @@ proceeds normally without mentioning them.
|
|
|
470
473
|
pull-request run passes both: `--base` decides which paths are judged,
|
|
471
474
|
`--trust-base` decides what they are judged by. When `GITHUB_BASE_REF` is
|
|
472
475
|
set, an explicit `--trust-base` is accepted only when it resolves to the
|
|
473
|
-
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
|
|
474
478
|
CLI directly on a pull request, rather than through the Action, gets this
|
|
475
479
|
as its own refusal, named below.
|
|
476
480
|
- `--spec <path>` names the spec the intent gate imports its contract from.
|
|
@@ -483,6 +487,15 @@ proceeds normally without mentioning them.
|
|
|
483
487
|
repository root: with `--project` pointing elsewhere, a relative
|
|
484
488
|
`--output` still lands next to where you are, not next to the repository
|
|
485
489
|
being judged.
|
|
490
|
+
- `--text-report <path>`, with `--format sarif`, also writes the text report
|
|
491
|
+
to that file **from the same run**: exactly what `--format text` would have
|
|
492
|
+
rendered for this result (`--verbose`, `--compact-on-refusal` and
|
|
493
|
+
`--advisory` respected), and no gate is run a second time. This is how the
|
|
494
|
+
Action gets a SARIF log, a comment body and a verdict token that are one
|
|
495
|
+
run's answer. With `--format text` it is refused as a usage error (exit 2),
|
|
496
|
+
before any gate runs: the text report is the output already, so a second
|
|
497
|
+
copy in a file would only duplicate it. A path that cannot be written is
|
|
498
|
+
exit 2, like `--output`. See "The verdict token" below.
|
|
486
499
|
- `--verbose` prints the full per-gate report even when the run is clean.
|
|
487
500
|
Text output only; the SARIF log never changes shape with it.
|
|
488
501
|
- `--compact-on-refusal` shrinks the report to the version, the verdict and
|
|
@@ -548,6 +561,44 @@ could not run is a different failure from a blocking finding, and advisory
|
|
|
548
561
|
mode exists to leave that one alone. See "Running the gates as an advisory
|
|
549
562
|
check" below.
|
|
550
563
|
|
|
564
|
+
### The verdict token
|
|
565
|
+
|
|
566
|
+
The text report carries one more line: `verdict-token: <token>`, the **second
|
|
567
|
+
line**, directly under the version line (the closing `verdict:` sentence is
|
|
568
|
+
unchanged). It is a label for the umbrella's own exit decision, in a closed
|
|
569
|
+
set, so a person or a script can read the state without parsing a sentence.
|
|
570
|
+
It decides nothing and never overrules a gate: it is derived from the exit
|
|
571
|
+
code and the `enforce` flags the run already had.
|
|
572
|
+
|
|
573
|
+
- `pass`: exit 0, and no gate, enforced or not, has a blocking finding or
|
|
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`.
|
|
580
|
+
- `advisory-blocked (N)`: the run would have exited 1, and `--advisory` made
|
|
581
|
+
it exit 0. N is the blocking findings on enforced gates.
|
|
582
|
+
- `unenforced-findings (N)`: exit 0, but a gate with `enforce: false` had
|
|
583
|
+
blocking findings or could not run. N counts those findings plus those
|
|
584
|
+
gates. Exit 0 here is not a pass, and the token says so.
|
|
585
|
+
- `blocked (N)`: exit 1. N as for `advisory-blocked`.
|
|
586
|
+
- `could-not-run`: exit 2, a refused trust base included.
|
|
587
|
+
|
|
588
|
+
When several apply the order is `could-not-run`, then `blocked` or
|
|
589
|
+
`advisory-blocked`, then `unenforced-findings`, then `nothing-checked` (no gate
|
|
590
|
+
ran) or `pass`. A run with
|
|
591
|
+
`--advisory` whose only blocking findings sit on an unenforced gate is
|
|
592
|
+
`unenforced-findings`, not `advisory-blocked`, because the flag did nothing
|
|
593
|
+
there. A gate skipped for want of a contract does not by itself move the token
|
|
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
|
|
596
|
+
gate that exited non-zero with no finding marked blocking counts as one in N,
|
|
597
|
+
so a state that is not a pass never prints a count of zero. The one-line
|
|
598
|
+
summary of a clean, non-verbose run has no token line, since it is one line by
|
|
599
|
+
design. `conductor run` also prints the token on its job-log line,
|
|
600
|
+
`conductor run: 4 gate(s), 1 finding(s); verdict-token advisory-blocked (1); sarif report written to conductor.sarif`.
|
|
601
|
+
|
|
551
602
|
## The pull-request trust boundary
|
|
552
603
|
|
|
553
604
|
Every gate reads its own rules out of the repository it is judging. On a pull
|
|
@@ -694,15 +745,19 @@ to remove the input; see "The Action" below.
|
|
|
694
745
|
|
|
695
746
|
**The CLI check catches a misconfigured or innocent-looking redirect when
|
|
696
747
|
`GITHUB_BASE_REF` is set**, for anyone invoking the CLI directly in CI. When
|
|
697
|
-
that variable is set, an explicit `--trust-base` is accepted only when it
|
|
698
|
-
|
|
699
|
-
|
|
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
|
|
700
753
|
unaffected. A ref naming the pull request's own branch, or anything else that
|
|
701
754
|
disagrees, is refused with both refs and both commits named, through the same
|
|
702
755
|
could-not-run path as every other trust-base refusal: exit 2, the report
|
|
703
|
-
leads with the reason, and nothing is checked.
|
|
704
|
-
|
|
705
|
-
|
|
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.
|
|
706
761
|
|
|
707
762
|
**Neither layer closes anything against a pull request that edits its own
|
|
708
763
|
workflow file.** A CLI invocation on a pull request can simply omit
|
|
@@ -856,8 +911,11 @@ human step. That step is exactly what a pull request cannot carry, so at the
|
|
|
856
911
|
branch changed since it forked, from
|
|
857
912
|
`git diff --name-only --no-renames <base>...HEAD` in the repository root.
|
|
858
913
|
|
|
859
|
-
With no `--base`, `GITHUB_BASE_REF` is used
|
|
860
|
-
|
|
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
|
|
861
919
|
it does at a commit: against the staged index, or the paths you name.
|
|
862
920
|
|
|
863
921
|
**This is why a local preview and a pull-request run can disagree about a
|
|
@@ -1046,16 +1104,20 @@ provenance even though all four packages publish it.
|
|
|
1046
1104
|
> points npm at a mirror or proxy that does not (via `actions/setup-node`'s
|
|
1047
1105
|
> `registry-url:`, a corporate `~/.npmrc`, or `npm_config_registry`), the
|
|
1048
1106
|
> install succeeds and this step then fails with `EMISSINGSIGNATUREKEY`. A
|
|
1049
|
-
> sigstore outage has the same effect.
|
|
1050
|
-
>
|
|
1051
|
-
>
|
|
1107
|
+
> sigstore outage has the same effect. The audit is retried once after a short
|
|
1108
|
+
> pause before the step fails, to absorb a one-off registry hiccup. It fails
|
|
1109
|
+
> closed on purpose, so that is a red gate rather than a skipped check; pin to
|
|
1110
|
+
> `@v0.4.0`, which does not verify, if it blocks you.
|
|
1052
1111
|
|
|
1053
1112
|
`--base` is passed only when the `base-ref` input names one; left empty, the
|
|
1054
1113
|
umbrella reads `GITHUB_BASE_REF` itself and treats an empty value as "not a
|
|
1055
1114
|
pull request", which is what a push build wants.
|
|
1056
1115
|
|
|
1057
|
-
On a `pull_request` event the
|
|
1058
|
-
|
|
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
|
|
1059
1121
|
its configuration from the base branch and the pull request cannot change the
|
|
1060
1122
|
rules it is judged by; a change to the rules shows as a proposal line and
|
|
1061
1123
|
takes effect after merge. See "The pull-request trust boundary" above. On any
|
|
@@ -1069,7 +1131,8 @@ workflow file is the *base* branch's own instead, but the input is refused
|
|
|
1069
1131
|
there too, because pull-request mode already derives the trust base on both
|
|
1070
1132
|
events and an explicit redirect has no legitimate use on either. The refusal
|
|
1071
1133
|
names the value that was given and the fix, which is to remove the input: the
|
|
1072
|
-
action already derives `
|
|
1134
|
+
action already derives the private `refs/conductor/trust-base` itself on that
|
|
1135
|
+
event.
|
|
1073
1136
|
|
|
1074
1137
|
There is deliberately **no input that turns pull-request mode off**.
|
|
1075
1138
|
Base-ref judging is the floor rather than a knob, and on a `pull_request`
|
|
@@ -1104,7 +1167,7 @@ jobs:
|
|
|
1104
1167
|
with:
|
|
1105
1168
|
node-version: '22.11.0'
|
|
1106
1169
|
- id: conductor
|
|
1107
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1170
|
+
uses: vaultcompasshq/conductor@v0.8.0
|
|
1108
1171
|
with:
|
|
1109
1172
|
output: conductor.sarif
|
|
1110
1173
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -1114,6 +1177,14 @@ jobs:
|
|
|
1114
1177
|
sarif_file: ${{ steps.conductor.outputs.sarif }}
|
|
1115
1178
|
```
|
|
1116
1179
|
|
|
1180
|
+
The examples leave the trigger unnarrowed on purpose, so the job runs for a
|
|
1181
|
+
pull request into any branch. If you narrow it with a `branches:` filter,
|
|
1182
|
+
include every branch whose merges reach users, release branches and the
|
|
1183
|
+
production branch included, for instance `branches: [main, 'release/**',
|
|
1184
|
+
production]`. The pull request that promotes a release is where a bad
|
|
1185
|
+
dependency or a leaked secret actually ships, and a job that is not triggered
|
|
1186
|
+
leaves no red check and no report to notice.
|
|
1187
|
+
|
|
1117
1188
|
No version inputs there at all: left out, the four gates run at the versions
|
|
1118
1189
|
this tag ships, which is the intended default. The fully spelled-out example
|
|
1119
1190
|
below adds explicit version pins and comments explaining each one, for a
|
|
@@ -1139,7 +1210,6 @@ jobs:
|
|
|
1139
1210
|
# clone, because on a pull request the rules are read from it: a
|
|
1140
1211
|
# base ref that will not resolve is exit 2 for every enabled gate.
|
|
1141
1212
|
fetch-depth: 0
|
|
1142
|
-
- uses: pnpm/action-setup@v4
|
|
1143
1213
|
- uses: actions/setup-node@v7
|
|
1144
1214
|
with:
|
|
1145
1215
|
# Not a bare major: Node 22.0.0 ships npm 10.5.1, which the action
|
|
@@ -1147,13 +1217,16 @@ jobs:
|
|
|
1147
1217
|
# with. 22.1.0 or later, or 20.13.0 or later, carries an npm that
|
|
1148
1218
|
# can verify.
|
|
1149
1219
|
node-version: '22.11.0'
|
|
1150
|
-
|
|
1151
|
-
#
|
|
1152
|
-
#
|
|
1153
|
-
#
|
|
1154
|
-
|
|
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.
|
|
1155
1228
|
- id: conductor
|
|
1156
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1229
|
+
uses: vaultcompasshq/conductor@v0.8.0
|
|
1157
1230
|
with:
|
|
1158
1231
|
output: conductor.sarif
|
|
1159
1232
|
# Exact versions, never a range and never "latest". These four
|
|
@@ -1164,10 +1237,10 @@ jobs:
|
|
|
1164
1237
|
# request of their own. Forward only on a pull request: the action
|
|
1165
1238
|
# refuses a pin below what its tag ships, and the four lines can be
|
|
1166
1239
|
# left out entirely to take that tag's own versions.
|
|
1167
|
-
conductor-version: 0.
|
|
1168
|
-
dep-guard-version: 0.
|
|
1169
|
-
vault-guard-version: 1.
|
|
1170
|
-
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
|
|
1171
1244
|
- uses: github/codeql-action/upload-sarif@v3
|
|
1172
1245
|
# Always: the log is most worth having on the run that failed.
|
|
1173
1246
|
if: always()
|
|
@@ -1181,8 +1254,49 @@ jobs:
|
|
|
1181
1254
|
continue-on-error: true
|
|
1182
1255
|
with:
|
|
1183
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
|
|
1184
1271
|
```
|
|
1185
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
|
+
|
|
1186
1300
|
**The two external gates are installed by your workflow, not by the
|
|
1187
1301
|
Action.** The Action still installs exactly its four npm packages and has no
|
|
1188
1302
|
input for gitleaks or osv-scanner; conductor downloads, pins and checksums
|
|
@@ -1207,12 +1321,15 @@ checksum, the same way you would for a standalone security job:
|
|
|
1207
1321
|
echo "$bin" >> "$GITHUB_PATH"
|
|
1208
1322
|
```
|
|
1209
1323
|
|
|
1210
|
-
`fetch-depth: 0` on the checkout
|
|
1211
|
-
pull request conductor scans `<base>..HEAD
|
|
1212
|
-
|
|
1213
|
-
|
|
1214
|
-
|
|
1215
|
-
|
|
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.
|
|
1216
1333
|
|
|
1217
1334
|
The `@v4` pins there are readable, not safe: a tag moves, so pinning by one
|
|
1218
1335
|
runs whatever its author pushes to it next. Pin every third-party action by
|
|
@@ -1259,15 +1376,16 @@ jobs:
|
|
|
1259
1376
|
node-version: '22.11.0'
|
|
1260
1377
|
- id: conductor
|
|
1261
1378
|
timeout-minutes: 5
|
|
1262
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1379
|
+
uses: vaultcompasshq/conductor@v0.8.0
|
|
1263
1380
|
with:
|
|
1264
1381
|
pr-comment: true
|
|
1265
1382
|
advisory: true
|
|
1266
1383
|
```
|
|
1267
1384
|
|
|
1268
|
-
`action.yml`
|
|
1269
|
-
|
|
1270
|
-
|
|
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
|
|
1271
1389
|
the three steps above swallows its own exit code: a checkout or setup-node
|
|
1272
1390
|
failure is an infrastructure problem this recipe should still surface, and
|
|
1273
1391
|
the `conductor` step's own advisory behaviour comes from `advisory: true`
|
|
@@ -1357,6 +1475,15 @@ for `advisory` to act on. Leaving the check out of branch protection for
|
|
|
1357
1475
|
that one pull request is what keeps the expected exit 2 from blocking the
|
|
1358
1476
|
merge; the step posts a comment naming the ref and the remedy.
|
|
1359
1477
|
|
|
1478
|
+
The same refusal happens once on every new base branch, not only on the
|
|
1479
|
+
default branch, because rules are read from whatever branch the pull request
|
|
1480
|
+
targets. A release or release-candidate branch cut before the policy existed,
|
|
1481
|
+
or any long-lived branch that has never received `.guardrails.yaml`, refuses
|
|
1482
|
+
its first pull request the same way. There are two remedies. Carry the policy
|
|
1483
|
+
onto the branch before opening a pull request against it; a sync from the
|
|
1484
|
+
default branch does this. Or expect exactly one could-not-run run there, and
|
|
1485
|
+
leave the check out of that branch's protection for that one pull request.
|
|
1486
|
+
|
|
1360
1487
|
**Why "go required" means the job's own context, never the SARIF-upload
|
|
1361
1488
|
row.** The recipes above upload conductor's SARIF log with
|
|
1362
1489
|
`github/codeql-action/upload-sarif`, which can add its own code-scanning
|
|
@@ -1381,9 +1508,11 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1381
1508
|
security-events: write
|
|
1382
1509
|
pull-requests: write
|
|
1383
1510
|
steps:
|
|
1384
|
-
# ... 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. ...
|
|
1385
1514
|
- id: conductor
|
|
1386
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1515
|
+
uses: vaultcompasshq/conductor@v0.8.0
|
|
1387
1516
|
with:
|
|
1388
1517
|
output: conductor.sarif
|
|
1389
1518
|
pr-comment: true
|
|
@@ -1391,13 +1520,21 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1391
1520
|
|
|
1392
1521
|
That posts conductor's own text report, the one the README quotes above
|
|
1393
1522
|
("conductor: clean, nothing blocked. 2 gate(s) ran: ..."), as a comment on
|
|
1394
|
-
the pull request. It is **
|
|
1523
|
+
the pull request. It is **the report of the run that decided the job**: the
|
|
1524
|
+
gates step asks that one run for the SARIF log and the text report together
|
|
1525
|
+
(`--text-report`), and the comment step posts the file it wrote without
|
|
1526
|
+
running the gates again. Before this the comment came from a second run, which
|
|
1527
|
+
could disagree with the first whenever a gate's answer was time or network
|
|
1528
|
+
dependent, and doubled the gate time on every pull request. An installed
|
|
1529
|
+
`conductor-version` too old to have `--text-report` is detected by asking the
|
|
1530
|
+
binary, and gets the second-run behaviour it always had, without a token. It is **sticky**: a hidden marker in the comment body lets
|
|
1395
1531
|
a re-run find and update that same comment, so a push does not pile up a new
|
|
1396
1532
|
comment every time, the way the manual recipe below does. It runs on a
|
|
1397
1533
|
`pull_request` or `pull_request_target` event only, and it runs whether the
|
|
1398
1534
|
gates step passed or failed, since a blocking run is the one an advisory
|
|
1399
1535
|
check most needs a developer to actually see. The first line of every
|
|
1400
|
-
comment carries the version of conductor that produced it,
|
|
1536
|
+
comment carries the version of conductor that produced it, the second line
|
|
1537
|
+
carries the verdict token (see "The verdict token" above), and when the
|
|
1401
1538
|
trust base was refused and no gate ran at all, the comment shrinks to the
|
|
1402
1539
|
version, the verdict, and the refusal reason (with its remedy, when one
|
|
1403
1540
|
applies) rather than the full per-gate report, so an adopter with no policy
|
|
@@ -1416,6 +1553,18 @@ add; nothing here does that for you.
|
|
|
1416
1553
|
|
|
1417
1554
|
Off by default, so an existing consumer of this action is unaffected.
|
|
1418
1555
|
|
|
1556
|
+
**The verdict, whether or not the comment is on.** The gates step reads the
|
|
1557
|
+
token out of the text report its own run wrote and publishes it twice: as a
|
|
1558
|
+
line on the job summary, `conductor verdict: advisory-blocked (1)`, and as the
|
|
1559
|
+
Action's `verdict` output, spelled exactly as the report's second line spells
|
|
1560
|
+
it (`steps.conductor.outputs.verdict`). It is flattened to one line before it
|
|
1561
|
+
goes to either. It is a label for conductor's own exit decision, and the
|
|
1562
|
+
step's exit status is conductor's own in every state. When the gate packages
|
|
1563
|
+
could not be verified and no gate ran, the summary says
|
|
1564
|
+
`conductor verdict: could-not-run (<reason>)` and the output is
|
|
1565
|
+
`could-not-run`. The output is empty when the installed `conductor-version`
|
|
1566
|
+
predates the token.
|
|
1567
|
+
|
|
1419
1568
|
**The sticky match only ever adopts conductor's own comment.** On
|
|
1420
1569
|
`pull_request_target` this step runs with a write token even though the
|
|
1421
1570
|
pull request itself is untrusted, so anyone who can comment on the pull
|
|
@@ -1435,12 +1584,12 @@ per pull request.
|
|
|
1435
1584
|
|
|
1436
1585
|
```yaml
|
|
1437
1586
|
- id: conductor-package-a
|
|
1438
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1587
|
+
uses: vaultcompasshq/conductor@v0.8.0
|
|
1439
1588
|
with:
|
|
1440
1589
|
pr-comment: true
|
|
1441
1590
|
pr-comment-marker: 'package-a'
|
|
1442
1591
|
- id: conductor-package-b
|
|
1443
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1592
|
+
uses: vaultcompasshq/conductor@v0.8.0
|
|
1444
1593
|
with:
|
|
1445
1594
|
pr-comment: true
|
|
1446
1595
|
pr-comment-marker: 'package-b'
|
|
@@ -1471,9 +1620,12 @@ case, `pr-comment: true` is the built-in answer.
|
|
|
1471
1620
|
The SARIF upload produces no alerts on a private repository without GitHub
|
|
1472
1621
|
Code Security, which is why that step carries `continue-on-error`. A comment
|
|
1473
1622
|
is free there. Add `pull-requests: write` to the job's `permissions` and this
|
|
1474
|
-
step after the gates. It **runs the gates a second time**, because
|
|
1475
|
-
|
|
1476
|
-
|
|
1623
|
+
step after the gates. It **runs the gates a second time**, because a run has
|
|
1624
|
+
one format and the recipe below asks for text, so the job costs roughly twice
|
|
1625
|
+
the gate time and the comment can in principle disagree with the first run;
|
|
1626
|
+
the built-in `pr-comment: true` does not, since it posts the file the first
|
|
1627
|
+
run wrote (`--text-report`). `--verbose` because a clean run otherwise
|
|
1628
|
+
collapses to one line.
|
|
1477
1629
|
|
|
1478
1630
|
```yaml
|
|
1479
1631
|
- name: Comment the report on the pull request
|
package/dist/cli.js
CHANGED
|
@@ -7,18 +7,60 @@
|
|
|
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,
|
|
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';
|
|
14
14
|
import { applyInit, planInit, renderInitHuman, renderRevertHuman, revertInit, } from './init.js';
|
|
15
15
|
import { renderSarif } from './output-sarif.js';
|
|
16
|
-
import { jobLogSummary, renderText } from './output-text.js';
|
|
16
|
+
import { jobLogSummary, renderText, verdictToken } from './output-text.js';
|
|
17
17
|
import { GATE_ROLES, GATE_STAGES, POLICY_FILE_NAME, PolicyError, applyCliOverrides, loadPolicy, parsePolicy, } from './policy.js';
|
|
18
18
|
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,9 +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')
|
|
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).')
|
|
438
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')
|
|
439
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.')
|
|
440
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.')
|
|
@@ -444,6 +487,7 @@ export function buildProgram() {
|
|
|
444
487
|
.exitOverride()
|
|
445
488
|
.action((options) => {
|
|
446
489
|
const cwd = process.cwd();
|
|
490
|
+
let textReportPath;
|
|
447
491
|
try {
|
|
448
492
|
// Inside the try, because resolveProjectRoot (like repoRoot before
|
|
449
493
|
// it) reports rather than guesses, and the catch below is what turns
|
|
@@ -459,6 +503,14 @@ export function buildProgram() {
|
|
|
459
503
|
const source = policyForRun(root, options.trustBase, overrides, process.env.GITHUB_BASE_REF);
|
|
460
504
|
const policy = source.kind === 'policy' ? source.policy : source.inventory;
|
|
461
505
|
const format = parseFormat(options.format ?? policy.report.format);
|
|
506
|
+
// BEFORE ANY GATE RUNS. With --format text the text report already is
|
|
507
|
+
// the run's output, so a second copy of it in a file is not something
|
|
508
|
+
// this option can add: refused as a usage error rather than accepted
|
|
509
|
+
// and ignored, which would leave a caller reading a file that was
|
|
510
|
+
// never written, or one that duplicates stdout.
|
|
511
|
+
if (options.textReport !== undefined && format !== 'sarif') {
|
|
512
|
+
throw new PolicyError('--text-report is only meaningful with --format sarif: with --format text the text report is the output already.');
|
|
513
|
+
}
|
|
462
514
|
const result = source.kind === 'refused'
|
|
463
515
|
? refusedTrustBase(source.inventory, source.ref, source.detail, {
|
|
464
516
|
...(stage === undefined ? {} : { stage }),
|
|
@@ -478,14 +530,16 @@ export function buildProgram() {
|
|
|
478
530
|
// there: each finding's `properties.blocking` is the gate's own
|
|
479
531
|
// decision (see output-sarif.ts) and is unaffected by this flag,
|
|
480
532
|
// exactly as the text report's per-finding BLOCKING marker is.
|
|
481
|
-
const
|
|
482
|
-
|
|
483
|
-
:
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
533
|
+
const renderTextReport = () => renderText(result, {
|
|
534
|
+
verbose: Boolean(options.verbose),
|
|
535
|
+
version: pkg.version,
|
|
536
|
+
compact: Boolean(options.compactOnRefusal),
|
|
537
|
+
advisory,
|
|
538
|
+
});
|
|
539
|
+
const rendered = format === 'sarif' ? `${renderSarif(result, pkg.version)}\n` : renderTextReport();
|
|
540
|
+
// The SAME result, rendered a second time, never a second run: the
|
|
541
|
+
// token in this file is for the run that set the exit code below.
|
|
542
|
+
const textReport = options.textReport === undefined ? undefined : renderTextReport();
|
|
489
543
|
if (options.output === undefined) {
|
|
490
544
|
process.stdout.write(rendered);
|
|
491
545
|
}
|
|
@@ -495,7 +549,22 @@ export function buildProgram() {
|
|
|
495
549
|
// own. Reporting exit 0 next to a report nobody can read is the
|
|
496
550
|
// worst of the available answers: the upload step downstream would
|
|
497
551
|
// fail on a missing file with no explanation here.
|
|
498
|
-
|
|
552
|
+
writeReportFile(options.output, 'the report', rendered);
|
|
553
|
+
}
|
|
554
|
+
// WRITTEN LAST, after the SARIF log or stdout, and removed again in
|
|
555
|
+
// the catch below if anything after it throws. A run that exits 2
|
|
556
|
+
// because a write failed must never leave a finished text report on
|
|
557
|
+
// disk: the action would read a clean report and publish a pass, and
|
|
558
|
+
// post it as a comment, beside a red job. A text report that cannot
|
|
559
|
+
// be written takes the could-not-run code, like an unwritable --output.
|
|
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');
|
|
564
|
+
textReportPath = options.textReport;
|
|
565
|
+
writeReportFile(options.textReport, 'the text report', textReport);
|
|
566
|
+
}
|
|
567
|
+
if (options.output !== undefined) {
|
|
499
568
|
// One line, so a CI job whose only product is an uploaded artifact
|
|
500
569
|
// does not read as a job that did nothing. jobLogSummary carries
|
|
501
570
|
// its own "N gate(s), N finding(s)" on an ordinary run, unchanged,
|
|
@@ -504,11 +573,22 @@ export function buildProgram() {
|
|
|
504
573
|
// outcome per enabled gate, so the plain count used to read as
|
|
505
574
|
// "N gate(s), N finding(s)" on a run where nothing ran and nothing
|
|
506
575
|
// was found (issue #46).
|
|
507
|
-
process.stdout.write(`conductor run: ${jobLogSummary(result)}; ${
|
|
576
|
+
process.stdout.write(`conductor run: ${jobLogSummary(result)}; verdict-token ${verdictToken(result, advisory)}; ` +
|
|
577
|
+
`${format} report written to ${options.output}\n`);
|
|
508
578
|
}
|
|
509
579
|
process.exitCode = applyAdvisory(result.exitCode, advisory);
|
|
510
580
|
}
|
|
511
581
|
catch (err) {
|
|
582
|
+
// A text report this run already wrote (or half wrote) is removed:
|
|
583
|
+
// this run exits 2, and no report may say otherwise.
|
|
584
|
+
if (textReportPath !== undefined) {
|
|
585
|
+
try {
|
|
586
|
+
unlinkSync(textReportPath);
|
|
587
|
+
}
|
|
588
|
+
catch {
|
|
589
|
+
// Nothing to remove, or not removable; the exit code stands.
|
|
590
|
+
}
|
|
591
|
+
}
|
|
512
592
|
// One line, never a stack. runGate is total, so nothing from a gate
|
|
513
593
|
// reaches here; anything that does is the umbrella's own problem and
|
|
514
594
|
// still must not put a local filesystem path in front of a user who
|
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) {
|