@vaultcompass/conductor 0.5.0 → 0.7.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 +305 -32
- package/dist/cli.js +214 -50
- package/dist/gate-runner.js +12 -2
- package/dist/normalize.d.ts +13 -2
- package/dist/normalize.js +137 -8
- package/dist/output-sarif.js +58 -0
- package/dist/output-text.d.ts +33 -0
- package/dist/output-text.js +139 -22
- package/dist/products.d.ts +16 -0
- package/dist/products.js +9 -0
- package/dist/run.d.ts +40 -0
- package/dist/run.js +39 -1
- package/dist/trust-base.d.ts +68 -0
- package/dist/trust-base.js +152 -0
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -16,7 +16,7 @@ runs, with exactly the configuration it had.
|
|
|
16
16
|
The claim is checked in public. The
|
|
17
17
|
[conductor-proof](https://github.com/vaultcompasshq/conductor-proof)
|
|
18
18
|
repository runs an ordinary gitleaks and osv-scanner job beside conductor,
|
|
19
|
-
with
|
|
19
|
+
with six pull requests left open on purpose, one planted problem each.
|
|
20
20
|
Read the checks on each pull request rather than this table.
|
|
21
21
|
|
|
22
22
|
| Planted problem | Ordinary job | conductor |
|
|
@@ -25,10 +25,13 @@ Read the checks on each pull request rather than this table.
|
|
|
25
25
|
| [A pull request that turns off its own checks, then adds that dependency](https://github.com/vaultcompasshq/conductor-proof/pull/7) | skipped | fail |
|
|
26
26
|
| [A credential-shaped string in a test fixture](https://github.com/vaultcompasshq/conductor-proof/pull/8) | fail | fail |
|
|
27
27
|
| [An edit to a path the intent contract protects](https://github.com/vaultcompasshq/conductor-proof/pull/11) | pass | fail |
|
|
28
|
+
| [A credential-shaped string committed, then replaced, so only history carries it](https://github.com/vaultcompasshq/conductor-proof/pull/15) | fail | fail |
|
|
29
|
+
| [A dependency at a version with a known advisory](https://github.com/vaultcompasshq/conductor-proof/pull/16) | fail | fail |
|
|
28
30
|
|
|
29
|
-
The
|
|
30
|
-
|
|
31
|
-
and
|
|
31
|
+
The rows where both fail are parity, not a catch: both jobs run gitleaks
|
|
32
|
+
and osv-scanner, so both see a credential shape, a credential in history,
|
|
33
|
+
and a known advisory. The other three are what a scanner that only knows
|
|
34
|
+
about vulnerabilities and secrets has no way to know.
|
|
32
35
|
|
|
33
36
|
<!-- guardrails-family: shared block, keep it identical in dep-guard, vault-guard, intent-guard and conductor -->
|
|
34
37
|
The Vault & Compass guardrails are three gates over an AI-assisted coding
|
|
@@ -43,7 +46,11 @@ contract, and change budgets). Each one installs, configures and runs on its
|
|
|
43
46
|
own;
|
|
44
47
|
[conductor](https://www.npmjs.com/package/@vaultcompass/conductor) is the
|
|
45
48
|
optional umbrella that runs them from one policy file, one hook and one
|
|
46
|
-
report
|
|
49
|
+
report, beside two scanners you install yourself:
|
|
50
|
+
[gitleaks](https://github.com/gitleaks/gitleaks) for secrets anywhere in git
|
|
51
|
+
history and [osv-scanner](https://github.com/google/osv-scanner) for known
|
|
52
|
+
vulnerabilities. conductor scans nothing itself and installs nothing that
|
|
53
|
+
is not its own.
|
|
47
54
|
<!-- /guardrails-family -->
|
|
48
55
|
|
|
49
56
|
## Adopting conductor
|
|
@@ -149,28 +156,42 @@ required.
|
|
|
149
156
|
commit at all). A clean commit prints one line:
|
|
150
157
|
|
|
151
158
|
```
|
|
152
|
-
conductor: clean, nothing blocked. 2 gate(s) ran: dependencies (dep-guard), secrets (vault-guard). Deferred to a later stage: intent (intent-guard) from stage ci. 1 note(s). Re-run with --verbose for the full report.
|
|
159
|
+
conductor: clean, nothing blocked. 2 gate(s) ran: dependencies (dep-guard), secrets (vault-guard). Deferred to a later stage: intent (intent-guard) from stage ci. 0 gate(s) left out by --gate. 0 gate(s) not enforced. 1 note(s). 0 suppressed across all gates. Re-run with --verbose for the full report.
|
|
153
160
|
```
|
|
154
161
|
|
|
162
|
+
The line names every disposition a gate can have on that run, with its
|
|
163
|
+
count, even when the count is zero: ran, deferred to a later stage, left
|
|
164
|
+
out by `--gate`, not enforced, and suppressed findings. Which gates appear
|
|
165
|
+
in each depends on your policy file.
|
|
166
|
+
|
|
155
167
|
A commit with a staged credential in it prints the full report and exits 1:
|
|
156
168
|
|
|
157
169
|
```
|
|
158
|
-
conductor 0.
|
|
170
|
+
conductor 0.7.0
|
|
171
|
+
verdict-token: blocked (1)
|
|
159
172
|
conductor run: 2 gate(s), 1 finding(s)
|
|
160
173
|
|
|
161
|
-
dependencies dep-guard 0.
|
|
174
|
+
dependencies dep-guard 0.7.0 exit 0 153ms via dep-guard on path
|
|
162
175
|
threshold medium suppressed 0 ignored 0
|
|
176
|
+
mode staged corpusBuiltAt 2026-09-20T06:16:40.340Z lockfileFormat npm online-flag not passed
|
|
163
177
|
|
|
164
|
-
secrets vault-guard 1.
|
|
165
|
-
BLOCKING critical vault-guard/anthropic jest.config.mjs:
|
|
178
|
+
secrets vault-guard 1.8.0 exit 1 105ms via vault-guard on path
|
|
179
|
+
BLOCKING critical vault-guard/anthropic jest.config.mjs:14:12
|
|
166
180
|
Possible secret of type 'anthropic'
|
|
167
181
|
threshold medium suppressed 0 ignored not reported
|
|
182
|
+
filesScanned 1 patternsActive 59
|
|
168
183
|
|
|
169
184
|
deferred intent intent-guard did not run here; it runs from stage ci onwards
|
|
170
185
|
|
|
171
186
|
verdict: exit 1, 1 blocking finding(s) across 2 gate(s).
|
|
172
187
|
```
|
|
173
188
|
|
|
189
|
+
The `mode`, `corpusBuiltAt`, `lockfileFormat` and `online-flag` line under
|
|
190
|
+
`dependencies`, and the `filesScanned`/`patternsActive` line under
|
|
191
|
+
`secrets`, are each gate's own run facts, one line per gate, added to the
|
|
192
|
+
full report so a reader can see what a gate actually scanned and with
|
|
193
|
+
what, not only its verdict.
|
|
194
|
+
|
|
174
195
|
Both gates there are the ones you installed a moment ago, running with
|
|
175
196
|
their own thresholds and their own baselines. The umbrella found nothing
|
|
176
197
|
of its own, because it looks for nothing of its own.
|
|
@@ -202,7 +223,9 @@ required.
|
|
|
202
223
|
exit code, only a blocking finding's. Leaving the check out of branch
|
|
203
224
|
protection is what keeps that expected exit 2 from blocking the merge;
|
|
204
225
|
the step posts a comment saying so with the remedy on it, which is the
|
|
205
|
-
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.
|
|
206
229
|
|
|
207
230
|
3. **Merge.** Every pull request after that is judged by the policy on the
|
|
208
231
|
base branch, and a change to that policy shows up as a proposal line and
|
|
@@ -405,6 +428,10 @@ above); do not commit it.
|
|
|
405
428
|
somebody else's file into one this tool may overwrite. Like `--adopt`,
|
|
406
429
|
only meaningful together with `--hook` on an init (not on a `--revert`);
|
|
407
430
|
without it, init errors.
|
|
431
|
+
- `--project <dir>` writes into that repository instead of the current
|
|
432
|
+
directory, resolved to its git top level the same way the current
|
|
433
|
+
directory already is, so a script can point init at a repository without a
|
|
434
|
+
`cd` compound.
|
|
408
435
|
|
|
409
436
|
The rest of this section, on hook managers already wired into the
|
|
410
437
|
repository, applies only when `--hook` is given: none of it is consulted,
|
|
@@ -444,13 +471,30 @@ proceeds normally without mentioning them.
|
|
|
444
471
|
control input of the gates that support it. See "The pull-request trust
|
|
445
472
|
boundary" below. `--base` and `--trust-base` are independent and a
|
|
446
473
|
pull-request run passes both: `--base` decides which paths are judged,
|
|
447
|
-
`--trust-base` decides what they are judged by.
|
|
474
|
+
`--trust-base` decides what they are judged by. When `GITHUB_BASE_REF` is
|
|
475
|
+
set, an explicit `--trust-base` is accepted only when it resolves to the
|
|
476
|
+
same commit as `origin/$GITHUB_BASE_REF` (issue #58); anyone invoking the
|
|
477
|
+
CLI directly on a pull request, rather than through the Action, gets this
|
|
478
|
+
as its own refusal, named below.
|
|
448
479
|
- `--spec <path>` names the spec the intent gate imports its contract from.
|
|
449
480
|
- `--output <path>` writes the report to a file instead of to stdout, for a
|
|
450
481
|
CI step that uploads it. One line still goes to stdout, because a job whose
|
|
451
482
|
only product is an uploaded artifact otherwise reads as a job that did
|
|
452
483
|
nothing. A path that cannot be written is exit 2, not a green run beside a
|
|
453
|
-
report nobody can read.
|
|
484
|
+
report nobody can read. A relative value resolves against the current
|
|
485
|
+
directory the command was invoked from, not against `--project` or the
|
|
486
|
+
repository root: with `--project` pointing elsewhere, a relative
|
|
487
|
+
`--output` still lands next to where you are, not next to the repository
|
|
488
|
+
being judged.
|
|
489
|
+
- `--text-report <path>`, with `--format sarif`, also writes the text report
|
|
490
|
+
to that file **from the same run**: exactly what `--format text` would have
|
|
491
|
+
rendered for this result (`--verbose`, `--compact-on-refusal` and
|
|
492
|
+
`--advisory` respected), and no gate is run a second time. This is how the
|
|
493
|
+
Action gets a SARIF log, a comment body and a verdict token that are one
|
|
494
|
+
run's answer. With `--format text` it is refused as a usage error (exit 2),
|
|
495
|
+
before any gate runs: the text report is the output already, so a second
|
|
496
|
+
copy in a file would only duplicate it. A path that cannot be written is
|
|
497
|
+
exit 2, like `--output`. See "The verdict token" below.
|
|
454
498
|
- `--verbose` prints the full per-gate report even when the run is clean.
|
|
455
499
|
Text output only; the SARIF log never changes shape with it.
|
|
456
500
|
- `--compact-on-refusal` shrinks the report to the version, the verdict and
|
|
@@ -472,6 +516,13 @@ proceeds normally without mentioning them.
|
|
|
472
516
|
verdict line's own wording (it says findings were advisory and did not
|
|
473
517
|
block) change. Text output only; the SARIF log has no verdict line to
|
|
474
518
|
change and its `properties.blocking` on each result is unaffected.
|
|
519
|
+
- `--project <dir>` runs against that repository instead of the current
|
|
520
|
+
directory, resolved to its git top level the same way the current
|
|
521
|
+
directory already is, so a subdirectory resolves to that repository's top
|
|
522
|
+
level. A relative value resolves against the current directory. A path
|
|
523
|
+
that does not exist, is not a directory, or is not inside a git repository
|
|
524
|
+
is a usage error naming the path and exits 2 rather than falling back to
|
|
525
|
+
the current directory.
|
|
475
526
|
|
|
476
527
|
### Exit codes
|
|
477
528
|
|
|
@@ -509,6 +560,37 @@ could not run is a different failure from a blocking finding, and advisory
|
|
|
509
560
|
mode exists to leave that one alone. See "Running the gates as an advisory
|
|
510
561
|
check" below.
|
|
511
562
|
|
|
563
|
+
### The verdict token
|
|
564
|
+
|
|
565
|
+
The text report carries one more line: `verdict-token: <token>`, the **second
|
|
566
|
+
line**, directly under the version line (the closing `verdict:` sentence is
|
|
567
|
+
unchanged). It is a label for the umbrella's own exit decision, in a closed
|
|
568
|
+
set, so a person or a script can read the state without parsing a sentence.
|
|
569
|
+
It decides nothing and never overrules a gate: it is derived from the exit
|
|
570
|
+
code and the `enforce` flags the run already had.
|
|
571
|
+
|
|
572
|
+
- `pass`: exit 0, and no gate, enforced or not, has a blocking finding or
|
|
573
|
+
could not run.
|
|
574
|
+
- `advisory-blocked (N)`: the run would have exited 1, and `--advisory` made
|
|
575
|
+
it exit 0. N is the blocking findings on enforced gates.
|
|
576
|
+
- `unenforced-findings (N)`: exit 0, but a gate with `enforce: false` had
|
|
577
|
+
blocking findings or could not run. N counts those findings plus those
|
|
578
|
+
gates. Exit 0 here is not a pass, and the token says so.
|
|
579
|
+
- `blocked (N)`: exit 1. N as for `advisory-blocked`.
|
|
580
|
+
- `could-not-run`: exit 2, a refused trust base included.
|
|
581
|
+
|
|
582
|
+
When several apply the order is `could-not-run`, then `blocked` or
|
|
583
|
+
`advisory-blocked`, then `unenforced-findings`, then `pass`. A run with
|
|
584
|
+
`--advisory` whose only blocking findings sit on an unenforced gate is
|
|
585
|
+
`unenforced-findings`, not `advisory-blocked`, because the flag did nothing
|
|
586
|
+
there. A gate skipped for want of a contract does not by itself move the token
|
|
587
|
+
off `pass`; the verdict sentence is where "nothing was checked" is said. A
|
|
588
|
+
gate that exited non-zero with no finding marked blocking counts as one in N,
|
|
589
|
+
so a state that is not a pass never prints a count of zero. The one-line
|
|
590
|
+
summary of a clean, non-verbose run has no token line, since it is one line by
|
|
591
|
+
design. `conductor run` also prints the token on its job-log line,
|
|
592
|
+
`conductor run: 4 gate(s), 1 finding(s); verdict-token advisory-blocked (1); sarif report written to conductor.sarif`.
|
|
593
|
+
|
|
512
594
|
## The pull-request trust boundary
|
|
513
595
|
|
|
514
596
|
Every gate reads its own rules out of the repository it is judging. On a pull
|
|
@@ -636,6 +718,46 @@ one-line summary and on the verdict, with a line each under `--verbose` and a
|
|
|
636
718
|
reflow, a re-quote or an edited comment is not a proposal: the two files are
|
|
637
719
|
compared as parsed documents.
|
|
638
720
|
|
|
721
|
+
**An explicit `--trust-base` redirect gets a refusal on a pull request, at two
|
|
722
|
+
places (issue #58), and neither closes the whole hole by itself.**
|
|
723
|
+
`refuseTrustBaseRef` above only refuses a ref that resolves to HEAD's own
|
|
724
|
+
commit or to HEAD's own tree, which covers HEAD itself and an *unmoved*
|
|
725
|
+
`origin/<pr-branch>`. Once the base branch has moved, `origin/<pr-branch>` no
|
|
726
|
+
longer matches either test, so a same-repo pull request could set
|
|
727
|
+
`trust-base` to its own branch, in its own workflow file, and have conductor
|
|
728
|
+
read `.guardrails.yaml` from the pull request after all, at which point the
|
|
729
|
+
pull request controls the whole policy. dep-guard's own base input took the
|
|
730
|
+
stronger line for its base input in 0.8.0: on a `pull_request` event an
|
|
731
|
+
explicit value is refused outright.
|
|
732
|
+
|
|
733
|
+
**The Action refuses an explicit redirect on `pull_request` and
|
|
734
|
+
`pull_request_target` events.** Its validate step refuses a `trust-base`
|
|
735
|
+
input outright on those events, naming the value given and the fix, which is
|
|
736
|
+
to remove the input; see "The Action" below.
|
|
737
|
+
|
|
738
|
+
**The CLI check catches a misconfigured or innocent-looking redirect when
|
|
739
|
+
`GITHUB_BASE_REF` is set**, for anyone invoking the CLI directly in CI. When
|
|
740
|
+
that variable is set, an explicit `--trust-base` is accepted only when it
|
|
741
|
+
resolves to the same commit as `origin/$GITHUB_BASE_REF`, which is exactly
|
|
742
|
+
what the Action itself always passes, so an ordinary pull-request run is
|
|
743
|
+
unaffected. A ref naming the pull request's own branch, or anything else that
|
|
744
|
+
disagrees, is refused with both refs and both commits named, through the same
|
|
745
|
+
could-not-run path as every other trust-base refusal: exit 2, the report
|
|
746
|
+
leads with the reason, and nothing is checked. When `origin/$GITHUB_BASE_REF`
|
|
747
|
+
itself does not resolve, this fails closed too, naming it, for the same
|
|
748
|
+
reason the fetch-depth remedy below exists.
|
|
749
|
+
|
|
750
|
+
**Neither layer closes anything against a pull request that edits its own
|
|
751
|
+
workflow file.** A CLI invocation on a pull request can simply omit
|
|
752
|
+
`--trust-base`, or a workflow step can blank `GITHUB_BASE_REF` in its own env,
|
|
753
|
+
and nothing here refuses either; the Action has the matching gap, since a
|
|
754
|
+
pull request can pin `uses:` to a tag published before this fix, in its own
|
|
755
|
+
workflow file. This is exactly the boundary "On a pull request those four
|
|
756
|
+
inputs may not pin backward" (below, under "The Action") already draws for
|
|
757
|
+
the four `*-version` inputs: the control for a workflow edit is branch
|
|
758
|
+
protection on the base branch with review required for `.github/workflows`,
|
|
759
|
+
and nothing in this section, or in that one, substitutes for it.
|
|
760
|
+
|
|
639
761
|
**It fails closed.** A `--trust-base` that does not resolve is not a reason to
|
|
640
762
|
fall back to the pull request's own file, because that fallback is the hole:
|
|
641
763
|
the run exits 2 and the report **leads with the refusal**, naming the ref and
|
|
@@ -649,6 +771,39 @@ judged while still reporting pull-request mode as on. Pass the base
|
|
|
649
771
|
commit, which is HEAD. If the base branch has no `.guardrails.yaml` at all,
|
|
650
772
|
the run has no rules and exits 2 rather than using the pull request's; the
|
|
651
773
|
file the pull request adds decides what runs once it is on the base branch.
|
|
774
|
+
|
|
775
|
+
**One narrow exception to the equal-tree refusal (issue #69).** When a pull
|
|
776
|
+
request's net diff is empty -- a value committed and then backed out inside
|
|
777
|
+
the same pull request -- the merge ref GitHub builds has a tree
|
|
778
|
+
byte-identical to the base's, and the refusal above would stop
|
|
779
|
+
secrets-history from running on exactly the shape it exists to catch: the
|
|
780
|
+
value is gone from the tree but still in the history between the base and
|
|
781
|
+
HEAD. So the refusal makes one exception, and only one: when HEAD is a real
|
|
782
|
+
merge commit (two or more parents) and `--trust-base` resolves to HEAD's
|
|
783
|
+
**first** parent, the run is not refused. First-parent identity is the
|
|
784
|
+
discriminator, not ancestry, because GitHub always builds the merge ref with
|
|
785
|
+
the base branch as the first parent and the pull request's own head as the
|
|
786
|
+
second: a trust base resolving to HEAD's **second** parent is also an
|
|
787
|
+
ancestor and also carries the same tree, and it is exactly the ref this rule
|
|
788
|
+
must keep refusing. In the accepted shape the umbrella still does not judge
|
|
789
|
+
the unchanged tree as if it were the change: it runs every enabled gate
|
|
790
|
+
whose input is git history rather than the tree -- gitleaks today -- with its
|
|
791
|
+
ordinary arguments (already scoped to `<base>..HEAD`), and every other
|
|
792
|
+
enabled gate is reported as tree-unchanged rather than spawned: one line in
|
|
793
|
+
the full report, a clause on the one-line summary, and a
|
|
794
|
+
`conductor/tree-unchanged` notification in the SARIF log, never reaching the
|
|
795
|
+
exit code. Every other equal-tree shape -- a non-merge HEAD, the second
|
|
796
|
+
parent, any other ancestor -- keeps refusing exactly as before.
|
|
797
|
+
|
|
798
|
+
The exception needs HEAD's own parents, so it needs the same non-shallow
|
|
799
|
+
checkout the rest of pull-request mode already requires: `fetch-depth: 0`
|
|
800
|
+
(see below). On a depth-1 checkout git reports the merge commit with no
|
|
801
|
+
parents at all, so the first-parent check cannot match and the run keeps
|
|
802
|
+
refusing with the ordinary equal-tree message -- it fails closed rather than
|
|
803
|
+
guessing. That loss costs nothing real: at depth 1 gitleaks could not have
|
|
804
|
+
seen the backed-out commit either, since its own history scan has nothing
|
|
805
|
+
before HEAD to scope `<base>..HEAD` against.
|
|
806
|
+
|
|
652
807
|
That is why adopting conductor takes one merge before the gates can judge
|
|
653
808
|
anything, and it is not an oversight: the policy file can name a program to
|
|
654
809
|
run, so a run that read it from the pull request would let the pull request
|
|
@@ -848,7 +1003,24 @@ and keeps it committed.
|
|
|
848
1003
|
**What blocks is unchanged.** Blocking stays where intent-guard puts it:
|
|
849
1004
|
budget breaches block, subject to `enforce`. Drift on its own is reported and
|
|
850
1005
|
not blocked, which is already intent-guard's own behaviour. The umbrella adds
|
|
851
|
-
no severity threshold of its own here either.
|
|
1006
|
+
no severity threshold of its own here either, and intent-guard 1.7.0's own
|
|
1007
|
+
advance-notice warnings about an unmatchable `protected_paths` or
|
|
1008
|
+
`allowed_paths` entry never reach the exit code either, right up until the
|
|
1009
|
+
2.0.0 release where intent-guard turns that same shape into a blocking
|
|
1010
|
+
reason. Where they print depends on how much of the report is showing: as a
|
|
1011
|
+
note under the intent gate in the full report (`--verbose`, a non-clean run,
|
|
1012
|
+
or the pull-request comment, which the Action always renders with
|
|
1013
|
+
`--verbose`), and, on an otherwise-clean run with neither, counted without
|
|
1014
|
+
their text in the one-line summary's own note count instead.
|
|
1015
|
+
|
|
1016
|
+
**A prose-sourced constraint finding is never marked blocking, even when the
|
|
1017
|
+
run blocks for an unrelated reason.** intent-guard 1.6.0 caps a constraint
|
|
1018
|
+
whose source is one of those same prose rules files at advisory: a strong
|
|
1019
|
+
match is still reported, but it never raises the gate's own exit code. A run
|
|
1020
|
+
that blocks on scope creep alone still carries that capped finding in its
|
|
1021
|
+
report, and it is rendered as a non-blocking, lower-severity line in the text
|
|
1022
|
+
report and with `properties.blocking: false` in SARIF, rather than inheriting
|
|
1023
|
+
the run's own blocking flag the way every other drift finding does.
|
|
852
1024
|
|
|
853
1025
|
## The Action
|
|
854
1026
|
|
|
@@ -917,9 +1089,10 @@ provenance even though all four packages publish it.
|
|
|
917
1089
|
> points npm at a mirror or proxy that does not (via `actions/setup-node`'s
|
|
918
1090
|
> `registry-url:`, a corporate `~/.npmrc`, or `npm_config_registry`), the
|
|
919
1091
|
> install succeeds and this step then fails with `EMISSINGSIGNATUREKEY`. A
|
|
920
|
-
> sigstore outage has the same effect.
|
|
921
|
-
>
|
|
922
|
-
>
|
|
1092
|
+
> sigstore outage has the same effect. The audit is retried once after a short
|
|
1093
|
+
> pause before the step fails, to absorb a one-off registry hiccup. It fails
|
|
1094
|
+
> closed on purpose, so that is a red gate rather than a skipped check; pin to
|
|
1095
|
+
> `@v0.4.0`, which does not verify, if it blocks you.
|
|
923
1096
|
|
|
924
1097
|
`--base` is passed only when the `base-ref` input names one; left empty, the
|
|
925
1098
|
umbrella reads `GITHUB_BASE_REF` itself and treats an empty value as "not a
|
|
@@ -932,7 +1105,15 @@ rules it is judged by; a change to the rules shows as a proposal line and
|
|
|
932
1105
|
takes effect after merge. See "The pull-request trust boundary" above. On any
|
|
933
1106
|
other event it passes nothing and behaviour is unchanged. The `trust-base`
|
|
934
1107
|
input names the ref explicitly, for a platform where `GITHUB_BASE_REF` is not
|
|
935
|
-
set.
|
|
1108
|
+
set. **On a `pull_request` or `pull_request_target` event this input is
|
|
1109
|
+
refused outright, in the validate step** (issue #58). On `pull_request` the
|
|
1110
|
+
workflow file is the pull request's own, so a value here that redirects the
|
|
1111
|
+
trust base is settable by the thing it judges; on `pull_request_target` the
|
|
1112
|
+
workflow file is the *base* branch's own instead, but the input is refused
|
|
1113
|
+
there too, because pull-request mode already derives the trust base on both
|
|
1114
|
+
events and an explicit redirect has no legitimate use on either. The refusal
|
|
1115
|
+
names the value that was given and the fix, which is to remove the input: the
|
|
1116
|
+
action already derives `origin/$GITHUB_BASE_REF` itself on that event.
|
|
936
1117
|
|
|
937
1118
|
There is deliberately **no input that turns pull-request mode off**.
|
|
938
1119
|
Base-ref judging is the floor rather than a knob, and on a `pull_request`
|
|
@@ -967,7 +1148,7 @@ jobs:
|
|
|
967
1148
|
with:
|
|
968
1149
|
node-version: '22.11.0'
|
|
969
1150
|
- id: conductor
|
|
970
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1151
|
+
uses: vaultcompasshq/conductor@v0.7.0
|
|
971
1152
|
with:
|
|
972
1153
|
output: conductor.sarif
|
|
973
1154
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -977,6 +1158,14 @@ jobs:
|
|
|
977
1158
|
sarif_file: ${{ steps.conductor.outputs.sarif }}
|
|
978
1159
|
```
|
|
979
1160
|
|
|
1161
|
+
The examples leave the trigger unnarrowed on purpose, so the job runs for a
|
|
1162
|
+
pull request into any branch. If you narrow it with a `branches:` filter,
|
|
1163
|
+
include every branch whose merges reach users, release branches and the
|
|
1164
|
+
production branch included, for instance `branches: [main, 'release/**',
|
|
1165
|
+
production]`. The pull request that promotes a release is where a bad
|
|
1166
|
+
dependency or a leaked secret actually ships, and a job that is not triggered
|
|
1167
|
+
leaves no red check and no report to notice.
|
|
1168
|
+
|
|
980
1169
|
No version inputs there at all: left out, the four gates run at the versions
|
|
981
1170
|
this tag ships, which is the intended default. The fully spelled-out example
|
|
982
1171
|
below adds explicit version pins and comments explaining each one, for a
|
|
@@ -1016,7 +1205,7 @@ jobs:
|
|
|
1016
1205
|
# pinned below.
|
|
1017
1206
|
- run: pnpm install --frozen-lockfile
|
|
1018
1207
|
- id: conductor
|
|
1019
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1208
|
+
uses: vaultcompasshq/conductor@v0.7.0
|
|
1020
1209
|
with:
|
|
1021
1210
|
output: conductor.sarif
|
|
1022
1211
|
# Exact versions, never a range and never "latest". These four
|
|
@@ -1027,10 +1216,10 @@ jobs:
|
|
|
1027
1216
|
# request of their own. Forward only on a pull request: the action
|
|
1028
1217
|
# refuses a pin below what its tag ships, and the four lines can be
|
|
1029
1218
|
# left out entirely to take that tag's own versions.
|
|
1030
|
-
conductor-version: 0.
|
|
1031
|
-
dep-guard-version: 0.
|
|
1219
|
+
conductor-version: 0.7.0
|
|
1220
|
+
dep-guard-version: 0.9.0
|
|
1032
1221
|
vault-guard-version: 1.8.0
|
|
1033
|
-
intent-guard-version: 1.
|
|
1222
|
+
intent-guard-version: 1.7.0
|
|
1034
1223
|
- uses: github/codeql-action/upload-sarif@v3
|
|
1035
1224
|
# Always: the log is most worth having on the run that failed.
|
|
1036
1225
|
if: always()
|
|
@@ -1122,7 +1311,7 @@ jobs:
|
|
|
1122
1311
|
node-version: '22.11.0'
|
|
1123
1312
|
- id: conductor
|
|
1124
1313
|
timeout-minutes: 5
|
|
1125
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1314
|
+
uses: vaultcompasshq/conductor@v0.7.0
|
|
1126
1315
|
with:
|
|
1127
1316
|
pr-comment: true
|
|
1128
1317
|
advisory: true
|
|
@@ -1153,6 +1342,58 @@ author nothing they could not already do by editing the workflow to add
|
|
|
1153
1342
|
edit, is branch protection requiring review on `.github/workflows`, not
|
|
1154
1343
|
anything in `action.yml`.
|
|
1155
1344
|
|
|
1345
|
+
**A `paths:` filter on this job is a real trade, not a free speedup, and the
|
|
1346
|
+
honest default is to skip it.** The biggest reason is not about coverage, it
|
|
1347
|
+
is about merging at all: `paths:` applies to the workflow's own trigger, and
|
|
1348
|
+
a required check whose workflow a `paths:` filter kept from running is
|
|
1349
|
+
reported as never having run at all, not as passed. That check then sits
|
|
1350
|
+
**pending**, and a pull request cannot merge while a required check is
|
|
1351
|
+
pending, regardless of how trivial the change is. GitHub's own documentation
|
|
1352
|
+
describes exactly this failure mode for a required, `paths:`-filtered
|
|
1353
|
+
workflow, and its usual workaround: a job that always runs, regardless of
|
|
1354
|
+
what changed, and reports success or failure on its own rather than relying
|
|
1355
|
+
on the whole workflow being skipped or not.
|
|
1356
|
+
|
|
1357
|
+
The coverage cost is real too, separately from the merge-blocking one. Every
|
|
1358
|
+
gate in the default policy reads the whole changed set, not a slice of it:
|
|
1359
|
+
gitleaks scans git history, so a secret can land in any file regardless of
|
|
1360
|
+
what kind of pull request carries it; vault-guard's own staged scan is the
|
|
1361
|
+
same, over whatever paths changed; dep-guard and osv-scanner only care about
|
|
1362
|
+
manifests and lockfiles, but they still need to see a pull request touch one
|
|
1363
|
+
to react to it; and intent-guard's drift and budget checks are evaluated
|
|
1364
|
+
against every changed path, not only source. A `paths:` filter keyed on
|
|
1365
|
+
`package.json`, the lockfile, and your source globs is exactly right for
|
|
1366
|
+
dep-guard and osv-scanner and exactly wrong for the two secrets gates: it
|
|
1367
|
+
makes a docs-only pull request skip the whole job, gitleaks and vault-guard
|
|
1368
|
+
included, which means a secret pasted into a docs-only change, a comment, or
|
|
1369
|
+
a config file the filter did not list is never scanned at all. That is the
|
|
1370
|
+
cost, plainly: fewer runs bought by turning off secrets scanning on the pull
|
|
1371
|
+
requests the filter excludes.
|
|
1372
|
+
|
|
1373
|
+
If your workflow already has its own required security job and you only
|
|
1374
|
+
want this one to skip clean docs-only changes, add GitHub's own `paths:`
|
|
1375
|
+
(or `paths-ignore:`) to the `on: pull_request` block, the same syntax GitHub
|
|
1376
|
+
documents for any workflow trigger, and account for both traps above before
|
|
1377
|
+
you make the job required: the pull requests it would leave permanently
|
|
1378
|
+
pending, and the coverage this recipe would then lose on exactly the pull
|
|
1379
|
+
requests it skips. The alternative this README recommends is to leave
|
|
1380
|
+
the job triggering on every pull request: a run with nothing to report is
|
|
1381
|
+
not a run worth avoiding, and this recipe has no documented time budget to
|
|
1382
|
+
promise you here, because that number depends on your repository's size and
|
|
1383
|
+
the gates you enable, not on anything conductor fixes. Measure it once on
|
|
1384
|
+
your own repository if you need a number to plan around.
|
|
1385
|
+
|
|
1386
|
+
**Renaming the job changes what branch protection is watching for.** GitHub
|
|
1387
|
+
matches a required check by its context, which is the JOB's name (`gates`
|
|
1388
|
+
here), never the workflow's name (`guardrails-advisory`). If you split this
|
|
1389
|
+
into a paths-filtered job with a different name, or rename the job for any
|
|
1390
|
+
other reason, a pull request that no longer produces the old context name
|
|
1391
|
+
will sit waiting on a check that will never report, until you also update
|
|
1392
|
+
the required-checks list in
|
|
1393
|
+
the branch protection ruleset to match. That edit lives on the repository's
|
|
1394
|
+
settings, not in the workflow file, so it is easy to make the workflow
|
|
1395
|
+
change and forget the other half.
|
|
1396
|
+
|
|
1156
1397
|
### Adopting conductor
|
|
1157
1398
|
|
|
1158
1399
|
See "Adopting conductor" near the top of this README for the ordered
|
|
@@ -1168,6 +1409,15 @@ for `advisory` to act on. Leaving the check out of branch protection for
|
|
|
1168
1409
|
that one pull request is what keeps the expected exit 2 from blocking the
|
|
1169
1410
|
merge; the step posts a comment naming the ref and the remedy.
|
|
1170
1411
|
|
|
1412
|
+
The same refusal happens once on every new base branch, not only on the
|
|
1413
|
+
default branch, because rules are read from whatever branch the pull request
|
|
1414
|
+
targets. A release or release-candidate branch cut before the policy existed,
|
|
1415
|
+
or any long-lived branch that has never received `.guardrails.yaml`, refuses
|
|
1416
|
+
its first pull request the same way. There are two remedies. Carry the policy
|
|
1417
|
+
onto the branch before opening a pull request against it; a sync from the
|
|
1418
|
+
default branch does this. Or expect exactly one could-not-run run there, and
|
|
1419
|
+
leave the check out of that branch's protection for that one pull request.
|
|
1420
|
+
|
|
1171
1421
|
**Why "go required" means the job's own context, never the SARIF-upload
|
|
1172
1422
|
row.** The recipes above upload conductor's SARIF log with
|
|
1173
1423
|
`github/codeql-action/upload-sarif`, which can add its own code-scanning
|
|
@@ -1194,7 +1444,7 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1194
1444
|
steps:
|
|
1195
1445
|
# ... checkout, pnpm, setup-node, install, as in the example above ...
|
|
1196
1446
|
- id: conductor
|
|
1197
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1447
|
+
uses: vaultcompasshq/conductor@v0.7.0
|
|
1198
1448
|
with:
|
|
1199
1449
|
output: conductor.sarif
|
|
1200
1450
|
pr-comment: true
|
|
@@ -1202,13 +1452,21 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1202
1452
|
|
|
1203
1453
|
That posts conductor's own text report, the one the README quotes above
|
|
1204
1454
|
("conductor: clean, nothing blocked. 2 gate(s) ran: ..."), as a comment on
|
|
1205
|
-
the pull request. It is **
|
|
1455
|
+
the pull request. It is **the report of the run that decided the job**: the
|
|
1456
|
+
gates step asks that one run for the SARIF log and the text report together
|
|
1457
|
+
(`--text-report`), and the comment step posts the file it wrote without
|
|
1458
|
+
running the gates again. Before this the comment came from a second run, which
|
|
1459
|
+
could disagree with the first whenever a gate's answer was time or network
|
|
1460
|
+
dependent, and doubled the gate time on every pull request. An installed
|
|
1461
|
+
`conductor-version` too old to have `--text-report` is detected by asking the
|
|
1462
|
+
binary, and gets the second-run behaviour it always had, without a token. It is **sticky**: a hidden marker in the comment body lets
|
|
1206
1463
|
a re-run find and update that same comment, so a push does not pile up a new
|
|
1207
1464
|
comment every time, the way the manual recipe below does. It runs on a
|
|
1208
1465
|
`pull_request` or `pull_request_target` event only, and it runs whether the
|
|
1209
1466
|
gates step passed or failed, since a blocking run is the one an advisory
|
|
1210
1467
|
check most needs a developer to actually see. The first line of every
|
|
1211
|
-
comment carries the version of conductor that produced it,
|
|
1468
|
+
comment carries the version of conductor that produced it, the second line
|
|
1469
|
+
carries the verdict token (see "The verdict token" above), and when the
|
|
1212
1470
|
trust base was refused and no gate ran at all, the comment shrinks to the
|
|
1213
1471
|
version, the verdict, and the refusal reason (with its remedy, when one
|
|
1214
1472
|
applies) rather than the full per-gate report, so an adopter with no policy
|
|
@@ -1227,6 +1485,18 @@ add; nothing here does that for you.
|
|
|
1227
1485
|
|
|
1228
1486
|
Off by default, so an existing consumer of this action is unaffected.
|
|
1229
1487
|
|
|
1488
|
+
**The verdict, whether or not the comment is on.** The gates step reads the
|
|
1489
|
+
token out of the text report its own run wrote and publishes it twice: as a
|
|
1490
|
+
line on the job summary, `conductor verdict: advisory-blocked (1)`, and as the
|
|
1491
|
+
Action's `verdict` output, spelled exactly as the report's second line spells
|
|
1492
|
+
it (`steps.conductor.outputs.verdict`). It is flattened to one line before it
|
|
1493
|
+
goes to either. It is a label for conductor's own exit decision, and the
|
|
1494
|
+
step's exit status is conductor's own in every state. When the gate packages
|
|
1495
|
+
could not be verified and no gate ran, the summary says
|
|
1496
|
+
`conductor verdict: could-not-run (<reason>)` and the output is
|
|
1497
|
+
`could-not-run`. The output is empty when the installed `conductor-version`
|
|
1498
|
+
predates the token.
|
|
1499
|
+
|
|
1230
1500
|
**The sticky match only ever adopts conductor's own comment.** On
|
|
1231
1501
|
`pull_request_target` this step runs with a write token even though the
|
|
1232
1502
|
pull request itself is untrusted, so anyone who can comment on the pull
|
|
@@ -1246,12 +1516,12 @@ per pull request.
|
|
|
1246
1516
|
|
|
1247
1517
|
```yaml
|
|
1248
1518
|
- id: conductor-package-a
|
|
1249
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1519
|
+
uses: vaultcompasshq/conductor@v0.7.0
|
|
1250
1520
|
with:
|
|
1251
1521
|
pr-comment: true
|
|
1252
1522
|
pr-comment-marker: 'package-a'
|
|
1253
1523
|
- id: conductor-package-b
|
|
1254
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1524
|
+
uses: vaultcompasshq/conductor@v0.7.0
|
|
1255
1525
|
with:
|
|
1256
1526
|
pr-comment: true
|
|
1257
1527
|
pr-comment-marker: 'package-b'
|
|
@@ -1282,9 +1552,12 @@ case, `pr-comment: true` is the built-in answer.
|
|
|
1282
1552
|
The SARIF upload produces no alerts on a private repository without GitHub
|
|
1283
1553
|
Code Security, which is why that step carries `continue-on-error`. A comment
|
|
1284
1554
|
is free there. Add `pull-requests: write` to the job's `permissions` and this
|
|
1285
|
-
step after the gates. It **runs the gates a second time**, because
|
|
1286
|
-
|
|
1287
|
-
|
|
1555
|
+
step after the gates. It **runs the gates a second time**, because a run has
|
|
1556
|
+
one format and the recipe below asks for text, so the job costs roughly twice
|
|
1557
|
+
the gate time and the comment can in principle disagree with the first run;
|
|
1558
|
+
the built-in `pr-comment: true` does not, since it posts the file the first
|
|
1559
|
+
run wrote (`--text-report`). `--verbose` because a clean run otherwise
|
|
1560
|
+
collapses to one line.
|
|
1288
1561
|
|
|
1289
1562
|
```yaml
|
|
1290
1563
|
- name: Comment the report on the pull request
|