@vaultcompass/conductor 0.15.0 → 0.17.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
@@ -1,10 +1,10 @@
1
1
  # conductor
2
2
 
3
3
  conductor is the one required check for a repository an AI agent edits. It
4
- runs the scanners a maintainer already trusts, and adds the checks those
5
- scanners cannot do on their own: a hallucinated package name, a credential
6
- caught before the edit lands, a pull request that edits its own gate, a
7
- change that reaches outside what was approved for it.
4
+ runs the scanners a maintainer already trusts beside the three family
5
+ gates, which check what those scanners do not: a hallucinated package name,
6
+ a credential caught before the edit lands, a pull request that edits its
7
+ own gate, a change that reaches outside what was approved for it.
8
8
 
9
9
  It does that by running five gates over one policy file, one init, one
10
10
  hook and one report: three from this family, and two the adopter already
@@ -33,9 +33,70 @@ and osv-scanner, so both see a credential shape, a credential in history,
33
33
  and a known advisory. The other three are what a scanner that only knows
34
34
  about vulnerabilities and secrets has no way to know.
35
35
 
36
+ ## Quick start
37
+
38
+ Install the umbrella and the three gates, look at what init would write, then
39
+ write it with one pre-commit hook:
40
+
41
+ ```sh
42
+ npm install -g @vaultcompass/conductor @vaultcompass/dep-guard @vaultcompass/vault-guard @vaultcompass/intent-guard
43
+ conductor init --dry-run # prints every file it would write, writes nothing
44
+ conductor init --hook # writes .guardrails.yaml and one pre-commit hook
45
+ ```
46
+
47
+ The hook runs every enabled gate on each commit and, when the commit is
48
+ clean, prints one summary line, plus one status line per gate on stderr.
49
+ Each gate can also be installed and run on its own.
50
+
51
+ Then the same gates on every pull request, as one pinned workflow:
52
+
53
+ ```yaml
54
+ name: guardrails
55
+ on: [pull_request, push]
56
+ permissions:
57
+ contents: read
58
+ security-events: write
59
+ jobs:
60
+ gates:
61
+ runs-on: ubuntu-latest
62
+ steps:
63
+ - uses: actions/checkout@v7
64
+ with:
65
+ fetch-depth: 0
66
+ - name: Install gitleaks and osv-scanner
67
+ run: |
68
+ set -euo pipefail
69
+ bin="$RUNNER_TEMP/external-gates"
70
+ mkdir -p "$bin"
71
+ cd "$RUNNER_TEMP"
72
+ curl -sSLO https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz
73
+ echo "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb gitleaks_8.30.1_linux_x64.tar.gz" | sha256sum -c -
74
+ tar -xzf gitleaks_8.30.1_linux_x64.tar.gz -C "$bin" gitleaks
75
+ curl -sSL -o "$bin/osv-scanner" https://github.com/google/osv-scanner/releases/download/v2.6.0/osv-scanner_linux_amd64
76
+ echo "ca69b3d3cd08f889a49dc0a383122f71cc528b83803671df5fd874d97485b108 $bin/osv-scanner" | sha256sum -c -
77
+ chmod +x "$bin/osv-scanner"
78
+ echo "$bin" >> "$GITHUB_PATH"
79
+ - uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
80
+ - uses: github/codeql-action/upload-sarif@v4
81
+ if: always()
82
+ with:
83
+ sarif_file: conductor.sarif
84
+ ```
85
+
86
+ One pin, not five: the action tag decides which version of each of the four
87
+ npm packages is installed. The install step for gitleaks and osv-scanner is
88
+ needed when the policy enables the secrets-history and vulnerabilities gates,
89
+ and it pins both by version and checksum. On a pull request every gate reads
90
+ its rules from the base branch, so a change cannot turn off the check that
91
+ exists to catch it. The first pull request under a new policy cannot be judged
92
+ by that policy, so read the careful path below before you make the check
93
+ required.
94
+
95
+ ## Part of the Vault & Compass guardrails
96
+
36
97
  <!-- guardrails-family: shared block, keep it identical in dep-guard, vault-guard, intent-guard and conductor -->
37
98
  The Vault & Compass guardrails are three gates over an AI-assisted coding
