@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 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.6.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` (issue #58); anyone invoking the
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
- resolves to the same commit as `origin/$GITHUB_BASE_REF`, which is exactly
699
- what the Action itself always passes, so an ordinary pull-request run is
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. When `origin/$GITHUB_BASE_REF`
704
- itself does not resolve, this fails closed too, naming it, for the same
705
- reason the fetch-depth remedy below exists.
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 as `origin/<value>` when it is
860
- set, and the text report says so. With neither, the intent gate runs the way
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. It fails closed on purpose, so that is a
1050
- > red gate rather than a skipped check; pin to `@v0.4.0`, which does not
1051
- > verify, if it blocks you.
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 action passes
1058
- **`--trust-base origin/$GITHUB_BASE_REF`** of its own accord, so the run takes
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 `origin/$GITHUB_BASE_REF` itself on that event.
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.6.0
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
- cache: pnpm
1151
- # Your own dependencies. The gates are NOT among the things this has to
1152
- # install: the action installs those itself, globally, at the versions
1153
- # pinned below.
1154
- - run: pnpm install --frozen-lockfile
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.6.0
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.6.0
1168
- dep-guard-version: 0.9.0
1169
- vault-guard-version: 1.8.0
1170
- intent-guard-version: 1.7.0
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 matters more with gitleaks enabled: on a
1211
- pull request conductor scans `<base>..HEAD`, and a base that was never
1212
- fetched is a git error gitleaks itself would report as a clean scan of
1213
- nothing. conductor reads that error off gitleaks' log and reports the gate
1214
- as could-not-run instead. A missing tool is could-not-run as well, with the
1215
- install step named in the report.
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.6.0
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` already shallow-fetches the trust base itself as of 0.4.5 when
1269
- the checkout does not already carry it (see the changelog entry for that
1270
- version), so this recipe needs no separate "fetch the base ref" step. None of
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, pnpm, setup-node, install, as in the example above ...
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.6.0
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 **sticky**: a hidden marker in the comment body lets
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, and when the
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.6.0
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.6.0
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 the Action
1475
- writes SARIF and nothing else, so the job costs roughly twice the gate time;
1476
- `--verbose` because a clean run otherwise collapses to one line.
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, writeFileSync } from 'node:fs';
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 origin/<GITHUB_BASE_REF>, which is
216
- // exactly what the composite action itself always passes. So on an
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> when it is set.')
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 origin/<GITHUB_BASE_REF> on a pull_request event.')
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 rendered = format === 'sarif'
482
- ? `${renderSarif(result, pkg.version)}\n`
483
- : renderText(result, {
484
- verbose: Boolean(options.verbose),
485
- version: pkg.version,
486
- compact: Boolean(options.compactOnRefusal),
487
- advisory,
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
- writeFileSync(options.output, rendered);
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)}; ${format} report written to ${options.output}\n`);
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
@@ -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
- const child = spawnSync('git', ['show', `${ref}:${file}`], { cwd: repoRoot, encoding: 'utf8' });
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) {