@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 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 four pull requests left open on purpose, one planted problem each.
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 third row is parity, not a catch: both jobs see a credential shape.
30
- The other three are what a scanner that only knows about vulnerabilities
31
- and secrets has no way to know.
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.5.0
170
+ conductor 0.6.0
159
171
  conductor run: 2 gate(s), 1 finding(s)
160
172
 
161
- dependencies dep-guard 0.2.1 exit 0 251ms via dep-guard on path
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.4.6 exit 1 97ms via vault-guard on path
165
- BLOCKING critical vault-guard/anthropic jest.config.mjs:27:32
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.5.0
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.5.0
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.5.0
1031
- dep-guard-version: 0.7.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.5.2
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.5.0
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.5.0
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.5.0
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.5.0
1443
+ uses: vaultcompasshq/conductor@v0.6.0
1255
1444
  with:
1256
1445
  pr-comment: true
1257
1446
  pr-comment-marker: 'package-b'