38
- session: [dep-guard](https://www.npmjs.com/package/@vaultcompass/dep-guard)
99
+ session, plus an optional umbrella: [dep-guard](https://www.npmjs.com/package/@vaultcompass/dep-guard)
39
100
  checks what comes in (hallucinated package names, typosquats, tampered
40
101
  lockfile entries),
41
102
  [vault-guard](https://www.npmjs.com/package/@vaultcompass/vault-guard) checks
@@ -53,7 +114,7 @@ vulnerabilities. conductor scans nothing itself and installs nothing that
53
114
  is not its own.
54
115
  <!-- /guardrails-family -->
55
116
 
56
- ## Adopting conductor
117
+ ## Adopting conductor: the careful path
57
118
 
58
119
  The first pull request under a policy conductor just added cannot be judged
59
120
  by that policy, so plan for a short, ordered sequence rather than one
@@ -98,8 +159,9 @@ required.
98
159
  run the umbrella never looks in `node_modules/.bin` at all, because what
99
160
  is installed there is chosen by the head's own manifest and lockfile. The
100
161
  Action installs all four packages itself, globally, at versions pinned in
101
- your workflow file. See "The pull-request trust boundary" and "The
102
- Action" below.
162
+ your workflow file. See
163
+ [The pull-request trust boundary](docs/pull-request-trust-boundary.md) and
164
+ [The Action](#the-action) below.
103
165
 
104
166
  From the repository root, look before you write:
105
167
 
@@ -154,7 +216,7 @@ required.
154
216
  Commit something, now that `--hook` above has installed the pre-commit
155
217
  hook (this walkthrough's output below only appears when the hook is
156
218
  installed; a bare `conductor init` with no `--hook` runs no gate on
157
- commit at all). A clean commit prints one line:
219
+ commit at all). A clean commit prints one summary line on stdout:
158
220
 
159
221
  ```
160
222
  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.
@@ -165,18 +227,25 @@ required.
165
227
  out by `--gate`, not enforced, and suppressed findings. Which gates appear
166
228
  in each depends on your policy file.
167
229
 
230
+ Your terminal also shows one status line per gate, written to stderr so a
231
+ CI job log has a per-gate record even when the report goes to a file,
232
+ such as `conductor: gate dependencies (dep-guard 0.18.1): ok, exit 0` or
233
+ a `skipped (deferred to stage ci)` line for a deferred gate. They carry
234
+ nothing the summary does not; to see only the summary, redirect stderr
235
+ (`conductor run --staged --stage commit 2>/dev/null` in the hook).
236
+
168
237
  A commit with a staged credential in it prints the full report and exits 1:
169
238
 
170
239
  ```
171
- conductor 0.15.0
240
+ conductor 0.17.0
172
241
  verdict-token: blocked (1)
173
242
  conductor run: 2 gate(s), 1 finding(s)
174
243
 
175
- dependencies dep-guard 0.7.0 exit 0 153ms via dep-guard on path
244
+ dependencies dep-guard 0.18.1 exit 0 153ms via dep-guard on path
176
245
  threshold medium suppressed 0 ignored 0
177
- mode staged corpusBuiltAt 2026-09-20T06:16:40.340Z lockfileFormat npm online-flag not passed
246
+ mode staged corpusBuiltAt 2026-09-20T06:16:40.340Z lockfileFormat npm online false lookups 0 skipped-by-deadline 0
178
247
 
179
- secrets vault-guard 1.8.0 exit 1 105ms via vault-guard on path
248
+ secrets vault-guard 1.13.1 exit 1 105ms via vault-guard on path
180
249
  BLOCKING critical vault-guard/anthropic jest.config.mjs:14:12
181
250
  Possible secret of type 'anthropic'
182
251
  threshold medium suppressed 0 ignored not reported
@@ -187,7 +256,8 @@ required.
187
256
  verdict: exit 1, 1 blocking finding(s) in 1 of 2 enforced gate(s).
188
257
  ```
189
258
 
190
- The `mode`, `corpusBuiltAt`, `lockfileFormat` and `online-flag` line under
259
+ The `mode`, `corpusBuiltAt`, `lockfileFormat`, `online`, `lookups` and
260
+ `skipped-by-deadline` line under
191
261
  `dependencies`, and the `filesScanned`/`patternsActive` line under
192
262
  `secrets`, are each gate's own run facts, one line per gate, added to the
193
263
  full report so a reader can see what a gate actually scanned and with
@@ -212,7 +282,8 @@ required.
212
282
  gate `skipped ... no contract` and never reaches the exit code. So a
213
283
  first pull request with no contract yet is not blocked by the intent gate
214
284
  on the pull request, whatever the local preview showed a moment before.
215
- See "Intent at a pull request" below for the full mechanism.
285
+ See [Intent at a pull request](docs/intent-at-a-pull-request.md) for the
286
+ full mechanism.
216
287
 
217
288
  2. **Open the first pull request in advisory mode.** Add `.guardrails.yaml`
218
289
  and the workflow together, with `advisory: true` and `pr-comment: true`
@@ -250,7 +321,7 @@ A repository with history will not start clean, and a gate that is red on its
250
321
  first pull request gets switched off. The order that works:
251
322
 
252
323
  1. **Advisory first.** The first pull request runs with `advisory: true` and
253
- `pr-comment: true`, as in "Adopting conductor" above. Findings print and
324
+ `pr-comment: true`, as in "Adopting conductor: the careful path" above. Findings print and
254
325
  are commented, and none of them fails the run.
255
326
 
256
327
  2. **Record what is already there, in each gate's own file.** conductor does
@@ -328,1088 +399,14 @@ It does not overrule a gate. A gate that says a commit is blocked blocks
328
399
  the commit. The umbrella can add to that decision and never subtracts from
329
400
  it.
330
401
 
331
- ## The policy file
332
-
333
- `.guardrails.yaml`, at the repository root. `conductor init` writes one with
334
- every gate listed and only the ones it found switched on.
335
-
336
- ```yaml
337
- version: 1
338
-
339
- gates:
340
- dependencies:
341
- product: dep-guard
342
- enabled: true
343
- stage: commit
344
- enforce: true
345
- options:
346
- fail-on: high
347
- secrets:
348
- product: vault-guard
349
- enabled: true
350
- stage: commit
351
- enforce: true
352
- intent:
353
- product: intent-guard
354
- enabled: true
355
- stage: ci
356
- # It runs and reports in CI without failing the run. Flip it to
357
- # true once a few pull requests show the signal is worth blocking on.
358
- enforce: false
359
- options:
360
- require-frozen: false
361
- secrets-history:
362
- product: gitleaks
363
- enabled: true
364
- # Enabled because gitleaks was found on the machine that ran init. CI must
365
- # install gitleaks itself (conductor does not); without it this gate
366
- # reports conductor/gate-missing and the run exits 2.
367
- stage: ci
368
- enforce: true
369
- vulnerabilities:
370
- product: osv-scanner
371
- enabled: true
372
- # Enabled because osv-scanner was found on the machine that ran init. CI must
373
- # install osv-scanner itself (conductor does not); without it this gate
374
- # reports conductor/gate-missing and the run exits 2.
375
- stage: ci
376
- enforce: true
377
- present-on-base: report
378
-
379
- report:
380
- format: text
381
- ```
402
+ ## Reference
382
403
 
383
- **Gates are keyed by role**, not by product. `dependencies` (dep-guard),
384
- `secrets` (vault-guard), `intent` (intent-guard), `secrets-history`
385
- (gitleaks, scanning git history) and `vulnerabilities` (osv-scanner, over
386
- the resolved dependency tree). The `product` field says which binary fills
387
- that role today. The last two are external tools you install yourself.
388
-
389
- **`enabled`** defaults to true. A gate that is enabled and whose binary
390
- cannot be found is a blocking finding of the umbrella's own
391
- (`conductor/gate-missing`), never a silent skip.
392
-
393
- **`stage`** says when a gate runs: `commit`, `push`, or `ci`. Stages are
394
- **cumulative** in that order, so a gate runs at its own stage and at every
395
- later one, and a run at `ci` runs everything that is enabled. The defaults
396
- are `commit` for `dependencies` and `secrets`, and `ci` for `intent`,
397
- `secrets-history` and `vulnerabilities`: a history scan and a registry
398
- lookup are pull-request work, not commit-time work.
399
-
400
- A gate held back by the stage filter is never silent. It is one line in the
401
- text report naming the stage it is waiting for, and a `conductor/gate-deferred`
402
- notification in the SARIF log's `conductor` run. Its binary is not even looked
403
- for, so a gate installed only on the CI image does not fail a developer's
404
- commit.
405
-
406
- **`enforce`** defaults to true. A gate with `enforce: false` runs, reports,
407
- and its findings appear in the text report and the SARIF log exactly as an
408
- enforced gate's do. The only thing it cannot do is change the exit code: its
409
- blocking findings do not raise it, and its failing to run at all does not
410
- make the run exit 2. That is the adoption ramp, so a gate can be switched on
411
- and read for a few weeks before it is allowed to refuse anybody's commit.
412
- `init` writes it out for every gate. For the intent gate it writes `true`
413
- (and see `present-on-base` below for the vulnerabilities gate)
414
- when a frozen contract already exists at init time
415
- (`.intent-guard/intent-contract.yaml`, or the pre-1.3.0
416
- `.conductor/intent-contract.yaml`), since the ramp is already climbed by
417
- then, and leaving it unenforced would silently let a frozen contract's
418
- protected paths produce findings that never fail the check. It writes
419
- `false`, with a comment explaining why, when there is no contract yet to
420
- enforce against, and in that case it also writes `require-frozen: false`
421
- under `options`, since intent-guard otherwise blocks on a missing contract.
422
- The `options` comment is written per gate: gitleaks and osv-scanner have no
423
- severity floor, so their comments point at `.gitleaks.toml` and
424
- `osv-scanner.toml` rather than at `fail-on`.
425
-
426
- **`options`** is handed to that gate unchanged. Each key is one of that
427
- gate's own long flags with the leading dashes stripped: `fail-on: high`
428
- becomes `--fail-on high`, `online: true` becomes `--online`,
429
- `require-frozen: false` becomes `--no-require-frozen`, and a list becomes
430
- one flag per entry. The handful of flags the umbrella supplies itself (the
431
- JSON format flag, `--staged`, and the intent gate's `--project`) are
432
- rejected if you also set them, rather than being silently overridden. For
433
- the external gates the umbrella writes `--report-format`, `--report-path`,
434
- `--exit-code`, `--log-opts`, `--config`, `--gitleaks-ignore-path`,
435
- `--ignore-gitleaks-allow`, `--log-level`, `--redact` and `--no-banner` to
436
- gitleaks, and
437
- `--format`, `--config` and `--lockfile` to osv-scanner, so those are
438
- reserved too. Narrow what either
439
- tool reports in its own config file (`.gitleaks.toml`, `osv-scanner.toml`)
440
- instead. Two osv-scanner flags are written without being reserved: a run
441
- that scans a requirements file always gets `--no-resolve`, and a
442
- `no-resolve` key here is dropped from that run with a note; and a
443
- pull-request run gets `--no-call-analysis=all` unless this block names
444
- `call-analysis` or `no-call-analysis`, in which case that value is used.
445
- `timeout-seconds` is refused under `options` on every gate, and `timeout`
446
- on every gate but gitleaks, where it is gitleaks' own `--timeout` flag and
447
- is passed through (see `timeout-seconds` below and "What a history scan
448
- costs").
449
-
450
- **`present-on-base`** (the `vulnerabilities` gate only, beside `enforce`,
451
- never under `options`) is `block` or `report`. On a pull-request run whose
452
- osv-scanner scan blocked, the umbrella also scans the base branch copies of
453
- the lockfiles that carry findings and labels each finding `introduced` or
454
- `present-on-base`. `block` blocks on every finding; `report` reports the
455
- present-on-base ones without blocking and blocks only on what the pull
456
- request introduced. A policy without the key blocks on every finding, so no
457
- existing policy is loosened; `init` writes `report` for a new repository.
458
- On a pull request the key is read from the base branch's policy like every
459
- other key, so a pull request cannot set it for itself. A run with no base (a
460
- local run, a push) has no labels, and every finding blocks. The key on any
461
- other gate is an error, and an older conductor rejects it, so move the
462
- Action first.
463
-
464
- **`timeout-seconds`** (any gate, beside `enforce`, never under `options`)
465
- is how long conductor lets that gate run before stopping it: a whole number
466
- of seconds from 10 to 21600. The floor is there because the same limit
467
- bounds the gate's version probe, and a limit of a second or two can stop the
468
- probe of a gate that starts slowly before it ever scans. The ceiling is the
469
- six hours after which a GitHub-hosted job is cancelled; a larger limit could
470
- never fire there. Without the key each gate keeps the default for its
471
- product: 120 seconds for dep-guard, vault-guard and intent-guard, 600 for
472
- gitleaks, 300 for osv-scanner. There is no policy-wide default, for the same
473
- reason there is no shared severity threshold: the five gates differ in cost
474
- by orders of magnitude. Every spawn of the gate gets the full limit (the
475
- version probe, the scan, the intent gate's preparation steps, osv-scanner's
476
- base run on a pull request). A gate stopped at its limit could not run, with
477
- the reason `timed-out` and what to do about it, and an enforced one makes
478
- the run exit 2. On a pull request the key is read from the base branch's
479
- policy like every other key, so a pull request cannot raise, lower or
480
- remove its own limit; an invalid value on the base fails every pull request
481
- with exit 2 until the base is fixed, and an invalid value only on the head
482
- is a policy proposal there and fails the push run after merge. An older
483
- conductor rejects the key, so move the Action first.
484
-
485
- **There is no shared severity threshold, on purpose.** One top-level
486
- `failOn` would read as one decision and mean five different things, so
487
- setting one is an error rather than a knob that half works. Each gate keeps
488
- its own threshold in its own `options` block, spelled the way that gate
489
- spells it.
490
-
491
- **`command`** takes an absolute path and overrides binary resolution for
492
- that gate, for pointing at a build that is not installed anywhere. `args`
493
- beside it sets the argument prefix. conductor's history gate assumes
494
- gitleaks' `git` mode; an `args` that switches it to `dir` mode changes what
495
- gitleaks' own `--timeout` does (in `dir` mode it exits 0 after a partial
496
- scan, with no warning).
497
-
498
- **`report.format`** is `text` or `sarif`, and `--format` overrides it.
499
-
500
- ## Commands
501
-
502
- `conductor init` writes the policy file and `.guardrails/manifest.json`, the
503
- record `--revert` reads back later. The manifest currently records absolute
504
- machine paths rather than repo-relative ones (see "Adopting conductor"
505
- above); do not commit it. When git does not already ignore it, init appends
506
- `.guardrails/` to `.gitignore` (or creates one) and says so; a `.gitignore`
507
- that is a symbolic link or not a regular file is left alone and the line is
508
- printed for you to add. On a policy file that already exists, init lists the
509
- gate roles it has no entry for, with the two lines that add each. An external
510
- gate (gitleaks, osv-scanner) is written enabled only when its binary is found
511
- on the machine running init, with a comment under it that CI must install it;
512
- a CI job without it gets `conductor/gate-missing` and exit 2.
513
-
514
- - `--hook` also writes one pre-commit hook running every enabled gate whose
515
- stage is `commit`. Without it, init writes only the policy file and the
516
- manifest: no hook, and none of the hook-manager detection below runs
517
- either. `.git/hooks` is never part of a clone, so a hook one checkout has
518
- does not follow a teammate's clone, or a fresh clone of your own; each
519
- needs its own `conductor init --hook`. `--revert` still removes a hook a
520
- previous `--hook` run left behind, whether or not this invocation passes
521
- `--hook` itself.
522
- - `--dry-run` prints every file it would write or change and writes nothing.
523
- - `--revert` removes exactly what a previous init wrote, and nothing else.
524
- A file changed since init is reported and left alone. The one exception is
525
- the `.guardrails/` line init appends to `.gitignore`: `--revert` does not
526
- remove it.
527
- - `--adopt` replaces one gate's own pre-commit hook with the umbrella hook.
528
- Without it, init reports the collision and stops rather than stacking a
529
- second invocation of a gate that is already hooked. A hook the umbrella
530
- does not recognise is never replaced, with or without `--adopt`. Only
531
- meaningful together with `--hook`; without it, init errors rather than
532
- silently ignoring the flag, because there is no hook for it to act on.
533
- - `--force` acts on a file **conductor itself wrote** and that has changed
534
- since: on its own it replaces a managed hook somebody has edited, and with
535
- `--revert` it removes one, restoring an adopted hook if there was one. It
536
- never overrides a foreign-hook or gate-hook refusal, with or without
537
- `--adopt`: those hooks were never conductor's, and no flag here turns
538
- somebody else's file into one this tool may overwrite. Like `--adopt`,
539
- only meaningful together with `--hook` on an init (not on a `--revert`);
540
- without it, init errors.
541
- - `--project <dir>` writes into that repository instead of the current
542
- directory, resolved to its git top level the same way the current
543
- directory already is, so a script can point init at a repository without a
544
- `cd` compound.
545
-
546
- The rest of this section, on hook managers already wired into the
547
- repository, applies only when `--hook` is given: none of it is consulted,
548
- and none of it can block the policy file from being written, on a plain
549
- `conductor init`.
550
-
551
- Init recognises the hook manager already wired into the repository. husky is
552
- redirected to the tracked hook it maintains rather than the generated
553
- dispatcher git runs. On a fresh clone, where husky's install has not set
554
- `core.hooksPath` yet, husky is recognised from `package.json` (a `husky`
555
- dependency or devDependency, or a `prepare` script that runs husky) or a
556
- tracked `.husky/` directory, and init writes `.husky/pre-commit` and says the
557
- install still has to run, rather than writing `.git/hooks/pre-commit`, which
558
- husky's install would bypass. This applies only when `core.hooksPath` is not
559
- set at all: one set by hand, even to `.git/hooks`, is left alone. A prepare
560
- script counts only when it runs husky as a command. lefthook and the pre-commit framework are refused, with
561
- the stanza to add to their own config file. simple-git-hooks and yorkie are
562
- refused too, and recognised from the declaration as well as from the hook
563
- file, because the declaration is there on a fresh clone where the generated
564
- hook is not yet: the `simple-git-hooks` or `gitHooks` key in package.json, or
565
- any of the standalone config files simple-git-hooks reads. Their hook text
566
- lives in package.json, which conductor does not write, so the guidance names
567
- the entry to add and `--force` does not override the refusal.
568
-
569
- That refusal applies only where git actually runs `.git/hooks`. Both managers
570
- write that directory and neither reads `core.hooksPath`, so a repository that
571
- has pointed git somewhere else has taken their file out of play, and init
572
- proceeds normally without mentioning them.
573
-
574
- `conductor run` runs every enabled gate and prints one report.
575
-
576
- - `--staged` gates the git index against HEAD, which is what the hook does.
577
- - `--format text|sarif`.
578
- - `--stage commit|push|ci` runs the gates at that stopping point and every
579
- earlier one. With no `--stage` at all, every enabled gate runs, whatever
580
- its stage. An unknown value is a usage error and exits 2 rather than
581
- quietly running everything or nothing: a typo in a CI file that runs every
582
- gate and one that runs none both look like a passing build.
583
- - `--base <ref>` measures the intent gate against what this branch changed
584
- since `<ref>`, rather than against the index. See "Intent at a pull
585
- request" below.
586
- - `--trust-base <ref>` reads the **rules** from `<ref>` instead of from the
587
- tree being judged: this repository's own `.guardrails.yaml`, and every
588
- control input of the gates that support it. See "The pull-request trust
589
- boundary" below. `--base` and `--trust-base` are independent and a
590
- pull-request run passes both: `--base` decides which paths are judged,
591
- `--trust-base` decides what they are judged by. When `GITHUB_BASE_REF` is
592
- set, an explicit `--trust-base` is accepted only when it resolves to the
593
- same commit as `refs/remotes/origin/$GITHUB_BASE_REF`, or is the Action's
594
- private `refs/conductor/trust-base` (issue #58); anyone invoking the
595
- CLI directly on a pull request, rather than through the Action, gets this
596
- as its own refusal, named below.
597
- - `--spec <path>` names the spec the intent gate imports its contract from.
598
- - `--output <path>` writes the report to a file instead of to stdout, for a
599
- CI step that uploads it. One line still goes to stdout, because a job whose
600
- only product is an uploaded artifact otherwise reads as a job that did
601
- nothing. A path that cannot be written is exit 2, not a green run beside a
602
- report nobody can read. A relative value resolves against the current
603
- directory the command was invoked from, not against `--project` or the
604
- repository root: with `--project` pointing elsewhere, a relative
605
- `--output` still lands next to where you are, not next to the repository
606
- being judged.
607
- - `--text-report <path>`, with `--format sarif`, also writes the text report
608
- to that file **from the same run**: exactly what `--format text` would have
609
- rendered for this result (`--verbose`, `--compact-on-refusal` and
610
- `--advisory` respected), and no gate is run a second time. This is how the
611
- Action gets a SARIF log, a comment body and a verdict token that are one
612
- run's answer. With `--format text` it is refused as a usage error (exit 2),
613
- before any gate runs: the text report is the output already, so a second
614
- copy in a file would only duplicate it. A path that cannot be written is
615
- exit 2, like `--output`. See "The verdict token" below.
616
- - `--verbose` prints the full per-gate report even when the run is clean.
617
- Text output only; the SARIF log never changes shape with it. Without it a
618
- gate prints its first 20 findings, blocking first, and one line saying how
619
- many more there are; every count, the verdict and SARIF include all of
620
- them. `--verbose` also lists the lockfiles behind an osv-scanner line
621
- that groups one advisory across several ("lodash@4.17.20 2 lockfiles
622
- fix 4.17.21"). A gitleaks finding shows its short commit and the
623
- fingerprint `.gitleaksignore` takes.
624
- - `--compact-on-refusal` shrinks the report to the version, the verdict and
625
- the refusal reason when the trust base was refused and no gate ran,
626
- instead of the full per-gate report. Built for the pull-request-comment
627
- step. It has no effect on a run that was not refused, whatever `--verbose`
628
- says. Text output only; it has no effect on the SARIF log and never
629
- changes the exit code.
630
- - `--gate <role>`, repeatable. A gate the policy file enables and this flag
631
- leaves out is named as excluded, on one line in the text report and as a
632
- `conductor/gate-excluded` notification in the SARIF log's `conductor` run.
633
- It never reaches the exit code.
634
- - `--advisory` maps exit 1 to exit 0: a run whose only failure is a blocking
635
- finding no longer fails. A gate that could not run is unaffected and still
636
- exits 2, so a crashed install or a missing policy still shows red rather
637
- than a silent green: this flag changes what a **finding** does, never what
638
- a **broken gate** does. The report is unchanged, a blocking finding still
639
- prints with its `BLOCKING` marker, and only the process exit and the
640
- verdict line's own wording (it says findings were advisory and did not
641
- block) change. Text output only; the SARIF log has no verdict line to
642
- change and its `properties.blocking` on each result is unaffected.
643
- - `--project <dir>` runs against that repository instead of the current
644
- directory, resolved to its git top level the same way the current
645
- directory already is, so a subdirectory resolves to that repository's top
646
- level. A relative value resolves against the current directory. A path
647
- that does not exist, is not a directory, or is not inside a git repository
648
- is a usage error naming the path and exits 2 rather than falling back to
649
- the current directory.
650
-
651
- ### Exit codes
652
-
653
- - **0** every enabled gate ran and none blocked.
654
- - **1** every enabled gate ran and at least one blocked.
655
- - **2** an enabled gate could not run: its binary is missing, it exited with
656
- its own could-not-run code, it exited 1 with nothing parseable on
657
- stdout, which is what a rejected config file looks like from two of the
658
- three family gates, or conductor stopped it at its time limit
659
- (`timed-out`, see `timeout-seconds` in the policy file).
660
-
661
- The external gates' exits are read per tool. gitleaks exits 1 for an error
662
- as well as for a leak, so the umbrella hands it `--exit-code 3`: 3 is a leak
663
- (blocked), 1 is could-not-run. gitleaks also exits 0 with an empty report
664
- when git itself fails (a base ref the checkout never fetched), so a clean
665
- exit that logged an `ERR` line is could-not-run too, never a pass. A
666
- gitleaks exit with no report file behind it is could-not-run. osv-scanner is
667
- handed every tracked lockfile by name, at any depth, never under
668
- `node_modules`: `package-lock.json`, `npm-shrinkwrap.json`,
669
- `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, `go.mod`, `poetry.lock`,
670
- `Pipfile.lock`, `uv.lock`, `pdm.lock`, `Cargo.lock`, `Gemfile.lock`,
671
- `composer.lock`, `gradle.lockfile`, `packages.lock.json`, `mix.lock`,
672
- `pubspec.lock`, `Package.resolved`, `conan.lock`, `renv.lock`,
673
- `packages.config`, `buildscript-gradle.lockfile`, `gems.locked`,
674
- `pylock.toml`, `cabal.project.freeze`, `stack.yaml.lock` and
675
- `verification-metadata.xml` inside a `gradle` directory, and pip
676
- requirements files (`requirements.txt`, `requirements-dev.txt`,
677
- `requirements_test.txt`, `requirements.prod.txt`, `dev-requirements.txt`)
678
- whose every requirement, includes followed, is pinned with `==`. `go.sum`
679
- is never handed over: osv-scanner reads `go.mod` for Go. A requirements
680
- file with an unpinned line, or an include that is missing, untracked or
681
- outside the repository, is not scanned and is named in a
682
- `conductor/requirements-not-scanned` note with the line that stopped it,
683
- because any version osv-scanner reported for it would be a guess.
684
- Requirements files are scanned with `--no-resolve`: direct requirements
685
- only, as written, and the report says so per file. On a pull request a
686
- requirements file that is pinned on the base stays scanned even when the
687
- pull request adds an unpinned line to it. When the repository tracks none
688
- of these, osv-scanner is not spawned at all and the gate is reported clean
689
- with a `conductor/nothing-to-scan` note, so a docs-only repository is not
690
- red on every pull request. The note says that nothing was scanned and names
691
- the tracked manifests that were not handed to osv-scanner (a
692
- `pyproject.toml`, a `go.sum`, a `Dockerfile`, a workflow, or a requirements
693
- file the pin check left out), so a green gate is not read as a scan of
694
- them. A `go.mod` or a pinned requirements file is handed over and so is
695
- never on that list. It says nothing about what other gates read. When
696
- other lockfiles WERE handed over, the same list (a `Podfile.lock` beside a
697
- scanned `mix.lock`, say) is printed as a `conductor/manifests-not-handed`
698
- note under the gate instead. Its 1 is
699
- blocked. Its own 128 ("no package sources found") on lockfiles it WAS
700
- handed means they parsed to no packages; that is clean too, with a distinct
701
- `conductor/lockfiles-empty` note naming the files. When some handed
702
- lockfiles had packages and one had none (a lockfile rewritten to `{}` beside
703
- others), the same note names the empty one and the `lockfiles` line marks it
704
- `[no packages read]`; the verdict over the other files is unchanged. That
705
- naming reads osv-scanner's own per-file count, which it prints at its
706
- default verbosity. Lockfiles inside git
707
- submodules are never listed. In a sparse
708
- checkout a tracked lockfile that is not on disk is still handed over and
709
- osv-scanner exits 127 on it, a false could-not-run that fails closed. Any other osv-scanner exit
710
- (127 is its error code) is could-not-run. A gitleaks older than 8.19 or an
711
- osv-scanner older than 2.0 is could-not-run, naming the floor.
712
-
713
- `run --advisory` maps exit 1 to exit 0. It never touches exit 2: a gate that
714
- could not run is a different failure from a blocking finding, and advisory
715
- mode exists to leave that one alone. See "Running the gates as an advisory
716
- check" below.
717
-
718
- ### The verdict token
719
-
720
- The text report carries one more line: `verdict-token: <token>`, the **second
721
- line**, directly under the version line (the closing `verdict:` sentence is
722
- unchanged). It is a label for the umbrella's own exit decision, in a closed
723
- set, so a person or a script can read the state without parsing a sentence.
724
- It decides nothing and never overrules a gate: it is derived from the exit
725
- code and the `enforce` flags the run already had.
726
-
727
- - `pass`: exit 0, and no gate, enforced or not, has a blocking finding or
728
- could not run. Under `present-on-base: report` a `pass` can carry known
729
- vulnerabilities already on the base branch, reported and not blocking;
730
- the report's third line then says `present-on-base: N reported, not
731
- blocking`, the verdict sentence says the same, and the Action copies that
732
- line to the job summary under the token. When the intent gate's spec was
733
- chosen weakly, differently than before 0.11.0, or not at all because of a
734
- tie or a branch 0.10.0 bound, the line after the token (after the
735
- present-on-base line, when there is one) is one of four fixed
736
- `intent-spec:` lines naming no branch or file, and the Action copies that
737
- one too.
738
- - `nothing-checked`: exit 0, but nothing was checked. Either no gate ran at
739
- all (none is enabled, or every enabled one was deferred to a later stage,
740
- had nothing to judge, or was skipped), or every gate that ran examined
741
- nothing: the vulnerabilities gate with no lockfile it reads, or the intent
742
- gate with no contract to check against. The second case was `pass` in
743
- 0.8.x. The exit status is unchanged, since nothing failed, but this is not
744
- a pass: nothing was verified. In the Action the `verdict` output carries
745
- this token, so a workflow can tell it apart from `pass`.
746
- - `advisory-blocked (N)`: the run would have exited 1, and `--advisory` made
747
- it exit 0. N is the blocking findings on enforced gates.
748
- - `unenforced-findings (N)`: exit 0, but a gate with `enforce: false` had
749
- blocking findings or could not run. N counts those findings plus those
750
- gates. Exit 0 here is not a pass, and the token says so.
751
- - `blocked (N)`: exit 1. N as for `advisory-blocked`.
752
- - `could-not-run`: exit 2, a refused trust base included.
753
-
754
- When several apply the order is `could-not-run`, then `blocked` or
755
- `advisory-blocked`, then `unenforced-findings`, then `nothing-checked` (no gate
756
- ran, or none that ran checked anything) or `pass`. A run with
757
- `--advisory` whose only blocking findings sit on an unenforced gate is
758
- `unenforced-findings`, not `advisory-blocked`, because the flag did nothing
759
- there. A gate skipped for want of a contract does not by itself move the token
760
- off `pass` when another gate ran and checked something; when no gate ran, or
761
- every gate that ran checked nothing, the token is `nothing-checked` and the
762
- verdict sentence says "nothing was checked". A
763
- gate that exited non-zero with no finding marked blocking counts as one in N,
764
- so a state that is not a pass never prints a count of zero. The one-line
765
- summary of a clean, non-verbose run has no token line, since it is one line by
766
- design. `conductor run` also prints the token on its job-log line,
767
- `conductor run: 4 gate(s), 1 finding(s); verdict-token advisory-blocked (1); sarif report written to conductor.sarif`.
768
-
769
- ## The pull-request trust boundary
770
-
771
- Every gate reads its own rules out of the repository it is judging. On a pull
772
- request the author controls that repository, so without this a pull request
773
- could turn a gate off in the same commit that carries the thing the gate
774
- exists to catch, and the report would say the run was clean. For the umbrella
775
- the sharpest version is `command:`, which names a program to run: a pull
776
- request could point a gate at a script it added in the same commit.
777
-
778
- **On a pull-request run the rules come from the base branch.** With
779
- `--trust-base <ref>` the umbrella reads `.guardrails.yaml` from that ref with
780
- git and judges the head tree against it. A trusted file at the base that git
781
- cannot read as a regular file (a symlink, a directory, a submodule, or a file
782
- below a symlinked or submodule directory) is could-not-run, never replaced by
783
- a default. Clear it by making the file a regular file on the base branch; the
784
- pull request that does so is judged against that same base, so it has to be
785
- merged by someone allowed to merge without this check passing. A `.guardrails.yaml` in the
786
- pull request never takes effect for that run, `command:` and `args:`
787
- included, so **a pull request cannot change the rules it is judged by, and
788
- cannot choose the program that judges it, as long as that program is
789
- self-contained** (see the directory rule below). "The program" includes a
790
- script handed to an interpreter: with `command: /usr/bin/node` and
791
- `args: [tools/gate/run.mjs]`, the script is what judges, and it is vetted
792
- exactly as a `command:` inside the tree would be. The same ref is passed
793
- down to every gate that supports it, so their contracts, configs and
794
- baselines come from the base branch too.
795
-
796
- **The program is checked as well as the rules.** Reading the rules from the
797
- base ref is worth nothing if the pull request supplies the binary that
798
- applies them, and without this it could, two ways that both look ordinary in
799
- a diff: a base `command:` pointing at a path inside the repository, where the
800
- head replaces the file behind the approved path; and no `command:` at all,
801
- where a head-committed `node_modules/.bin/<gate>` shadows the real gate,
802
- because resolution prefers the repository's own copy over PATH so that a
803
- project pin beats a global install.
804
-
805
- **On a pull-request run `node_modules/.bin` is not consulted at all.** That
806
- second shape is closed one step earlier than the first, and this is why: what
807
- is installed there is chosen by the head's own manifest and lockfile, so it is
808
- never approved by any ref, and a repository whose gates are devDependencies
809
- would otherwise meet the program refusal on every ordinary pull request. So
810
- that location is simply not searched when a trust base is set. PATH and an
811
- absolute `command:` remain, and both still go through the program check below.
812
- The skip is never silent: one line in the full report and one
813
- `conductor/node-modules-skipped` note in the SARIF log name each gate and the
814
- copy that was not taken, and a gate with nothing on PATH either is
815
- could-not-run with `npm install -g` and the Action's version input named as
816
- the remedy. **Outside pull-request mode nothing changes**: your own checkout
817
- and your pre-commit hook still run the pin, which is what `pnpm exec` does in
818
- the same repository.
819
-
820
- **The versions that judge a pull request are pinned in the workflow file**,
821
- and that is the point: the pull request can change its own lockfile,
822
- manifest and `node_modules`, and none of those decide which conductor and
823
- which gates run over it any more. Be clear about what that does not cover.
824
- On a `pull_request` event GitHub runs the workflow as it is in the pull
825
- request's merge commit, so a pull request that edits the workflow file can
826
- change the pins or remove the gates step, exactly as it could rewrite any
827
- other step in your CI. The boundary here is against the tree choosing its
828
- own judge; the control for a workflow edit is branch protection on your
829
- base branch with review required for `.github/workflows`, and no action can
830
- provide that for you. Only `pull_request_target` runs the base branch's copy
831
- of a workflow, and that event exposes the base's secrets to the pull
832
- request's code, which is the wrong trade for a gate over untrusted changes.
833
-
834
- One part of that is closed, and only one. Because the pins are written in a
835
- file the pull request controls, a pull request could otherwise pin a gate
836
- **backward** to a published version that predates the rule which would have
837
- caught it: an exact version, so the validate step's shape check accepts it,
838
- and a change that reads as ordinary version management. **On a pull request
839
- the action now refuses any of the four `*-version` inputs naming a version
840
- below the one the action tag ships.** Pinning forward is still accepted.
841
- See "The Action" below.
842
-
843
- So on a pull-request run a gate's program must be **outside the working tree**
844
- (on PATH, or an absolute `command:` elsewhere on the machine), or else meet
845
- **both** of these:
846
-
847
- - it is a **tracked regular file whose contents are identical** at the base
848
- ref and at the head commit; and
849
- - **the tree object id of its containing directory is identical** at those
850
- two refs, which is to say the pull request changed nothing anywhere in that
851
- directory's subtree.
852
-
853
- Both are compared with `git ls-tree` on both refs and never read from the
854
- working tree. The second is not belt and braces. A vendored gate is rarely
855
- one file: `vendor/vault-guard` execs `vendor/impl.sh`, and a pull request
856
- that leaves the wrapper byte for byte alone and rewrites the helper beside it
857
- passes a per-file check while running its own code. Comparing the directory
858
- covers every file under it at once, without this tool having to know what a
859
- wrapper calls.
860
-
861
- **What is and is not vetted**, exactly: the program file and everything in
862
- its directory subtree. Anything the program reaches **outside** that
863
- directory is not vetted at all, so an in-repo gate must be **self-contained
864
- within its own directory**. A program at the repository ROOT is refused, and
865
- the message says to give it a directory: at the root the containing directory
866
- is the whole repository, so the rule would mean "no pull request may change
867
- anything".
868
-
869
- **In-tree script arguments are vetted too.** Since 0.15.0 every entry of a
870
- gate's `args:` that names something inside the working tree goes through the
871
- same rule as the program, because an interpreter `command:` (Node, Python, a
872
- shell) takes the program it runs as an argument. Before that, a base policy
873
- of `command: /usr/bin/node` with `args: [tools/gate/run.mjs, scan]` let a
874
- pull request rewrite `tools/gate/run.mjs` and report itself clean. Exactly
875
- what counts:
876
-
877
- - An entry is resolved against the repository root. Everything an
878
- interpreter could load for it is vetted: the entry as written, and every
879
- `<entry>.js`, `.mjs`, `.cjs`, `.json` or `.node` beside it, with or
880
- without a slash. Node loads `tools/gate.js` before the directory
881
- `tools/gate/`, and runs `run.js` for a bare `run`, so a sibling file the
882
- pull request adds is refused because the base does not have it.
883
- - A file (or a symbolic link) must meet the two conditions above; a
884
- directory must have the same tree object id at the base and the head; the
885
- repository root itself (`.`) is refused, since conductor already hands
886
- each gate the repository it scans. A directory's `package.json` `main`
887
- that points outside the directory is not vetted.
888
- - `--name=value` is read for the value, so `--config=tools/gate/rules.json`
889
- and `--import=./tools/gate/hook.mjs` are vetted. An option with no `=` and
890
- a word that names nothing on disk are not paths and are never refused.
891
- - The gate's own subcommand words (`scan`, `git`, `source`, `check`) are not
892
- read as paths only when `command:` is the gate itself (its file name is
893
- the gate's name, such as a vendored `vault-guard`). For an interpreter
894
- they are paths like any other word: `node scan` runs `scan/index.js`.
895
- A renamed gate binary, or any wrapper whose name is not a gate name, is
896
- treated as an interpreter, so its `scan` or `source` is vetted if a file
897
- or directory of that name exists, and a pull request touching it is
898
- refused.
899
- - Not recognised as a path, and **not** vetted: a Python `-m` module name, a
900
- bare package name an interpreter resolves for itself, code passed as a
901
- string (`node -e`, `bash -c`), and a package runner such as `npx`, which
902
- resolves the gate from the head's own `node_modules`. Name the script by
903
- its path, and do not run a gate through a package runner on pull requests.
904
- - The sibling extensions tried are Node's (`.js`, `.mjs`, `.cjs`, `.json`,
905
- `.node`). A TypeScript runner such as `tsx`, `ts-node` or `bun` also
906
- resolves `.ts`, `.mts` and `.cts`, which are not tried, so name a
907
- TypeScript script with its extension (`tools/gate/run.ts`, not
908
- `tools/gate/run`).
909
- - A script outside the working tree is accepted, as a program there is.
910
-
911
- The version probe asks the script, not the interpreter: the args up to the
912
- first non-option entry, when that entry names something loadable, then
913
- `--version`, so `node tools/gate/run.mjs scan` is asked `node
914
- tools/gate/run.mjs --version` and `node tools/gate` is asked `node
915
- tools/gate --version`. The version conductor reports and checks against an
916
- expected-version pin is then the gate's own. When the first non-option
917
- entry names nothing loadable, or the command is the gate itself, the probe
918
- is the command's own. One shape still reports the interpreter's version: a
919
- flag that takes a file as its own entry before the script (`node -r
920
- ./setup.js tools/gate/run.mjs`) makes `./setup.js` the first entry, so the
921
- probe is `node -r ./setup.js --version`; under an expected-version pin that
922
- gate is could-not-run. Write `--require=./setup.js` instead.
923
-
924
- A symlink inside the repository is refused on **its own entry**, before its
925
- target is considered: it is either untracked, or its tree entry is a link
926
- rather than a regular file, and either refuses. (A symlink whose own path is
927
- outside the tree but which points into it has its target vetted; that is the
928
- case following the link exists for.)
929
-
930
- Anything else is could-not-run for that gate, naming the path, and it reaches
931
- the exit code even where the policy sets `enforce: false`, because the gate
932
- produced no findings to un-enforce: the umbrella declined to run a program
933
- the pull request chose.
934
-
935
- Nothing under `node_modules` is ever base-approved, which is why the rule
936
- above does not look there at all. Were it to look, the answer would always be
937
- the same refusal: what is there is chosen by the head's own manifest and
938
- lockfile and installed by a step that runs before the gates, so git has no
939
- record of those bytes at either ref. A pull request that edits its lockfile to
940
- pull a different build of a gate has chosen its own judge just as surely as
941
- one that commits a stub. **Vendoring a gate still works**, on those
942
- terms: put it in its own directory, keep everything it needs inside that
943
- directory, and leave the whole directory alone in a pull request the gate is
944
- meant to judge. Changing it is not forbidden, it just has to land on the base
945
- branch first, like any other rule change.
946
-
947
- **A change to the rules is not refused, it is proposed.** Rules legitimately
948
- change, and a gate that blocked every such pull request would train people to
949
- bypass it. So a policy file that differs from the base ref's is reported as
950
- one line per changed key, `policy: gates.<role>.<key> <old> -> <new>`, counted
951
- as one proposal each; a head `.guardrails.yaml` that is absent or does not
952
- parse gives one line saying its changes are not known, and when no effective
953
- key differs (a default spelled out, or the YAML reordered) the old single line,
954
- `policy changed in this pull request`, is kept. The run continues under the
955
- base ref's rules, and the change takes effect **after merge**, on the first
956
- run whose base branch carries it. The gates' own proposals are summed with it
957
- into one sentence, `N control change(s) proposed in this pull request`, on the
958
- one-line summary and on the verdict, with a line each under `--verbose` and a
959
- `conductor/control-change-proposed` notification each in the SARIF log. A
960
- reflow, a re-quote or an edited comment is not a proposal: the two files are
961
- compared as parsed documents.
962
-
963
- **An explicit `--trust-base` redirect gets a refusal on a pull request, at two
964
- places (issue #58), and neither closes the whole hole by itself.**
965
- `refuseTrustBaseRef` above only refuses a ref that resolves to HEAD's own
966
- commit or to HEAD's own tree, which covers HEAD itself and an *unmoved*
967
- `origin/<pr-branch>`. Once the base branch has moved, `origin/<pr-branch>` no
968
- longer matches either test, so a same-repo pull request could set
969
- `trust-base` to its own branch, in its own workflow file, and have conductor
970
- read `.guardrails.yaml` from the pull request after all, at which point the
971
- pull request controls the whole policy. dep-guard's own base input took the
972
- stronger line for its base input in 0.8.0: on a `pull_request` event an
973
- explicit value is refused outright.
974
-
975
- **The Action refuses an explicit redirect on `pull_request` and
976
- `pull_request_target` events.** Its validate step refuses a `trust-base`
977
- input outright on those events, naming the value given and the fix, which is
978
- to remove the input; see "The Action" below.
979
-
980
- **The CLI check catches a misconfigured or innocent-looking redirect when
981
- `GITHUB_BASE_REF` is set**, for anyone invoking the CLI directly in CI. When
982
- that variable is set, an explicit `--trust-base` is accepted only when it is
983
- `refs/conductor/trust-base`, the private ref the Action fetches the base
984
- branch into and always passes (that ref is the authority and is not compared
985
- with anything), or resolves to the same commit as
986
- `refs/remotes/origin/$GITHUB_BASE_REF`. So an ordinary pull-request run is
987
- unaffected. A ref naming the pull request's own branch, or anything else that
988
- disagrees, is refused with both refs and both commits named, through the same
989
- could-not-run path as every other trust-base refusal: exit 2, the report
990
- leads with the reason, and nothing is checked. A short name that matches both
991
- a tag and a branch or remote-tracking ref (a tag named `origin/main`) is
992
- refused as ambiguous: spell the ref in full. When neither resolves, this fails
993
- closed too, naming it, for the same reason the fetch-depth remedy below
994
- exists.
995
-
996
- **Neither layer closes anything against a pull request that edits its own
997
- workflow file.** A CLI invocation on a pull request can simply omit
998
- `--trust-base`, or a workflow step can blank `GITHUB_BASE_REF` in its own env,
999
- and nothing here refuses either; the Action has the matching gap, since a
1000
- pull request can pin `uses:` to a tag published before this fix, in its own
1001
- workflow file. This is exactly the boundary "On a pull request those four
1002
- inputs may not pin backward" (below, under "The Action") already draws for
1003
- the four `*-version` inputs: the control for a workflow edit is branch
1004
- protection on the base branch with review required for `.github/workflows`,
1005
- and nothing in this section, or in that one, substitutes for it.
1006
-
1007
- **It fails closed.** A `--trust-base` that does not resolve is not a reason to
1008
- fall back to the pull request's own file, because that fallback is the hole:
1009
- the run exits 2 and the report **leads with the refusal**, naming the ref and
1010
- the remedy, whether or not it can name any gate. That last part matters: with
1011
- no base ref there is no base policy, so the only list of gates available is
1012
- the head's, and a head that switches every gate off leaves it empty. So is a
1013
- base ref that resolves to the head commit, or to a different commit carrying
1014
- the head's tree, both of which would put the rules back inside the tree being
1015
- judged while still reporting pull-request mode as on. Pass the base
1016
- **branch**, never a SHA: on a `pull_request` event `github.sha` is the merge
1017
- commit, which is HEAD. If the base branch has no `.guardrails.yaml` at all,
1018
- the run has no rules and exits 2 rather than using the pull request's; the
1019
- file the pull request adds decides what runs once it is on the base branch.
1020
-
1021
- **One narrow exception to the equal-tree refusal (issue #69).** When a pull
1022
- request's net diff is empty -- a value committed and then backed out inside
1023
- the same pull request -- the merge ref GitHub builds has a tree
1024
- byte-identical to the base's, and the refusal above would stop
1025
- secrets-history from running on exactly the shape it exists to catch: the
1026
- value is gone from the tree but still in the history between the base and
1027
- HEAD. So the refusal makes one exception, and only one: when HEAD is a real
1028
- merge commit (two or more parents) and `--trust-base` resolves to HEAD's
1029
- **first** parent, the run is not refused. First-parent identity is the
1030
- discriminator, not ancestry, because GitHub always builds the merge ref with
1031
- the base branch as the first parent and the pull request's own head as the
1032
- second: a trust base resolving to HEAD's **second** parent is also an
1033
- ancestor and also carries the same tree, and it is exactly the ref this rule
1034
- must keep refusing. In the accepted shape the umbrella still does not judge
1035
- the unchanged tree as if it were the change: it runs every enabled gate
1036
- whose input is git history rather than the tree -- gitleaks today -- with its
1037
- ordinary arguments (already scoped to `<base>..HEAD`), and every other
1038
- enabled gate is reported as tree-unchanged rather than spawned: one line in
1039
- the full report, a clause on the one-line summary, and a
1040
- `conductor/tree-unchanged` notification in the SARIF log, never reaching the
1041
- exit code. Every other equal-tree shape -- a non-merge HEAD, the second
1042
- parent, any other ancestor -- keeps refusing exactly as before.
1043
-
1044
- The exception needs HEAD's own parents, so it needs the same non-shallow
1045
- checkout the rest of pull-request mode already requires: `fetch-depth: 0`
1046
- (see below). On a depth-1 checkout git reports the merge commit with no
1047
- parents at all, so the first-parent check cannot match and the run keeps
1048
- refusing with the ordinary equal-tree message -- it fails closed rather than
1049
- guessing. That loss costs nothing real: at depth 1 gitleaks could not have
1050
- seen the backed-out commit either, since its own history scan has nothing
1051
- before HEAD to scope `<base>..HEAD` against.
1052
-
1053
- That is why adopting conductor takes one merge before the gates can judge
1054
- anything, and it is not an oversight: the policy file can name a program to
1055
- run, so a run that read it from the pull request would let the pull request
1056
- choose its own judge on exactly the repositories that have no rules yet. See
1057
- "Adopting conductor" below for the sequence and for how to see what your
1058
- policy will do before you merge it.
1059
-
1060
- **Which gates are covered.** All five: dep-guard from **0.10.1**,
1061
- intent-guard from **1.8.1**, vault-guard from **1.9.1**, and the two
1062
- external gates at their command-line floors, gitleaks **8.19.0** and
1063
- osv-scanner **2.0.0**. On a pull-request run an older family gate is
1064
- could-not-run rather than run outside pull-request mode.
1065
-
1066
- **The external gates get their pull-request mode from the umbrella.**
1067
- Neither tool has a `--trust-base`, and both auto-load a config from the tree
1068
- they scan, which on a pull request is the head: a pull request could add an
1069
- allowlist entry for exactly the secret or advisory it introduces. So on a
1070
- pull-request run the umbrella reads `.gitleaks.toml` and `osv-scanner.toml`
1071
- from the base ref with `git show` and passes each tool that copy with
1072
- `--config`. When the base has none, the tool gets a neutral one (gitleaks'
1073
- built-in rules, an empty osv-scanner config) rather than nothing, because
1074
- nothing would let it find the head's file on its own. gitleaks'
1075
- `.gitleaksignore` is handled the same way, and because gitleaks also loads
1076
- the ignore file at the root of whatever it scans, the umbrella scans the
1077
- repository's git directory instead of the working tree on a pull request:
1078
- the same history, without the head's ignore file. A head-side change to any
1079
- of these files is reported as a proposal line and takes effect after merge,
1080
- exactly like a change to `.guardrails.yaml`. History is scoped to
1081
- `<base>..HEAD` on a pull request and to `HEAD` locally, so a secret on
1082
- another branch never reddens this one. Merge commits are scanned by their
1083
- first-parent diff, so a secret added inside a merge (while resolving a
1084
- conflict, say) is found; the same leak seen in a pull request's commit and
1085
- again in its merge is reported once, with the other commit listed.
1086
-
1087
- A base `.gitleaks.toml` can name another file with `[extend] path`, which
1088
- gitleaks resolves against its working directory. On a pull request
1089
- conductor copies every file in that chain from the base ref into a
1090
- directory of its own and runs gitleaks from there, so the head's copy of an
1091
- extended file is never read; a head-side edit to one is a proposal, and an
1092
- extended file the base does not have makes the gate could-not-run, naming
1093
- it. gitleaks' log level is pinned at `info` and `log-level` is reserved,
1094
- because conductor reads gitleaks' error lines to tell a failed scan from a
1095
- clean one. Write the extend as a plain relative path in an `[extend]` table:
1096
- a base `.gitleaks.toml` whose extend target is a symbolic link, or which
1097
- writes the extend as an inline table or a quoted key, fails closed on every
1098
- pull request until it is rewritten that way.
1099
-
1100
- **Local runs and `.gitattributes`.** On a pull request gitleaks scans the
1101
- repository's git directory, where the head's `.gitattributes` is not read.
1102
- A local run scans the working tree, so a file your own `.gitattributes`
1103
- marks `binary` is skipped by gitleaks there. Pull requests are not affected.
1104
-
1105
- On a pull request gitleaks is also passed `--ignore-gitleaks-allow`, so an
1106
- inline `gitleaks:allow` comment does not hide a secret: an inline allow
1107
- lives in the tree being judged, so the pull request controls it. A
1108
- legitimate allow belongs in the base branch's `.gitleaks.toml` allowlist or
1109
- `.gitleaksignore`, both of which conductor already reads from the base.
1110
- Local runs keep inline allows.
1111
-
1112
- osv-scanner is never pointed at a directory to walk, because its own walk
1113
- skips anything `.gitignore` matches, tracked or not, so one ignore line in a
1114
- pull request could hide a committed lockfile. conductor lists the tracked
1115
- lockfiles with `git ls-files` and hands each one over with `--lockfile`. On
1116
- a pull request that list comes from the head's index, not the base ref: the
1117
- lockfiles are the tree being judged, and adding or removing one is visible
1118
- in the diff. Only the root `osv-scanner.toml` is read from the base and
1119
- passed with `--config`, which overrides any nested one for the run; a
1120
- nested one the pull request adds or edits is reported as a proposal.
1121
-
1122
- The umbrella asks each gate its version before it runs it. On a run with a
1123
- trust base, a gate older than its pull-request-mode minimum (intent-guard
1124
- 1.8.1, vault-guard 1.9.1, dep-guard 0.10.1) is could-not-run (exit 2),
1125
- never run without the flag: without it the gate would take its rules from
1126
- the tree being judged. The fix is to install that minimum or newer, or to
1127
- remove an explicit older version pin. A version that cannot be read at all
1128
- is could-not-run too: the umbrella cannot establish that the gate would
1129
- take its rules from the base ref. The one gate that runs without the flag
1130
- is an intent gate judging a contract imported from the base for the run,
1131
- whose project is a temporary directory with no repository to resolve a ref
1132
- in; that is never silent: it gets a line in the report, a clause on the
1133
- clean one-line summary, and a `conductor/trust-base-not-passed`
1134
- notification in the SARIF log.
1135
-
1136
- Outside pull-request mode nothing changes. A pre-commit hook and a direct run
1137
- on your own checkout are already inside the trust boundary, and neither passes
1138
- the flag.
1139
-
1140
- **In CI, pull-request mode needs a trust base.** A run in GitHub Actions with
1141
- `GITHUB_BASE_REF` set and no `--trust-base` is could-not-run (exit 2): its
1142
- rules have to come from the base branch, and no base was named. Pass `--trust-base
1143
- refs/remotes/origin/<base branch>` with `fetch-depth: 0`, or use the Action,
1144
- which always passes one. A pre-commit hook run inside a pull-request job hits
1145
- this too: skip the hook in CI, or pass the trust base to it.
1146
-
1147
- **On a pull-request run PATH holds only absolute entries, and conductor's own
1148
- git comes from outside the repository.** Empty and relative entries are
1149
- removed for conductor and every gate it starts, with one notice naming them,
1150
- and conductor runs the first git on PATH that lives outside the repository's
1151
- work tree; with none, the run is could-not-run and says to put git's own
1152
- directory on PATH. A gate found only through a removed entry is reported
1153
- missing; put it on an absolute PATH entry or name it with an absolute
1154
- `command:`. Every gate conductor starts, and everything a gate starts, gets
1155
- a PATH whose first entry is a private directory outside the repository
1156
- holding only that same git, so a gate that runs git by name runs it too; on
1157
- Windows no such directory is made and the gates look git up through the
1158
- cleaned PATH, and a system temp directory inside the repository is
1159
- could-not-run until TMPDIR names one outside it.
1160
-
1161
- **git 2.31 or later** is needed on a pull-request run with the secrets-history
1162
- gate (gitleaks) enabled, because conductor hands it `git log --diff-merges`,
1163
- which arrived in git 2.31. Only that gate checks: an older git makes it
1164
- could-not-run, naming the version, and the other gates run.
1165
-
1166
- ### Trying pull-request mode locally
1167
-
1168
- To see roughly what CI would say about a branch, check it out and name the
1169
- base as the trust base:
1170
-
1171
- ```
1172
- conductor run --trust-base refs/remotes/origin/main --verbose
1173
- ```
1174
-
1175
- `--trust-base` takes any ref git resolves in your clone, so use a clone with
1176
- the base branch present (the CI recipes use `fetch-depth: 0` for the same
1177
- reason). With no `GITHUB_BASE_REF` set, as on a laptop, the change set for the
1178
- intent gate is measured from the trust base, so `--base` is optional; add
1179
- `--base <ref>` to measure from a different ref. Add `--stage ci` to run at
1180
- the stage the Action runs at.
1181
-
1182
- The gotcha is the same locally as in CI: the policy and the other control
1183
- files are read from the base ref, not from your working tree. A local edit to
1184
- `.guardrails.yaml` has no effect on a `--trust-base` run until the change is
1185
- on the base; it shows up as a proposal line in the report instead. To preview
1186
- a policy edit, run `conductor run` without `--trust-base`, as in "Adopting
1187
- conductor" above.
1188
-
1189
- Where the proposals appear under the Action: the job log gets a
1190
- `conductor: N control change(s) proposed in this pull request.` line followed
1191
- by one `conductor: proposed <product> <line>` line per proposal, and the step
1192
- summary gets the same count and up to 50 proposed lines under `control
1193
- changes:` in a text block, with a `(n more in the report)` line when there are
1194
- more. This does not depend on `pr-comment`. A proposed line that holds a
1195
- backtick or a character outside printable ASCII is replaced by a placeholder.
1196
-
1197
- ### The preview under the proposed rules
1198
-
1199
- A pull request that switches a gate on or off, or moves its `stage`, is judged
1200
- under the base's rules, so the author would not otherwise see what the
1201
- proposed rules say until after merge. With the preview, each role whose
1202
- `enabled` or `stage` changed runs once more (a role the head switches off is skipped), after the verdict, under the base
1203
- policy with only `enabled`, `stage` and `enforce` taken from the head. Every
1204
- other head value, `command:`, `args:`, `options` and `timeout-seconds`
1205
- included, never reaches it: the base's command and the base's limit are what
1206
- run, and a base `command:` that resolves inside the working tree is refused
1207
- there, as is a base `args:` entry that names a path inside it (an
1208
- interpreter's script). A gate's own config is another matter: in the preview, dep-guard and
1209
- vault-guard read their own `.dep-guard.json` and `.vault-guard.json` from the
1210
- head, because previewing the proposed rules means their rules too, while
1211
- gitleaks and osv-scanner keep the base's config. osv-scanner call analysis is
1212
- refused in the preview, because it would build the head's code. The intent
1213
- gate is deferred and not previewed.
1214
-
1215
- **The preview decides nothing.** The exit code, the verdict token and the SARIF
1216
- results are those of the run under the base rules, whatever the preview finds
1217
- or however it fails. In the full report (`--verbose`, the form the Action
1218
- reads) the first four lines are untouched; in the one-line clean form the
1219
- primary report is a byte-for-byte prefix and the preview follows it. It prints after
1220
- the verdict under `Preview under the proposed rules (does not affect the
1221
- verdict)`, as `conductor: preview ...` lines in the job log, as note-level
1222
- `conductor/preview-under-proposed-rules` notifications on the umbrella's SARIF
1223
- run, and as one `preview: N gate(s), M finding(s), K could-not-run` line in
1224
- the step summary. The whole preview has a hard deadline of 300 seconds; a
1225
- gate reached with no budget left is listed as over budget, and one that starts and is killed at the deadline is could-not-run (timed-out). A gate section in the preview
1226
- uses the same words as a primary section, so a finding may read `BLOCKING`
1227
- there: it means the finding would block under the proposed rules, and it does
1228
- not affect this run. A pull-request comment is cut at 60000 characters, the
1229
- preview block first. Every character outside printable ASCII in the preview
1230
- (in the report, the job log and the SARIF notes) is written as a `\uXXXX`
1231
- escape, because a gate there can read text the head chose, a
1232
- right-to-left override in a pattern name included. The primary text report
1233
- escapes finding file paths the same way, since a pull request names its own
1234
- files; other primary gate text, and every path in the SARIF log, is printed
1235
- as the gate gave it.
1236
-
1237
- Ask for it with `--preview` on `conductor run`, or with the Action's `preview`
1238
- input, which defaults to `true`; any other value turns it off. There is no
1239
- preview when the head `.guardrails.yaml` does not parse.
1240
-
1241
- ## Intent at a pull request
1242
-
1243
- The intent gate is the only one of the five with any ceremony: its native
1244
- flow wants a contract approved before the work starts, which is a per-task
1245
- human step. That step is exactly what a pull request cannot carry, so at the
1246
- `ci` stage the umbrella stands in for it.
1247
-
1248
- **What it measures.** With `--base <ref>`, the changed-path set is what this
1249
- branch changed since it forked, from
1250
- `git diff --name-only --no-renames <base>...HEAD` in the repository root.
1251
-
1252
- With no `--base`, `GITHUB_BASE_REF` is used when it is set, spelled in full:
1253
- `refs/conductor/trust-base` (the Action's private fetch of the base) if that
1254
- exists, else `refs/remotes/origin/<value>`, so a tag of that name cannot
1255
- shadow it. The text report says which. An explicit `--base` that matches both
1256
- a tag and a branch is refused as ambiguous. With neither but a `--trust-base`
1257
- (merge_group, workflow_dispatch, a CLI run), the change set is measured from
1258
- the trust base. With none of the three, the intent gate runs the way
1259
- it does at a commit: against the staged index, or the paths you name.
1260
-
1261
- **This is why a local preview and a pull-request run can disagree about a
1262
- missing contract.** The contract-discovery rules below (`--spec`, a frozen
1263
- native contract, a `Spec:` line, the `docs/superpowers/specs` convention)
1264
- only engage once `--base` resolves to something, or `--spec` is given.
1265
- Neither is true of a plain `conductor run` on your own checkout, so a
1266
- repository with no contract gets intent-guard's own native answer instead:
1267
- `BLOCKING critical intent-guard/gate-blocked`, because that flow wants an
1268
- approved contract and none exists. On a pull request `--base` is set, this
1269
- whole section's machinery engages, and a branch with nothing to import
1270
- lands in the no-contract state below instead: reported, and never reaching
1271
- the exit code. Read a local `BLOCKING` line on the intent gate as "there is
1272
- no contract for the umbrella to import here yet," not as "this pull request
1273
- will fail."
1274
-
1275
- A git failure here is **fail-closed**: could-not-run, so exit 2 for an
1276
- enforced gate and a note for an unenforced one. There is deliberately no
1277
- fallback to an empty path set, because an empty path set is what a passing
1278
- gate looks like. In Actions this is almost always a shallow checkout, so
1279
- **`actions/checkout` needs `fetch-depth: 0`** for the merge base to exist.
1280
-
1281
- **On a pull-request run the base decides.** With `--trust-base`, whether a
1282
- frozen contract governs the pull request is read from the base ref alone. A
1283
- frozen contract on the base is used, ahead of everything in the list below,
1284
- `--spec` included (the report says so when `--spec` was given), and the gate
1285
- judges any edit to it against the base copy. That holds for every
1286
- intent-guard that can run on a pull-request run, since one older than its
1287
- pull-request-mode minimum is could-not-run rather than run without the base
1288
- ref. With no frozen contract on the
1289
- base, nothing in the pull request becomes the contract: a spec on the base,
1290
- found by rules 1, 3 and 4 below, is imported from its base copy (so on such a
1291
- run `--spec` must be a plain path inside the repository that the base
1292
- carries), and otherwise
1293
- the gate is skipped with "No contract on the base". A contract or spec the
1294
- pull request adds is reported as a proposal, so adopting the intent gate
1295
- merges, and the next pull request is judged against it. Retiring or replacing
1296
- a frozen contract through a judged pull request is refused by the intent gate
1297
- itself and needs an administrator to merge it.
1298
-
1299
- **Where the contract comes from**, in order:
1300
-
1301
- 1. `--spec <path>` on the umbrella's own command line. Typed just now, so it
1302
- outranks everything else in this list, and a path here that is not on
1303
- disk is reported rather than replaced: running a different contract than
1304
- the one somebody named is the wrong kindness. On a pull-request run it is
1305
- read from the base, and a frozen contract on the base takes precedence.
1306
- 2. `<repo>/.intent-guard/intent-contract.yaml`, when it is **frozen**, and
1307
- `<repo>/.conductor/intent-contract.yaml` after it. The native flow wins
1308
- wherever a team has done it. Frozen is the test rather than present: an
1309
- unfrozen contract is a draft somebody left behind, and running the gate
1310
- against it fails every pull request on "not frozen by user" without
1311
- checking anything.
1312
-
1313
- The second path is the directory intent-guard used before 1.3.0, which
1314
- renamed it because `.conductor` had become the name of a different product
1315
- in this family. Both are read, so a repository on either version is
1316
- checked rather than blocked, and a run that used the old one says so: one
1317
- line on the gate's contract line in the text report, and an
1318
- `intent-guard/legacy-state-dir` notification in the SARIF log. If the
1319
- repository holds **both** directories, the gate does not run and says so,
1320
- naming both: that is the state intent-guard itself refuses every command
1321
- in, so the umbrella refuses on exactly the gate's rule rather than a
1322
- softer one. A `.conductor` holding nothing intent-guard wrote belongs to
1323
- something else and is ignored.
1324
- 3. The **first** `Spec: <path>` line in the pull request body, read from the
1325
- event payload at `GITHUB_EVENT_PATH`. A path here that is not on disk, or
1326
- one that leaves the repository, falls through to the next rule.
1327
- `Spec: none` is a **waiver**: it says this pull request deliberately has
1328
- no spec, so rule 4 is not tried and the gate reports itself skipped with
1329
- `intent-guard/contract-waived` instead of `intent-guard/no-contract`. The
1330
- token is exact and lowercase, a frozen contract at rule 2 still wins over
1331
- it, and `--spec` at rule 1 still overrides it.
1332
- 4. A markdown file **directly under** `docs/superpowers/specs` whose name
1333
- matches the branch on **whole words**. The branch slug is the branch name
1334
- with its first segment (`feat/`, `fix/`) removed; a filename is reduced by
1335
- stripping a `YYYY-MM-DD-` prefix and a trailing `-design`. Both have their
1336
- ASCII letters lower-cased and are split into words on `-`, `_`, `/` and
1337
- spaces. A spec is a candidate when one name's words appear, in order and
1338
- together, inside the other's, and at least one shared word is three or
1339
- more characters, contains a letter, and is not a common branch word
1340
- (`fix`, `feat`, `wip`, `docs`, and the rest of the list in
1341
- `src/intent-spec.ts`). Candidates are ranked by an equal name first, then
1342
- the most shared words, then the longest shared word, then the lexically
1343
- greatest filename among files with the same name (the newest date when
1344
- every spec is dated `YYYY-MM-DD-`, so **date every spec** in that form).
1345
- Two different specs that tie are **not** guessed between: the gate is
1346
- skipped as `intent-guard/spec-ambiguous`, naming both. A spec chosen on
1347
- one shared word, or on word length alone, is used and the report says the
1348
- match is weak. Branch names like `pr` or `fix/wip` choose nothing. When
1349
- the choice matters, say it: a `Spec:` line in the pull request body, or a
1350
- branch named after the spec.
1351
-
1352
- **A branch with neither** is a third state beside deferred and could-not-run:
1353
- the gate is switched on, it ran, and it had nothing to check. It gets one
1354
- line in the text report and one `intent-guard/no-contract` notification
1355
- in the `conductor` run, and it **never** reaches the exit code, enforced or
1356
- not. A branch with no spec is a branch this gate has no opinion about, and
1357
- turning that into a failed build is how a gate gets switched off across a
1358
- repository. A waived pull request lands in the same state and is reported
1359
- under its own `intent-guard/contract-waived` id, with its own wording on the
1360
- skipped line, in the verdict and on the one-line summary of a clean run, so a
1361
- reader can tell "nobody has written one" from "somebody decided against one"
1362
- wherever they meet it. An ambiguous branch, one two specs match equally,
1363
- lands in the same advisory state under its own `intent-guard/spec-ambiguous`
1364
- id, and never reaches the exit code either.
1365
-
1366
- **A repository with no contract yet is not a repository this gate can act
1367
- on**, and the no-contract skip line names `docs/superpowers/specs`, which is
1368
- a convention from this family's own tooling and not one an outside adopter
1369
- has reason to recognise. The next step, if you want this gate to have an
1370
- opinion here, is the one intent-guard's own documentation describes: draft a
1371
- contract naming the paths worth protecting, then freeze it, and keep the
1372
- frozen file committed so rule 2 above finds it on every pull request from
1373
- then on. Until you do that, a project rule that lives only in `AGENTS.md`
1374
- never blocks anything through this gate. intent-guard does read prose rules
1375
- files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, cursor rules) as constraint
1376
- sources, but by its own design a constraint from that source is advisory
1377
- and leaves the exit code alone; only a user-stated constraint, or one
1378
- promoted with `intent-guard correct --promote`, can block. Conductor itself
1379
- never opens that file. What is enforced is the frozen contract or the
1380
- imported spec, never project convention documented in prose.
1381
-
1382
- **A waiver is a decision, recorded by whoever wrote the pull request body,
1383
- and that includes a contributor from a fork.** On the ordinary path, where a
1384
- repository has no frozen contract of its own, `Spec: none` means the intent
1385
- gate does not run at all on that pull request, and budget breaches are the
1386
- thing this gate blocks on. The one thing a waiver cannot override is a frozen
1387
- native contract, under either of the two paths above, which is checked first:
1388
- a repository that wants the gate to be non-waivable freezes a native contract
1389
- and keeps it committed. The branch-name convention is not a control either:
1390
- whoever names the branch chooses among the base's specs.
1391
-
1392
- **What blocks is unchanged.** Blocking stays where intent-guard puts it:
1393
- budget breaches block, subject to `enforce`. Drift on its own is reported and
1394
- not blocked, which is already intent-guard's own behaviour. The umbrella adds
1395
- no severity threshold of its own here either, and intent-guard 1.7.0's own
1396
- advance-notice warnings about an unmatchable `protected_paths` or
1397
- `allowed_paths` entry never reach the exit code either, right up until the
1398
- 2.0.0 release where intent-guard turns that same shape into a blocking
1399
- reason. Where they print depends on how much of the report is showing: as a
1400
- note under the intent gate in the full report (`--verbose`, a non-clean run,
1401
- or the pull-request comment, which the Action always renders with
1402
- `--verbose`), and, on an otherwise-clean run with neither, counted without
1403
- their text in the one-line summary's own note count instead.
1404
-
1405
- **A prose-sourced constraint finding is never marked blocking, even when the
1406
- run blocks for an unrelated reason.** intent-guard 1.6.0 caps a constraint
1407
- whose source is one of those same prose rules files at advisory: a strong
1408
- match is still reported, but it never raises the gate's own exit code. A run
1409
- that blocks on scope creep alone still carries that capped finding in its
1410
- report, and it is rendered as a non-blocking, lower-severity line in the text
1411
- report and with `properties.blocking: false` in SARIF, rather than inheriting
1412
- the run's own blocking flag the way every other drift finding does.
404
+ - The policy file: see [docs/policy-file.md](docs/policy-file.md).
405
+ - Commands, exit codes and the verdict token: see [docs/commands.md](docs/commands.md).
406
+ - The pull-request trust boundary: see [docs/pull-request-trust-boundary.md](docs/pull-request-trust-boundary.md).
407
+ - Intent at a pull request: see [docs/intent-at-a-pull-request.md](docs/intent-at-a-pull-request.md).
408
+ - Upgrading and the defaults per action tag: see [docs/upgrading.md](docs/upgrading.md).
409
+ - The Action recipes and inputs are the section [The Action](#the-action) below.
1413
410
 
1414
411
  ## The Action
1415
412
 
@@ -1506,7 +503,8 @@ rather than running without a trust base; the token exists only in that fetch
1506
503
  step and never in the gates), so the run takes
1507
504
  its configuration from the base branch and the pull request cannot change the
1508
505
  rules it is judged by; a change to the rules shows as a proposal line and
1509
- takes effect after merge. See "The pull-request trust boundary" above. On any
506
+ takes effect after merge. See
507
+ [The pull-request trust boundary](docs/pull-request-trust-boundary.md). On any
1510
508
  other event it passes nothing and behaviour is unchanged. The `trust-base`
1511
509
  input names the ref explicitly, for a platform where `GITHUB_BASE_REF` is not
1512
510
  set. **On a `pull_request` or `pull_request_target` event this input is
@@ -1534,7 +532,8 @@ request being judged, and the version-pin protection described above
1534
532
  "protects nothing" against a tree that controls its own judge (the
1535
533
  validate step's own comment in `action.yml` says so in those words). A tag
1536
534
  moves when someone pushes it. Name this action by owner and the full commit
1537
- SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.15.0.
535
+ SHA instead. The recipes in this README name v0.16.0 that way, as
536
+ `vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0`.
1538
537
 
1539
538
  ```yaml
1540
539
  name: guardrails
@@ -1556,10 +555,10 @@ jobs:
1556
555
  with:
1557
556
  node-version: '22.23.4'
1558
557
  - id: conductor
1559
- uses: vaultcompasshq/conductor@v0.15.0
558
+ uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
1560
559
  with:
1561
560
  output: conductor.sarif
1562
- - uses: github/codeql-action/upload-sarif@v3
561
+ - uses: github/codeql-action/upload-sarif@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
1563
562
  if: always()
1564
563
  continue-on-error: true
1565
564
  with:
@@ -1588,10 +587,32 @@ pinned `action.yml`, which is the version that commit ships, so the installed
1588
587
  umbrella follows the pin and a Dependabot bump is the one `uses` line. If the
1589
588
  input is set and is older than the constants in that pinned action.yml, a
1590
589
  pull request run is refused and the validate step says to remove the input. A
1591
- newer value is accepted and is what gets installed. The three gate version
1592
- inputs can be left out too: each one then takes the default in the pinned
1593
- action.yml. The spelled-out example below names them when a workflow wants
1594
- that transparency.
590
+ newer value is accepted and is what gets installed.
591
+
592
+ **Omit the three gate version inputs too, unless you need to pin a gate
593
+ forward** (issue 145). Each one then takes the default in the pinned
594
+ action.yml, so the defaults travel with the tag and a Dependabot or Renovate
595
+ bump of the `uses:` line moves the gates with it. Pinned by hand, they do
596
+ not move: after the bump `dep-guard-version`, `vault-guard-version` or
597
+ `intent-guard-version` sits below the new tag's defaults, a pull request
598
+ refuses a pin below them, and that bump's own pull request goes red with
599
+ nothing wrong in it. The fix is in the same pull request: raise each pinned
600
+ line to the new tag's default (the CHANGELOG entry for the tag lists them,
601
+ and so does the table in [Upgrading](docs/upgrading.md)), or delete it. The
602
+ spelled-out example below names them when a workflow wants that
603
+ transparency, and carries that cost.
604
+
605
+ **The gates the Action installs are as new as the tag** (issue 146). A
606
+ tag's defaults can reach npm the same day the tag does, so they can be
607
+ younger than the minimum release age dep-guard holds your own dependencies
608
+ to (7 days by default, a check that runs when dep-guard runs with
609
+ `--online`). The Action installs them itself, outside your
610
+ lockfile, so dep-guard does not see them. To run older gates, pin the action
611
+ ref to an older tag, whose defaults are older; pinning the version inputs
612
+ below the tag's own defaults is refused on a pull request, because a pull
613
+ request must not choose an older, weaker judge. A Dependabot `cooldown`
614
+ setting on the `github-actions` ecosystem delays the bump itself by the
615
+ same number of days.
1595
616
 
1596
617
  ```yaml
1597
618
  name: guardrails
@@ -1633,7 +654,7 @@ jobs:
1633
654
  # installs those itself, globally. Leave conductor-version unset so the
1634
655
  # umbrella is the default in the pinned action.yml.
1635
656
  - id: conductor
1636
- uses: vaultcompasshq/conductor@v0.15.0
657
+ uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
1637
658
  with:
1638
659
  output: conductor.sarif
1639
660
  # Exact versions, never a range and never "latest". These three
@@ -1644,10 +665,10 @@ jobs:
1644
665
  # request of their own. On a pull request the action refuses a pin
1645
666
  # below what the pinned action.yml ships, and the three lines can
1646
667
  # be left out entirely to take that action's own versions.
1647
- dep-guard-version: 0.17.0
1648
- vault-guard-version: 1.12.1
1649
- intent-guard-version: 1.10.2
1650
- - uses: github/codeql-action/upload-sarif@v3
668
+ dep-guard-version: 0.18.1
669
+ vault-guard-version: 1.13.1
670
+ intent-guard-version: 1.10.4
671
+ - uses: github/codeql-action/upload-sarif@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
1651
672
  # Always: the log is most worth having on the run that failed.
1652
673
  if: always()
1653
674
  # The sarif path is published BEFORE the gates run, so on the exit 2
@@ -1812,12 +833,19 @@ days (issue #36) because the step's exit code was swallowed regardless of
1812
833
  which of the two reasons produced it. `advisory` fixes the failure that
1813
834
  caused that; `continue-on-error` is the thing that let it happen, so the two
1814
835
  do not belong in the same recipe. Set a step `timeout-minutes` as well: the
1815
- Action already caps each gate's own subprocess at 120 seconds and reports one
1816
- that exceeds it as could-not-run, so the timeout is an outer bound around the
1817
- whole run rather than the primary control. Make it at least what the primary
1818
- run needs plus 300 seconds (5 minutes), because the preview under the
1819
- proposed rules can use up to that much on a pull request that changes a
1820
- gate's `enabled` or `stage`; a step killed mid-preview has no verdict. Check
836
+ Action already caps each gate's own subprocess (by default 120 seconds for
837
+ the three family gates, 600 for gitleaks and 300 for osv-scanner, see the
838
+ time limits above) and reports one that exceeds it as could-not-run, so the
839
+ timeout is an outer bound around the whole run rather than the primary
840
+ control. It must not undercut those limits, because a step killed by its
841
+ own timeout has no verdict at all, where a gate stopped at its limit is
842
+ reported. Make it at least the sum of the enabled gates' limits plus 300
843
+ seconds for the preview under the proposed rules, which can use up to that
844
+ much on a pull request that changes a gate's `enabled` or `stage`, plus the
845
+ time the step spends installing the gates before any of them runs. With all
846
+ five gates at their defaults that is 1260 plus 300 seconds, 26 minutes,
847
+ before the install, so the recipe below says 30; raise it with any
848
+ `timeout-seconds` you raise. Check
1821
849
  out with `persist-credentials: false` so the gates never run with a token
1822
850
  left in the checkout's git config.
1823
851
 
@@ -1844,9 +872,11 @@ jobs:
1844
872
  with:
1845
873
  node-version: '22.23.4'
1846
874
  - id: conductor
1847
- # The primary run's need (here 5 minutes) plus 300 seconds.
1848
- timeout-minutes: 10
1849
- uses: vaultcompasshq/conductor@v0.15.0
875
+ # The enabled gates' own limits (all five at their defaults: 1260
876
+ # seconds) plus 300 seconds for the preview, rounded up. A step
877
+ # timeout below that can kill a full gitleaks scan and leave no verdict.
878
+ timeout-minutes: 30
879
+ uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
1850
880
  with:
1851
881
  pr-comment: true
1852
882
  advisory: true
@@ -1932,7 +962,7 @@ change and forget the other half.
1932
962
 
1933
963
  ### Adopting conductor
1934
964
 
1935
- See "Adopting conductor" near the top of this README for the ordered
965
+ See "Adopting conductor: the careful path" near the top of this README for the ordered
1936
966
  walkthrough: init, a first pull request in advisory mode, merge, then go
1937
967
  required. This subsection is the mechanism behind two of those steps.
1938
968
 
@@ -1982,7 +1012,7 @@ step and add `pull-requests: write` to the job's `permissions`:
1982
1012
  # the pull request runs before the action in this job: no install, build
1983
1013
  # or test step here; those belong in a separate job. ...
1984
1014
  - id: conductor
1985
- uses: vaultcompasshq/conductor@v0.15.0
1015
+ uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
1986
1016
  with:
1987
1017
  output: conductor.sarif
1988
1018
  pr-comment: true
@@ -2004,7 +1034,7 @@ comment every time, the way the manual recipe below does. It runs on a
2004
1034
  gates step passed or failed, since a blocking run is the one an advisory
2005
1035
  check most needs a developer to actually see. The first line of every
2006
1036
  comment carries the version of conductor that produced it, the second line
2007
- carries the verdict token (see "The verdict token" above), and when the
1037
+ carries the verdict token (see [The verdict token](docs/commands.md#the-verdict-token)), and when the
2008
1038
  trust base was refused and no gate ran at all, the comment shrinks to the
2009
1039
  version, the verdict, and the refusal reason (with its remedy, when one
2010
1040
  applies) rather than the full per-gate report, so an adopter with no policy
@@ -2061,12 +1091,12 @@ per pull request.
2061
1091
 
2062
1092
  ```yaml
2063
1093
  - id: conductor-package-a
2064
- uses: vaultcompasshq/conductor@v0.15.0
1094
+ uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
2065
1095
  with:
2066
1096
  pr-comment: true
2067
1097
  pr-comment-marker: 'package-a'
2068
1098
  - id: conductor-package-b
2069
- uses: vaultcompasshq/conductor@v0.15.0
1099
+ uses: vaultcompasshq/conductor@be3f33defcca091c403af6d2dc6e377ef5b94af7 # v0.16.0
2070
1100
  with:
2071
1101
  pr-comment: true
2072
1102
  pr-comment-marker: 'package-b'
@@ -2166,68 +1196,6 @@ is one snapshot of one run: no per-finding state, nothing to dismiss, no
2166
1196
  history between runs, and a new comment every time rather than an alert that
2167
1197
  closes when the finding goes away.
2168
1198
 
2169
- ## Upgrading
2170
-
2171
- An adopter pins two numbers, and they control different things.
2172
-
2173
- - **The action ref**, `uses: vaultcompasshq/conductor@<tag or SHA>`, picks
2174
- which `action.yml` runs. That file carries the defaults for the four
2175
- version inputs and the constants the pull-request backward-pin rule
2176
- measures a pin against.
2177
- - **The `conductor-version` input** picks which `@vaultcompass/conductor`
2178
- the install step installs. The same step installs the three gates at
2179
- `dep-guard-version`, `vault-guard-version` and `intent-guard-version`.
2180
- Each input defaults to the version the tag shipped.
2181
-
2182
- **The recommended shape is to leave all four version inputs unset** and move
2183
- only the action ref. On a pull request, the validate step refuses an input
2184
- naming a version below the one the tag ships, so an explicit old pin breaks
2185
- the day you upgrade the ref (see "The Action" above). Outside a pull request
2186
- an explicit pin is unaffected, which is how a stale pin can sit unnoticed
2187
- until the first pull request after the upgrade.
2188
-
2189
- **Pin the action ref to a full commit SHA** with the tag as a comment, for
2190
- example `uses: vaultcompasshq/conductor@<40-character SHA> # v0.15.0`. To
2191
- find the SHA for a tag, run
2192
- `gh api repos/vaultcompasshq/conductor/git/ref/tags/v0.12.0` or read it off
2193
- the Releases page.
2194
-
2195
- **Dependabot or Renovate bumping that SHA changes the action ref only.** It
2196
- does not touch a `dep-guard-version`, `vault-guard-version`,
2197
- `intent-guard-version` or `conductor-version` you set by hand, so such a pin
2198
- must be raised or removed by hand in the same pull request, or that pull
2199
- request is refused by the rule above.
2200
-
2201
- **An action-only tag moves the tag while the npm package stays.** The
2202
- CHANGELOG marks these as "An action-only release" and says which
2203
- `conductor-version` default stays. `@vaultcompass/conductor` does not change
2204
- on those, so `conductor-version` need not change either; the gate defaults
2205
- may.
2206
-
2207
- Defaults per tag, taken only from CHANGELOG.md entries that state them. A
2208
- tag with no row here has an entry that does not state its defaults; read
2209
- `action.yml` at that tag.
2210
-
2211
- | Action tag | Kind | `conductor-version` default | Gate defaults the entry says moved |
2212
- | --- | --- | --- | --- |
2213
- | v0.15.0 | package | 0.15.0 | dep-guard 0.17.0 (from 0.16.1), intent-guard 1.10.2 (from 1.10.1) |
2214
- | v0.14.0 | package | 0.14.0 | none (gate defaults unchanged) |
2215
- | v0.13.2 | package | 0.13.2 | none (gate defaults unchanged) |
2216
- | v0.13.1 | action-only | 0.13.0 | dep-guard 0.16.1 (from 0.15.0) |
2217
- | v0.13.0 | package | 0.13.0 | none (gate defaults unchanged) |
2218
- | v0.12.0 | package | 0.12.0 | vault-guard 1.12.1 (from 1.12.0), intent-guard 1.10.1 (from 1.10.0) |
2219
- | v0.11.1 | action-only | 0.11.0 | dep-guard 0.15.0 (from 0.14.0), vault-guard 1.12.0 (from 1.11.0) |
2220
- | v0.11.0 | package | 0.11.0 | dep-guard 0.14.0, intent-guard 1.10.0 |
2221
- | v0.10.0 | package | 0.10.0 | dep-guard 0.13.0, vault-guard 1.11.0 |
2222
- | v0.8.2 | action-only | 0.8.1 | dep-guard 0.11.1 (from 0.10.1) |
2223
- | v0.8.1 | package | 0.8.1 | dep-guard 0.10.1, vault-guard 1.9.1, intent-guard 1.8.1 |
2224
- | v0.8.0 | package | 0.8.0 | dep-guard 0.10.0, vault-guard 1.9.0, intent-guard 1.8.0 |
2225
- | v0.7.0 | package | 0.7.0 | none |
2226
- | v0.6.0 | package | 0.6.0 | dep-guard 0.9.0 (from 0.8.0), intent-guard 1.7.0 (from 1.6.0) |
2227
- | v0.5.1 | action-only | 0.5.0 | dep-guard 0.8.0 (from 0.7.0), intent-guard 1.6.0 (from 1.5.2) |
2228
- | v0.4.4 | action-only | 0.4.0 | dep-guard 0.7.0 (from 0.6.0), vault-guard 1.8.0 (from 1.7.0) |
2229
- | v0.4.3 | action-only | 0.4.0 | intent-guard 1.5.2 (from 1.4.0) |
2230
-
2231
1199
  ## What is in and what is out
2232
1200
 
2233
1201
  In: the policy file and its schema, `init` with dry-run, revert, and adopt,