@vaultcompass/conductor 0.8.0 → 0.9.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.
Files changed (44) hide show
  1. package/README.md +263 -77
  2. package/dist/cli.js +152 -30
  3. package/dist/envelope.d.ts +8 -0
  4. package/dist/exit-codes.d.ts +52 -2
  5. package/dist/exit-codes.js +64 -14
  6. package/dist/external-config.d.ts +2 -1
  7. package/dist/external-config.js +33 -18
  8. package/dist/gate-runner.d.ts +141 -17
  9. package/dist/gate-runner.js +537 -83
  10. package/dist/git.d.ts +95 -0
  11. package/dist/git.js +244 -0
  12. package/dist/init-policy.js +38 -2
  13. package/dist/init.js +40 -3
  14. package/dist/intent-base.d.ts +35 -1
  15. package/dist/intent-base.js +124 -64
  16. package/dist/intent-prepare.d.ts +33 -2
  17. package/dist/intent-prepare.js +443 -34
  18. package/dist/intent-spec.d.ts +28 -0
  19. package/dist/intent-spec.js +22 -5
  20. package/dist/normalize.d.ts +11 -0
  21. package/dist/normalize.js +60 -6
  22. package/dist/osv-baseline.d.ts +84 -0
  23. package/dist/osv-baseline.js +325 -0
  24. package/dist/osv-coverage.d.ts +80 -0
  25. package/dist/osv-coverage.js +223 -0
  26. package/dist/output-sarif.js +55 -15
  27. package/dist/output-text.d.ts +53 -2
  28. package/dist/output-text.js +287 -27
  29. package/dist/policy.d.ts +10 -0
  30. package/dist/policy.js +21 -7
  31. package/dist/products.d.ts +32 -10
  32. package/dist/products.js +73 -9
  33. package/dist/requirements-pin.d.ts +47 -0
  34. package/dist/requirements-pin.js +256 -0
  35. package/dist/resolve.d.ts +1 -0
  36. package/dist/resolve.js +1 -1
  37. package/dist/run.d.ts +21 -0
  38. package/dist/run.js +74 -15
  39. package/dist/trust-base.d.ts +101 -20
  40. package/dist/trust-base.js +219 -73
  41. package/dist/unread-manifests.d.ts +14 -0
  42. package/dist/unread-manifests.js +69 -0
  43. package/package.json +1 -1
  44. package/schema/guardrails.schema.json +4 -0
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.8.0
170
+ conductor 0.9.0
171
171
  verdict-token: blocked (1)
172
172
  conductor run: 2 gate(s), 1 finding(s)
173
173
 
@@ -183,7 +183,7 @@ required.
183
183
 
184
184
  deferred intent intent-guard did not run here; it runs from stage ci onwards
185
185
 
