@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.
- package/README.md +263 -77
- package/dist/cli.js +152 -30
- package/dist/envelope.d.ts +8 -0
- package/dist/exit-codes.d.ts +52 -2
- package/dist/exit-codes.js +64 -14
- package/dist/external-config.d.ts +2 -1
- package/dist/external-config.js +33 -18
- package/dist/gate-runner.d.ts +141 -17
- package/dist/gate-runner.js +537 -83
- package/dist/git.d.ts +95 -0
- package/dist/git.js +244 -0
- package/dist/init-policy.js +38 -2
- package/dist/init.js +40 -3
- package/dist/intent-base.d.ts +35 -1
- package/dist/intent-base.js +124 -64
- package/dist/intent-prepare.d.ts +33 -2
- package/dist/intent-prepare.js +443 -34
- package/dist/intent-spec.d.ts +28 -0
- package/dist/intent-spec.js +22 -5
- package/dist/normalize.d.ts +11 -0
- package/dist/normalize.js +60 -6
- package/dist/osv-baseline.d.ts +84 -0
- package/dist/osv-baseline.js +325 -0
- package/dist/osv-coverage.d.ts +80 -0
- package/dist/osv-coverage.js +223 -0
- package/dist/output-sarif.js +55 -15
- package/dist/output-text.d.ts +53 -2
- package/dist/output-text.js +287 -27
- package/dist/policy.d.ts +10 -0
- package/dist/policy.js +21 -7
- package/dist/products.d.ts +32 -10
- package/dist/products.js +73 -9
- package/dist/requirements-pin.d.ts +47 -0
- package/dist/requirements-pin.js +256 -0
- package/dist/resolve.d.ts +1 -0
- package/dist/resolve.js +1 -1
- package/dist/run.d.ts +21 -0
- package/dist/run.js +74 -15
- package/dist/trust-base.d.ts +101 -20
- package/dist/trust-base.js +219 -73
- package/dist/unread-manifests.d.ts +14 -0
- package/dist/unread-manifests.js +69 -0
- package/package.json +1 -1
- 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.
|
|
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)
|
|
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
|
|
544
|
-
`
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
`
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
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
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
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,
|
|
595
|
-
|
|
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
|
-
|
|
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.
|
|
827
|
-
intent-guard from **1.
|
|
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
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
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
|
|
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
|
|
945
|
-
rather than replaced: running a different contract than
|
|
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
|
-
>
|
|
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
|
-
**
|
|
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).
|
|
1150
|
-
this action by owner and
|
|
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.
|
|
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
|
-
|
|
1189
|
-
|
|
1190
|
-
|
|
1191
|
-
|
|
1192
|
-
|
|
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
|
|
1208
|
-
#
|
|
1209
|
-
#
|
|
1210
|
-
#
|
|
1211
|
-
#
|
|
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
|
|
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.
|
|
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
|
|
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.
|
|
1238
|
-
#
|
|
1239
|
-
# left out entirely to take that
|
|
1240
|
-
|
|
1241
|
-
|
|
1242
|
-
|
|
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`.**
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
1778
|
+
uses: vaultcompasshq/conductor@v0.9.0
|
|
1593
1779
|
with:
|
|
1594
1780
|
pr-comment: true
|
|
1595
1781
|
pr-comment-marker: 'package-b'
|