@vaultcompass/conductor 0.5.0 → 0.6.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 +212 -23
- package/dist/cli.js +169 -40
- 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.js +59 -20
- 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,41 @@ 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.6.0
|
|
159
171
|
conductor run: 2 gate(s), 1 finding(s)
|
|
160
172
|
|
|
161
|
-
dependencies dep-guard 0.
|
|
173
|
+
dependencies dep-guard 0.7.0 exit 0 153ms via dep-guard on path
|
|
162
174
|
threshold medium suppressed 0 ignored 0
|
|
175
|
+
mode staged corpusBuiltAt 2026-09-20T06:16:40.340Z lockfileFormat npm online-flag not passed
|
|
163
176
|
|
|
164
|
-
secrets vault-guard 1.
|
|
165
|
-
BLOCKING critical vault-guard/anthropic jest.config.mjs:
|
|
177
|
+
secrets vault-guard 1.8.0 exit 1 105ms via vault-guard on path
|
|
178
|
+
BLOCKING critical vault-guard/anthropic jest.config.mjs:14:12
|
|
166
179
|
Possible secret of type 'anthropic'
|
|
167
180
|
threshold medium suppressed 0 ignored not reported
|
|
181
|
+
filesScanned 1 patternsActive 59
|
|
168
182
|
|
|
169
183
|
deferred intent intent-guard did not run here; it runs from stage ci onwards
|
|
170
184
|
|
|
171
185
|
verdict: exit 1, 1 blocking finding(s) across 2 gate(s).
|
|
172
186
|
```
|
|
173
187
|
|
|
188
|
+
The `mode`, `corpusBuiltAt`, `lockfileFormat` and `online-flag` line under
|
|
189
|
+
`dependencies`, and the `filesScanned`/`patternsActive` line under
|
|
190
|
+
`secrets`, are each gate's own run facts, one line per gate, added to the
|
|
191
|
+
full report so a reader can see what a gate actually scanned and with
|
|
192
|
+
what, not only its verdict.
|
|
193
|
+
|
|
174
194
|
Both gates there are the ones you installed a moment ago, running with
|
|
175
195
|
their own thresholds and their own baselines. The umbrella found nothing
|
|
176
196
|
of its own, because it looks for nothing of its own.
|
|
@@ -405,6 +425,10 @@ above); do not commit it.
|
|
|
405
425
|
somebody else's file into one this tool may overwrite. Like `--adopt`,
|
|
406
426
|
only meaningful together with `--hook` on an init (not on a `--revert`);
|
|
407
427
|
without it, init errors.
|
|
428
|
+
- `--project <dir>` writes into that repository instead of the current
|
|
429
|
+
directory, resolved to its git top level the same way the current
|
|
430
|
+
directory already is, so a script can point init at a repository without a
|
|
431
|
+
`cd` compound.
|
|
408
432
|
|
|
409
433
|
The rest of this section, on hook managers already wired into the
|
|
410
434
|
repository, applies only when `--hook` is given: none of it is consulted,
|
|
@@ -444,13 +468,21 @@ proceeds normally without mentioning them.
|
|
|
444
468
|
control input of the gates that support it. See "The pull-request trust
|
|
445
469
|
boundary" below. `--base` and `--trust-base` are independent and a
|
|
446
470
|
pull-request run passes both: `--base` decides which paths are judged,
|
|
447
|
-
`--trust-base` decides what they are judged by.
|
|
471
|
+
`--trust-base` decides what they are judged by. When `GITHUB_BASE_REF` is
|
|
472
|
+
set, an explicit `--trust-base` is accepted only when it resolves to the
|
|
473
|
+
same commit as `origin/$GITHUB_BASE_REF` (issue #58); anyone invoking the
|
|
474
|
+
CLI directly on a pull request, rather than through the Action, gets this
|
|
475
|
+
as its own refusal, named below.
|
|
448
476
|
- `--spec <path>` names the spec the intent gate imports its contract from.
|
|
449
477
|
- `--output <path>` writes the report to a file instead of to stdout, for a
|
|
450
478
|
CI step that uploads it. One line still goes to stdout, because a job whose
|
|
451
479
|
only product is an uploaded artifact otherwise reads as a job that did
|
|
452
480
|
nothing. A path that cannot be written is exit 2, not a green run beside a
|
|
453
|
-
report nobody can read.
|
|
481
|
+
report nobody can read. A relative value resolves against the current
|
|
482
|
+
directory the command was invoked from, not against `--project` or the
|
|
483
|
+
repository root: with `--project` pointing elsewhere, a relative
|
|
484
|
+
`--output` still lands next to where you are, not next to the repository
|
|
485
|
+
being judged.
|
|
454
486
|
- `--verbose` prints the full per-gate report even when the run is clean.
|
|
455
487
|
Text output only; the SARIF log never changes shape with it.
|
|
456
488
|
- `--compact-on-refusal` shrinks the report to the version, the verdict and
|
|
@@ -472,6 +504,13 @@ proceeds normally without mentioning them.
|
|
|
472
504
|
verdict line's own wording (it says findings were advisory and did not
|
|
473
505
|
block) change. Text output only; the SARIF log has no verdict line to
|
|
474
506
|
change and its `properties.blocking` on each result is unaffected.
|
|
507
|
+
- `--project <dir>` runs against that repository instead of the current
|
|
508
|
+
directory, resolved to its git top level the same way the current
|
|
509
|
+
directory already is, so a subdirectory resolves to that repository's top
|
|
510
|
+
level. A relative value resolves against the current directory. A path
|
|
511
|
+
that does not exist, is not a directory, or is not inside a git repository
|
|
512
|
+
is a usage error naming the path and exits 2 rather than falling back to
|
|
513
|
+
the current directory.
|
|
475
514
|
|
|
476
515
|
### Exit codes
|
|
477
516
|
|
|
@@ -636,6 +675,46 @@ one-line summary and on the verdict, with a line each under `--verbose` and a
|
|
|
636
675
|
reflow, a re-quote or an edited comment is not a proposal: the two files are
|
|
637
676
|
compared as parsed documents.
|
|
638
677
|
|
|
678
|
+
**An explicit `--trust-base` redirect gets a refusal on a pull request, at two
|
|
679
|
+
places (issue #58), and neither closes the whole hole by itself.**
|
|
680
|
+
`refuseTrustBaseRef` above only refuses a ref that resolves to HEAD's own
|
|
681
|
+
commit or to HEAD's own tree, which covers HEAD itself and an *unmoved*
|
|
682
|
+
`origin/<pr-branch>`. Once the base branch has moved, `origin/<pr-branch>` no
|
|
683
|
+
longer matches either test, so a same-repo pull request could set
|
|
684
|
+
`trust-base` to its own branch, in its own workflow file, and have conductor
|
|
685
|
+
read `.guardrails.yaml` from the pull request after all, at which point the
|
|
686
|
+
pull request controls the whole policy. dep-guard's own base input took the
|
|
687
|
+
stronger line for its base input in 0.8.0: on a `pull_request` event an
|
|
688
|
+
explicit value is refused outright.
|
|
689
|
+
|
|
690
|
+
**The Action refuses an explicit redirect on `pull_request` and
|
|
691
|
+
`pull_request_target` events.** Its validate step refuses a `trust-base`
|
|
692
|
+
input outright on those events, naming the value given and the fix, which is
|
|
693
|
+
to remove the input; see "The Action" below.
|
|
694
|
+
|
|
695
|
+
**The CLI check catches a misconfigured or innocent-looking redirect when
|
|
696
|
+
`GITHUB_BASE_REF` is set**, for anyone invoking the CLI directly in CI. When
|
|
697
|
+
that variable is set, an explicit `--trust-base` is accepted only when it
|
|
698
|
+
resolves to the same commit as `origin/$GITHUB_BASE_REF`, which is exactly
|
|
699
|
+
what the Action itself always passes, so an ordinary pull-request run is
|
|
700
|
+
unaffected. A ref naming the pull request's own branch, or anything else that
|
|
701
|
+
disagrees, is refused with both refs and both commits named, through the same
|
|
702
|
+
could-not-run path as every other trust-base refusal: exit 2, the report
|
|
703
|
+
leads with the reason, and nothing is checked. When `origin/$GITHUB_BASE_REF`
|
|
704
|
+
itself does not resolve, this fails closed too, naming it, for the same
|
|
705
|
+
reason the fetch-depth remedy below exists.
|
|
706
|
+
|
|
707
|
+
**Neither layer closes anything against a pull request that edits its own
|
|
708
|
+
workflow file.** A CLI invocation on a pull request can simply omit
|
|
709
|
+
`--trust-base`, or a workflow step can blank `GITHUB_BASE_REF` in its own env,
|
|
710
|
+
and nothing here refuses either; the Action has the matching gap, since a
|
|
711
|
+
pull request can pin `uses:` to a tag published before this fix, in its own
|
|
712
|
+
workflow file. This is exactly the boundary "On a pull request those four
|
|
713
|
+
inputs may not pin backward" (below, under "The Action") already draws for
|
|
714
|
+
the four `*-version` inputs: the control for a workflow edit is branch
|
|
715
|
+
protection on the base branch with review required for `.github/workflows`,
|
|
716
|
+
and nothing in this section, or in that one, substitutes for it.
|
|
717
|
+
|
|
639
718
|
**It fails closed.** A `--trust-base` that does not resolve is not a reason to
|
|
640
719
|
fall back to the pull request's own file, because that fallback is the hole:
|
|
641
720
|
the run exits 2 and the report **leads with the refusal**, naming the ref and
|
|
@@ -649,6 +728,39 @@ judged while still reporting pull-request mode as on. Pass the base
|
|
|
649
728
|
commit, which is HEAD. If the base branch has no `.guardrails.yaml` at all,
|
|
650
729
|
the run has no rules and exits 2 rather than using the pull request's; the
|
|
651
730
|
file the pull request adds decides what runs once it is on the base branch.
|
|
731
|
+
|
|
732
|
+
**One narrow exception to the equal-tree refusal (issue #69).** When a pull
|
|
733
|
+
request's net diff is empty -- a value committed and then backed out inside
|
|
734
|
+
the same pull request -- the merge ref GitHub builds has a tree
|
|
735
|
+
byte-identical to the base's, and the refusal above would stop
|
|
736
|
+
secrets-history from running on exactly the shape it exists to catch: the
|
|
737
|
+
value is gone from the tree but still in the history between the base and
|
|
738
|
+
HEAD. So the refusal makes one exception, and only one: when HEAD is a real
|
|
739
|
+
merge commit (two or more parents) and `--trust-base` resolves to HEAD's
|
|
740
|
+
**first** parent, the run is not refused. First-parent identity is the
|
|
741
|
+
discriminator, not ancestry, because GitHub always builds the merge ref with
|
|
742
|
+
the base branch as the first parent and the pull request's own head as the
|
|
743
|
+
second: a trust base resolving to HEAD's **second** parent is also an
|
|
744
|
+
ancestor and also carries the same tree, and it is exactly the ref this rule
|
|
745
|
+
must keep refusing. In the accepted shape the umbrella still does not judge
|
|
746
|
+
the unchanged tree as if it were the change: it runs every enabled gate
|
|
747
|
+
whose input is git history rather than the tree -- gitleaks today -- with its
|
|
748
|
+
ordinary arguments (already scoped to `<base>..HEAD`), and every other
|
|
749
|
+
enabled gate is reported as tree-unchanged rather than spawned: one line in
|
|
750
|
+
the full report, a clause on the one-line summary, and a
|
|
751
|
+
`conductor/tree-unchanged` notification in the SARIF log, never reaching the
|
|
752
|
+
exit code. Every other equal-tree shape -- a non-merge HEAD, the second
|
|
753
|
+
parent, any other ancestor -- keeps refusing exactly as before.
|
|
754
|
+
|
|
755
|
+
The exception needs HEAD's own parents, so it needs the same non-shallow
|
|
756
|
+
checkout the rest of pull-request mode already requires: `fetch-depth: 0`
|
|
757
|
+
(see below). On a depth-1 checkout git reports the merge commit with no
|
|
758
|
+
parents at all, so the first-parent check cannot match and the run keeps
|
|
759
|
+
refusing with the ordinary equal-tree message -- it fails closed rather than
|
|
760
|
+
guessing. That loss costs nothing real: at depth 1 gitleaks could not have
|
|
761
|
+
seen the backed-out commit either, since its own history scan has nothing
|
|
762
|
+
before HEAD to scope `<base>..HEAD` against.
|
|
763
|
+
|
|
652
764
|
That is why adopting conductor takes one merge before the gates can judge
|
|
653
765
|
anything, and it is not an oversight: the policy file can name a program to
|
|
654
766
|
run, so a run that read it from the pull request would let the pull request
|
|
@@ -848,7 +960,24 @@ and keeps it committed.
|
|
|
848
960
|
**What blocks is unchanged.** Blocking stays where intent-guard puts it:
|
|
849
961
|
budget breaches block, subject to `enforce`. Drift on its own is reported and
|
|
850
962
|
not blocked, which is already intent-guard's own behaviour. The umbrella adds
|
|
851
|
-
no severity threshold of its own here either.
|
|
963
|
+
no severity threshold of its own here either, and intent-guard 1.7.0's own
|
|
964
|
+
advance-notice warnings about an unmatchable `protected_paths` or
|
|
965
|
+
`allowed_paths` entry never reach the exit code either, right up until the
|
|
966
|
+
2.0.0 release where intent-guard turns that same shape into a blocking
|
|
967
|
+
reason. Where they print depends on how much of the report is showing: as a
|
|
968
|
+
note under the intent gate in the full report (`--verbose`, a non-clean run,
|
|
969
|
+
or the pull-request comment, which the Action always renders with
|
|
970
|
+
`--verbose`), and, on an otherwise-clean run with neither, counted without
|
|
971
|
+
their text in the one-line summary's own note count instead.
|
|
972
|
+
|
|
973
|
+
**A prose-sourced constraint finding is never marked blocking, even when the
|
|
974
|
+
run blocks for an unrelated reason.** intent-guard 1.6.0 caps a constraint
|
|
975
|
+
whose source is one of those same prose rules files at advisory: a strong
|
|
976
|
+
match is still reported, but it never raises the gate's own exit code. A run
|
|
977
|
+
that blocks on scope creep alone still carries that capped finding in its
|
|
978
|
+
report, and it is rendered as a non-blocking, lower-severity line in the text
|
|
979
|
+
report and with `properties.blocking: false` in SARIF, rather than inheriting
|
|
980
|
+
the run's own blocking flag the way every other drift finding does.
|
|
852
981
|
|
|
853
982
|
## The Action
|
|
854
983
|
|
|
@@ -932,7 +1061,15 @@ rules it is judged by; a change to the rules shows as a proposal line and
|
|
|
932
1061
|
takes effect after merge. See "The pull-request trust boundary" above. On any
|
|
933
1062
|
other event it passes nothing and behaviour is unchanged. The `trust-base`
|
|
934
1063
|
input names the ref explicitly, for a platform where `GITHUB_BASE_REF` is not
|
|
935
|
-
set.
|
|
1064
|
+
set. **On a `pull_request` or `pull_request_target` event this input is
|
|
1065
|
+
refused outright, in the validate step** (issue #58). On `pull_request` the
|
|
1066
|
+
workflow file is the pull request's own, so a value here that redirects the
|
|
1067
|
+
trust base is settable by the thing it judges; on `pull_request_target` the
|
|
1068
|
+
workflow file is the *base* branch's own instead, but the input is refused
|
|
1069
|
+
there too, because pull-request mode already derives the trust base on both
|
|
1070
|
+
events and an explicit redirect has no legitimate use on either. The refusal
|
|
1071
|
+
names the value that was given and the fix, which is to remove the input: the
|
|
1072
|
+
action already derives `origin/$GITHUB_BASE_REF` itself on that event.
|
|
936
1073
|
|
|
937
1074
|
There is deliberately **no input that turns pull-request mode off**.
|
|
938
1075
|
Base-ref judging is the floor rather than a knob, and on a `pull_request`
|
|
@@ -967,7 +1104,7 @@ jobs:
|
|
|
967
1104
|
with:
|
|
968
1105
|
node-version: '22.11.0'
|
|
969
1106
|
- id: conductor
|
|
970
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1107
|
+
uses: vaultcompasshq/conductor@v0.6.0
|
|
971
1108
|
with:
|
|
972
1109
|
output: conductor.sarif
|
|
973
1110
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -1016,7 +1153,7 @@ jobs:
|
|
|
1016
1153
|
# pinned below.
|
|
1017
1154
|
- run: pnpm install --frozen-lockfile
|
|
1018
1155
|
- id: conductor
|
|
1019
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1156
|
+
uses: vaultcompasshq/conductor@v0.6.0
|
|
1020
1157
|
with:
|
|
1021
1158
|
output: conductor.sarif
|
|
1022
1159
|
# Exact versions, never a range and never "latest". These four
|
|
@@ -1027,10 +1164,10 @@ jobs:
|
|
|
1027
1164
|
# request of their own. Forward only on a pull request: the action
|
|
1028
1165
|
# refuses a pin below what its tag ships, and the four lines can be
|
|
1029
1166
|
# left out entirely to take that tag's own versions.
|
|
1030
|
-
conductor-version: 0.
|
|
1031
|
-
dep-guard-version: 0.
|
|
1167
|
+
conductor-version: 0.6.0
|
|
1168
|
+
dep-guard-version: 0.9.0
|
|
1032
1169
|
vault-guard-version: 1.8.0
|
|
1033
|
-
intent-guard-version: 1.
|
|
1170
|
+
intent-guard-version: 1.7.0
|
|
1034
1171
|
- uses: github/codeql-action/upload-sarif@v3
|
|
1035
1172
|
# Always: the log is most worth having on the run that failed.
|
|
1036
1173
|
if: always()
|
|
@@ -1122,7 +1259,7 @@ jobs:
|
|
|
1122
1259
|
node-version: '22.11.0'
|
|
1123
1260
|
- id: conductor
|
|
1124
1261
|
timeout-minutes: 5
|
|
1125
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1262
|
+
uses: vaultcompasshq/conductor@v0.6.0
|
|
1126
1263
|
with:
|
|
1127
1264
|
pr-comment: true
|
|
1128
1265
|
advisory: true
|
|
@@ -1153,6 +1290,58 @@ author nothing they could not already do by editing the workflow to add
|
|
|
1153
1290
|
edit, is branch protection requiring review on `.github/workflows`, not
|
|
1154
1291
|
anything in `action.yml`.
|
|
1155
1292
|
|
|
1293
|
+
**A `paths:` filter on this job is a real trade, not a free speedup, and the
|
|
1294
|
+
honest default is to skip it.** The biggest reason is not about coverage, it
|
|
1295
|
+
is about merging at all: `paths:` applies to the workflow's own trigger, and
|
|
1296
|
+
a required check whose workflow a `paths:` filter kept from running is
|
|
1297
|
+
reported as never having run at all, not as passed. That check then sits
|
|
1298
|
+
**pending**, and a pull request cannot merge while a required check is
|
|
1299
|
+
pending, regardless of how trivial the change is. GitHub's own documentation
|
|
1300
|
+
describes exactly this failure mode for a required, `paths:`-filtered
|
|
1301
|
+
workflow, and its usual workaround: a job that always runs, regardless of
|
|
1302
|
+
what changed, and reports success or failure on its own rather than relying
|
|
1303
|
+
on the whole workflow being skipped or not.
|
|
1304
|
+
|
|
1305
|
+
The coverage cost is real too, separately from the merge-blocking one. Every
|
|
1306
|
+
gate in the default policy reads the whole changed set, not a slice of it:
|
|
1307
|
+
gitleaks scans git history, so a secret can land in any file regardless of
|
|
1308
|
+
what kind of pull request carries it; vault-guard's own staged scan is the
|
|
1309
|
+
same, over whatever paths changed; dep-guard and osv-scanner only care about
|
|
1310
|
+
manifests and lockfiles, but they still need to see a pull request touch one
|
|
1311
|
+
to react to it; and intent-guard's drift and budget checks are evaluated
|
|
1312
|
+
against every changed path, not only source. A `paths:` filter keyed on
|
|
1313
|
+
`package.json`, the lockfile, and your source globs is exactly right for
|
|
1314
|
+
dep-guard and osv-scanner and exactly wrong for the two secrets gates: it
|
|
1315
|
+
makes a docs-only pull request skip the whole job, gitleaks and vault-guard
|
|
1316
|
+
included, which means a secret pasted into a docs-only change, a comment, or
|
|
1317
|
+
a config file the filter did not list is never scanned at all. That is the
|
|
1318
|
+
cost, plainly: fewer runs bought by turning off secrets scanning on the pull
|
|
1319
|
+
requests the filter excludes.
|
|
1320
|
+
|
|
1321
|
+
If your workflow already has its own required security job and you only
|
|
1322
|
+
want this one to skip clean docs-only changes, add GitHub's own `paths:`
|
|
1323
|
+
(or `paths-ignore:`) to the `on: pull_request` block, the same syntax GitHub
|
|
1324
|
+
documents for any workflow trigger, and account for both traps above before
|
|
1325
|
+
you make the job required: the pull requests it would leave permanently
|
|
1326
|
+
pending, and the coverage this recipe would then lose on exactly the pull
|
|
1327
|
+
requests it skips. The alternative this README recommends is to leave
|
|
1328
|
+
the job triggering on every pull request: a run with nothing to report is
|
|
1329
|
+
not a run worth avoiding, and this recipe has no documented time budget to
|
|
1330
|
+
promise you here, because that number depends on your repository's size and
|
|
1331
|
+
the gates you enable, not on anything conductor fixes. Measure it once on
|
|
1332
|
+
your own repository if you need a number to plan around.
|
|
1333
|
+
|
|
1334
|
+
**Renaming the job changes what branch protection is watching for.** GitHub
|
|
1335
|
+
matches a required check by its context, which is the JOB's name (`gates`
|
|
1336
|
+
here), never the workflow's name (`guardrails-advisory`). If you split this
|
|
1337
|
+
into a paths-filtered job with a different name, or rename the job for any
|
|
1338
|
+
other reason, a pull request that no longer produces the old context name
|
|
1339
|
+
will sit waiting on a check that will never report, until you also update
|
|
1340
|
+
the required-checks list in
|
|
1341
|
+
the branch protection ruleset to match. That edit lives on the repository's
|
|
1342
|
+
settings, not in the workflow file, so it is easy to make the workflow
|
|
1343
|
+
change and forget the other half.
|
|
1344
|
+
|
|
1156
1345
|
### Adopting conductor
|
|
1157
1346
|
|
|
1158
1347
|
See "Adopting conductor" near the top of this README for the ordered
|
|
@@ -1194,7 +1383,7 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1194
1383
|
steps:
|
|
1195
1384
|
# ... checkout, pnpm, setup-node, install, as in the example above ...
|
|
1196
1385
|
- id: conductor
|
|
1197
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1386
|
+
uses: vaultcompasshq/conductor@v0.6.0
|
|
1198
1387
|
with:
|
|
1199
1388
|
output: conductor.sarif
|
|
1200
1389
|
pr-comment: true
|
|
@@ -1246,12 +1435,12 @@ per pull request.
|
|
|
1246
1435
|
|
|
1247
1436
|
```yaml
|
|
1248
1437
|
- id: conductor-package-a
|
|
1249
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1438
|
+
uses: vaultcompasshq/conductor@v0.6.0
|
|
1250
1439
|
with:
|
|
1251
1440
|
pr-comment: true
|
|
1252
1441
|
pr-comment-marker: 'package-a'
|
|
1253
1442
|
- id: conductor-package-b
|
|
1254
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1443
|
+
uses: vaultcompasshq/conductor@v0.6.0
|
|
1255
1444
|
with:
|
|
1256
1445
|
pr-comment: true
|
|
1257
1446
|
pr-comment-marker: 'package-b'
|