186
- verdict: exit 1, 1 blocking finding(s) across 2 gate(s).
186
+ verdict: exit 1, 1 blocking finding(s) in 1 of 2 enforced gate(s).
187
187
  ```
188
188
 
189
189
  The `mode`, `corpusBuiltAt`, `lockfileFormat` and `online-flag` line under
@@ -243,6 +243,47 @@ decides the run, not even as a preview: step 1's preview gives you the same
243
243
  report without putting a file the pull request controls behind a verdict on
244
244
  the pull request page.
245
245
 
246
+ ## Adoption ramp
247
+
248
+ A repository with history will not start clean, and a gate that is red on its
249
+ first pull request gets switched off. The order that works:
250
+
251
+ 1. **Advisory first.** The first pull request runs with `advisory: true` and
252
+ `pr-comment: true`, as in "Adopting conductor" above. Findings print and
253
+ are commented, and none of them fails the run.
254
+
255
+ 2. **Record what is already there, in each gate's own file.** conductor does
256
+ not write these and does not read them for the gates; each tool does.
257
+ - vault-guard keeps its own baseline of accepted findings. See the
258
+ [vault-guard documentation](https://github.com/vaultcompasshq/vault-guard)
259
+ for the file and how it is produced.
260
+ - osv-scanner reads `osv-scanner.toml` for ignored advisories, each with a
261
+ reason and an optional expiry. See the
262
+ [osv-scanner configuration docs](https://google.github.io/osv-scanner/configuration/).
263
+ - gitleaks reads `.gitleaks.toml` for rule tuning. Generic rules such as
264
+ `generic-api-key` are the usual noise on test fixtures and doc
265
+ placeholders; allowlist those paths there. See the
266
+ [gitleaks documentation](https://github.com/gitleaks/gitleaks).
267
+
268
+ 3. **Accept an old history finding.** A secret that is already in history and
269
+ already rotated stays in every history scan. Put its fingerprint on its own
270
+ line in a `.gitleaksignore` file at the repository root. gitleaks' own
271
+ report carries the fingerprint, in the form `commit:path:rule:line`:
272
+
273
+ ```
274
+ 0a1b2c3d4e5f60718293a4b5c6d7e8f901234567:docs/example.md:generic-api-key:12
275
+ ```
276
+
277
+ conductor reads `.gitleaksignore` from the base branch on a pull request,
278
+ so adding the line takes effect after its own merge, like any other
279
+ control change.
280
+
281
+ 4. **Switch to enforce.** When a few ordinary pull requests report only what
282
+ you expect, remove `advisory: true`, and set `enforce: true` on the gates
283
+ you want to be able to refuse a merge. `conductor init` writes the intent
284
+ gate with `enforce: false` and `require-frozen: false` until a contract is
285
+ frozen, so a repository with no contract is not blocked by that gate.
286
+
246
287
  ## Why
247
288
 
248
289
  Run all three family gates and you have three inits, three config files,
@@ -326,6 +367,7 @@ gates:
326
367
  enabled: true
327
368
  stage: ci
328
369
  enforce: true
370
+ present-on-base: report
329
371
 
330
372
  report:
331
373
  format: text
@@ -361,13 +403,18 @@ blocking findings do not raise it, and its failing to run at all does not
361
403
  make the run exit 2. That is the adoption ramp, so a gate can be switched on
362
404
  and read for a few weeks before it is allowed to refuse anybody's commit.
363
405
  `init` writes it out for every gate. For the intent gate it writes `true`
406
+ (and see `present-on-base` below for the vulnerabilities gate)
364
407
  when a frozen contract already exists at init time
365
408
  (`.intent-guard/intent-contract.yaml`, or the pre-1.3.0
366
409
  `.conductor/intent-contract.yaml`), since the ramp is already climbed by
367
410
  then, and leaving it unenforced would silently let a frozen contract's
368
411
  protected paths produce findings that never fail the check. It writes
369
412
  `false`, with a comment explaining why, when there is no contract yet to
370
- enforce against.
413
+ enforce against, and in that case it also writes `require-frozen: false`
414
+ under `options`, since intent-guard otherwise blocks on a missing contract.
415
+ The `options` comment is written per gate: gitleaks and osv-scanner have no
416
+ severity floor, so their comments point at `.gitleaks.toml` and
417
+ `osv-scanner.toml` rather than at `fail-on`.
371
418
 
372
419
  **`options`** is handed to that gate unchanged. Each key is one of that
373
420
  gate's own long flags with the leading dashes stripped: `fail-on: high`
@@ -383,7 +430,25 @@ gitleaks, and
383
430
  `--format`, `--config` and `--lockfile` to osv-scanner, so those are
384
431
  reserved too. Narrow what either
385
432
  tool reports in its own config file (`.gitleaks.toml`, `osv-scanner.toml`)
386
- instead.
433
+ instead. Two osv-scanner flags are written without being reserved: a run
434
+ that scans a requirements file always gets `--no-resolve`, and a
435
+ `no-resolve` key here is dropped from that run with a note; and a
436
+ pull-request run gets `--no-call-analysis=all` unless this block names
437
+ `call-analysis` or `no-call-analysis`, in which case that value is used.
438
+
439
+ **`present-on-base`** (the `vulnerabilities` gate only, beside `enforce`,
440
+ never under `options`) is `block` or `report`. On a pull-request run whose
441
+ osv-scanner scan blocked, the umbrella also scans the base branch copies of
442
+ the lockfiles that carry findings and labels each finding `introduced` or
443
+ `present-on-base`. `block` blocks on every finding; `report` reports the
444
+ present-on-base ones without blocking and blocks only on what the pull
445
+ request introduced. A policy without the key blocks on every finding, so no
446
+ existing policy is loosened; `init` writes `report` for a new repository.
447
+ On a pull request the key is read from the base branch's policy like every
448
+ other key, so a pull request cannot set it for itself. A run with no base (a
449
+ local run, a push) has no labels, and every finding blocks. The key on any
450
+ other gate is an error, and an older conductor rejects it, so move the
451
+ Action first.
387
452
 
388
453
  **There is no shared severity threshold, on purpose.** One top-level
389
454
  `failOn` would read as one decision and mean five different things, so
@@ -540,17 +605,47 @@ as well as for a leak, so the umbrella hands it `--exit-code 3`: 3 is a leak
540
605
  when git itself fails (a base ref the checkout never fetched), so a clean
541
606
  exit that logged an `ERR` line is could-not-run too, never a pass. A
542
607
  gitleaks exit with no report file behind it is could-not-run. osv-scanner is
543
- handed every tracked lockfile by name (`package-lock.json`,
544
- `npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, at any
545
- depth, never under `node_modules`); when the repository tracks none, it is
546
- not spawned at all and the gate is reported clean with a
547
- `conductor/nothing-to-scan` note, so a docs-only repository is not red on
548
- every pull request. Its 1 is blocked. Its own 128 ("no package sources
549
- found") on lockfiles it WAS handed means they parsed to no packages; that is
550
- clean too, with a distinct `conductor/lockfiles-empty` note naming the
551
- files. Only those npm-family names are handed over today: a repository
552
- whose only lockfile belongs to another ecosystem gets nothing-to-scan from
553
- this gate. Lockfiles inside git submodules are never listed. In a sparse
608
+ handed every tracked lockfile by name, at any depth, never under
609
+ `node_modules`: `package-lock.json`, `npm-shrinkwrap.json`,
610
+ `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, `go.mod`, `poetry.lock`,
611
+ `Pipfile.lock`, `uv.lock`, `pdm.lock`, `Cargo.lock`, `Gemfile.lock`,
612
+ `composer.lock`, `gradle.lockfile`, `packages.lock.json`, `mix.lock`,
613
+ `pubspec.lock`, `Package.resolved`, `conan.lock`, `renv.lock`,
614
+ `packages.config`, `buildscript-gradle.lockfile`, `gems.locked`,
615
+ `pylock.toml`, `cabal.project.freeze`, `stack.yaml.lock` and
616
+ `verification-metadata.xml` inside a `gradle` directory, and pip
617
+ requirements files (`requirements.txt`, `requirements-dev.txt`,
618
+ `requirements_test.txt`, `requirements.prod.txt`, `dev-requirements.txt`)
619
+ whose every requirement, includes followed, is pinned with `==`. `go.sum`
620
+ is never handed over: osv-scanner reads `go.mod` for Go. A requirements
621
+ file with an unpinned line, or an include that is missing, untracked or
622
+ outside the repository, is not scanned and is named in a
623
+ `conductor/requirements-not-scanned` note with the line that stopped it,
624
+ because any version osv-scanner reported for it would be a guess.
625
+ Requirements files are scanned with `--no-resolve`: direct requirements
626
+ only, as written, and the report says so per file. On a pull request a
627
+ requirements file that is pinned on the base stays scanned even when the
628
+ pull request adds an unpinned line to it. When the repository tracks none
629
+ of these, osv-scanner is not spawned at all and the gate is reported clean
630
+ with a `conductor/nothing-to-scan` note, so a docs-only repository is not
631
+ red on every pull request. The note says that nothing was scanned and names
632
+ the tracked manifests that were not handed to osv-scanner (a
633
+ `pyproject.toml`, a `go.sum`, a `Dockerfile`, a workflow, or a requirements
634
+ file the pin check left out), so a green gate is not read as a scan of
635
+ them. A `go.mod` or a pinned requirements file is handed over and so is
636
+ never on that list. It says nothing about what other gates read. When
637
+ other lockfiles WERE handed over, the same list (a `Podfile.lock` beside a
638
+ scanned `mix.lock`, say) is printed as a `conductor/manifests-not-handed`
639
+ note under the gate instead. Its 1 is
640
+ blocked. Its own 128 ("no package sources found") on lockfiles it WAS
641
+ handed means they parsed to no packages; that is clean too, with a distinct
642
+ `conductor/lockfiles-empty` note naming the files. When some handed
643
+ lockfiles had packages and one had none (a lockfile rewritten to `{}` beside
644
+ others), the same note names the empty one and the `lockfiles` line marks it
645
+ `[no packages read]`; the verdict over the other files is unchanged. That
646
+ naming reads osv-scanner's own per-file count, which it prints at its
647
+ default verbosity. Lockfiles inside git
648
+ submodules are never listed. In a sparse
554
649
  checkout a tracked lockfile that is not on disk is still handed over and
555
650
  osv-scanner exits 127 on it, a false could-not-run that fails closed. Any other osv-scanner exit
556
651
  (127 is its error code) is could-not-run. A gitleaks older than 8.19 or an
@@ -571,12 +666,19 @@ It decides nothing and never overrules a gate: it is derived from the exit
571
666
  code and the `enforce` flags the run already had.
572
667
 
573
668
  - `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`.
669
+ could not run. Under `present-on-base: report` a `pass` can carry known
670
+ vulnerabilities already on the base branch, reported and not blocking;
671
+ the report's third line then says `present-on-base: N reported, not
672
+ blocking`, the verdict sentence says the same, and the Action copies that
673
+ line to the job summary under the token.
674
+ - `nothing-checked`: exit 0, but nothing was checked. Either no gate ran at
675
+ all (none is enabled, or every enabled one was deferred to a later stage,
676
+ had nothing to judge, or was skipped), or every gate that ran examined
677
+ nothing: the vulnerabilities gate with no lockfile it reads, or the intent
678
+ gate with no contract to check against. The second case was `pass` in
679
+ 0.8.x. The exit status is unchanged, since nothing failed, but this is not
680
+ a pass: nothing was verified. In the Action the `verdict` output carries
681
+ this token, so a workflow can tell it apart from `pass`.
580
682
  - `advisory-blocked (N)`: the run would have exited 1, and `--advisory` made
581
683
  it exit 0. N is the blocking findings on enforced gates.
582
684
  - `unenforced-findings (N)`: exit 0, but a gate with `enforce: false` had
@@ -587,12 +689,13 @@ code and the `enforce` flags the run already had.
587
689
 
588
690
  When several apply the order is `could-not-run`, then `blocked` or
589
691
  `advisory-blocked`, then `unenforced-findings`, then `nothing-checked` (no gate
590
- ran) or `pass`. A run with
692
+ ran, or none that ran checked anything) or `pass`. A run with
591
693
  `--advisory` whose only blocking findings sit on an unenforced gate is
592
694
  `unenforced-findings`, not `advisory-blocked`, because the flag did nothing
593
695
  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
696
+ off `pass` when another gate ran and checked something; when no gate ran, or
697
+ every gate that ran checked nothing, the token is `nothing-checked` and the
698
+ verdict sentence says "nothing was checked". A
596
699
  gate that exited non-zero with no finding marked blocking counts as one in N,
597
700
  so a state that is not a pass never prints a count of zero. The one-line
598
701
  summary of a clean, non-verbose run has no token line, since it is one line by
@@ -610,7 +713,12 @@ request could point a gate at a script it added in the same commit.
610
713
 
611
714
  **On a pull-request run the rules come from the base branch.** With
612
715
  `--trust-base <ref>` the umbrella reads `.guardrails.yaml` from that ref with
613
- `git show` and judges the head tree against it. A `.guardrails.yaml` in the
716
+ git and judges the head tree against it. A trusted file at the base that git
717
+ cannot read as a regular file (a symlink, a directory, a submodule, or a file
718
+ below a symlinked or submodule directory) is could-not-run, never replaced by
719
+ a default. Clear it by making the file a regular file on the base branch; the
720
+ pull request that does so is judged against that same base, so it has to be
721
+ merged by someone allowed to merge without this check passing. A `.guardrails.yaml` in the
614
722
  pull request never takes effect for that run, `command:` and `args:`
615
723
  included, so **a pull request cannot change the rules it is judged by, and
616
724
  cannot choose the program that judges it, as long as that program is
@@ -823,10 +931,11 @@ choose its own judge on exactly the repositories that have no rules yet. See
823
931
  "Adopting conductor" below for the sequence and for how to see what your
824
932
  policy will do before you merge it.
825
933
 
826
- **Which gates are covered.** All five: dep-guard from **0.6.0**,
827
- intent-guard from **1.4.0**, vault-guard from **1.7.0**, and the two
934
+ **Which gates are covered.** All five: dep-guard from **0.10.1**,
935
+ intent-guard from **1.8.1**, vault-guard from **1.9.1**, and the two
828
936
  external gates at their command-line floors, gitleaks **8.19.0** and
829
- osv-scanner **2.0.0**.
937
+ osv-scanner **2.0.0**. On a pull-request run an older family gate is
938
+ could-not-run rather than run outside pull-request mode.
830
939
 
831
940
  **The external gates get their pull-request mode from the umbrella.**
832
941
  Neither tool has a `--trust-base`, and both auto-load a config from the tree
@@ -884,22 +993,50 @@ in the diff. Only the root `osv-scanner.toml` is read from the base and
884
993
  passed with `--config`, which overrides any nested one for the run; a
885
994
  nested one the pull request adds or edits is reported as a proposal.
886
995
 
887
- The umbrella asks each gate its version and passes the flag only to a build
888
- that understands it, so an older gate is not handed a flag it would reject. A
889
- gate that was not put into pull-request mode read its own rules out of the
890
- tree being judged, which is the thing this exists to prevent, so it is never
891
- silent: it gets a line in the report, a clause on the clean one-line summary,
892
- and a `conductor/trust-base-not-passed` notification in the SARIF log. For a
893
- gate that IS in the table, a version that cannot be read at all is
894
- could-not-run rather than a quiet downgrade: the umbrella cannot establish
895
- that the gate would take its rules from the base ref, and running it anyway
896
- would put it outside the boundary on exactly the runs where something is
897
- already wrong.
996
+ The umbrella asks each gate its version before it runs it. On a run with a
997
+ trust base, a gate older than its pull-request-mode minimum (intent-guard
998
+ 1.8.1, vault-guard 1.9.1, dep-guard 0.10.1) is could-not-run (exit 2),
999
+ never run without the flag: without it the gate would take its rules from
1000
+ the tree being judged. The fix is to install that minimum or newer, or to
1001
+ remove an explicit older version pin. A version that cannot be read at all
1002
+ is could-not-run too: the umbrella cannot establish that the gate would
1003
+ take its rules from the base ref. The one gate that runs without the flag
1004
+ is an intent gate judging a contract imported from the base for the run,
1005
+ whose project is a temporary directory with no repository to resolve a ref
1006
+ in; that is never silent: it gets a line in the report, a clause on the
1007
+ clean one-line summary, and a `conductor/trust-base-not-passed`
1008
+ notification in the SARIF log.
898
1009
 
899
1010
  Outside pull-request mode nothing changes. A pre-commit hook and a direct run
900
1011
  on your own checkout are already inside the trust boundary, and neither passes
901
1012
  the flag.
902
1013
 
1014
+ **In CI, pull-request mode needs a trust base.** A run in GitHub Actions with
1015
+ `GITHUB_BASE_REF` set and no `--trust-base` is could-not-run (exit 2): its
1016
+ rules have to come from the base branch, and no base was named. Pass `--trust-base
1017
+ refs/remotes/origin/<base branch>` with `fetch-depth: 0`, or use the Action,
1018
+ which always passes one. A pre-commit hook run inside a pull-request job hits
1019
+ this too: skip the hook in CI, or pass the trust base to it.
1020
+
1021
+ **On a pull-request run PATH holds only absolute entries, and conductor's own
1022
+ git comes from outside the repository.** Empty and relative entries are
1023
+ removed for conductor and every gate it starts, with one notice naming them,
1024
+ and conductor runs the first git on PATH that lives outside the repository's
1025
+ work tree; with none, the run is could-not-run and says to put git's own
1026
+ directory on PATH. A gate found only through a removed entry is reported
1027
+ missing; put it on an absolute PATH entry or name it with an absolute
1028
+ `command:`. Every gate conductor starts, and everything a gate starts, gets
1029
+ a PATH whose first entry is a private directory outside the repository
1030
+ holding only that same git, so a gate that runs git by name runs it too; on
1031
+ Windows no such directory is made and the gates look git up through the
1032
+ cleaned PATH, and a system temp directory inside the repository is
1033
+ could-not-run until TMPDIR names one outside it.
1034
+
1035
+ **git 2.31 or later** is needed on a pull-request run with the secrets-history
1036
+ gate (gitleaks) enabled, because conductor hands it `git log --diff-merges`,
1037
+ which arrived in git 2.31. Only that gate checks: an older git makes it
1038
+ could-not-run, naming the version, and the other gates run.
1039
+
903
1040
  ## Intent at a pull request
904
1041
 
905
1042
  The intent gate is the only one of the five with any ceremony: its native
@@ -915,7 +1052,9 @@ With no `--base`, `GITHUB_BASE_REF` is used when it is set, spelled in full:
915
1052
  `refs/conductor/trust-base` (the Action's private fetch of the base) if that
916
1053
  exists, else `refs/remotes/origin/<value>`, so a tag of that name cannot
917
1054
  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
1055
+ a tag and a branch is refused as ambiguous. With neither but a `--trust-base`
1056
+ (merge_group, workflow_dispatch, a CLI run), the change set is measured from
1057
+ the trust base. With none of the three, the intent gate runs the way
919
1058
  it does at a commit: against the staged index, or the paths you name.
920
1059
 
921
1060
  **This is why a local preview and a pull-request run can disagree about a
@@ -938,12 +1077,31 @@ fallback to an empty path set, because an empty path set is what a passing
938
1077
  gate looks like. In Actions this is almost always a shallow checkout, so
939
1078
  **`actions/checkout` needs `fetch-depth: 0`** for the merge base to exist.
940
1079
 
1080
+ **On a pull-request run the base decides.** With `--trust-base`, whether a
1081
+ frozen contract governs the pull request is read from the base ref alone. A
1082
+ frozen contract on the base is used, ahead of everything in the list below,
1083
+ `--spec` included (the report says so when `--spec` was given), and the gate
1084
+ judges any edit to it against the base copy. That holds for every
1085
+ intent-guard that can run on a pull-request run, since one older than its
1086
+ pull-request-mode minimum is could-not-run rather than run without the base
1087
+ ref. With no frozen contract on the
1088
+ base, nothing in the pull request becomes the contract: a spec on the base,
1089
+ found by rules 1, 3 and 4 below, is imported from its base copy (so on such a
1090
+ run `--spec` must be a plain path inside the repository that the base
1091
+ carries), and otherwise
1092
+ the gate is skipped with "No contract on the base". A contract or spec the
1093
+ pull request adds is reported as a proposal, so adopting the intent gate
1094
+ merges, and the next pull request is judged against it. Retiring or replacing
1095
+ a frozen contract through a judged pull request is refused by the intent gate
1096
+ itself and needs an administrator to merge it.
1097
+
941
1098
  **Where the contract comes from**, in order:
942
1099
 
943
1100
  1. `--spec <path>` on the umbrella's own command line. Typed just now, so it
944
- outranks everything, and a path here that is not on disk is reported
945
- rather than replaced: running a different contract than the one somebody
946
- named is the wrong kindness.
1101
+ outranks everything else in this list, and a path here that is not on
1102
+ disk is reported rather than replaced: running a different contract than
1103
+ the one somebody named is the wrong kindness. On a pull-request run it is
1104
+ read from the base, and a frozen contract on the base takes precedence.
947
1105
  2. `<repo>/.intent-guard/intent-contract.yaml`, when it is **frozen**, and
948
1106
  `<repo>/.conductor/intent-contract.yaml` after it. The native flow wins
949
1107
  wherever a team has done it. Frozen is the test rather than present: an
@@ -1107,7 +1265,8 @@ provenance even though all four packages publish it.
1107
1265
  > sigstore outage has the same effect. The audit is retried once after a short
1108
1266
  > pause before the step fails, to absorb a one-off registry hiccup. It fails
1109
1267
  > 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.
1268
+ > `45d2ecc2213244408495c22d0b8da1dc0f1ed288` (v0.4.0), which does not verify,
1269
+ > if it blocks you.
1111
1270
 
1112
1271
  `--base` is passed only when the `base-ref` input names one; left empty, the
1113
1272
  umbrella reads `GITHUB_BASE_REF` itself and treats an empty value as "not a
@@ -1140,14 +1299,15 @@ event the workflow file itself runs from the pull request's own ref, so an
1140
1299
  opt-out here would be settable by the very pull request the mode exists to
1141
1300
  judge: the knob and the thing it protects against would be the same file.
1142
1301
 
1143
- **The normal way to use this is by tag, not by path.** `uses: ./` reads
1302
+ **Pin the action by full commit SHA, with the version in a trailing comment, not by tag and not by path.** `uses: ./` reads
1144
1303
  `action.yml` out of whichever tree the workflow runs against, which is
1145
1304
  correct only for this repository's own workflows testing themselves; on a
1146
1305
  pull request from anywhere else it would read `action.yml` out of the pull
1147
1306
  request being judged, and the version-pin protection described above
1148
1307
  "protects nothing" against a tree that controls its own judge (the
1149
- validate step's own comment in `action.yml` says so in those words). Name
1150
- this action by owner and tag instead:
1308
+ validate step's own comment in `action.yml` says so in those words). A tag
1309
+ moves when someone pushes it. Name this action by owner and the full commit
1310
+ SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.9.0.
1151
1311
 
1152
1312
  ```yaml
1153
1313
  name: guardrails
@@ -1162,12 +1322,14 @@ jobs:
1162
1322
  steps:
1163
1323
  - uses: actions/checkout@v7
1164
1324
  with:
1325
+ # From 0.8.0 a shallow checkout on a pull-request run is
1326
+ # could-not-run for the history gate.
1165
1327
  fetch-depth: 0
1166
1328
  - uses: actions/setup-node@v7
1167
1329
  with:
1168
1330
  node-version: '22.11.0'
1169
1331
  - id: conductor
1170
- uses: vaultcompasshq/conductor@v0.8.0
1332
+ uses: vaultcompasshq/conductor@v0.9.0
1171
1333
  with:
1172
1334
  output: conductor.sarif
1173
1335
  - uses: github/codeql-action/upload-sarif@v3
@@ -1177,6 +1339,10 @@ jobs:
1177
1339
  sarif_file: ${{ steps.conductor.outputs.sarif }}
1178
1340
  ```
1179
1341
 
1342
+ The job has `permissions: contents: read`. Add `pull-requests: write` only
1343
+ where the recipe posts a comment. `security-events: write` is there because
1344
+ the upload step publishes the SARIF log.
1345
+
1180
1346
  The examples leave the trigger unnarrowed on purpose, so the job runs for a
1181
1347
  pull request into any branch. If you narrow it with a `branches:` filter,
1182
1348
  include every branch whose merges reach users, release branches and the
@@ -1185,11 +1351,20 @@ production]`. The pull request that promotes a release is where a bad
1185
1351
  dependency or a leaked secret actually ships, and a job that is not triggered
1186
1352
  leaves no red check and no report to notice.
1187
1353
 
1188
- No version inputs there at all: left out, the four gates run at the versions
1189
- this tag ships, which is the intended default. The fully spelled-out example
1190
- below adds explicit version pins and comments explaining each one, for a
1191
- workflow that wants that transparency; the four lines can still be left out
1192
- entirely to take the tag's own versions, exactly as the form above does.
1354
+ A job marked `continue-on-error` always concludes green, so a crash of the
1355
+ action is invisible unless someone opens the log. A workflow triggered only
1356
+ on pull requests to main never runs on a stacked pull request whose base is
1357
+ another branch, and no comment on such a pull request does not mean clean.
1358
+
1359
+ Omit `conductor-version`. Left unset, the action installs the default in the
1360
+ pinned `action.yml`, which is the version that commit ships, so the installed
1361
+ umbrella follows the pin and a Dependabot bump is the one `uses` line. If the
1362
+ input is set and is older than the constants in that pinned action.yml, a
1363
+ pull request run is refused and the validate step says to remove the input. A
1364
+ newer value is accepted and is what gets installed. The three gate version
1365
+ inputs can be left out too: each one then takes the default in the pinned
1366
+ action.yml. The spelled-out example below names them when a workflow wants
1367
+ that transparency.
1193
1368
 
1194
1369
  ```yaml
1195
1370
  name: guardrails
@@ -1204,11 +1379,13 @@ jobs:
1204
1379
  steps:
1205
1380
  - uses: actions/checkout@v7
1206
1381
  with:
1207
- # Required, for two reasons now. Without it there is no merge base
1208
- # to diff against, and the intent gate fails closed rather than
1209
- # checking an empty set. And the base ref itself has to be in the
1210
- # clone, because on a pull request the rules are read from it: a
1211
- # base ref that will not resolve is exit 2 for every enabled gate.
1382
+ # Required. From 0.8.0 a shallow checkout on a pull-request run is
1383
+ # could-not-run for the history gate. Without a full history there
1384
+ # is no merge base to diff against, and the intent gate fails closed
1385
+ # rather than checking an empty set. And the base ref itself has to
1386
+ # be in the clone, because on a pull request the rules are read from
1387
+ # it: a base ref that will not resolve is exit 2 for every enabled
1388
+ # gate.
1212
1389
  fetch-depth: 0
1213
1390
  - uses: actions/setup-node@v7
1214
1391
  with:
@@ -1224,23 +1401,23 @@ jobs:
1224
1401
  # policy is read from, before the gates ever start. Your own
1225
1402
  # dependencies, build and tests belong in a separate job (see below).
1226
1403
  # The gates are not among the things that job has to install: the action
1227
- # installs those itself, globally, at the versions pinned below.
1404
+ # installs those itself, globally. Leave conductor-version unset so the
1405
+ # umbrella is the default in the pinned action.yml.
1228
1406
  - id: conductor
1229
- uses: vaultcompasshq/conductor@v0.8.0
1407
+ uses: vaultcompasshq/conductor@v0.9.0
1230
1408
  with:
1231
1409
  output: conductor.sarif
1232
- # Exact versions, never a range and never "latest". These four
1233
- # lines decide which programs judge a pull request, so a pull
1410
+ # Exact versions, never a range and never "latest". These three
1411
+ # lines decide which gate programs judge a pull request, so a pull
1234
1412
  # request's own lockfile no longer does. They are only as protected
1235
1413
  # as this file is: require review on .github/workflows in your
1236
1414
  # branch protection. Bump them like any other pin, in a pull
1237
- # request of their own. Forward only on a pull request: the action
1238
- # refuses a pin below what its tag ships, and the four lines can be
1239
- # left out entirely to take that tag's own versions.
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
1415
+ # request of their own. On a pull request the action refuses a pin
1416
+ # below what the pinned action.yml ships, and the three lines can
1417
+ # be left out entirely to take that action's own versions.
1418
+ dep-guard-version: 0.11.1
1419
+ vault-guard-version: 1.10.0
1420
+ intent-guard-version: 1.8.1
1244
1421
  - uses: github/codeql-action/upload-sarif@v3
1245
1422
  # Always: the log is most worth having on the run that failed.
1246
1423
  if: always()
@@ -1290,12 +1467,12 @@ because the pull request supplies them, not the workflow file. Branch
1290
1467
  protection on the workflow directory does not stop them, so the gates must
1291
1468
  not share a job with head code that runs first.
1292
1469
 
1293
- **With gitleaks enabled the checkout must be `fetch-depth: 0`.** At the default
1470
+ **With gitleaks enabled the checkout must be `fetch-depth: 0`.** From 0.8.0 a
1471
+ shallow checkout on a pull-request run is could-not-run for the history gate,
1472
+ naming `fetch-depth: 0` (exit 2, whatever `enforce` says). At the default
1294
1473
  depth of 1 the checkout is shallow, the range from the base to HEAD holds one
1295
1474
  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.
1475
+ would never be seen. conductor does not deepen the checkout for you.
1299
1476
 
1300
1477
  **The two external gates are installed by your workflow, not by the
1301
1478
  Action.** The Action still installs exactly its four npm packages and has no
@@ -1370,13 +1547,15 @@ jobs:
1370
1547
  steps:
1371
1548
  - uses: actions/checkout@v7
1372
1549
  with:
1550
+ # From 0.8.0 a shallow checkout on a pull-request run is
1551
+ # could-not-run for the history gate.
1373
1552
  fetch-depth: 0
1374
1553
  - uses: actions/setup-node@v7
1375
1554
  with:
1376
1555
  node-version: '22.11.0'
1377
1556
  - id: conductor
1378
1557
  timeout-minutes: 5
1379
- uses: vaultcompasshq/conductor@v0.8.0
1558
+ uses: vaultcompasshq/conductor@v0.9.0
1380
1559
  with:
1381
1560
  pr-comment: true
1382
1561
  advisory: true
@@ -1512,7 +1691,7 @@ step and add `pull-requests: write` to the job's `permissions`:
1512
1691
  # the pull request runs before the action in this job: no install, build
1513
1692
  # or test step here; those belong in a separate job. ...
1514
1693
  - id: conductor
1515
- uses: vaultcompasshq/conductor@v0.8.0
1694
+ uses: vaultcompasshq/conductor@v0.9.0
1516
1695
  with:
1517
1696
  output: conductor.sarif
1518
1697
  pr-comment: true
@@ -1574,6 +1753,13 @@ the comment was authored by the GitHub Actions bot; a marker in anyone
1574
1753
  else's comment is never adopted, and conductor creates its own comment
1575
1754
  instead, exactly as if no marked comment existed.
1576
1755
 
1756
+ **The poster runs the `node` and `gh` that were on `PATH` when the Action
1757
+ started**, resolved by the Action's first step before any gate package is
1758
+ installed, and never a binary from the gate install directory. The gate
1759
+ install goes on `PATH` only after its signature audit passes. GitHub-hosted
1760
+ runners carry both; on a runner that has neither on `PATH` at that point the
1761
+ comment is skipped with a warning and the verdict is unaffected.
1762
+
1577
1763
  **Running this Action more than once against the same pull request** (for
1578
1764
  example, once per package in a monorepo) needs its own marker per run, or
1579
1765
  those runs fight over one shared comment. Set `pr-comment-marker` to a
@@ -1584,12 +1770,12 @@ per pull request.
1584
1770
 
1585
1771
  ```yaml
1586
1772
  - id: conductor-package-a
1587
- uses: vaultcompasshq/conductor@v0.8.0
1773
+ uses: vaultcompasshq/conductor@v0.9.0
1588
1774
  with:
1589
1775
  pr-comment: true
1590
1776
  pr-comment-marker: 'package-a'
1591
1777
  - id: conductor-package-b
1592
- uses: vaultcompasshq/conductor@v0.8.0
1778
+ uses: vaultcompasshq/conductor@v0.9.0
1593
1779
  with:
1594
1780
  pr-comment: true
1595
1781
  pr-comment-marker: 'package-b'