@vaultcompass/conductor 0.14.0 → 0.16.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 +159 -1123
- package/dist/gate-runner.d.ts +20 -0
- package/dist/gate-runner.js +64 -2
- package/dist/output-sarif.js +2 -2
- package/dist/output-text.js +24 -8
- package/dist/policy-diff.d.ts +9 -0
- package/dist/policy-diff.js +12 -4
- package/dist/resolve.d.ts +131 -0
- package/dist/resolve.js +287 -2
- package/dist/trust-base.d.ts +80 -1
- package/dist/trust-base.js +258 -5
- package/package.json +1 -1
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
|
|
5
|
-
|
|
6
|
-
caught before the edit lands, a pull request that edits its
|
|
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@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.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
|
|
102
|
-
|
|
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.0): 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.
|
|
240
|
+
conductor 0.16.0
|
|
172
241
|
verdict-token: blocked (1)
|
|
173
242
|
conductor run: 2 gate(s), 1 finding(s)
|
|
174
243
|
|
|
175
|
-
dependencies dep-guard 0.
|
|
244
|
+
dependencies dep-guard 0.18.0 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-
|
|
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.
|
|
248
|
+
secrets vault-guard 1.13.0 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
|
|
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
|
|
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,1023 +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
|
-
##
|
|
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
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
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 same ref is passed
|
|
790
|
-
down to every gate that supports it, so their contracts, configs and
|
|
791
|
-
baselines come from the base branch too.
|
|
792
|
-
|
|
793
|
-
**The program is checked as well as the rules.** Reading the rules from the
|
|
794
|
-
base ref is worth nothing if the pull request supplies the binary that
|
|
795
|
-
applies them, and without this it could, two ways that both look ordinary in
|
|
796
|
-
a diff: a base `command:` pointing at a path inside the repository, where the
|
|
797
|
-
head replaces the file behind the approved path; and no `command:` at all,
|
|
798
|
-
where a head-committed `node_modules/.bin/<gate>` shadows the real gate,
|
|
799
|
-
because resolution prefers the repository's own copy over PATH so that a
|
|
800
|
-
project pin beats a global install.
|
|
801
|
-
|
|
802
|
-
**On a pull-request run `node_modules/.bin` is not consulted at all.** That
|
|
803
|
-
second shape is closed one step earlier than the first, and this is why: what
|
|
804
|
-
is installed there is chosen by the head's own manifest and lockfile, so it is
|
|
805
|
-
never approved by any ref, and a repository whose gates are devDependencies
|
|
806
|
-
would otherwise meet the program refusal on every ordinary pull request. So
|
|
807
|
-
that location is simply not searched when a trust base is set. PATH and an
|
|
808
|
-
absolute `command:` remain, and both still go through the program check below.
|
|
809
|
-
The skip is never silent: one line in the full report and one
|
|
810
|
-
`conductor/node-modules-skipped` note in the SARIF log name each gate and the
|
|
811
|
-
copy that was not taken, and a gate with nothing on PATH either is
|
|
812
|
-
could-not-run with `npm install -g` and the Action's version input named as
|
|
813
|
-
the remedy. **Outside pull-request mode nothing changes**: your own checkout
|
|
814
|
-
and your pre-commit hook still run the pin, which is what `pnpm exec` does in
|
|
815
|
-
the same repository.
|
|
816
|
-
|
|
817
|
-
**The versions that judge a pull request are pinned in the workflow file**,
|
|
818
|
-
and that is the point: the pull request can change its own lockfile,
|
|
819
|
-
manifest and `node_modules`, and none of those decide which conductor and
|
|
820
|
-
which gates run over it any more. Be clear about what that does not cover.
|
|
821
|
-
On a `pull_request` event GitHub runs the workflow as it is in the pull
|
|
822
|
-
request's merge commit, so a pull request that edits the workflow file can
|
|
823
|
-
change the pins or remove the gates step, exactly as it could rewrite any
|
|
824
|
-
other step in your CI. The boundary here is against the tree choosing its
|
|
825
|
-
own judge; the control for a workflow edit is branch protection on your
|
|
826
|
-
base branch with review required for `.github/workflows`, and no action can
|
|
827
|
-
provide that for you. Only `pull_request_target` runs the base branch's copy
|
|
828
|
-
of a workflow, and that event exposes the base's secrets to the pull
|
|
829
|
-
request's code, which is the wrong trade for a gate over untrusted changes.
|
|
830
|
-
|
|
831
|
-
One part of that is closed, and only one. Because the pins are written in a
|
|
832
|
-
file the pull request controls, a pull request could otherwise pin a gate
|
|
833
|
-
**backward** to a published version that predates the rule which would have
|
|
834
|
-
caught it: an exact version, so the validate step's shape check accepts it,
|
|
835
|
-
and a change that reads as ordinary version management. **On a pull request
|
|
836
|
-
the action now refuses any of the four `*-version` inputs naming a version
|
|
837
|
-
below the one the action tag ships.** Pinning forward is still accepted.
|
|
838
|
-
See "The Action" below.
|
|
839
|
-
|
|
840
|
-
So on a pull-request run a gate's program must be **outside the working tree**
|
|
841
|
-
(on PATH, or an absolute `command:` elsewhere on the machine), or else meet
|
|
842
|
-
**both** of these:
|
|
843
|
-
|
|
844
|
-
- it is a **tracked regular file whose contents are identical** at the base
|
|
845
|
-
ref and at the head commit; and
|
|
846
|
-
- **the tree object id of its containing directory is identical** at those
|
|
847
|
-
two refs, which is to say the pull request changed nothing anywhere in that
|
|
848
|
-
directory's subtree.
|
|
849
|
-
|
|
850
|
-
Both are compared with `git ls-tree` on both refs and never read from the
|
|
851
|
-
working tree. The second is not belt and braces. A vendored gate is rarely
|
|
852
|
-
one file: `vendor/vault-guard` execs `vendor/impl.sh`, and a pull request
|
|
853
|
-
that leaves the wrapper byte for byte alone and rewrites the helper beside it
|
|
854
|
-
passes a per-file check while running its own code. Comparing the directory
|
|
855
|
-
covers every file under it at once, without this tool having to know what a
|
|
856
|
-
wrapper calls.
|
|
857
|
-
|
|
858
|
-
**What is and is not vetted**, exactly: the program file and everything in
|
|
859
|
-
its directory subtree. Anything the program reaches **outside** that
|
|
860
|
-
directory is not vetted at all, so an in-repo gate must be **self-contained
|
|
861
|
-
within its own directory**. A program at the repository ROOT is refused, and
|
|
862
|
-
the message says to give it a directory: at the root the containing directory
|
|
863
|
-
is the whole repository, so the rule would mean "no pull request may change
|
|
864
|
-
anything".
|
|
865
|
-
|
|
866
|
-
A symlink inside the repository is refused on **its own entry**, before its
|
|
867
|
-
target is considered: it is either untracked, or its tree entry is a link
|
|
868
|
-
rather than a regular file, and either refuses. (A symlink whose own path is
|
|
869
|
-
outside the tree but which points into it has its target vetted; that is the
|
|
870
|
-
case following the link exists for.)
|
|
871
|
-
|
|
872
|
-
Anything else is could-not-run for that gate, naming the path, and it reaches
|
|
873
|
-
the exit code even where the policy sets `enforce: false`, because the gate
|
|
874
|
-
produced no findings to un-enforce: the umbrella declined to run a program
|
|
875
|
-
the pull request chose.
|
|
876
|
-
|
|
877
|
-
Nothing under `node_modules` is ever base-approved, which is why the rule
|
|
878
|
-
above does not look there at all. Were it to look, the answer would always be
|
|
879
|
-
the same refusal: what is there is chosen by the head's own manifest and
|
|
880
|
-
lockfile and installed by a step that runs before the gates, so git has no
|
|
881
|
-
record of those bytes at either ref. A pull request that edits its lockfile to
|
|
882
|
-
pull a different build of a gate has chosen its own judge just as surely as
|
|
883
|
-
one that commits a stub. **Vendoring a gate still works**, on those
|
|
884
|
-
terms: put it in its own directory, keep everything it needs inside that
|
|
885
|
-
directory, and leave the whole directory alone in a pull request the gate is
|
|
886
|
-
meant to judge. Changing it is not forbidden, it just has to land on the base
|
|
887
|
-
branch first, like any other rule change.
|
|
888
|
-
|
|
889
|
-
**A change to the rules is not refused, it is proposed.** Rules legitimately
|
|
890
|
-
change, and a gate that blocked every such pull request would train people to
|
|
891
|
-
bypass it. So a policy file that differs from the base ref's is reported as
|
|
892
|
-
one line per changed key, `policy: gates.<role>.<key> <old> -> <new>`, counted
|
|
893
|
-
as one proposal each; a head `.guardrails.yaml` that is absent or does not
|
|
894
|
-
parse gives one line saying its changes are not known, and when no effective
|
|
895
|
-
key differs (a default spelled out, or the YAML reordered) the old single line,
|
|
896
|
-
`policy changed in this pull request`, is kept. The run continues under the
|
|
897
|
-
base ref's rules, and the change takes effect **after merge**, on the first
|
|
898
|
-
run whose base branch carries it. The gates' own proposals are summed with it
|
|
899
|
-
into one sentence, `N control change(s) proposed in this pull request`, on the
|
|
900
|
-
one-line summary and on the verdict, with a line each under `--verbose` and a
|
|
901
|
-
`conductor/control-change-proposed` notification each in the SARIF log. A
|
|
902
|
-
reflow, a re-quote or an edited comment is not a proposal: the two files are
|
|
903
|
-
compared as parsed documents.
|
|
904
|
-
|
|
905
|
-
**An explicit `--trust-base` redirect gets a refusal on a pull request, at two
|
|
906
|
-
places (issue #58), and neither closes the whole hole by itself.**
|
|
907
|
-
`refuseTrustBaseRef` above only refuses a ref that resolves to HEAD's own
|
|
908
|
-
commit or to HEAD's own tree, which covers HEAD itself and an *unmoved*
|
|
909
|
-
`origin/<pr-branch>`. Once the base branch has moved, `origin/<pr-branch>` no
|
|
910
|
-
longer matches either test, so a same-repo pull request could set
|
|
911
|
-
`trust-base` to its own branch, in its own workflow file, and have conductor
|
|
912
|
-
read `.guardrails.yaml` from the pull request after all, at which point the
|
|
913
|
-
pull request controls the whole policy. dep-guard's own base input took the
|
|
914
|
-
stronger line for its base input in 0.8.0: on a `pull_request` event an
|
|
915
|
-
explicit value is refused outright.
|
|
916
|
-
|
|
917
|
-
**The Action refuses an explicit redirect on `pull_request` and
|
|
918
|
-
`pull_request_target` events.** Its validate step refuses a `trust-base`
|
|
919
|
-
input outright on those events, naming the value given and the fix, which is
|
|
920
|
-
to remove the input; see "The Action" below.
|
|
921
|
-
|
|
922
|
-
**The CLI check catches a misconfigured or innocent-looking redirect when
|
|
923
|
-
`GITHUB_BASE_REF` is set**, for anyone invoking the CLI directly in CI. When
|
|
924
|
-
that variable is set, an explicit `--trust-base` is accepted only when it is
|
|
925
|
-
`refs/conductor/trust-base`, the private ref the Action fetches the base
|
|
926
|
-
branch into and always passes (that ref is the authority and is not compared
|
|
927
|
-
with anything), or resolves to the same commit as
|
|
928
|
-
`refs/remotes/origin/$GITHUB_BASE_REF`. So an ordinary pull-request run is
|
|
929
|
-
unaffected. A ref naming the pull request's own branch, or anything else that
|
|
930
|
-
disagrees, is refused with both refs and both commits named, through the same
|
|
931
|
-
could-not-run path as every other trust-base refusal: exit 2, the report
|
|
932
|
-
leads with the reason, and nothing is checked. A short name that matches both
|
|
933
|
-
a tag and a branch or remote-tracking ref (a tag named `origin/main`) is
|
|
934
|
-
refused as ambiguous: spell the ref in full. When neither resolves, this fails
|
|
935
|
-
closed too, naming it, for the same reason the fetch-depth remedy below
|
|
936
|
-
exists.
|
|
937
|
-
|
|
938
|
-
**Neither layer closes anything against a pull request that edits its own
|
|
939
|
-
workflow file.** A CLI invocation on a pull request can simply omit
|
|
940
|
-
`--trust-base`, or a workflow step can blank `GITHUB_BASE_REF` in its own env,
|
|
941
|
-
and nothing here refuses either; the Action has the matching gap, since a
|
|
942
|
-
pull request can pin `uses:` to a tag published before this fix, in its own
|
|
943
|
-
workflow file. This is exactly the boundary "On a pull request those four
|
|
944
|
-
inputs may not pin backward" (below, under "The Action") already draws for
|
|
945
|
-
the four `*-version` inputs: the control for a workflow edit is branch
|
|
946
|
-
protection on the base branch with review required for `.github/workflows`,
|
|
947
|
-
and nothing in this section, or in that one, substitutes for it.
|
|
948
|
-
|
|
949
|
-
**It fails closed.** A `--trust-base` that does not resolve is not a reason to
|
|
950
|
-
fall back to the pull request's own file, because that fallback is the hole:
|
|
951
|
-
the run exits 2 and the report **leads with the refusal**, naming the ref and
|
|
952
|
-
the remedy, whether or not it can name any gate. That last part matters: with
|
|
953
|
-
no base ref there is no base policy, so the only list of gates available is
|
|
954
|
-
the head's, and a head that switches every gate off leaves it empty. So is a
|
|
955
|
-
base ref that resolves to the head commit, or to a different commit carrying
|
|
956
|
-
the head's tree, both of which would put the rules back inside the tree being
|
|
957
|
-
judged while still reporting pull-request mode as on. Pass the base
|
|
958
|
-
**branch**, never a SHA: on a `pull_request` event `github.sha` is the merge
|
|
959
|
-
commit, which is HEAD. If the base branch has no `.guardrails.yaml` at all,
|
|
960
|
-
the run has no rules and exits 2 rather than using the pull request's; the
|
|
961
|
-
file the pull request adds decides what runs once it is on the base branch.
|
|
962
|
-
|
|
963
|
-
**One narrow exception to the equal-tree refusal (issue #69).** When a pull
|
|
964
|
-
request's net diff is empty -- a value committed and then backed out inside
|
|
965
|
-
the same pull request -- the merge ref GitHub builds has a tree
|
|
966
|
-
byte-identical to the base's, and the refusal above would stop
|
|
967
|
-
secrets-history from running on exactly the shape it exists to catch: the
|
|
968
|
-
value is gone from the tree but still in the history between the base and
|
|
969
|
-
HEAD. So the refusal makes one exception, and only one: when HEAD is a real
|
|
970
|
-
merge commit (two or more parents) and `--trust-base` resolves to HEAD's
|
|
971
|
-
**first** parent, the run is not refused. First-parent identity is the
|
|
972
|
-
discriminator, not ancestry, because GitHub always builds the merge ref with
|
|
973
|
-
the base branch as the first parent and the pull request's own head as the
|
|
974
|
-
second: a trust base resolving to HEAD's **second** parent is also an
|
|
975
|
-
ancestor and also carries the same tree, and it is exactly the ref this rule
|
|
976
|
-
must keep refusing. In the accepted shape the umbrella still does not judge
|
|
977
|
-
the unchanged tree as if it were the change: it runs every enabled gate
|
|
978
|
-
whose input is git history rather than the tree -- gitleaks today -- with its
|
|
979
|
-
ordinary arguments (already scoped to `<base>..HEAD`), and every other
|
|
980
|
-
enabled gate is reported as tree-unchanged rather than spawned: one line in
|
|
981
|
-
the full report, a clause on the one-line summary, and a
|
|
982
|
-
`conductor/tree-unchanged` notification in the SARIF log, never reaching the
|
|
983
|
-
exit code. Every other equal-tree shape -- a non-merge HEAD, the second
|
|
984
|
-
parent, any other ancestor -- keeps refusing exactly as before.
|
|
985
|
-
|
|
986
|
-
The exception needs HEAD's own parents, so it needs the same non-shallow
|
|
987
|
-
checkout the rest of pull-request mode already requires: `fetch-depth: 0`
|
|
988
|
-
(see below). On a depth-1 checkout git reports the merge commit with no
|
|
989
|
-
parents at all, so the first-parent check cannot match and the run keeps
|
|
990
|
-
refusing with the ordinary equal-tree message -- it fails closed rather than
|
|
991
|
-
guessing. That loss costs nothing real: at depth 1 gitleaks could not have
|
|
992
|
-
seen the backed-out commit either, since its own history scan has nothing
|
|
993
|
-
before HEAD to scope `<base>..HEAD` against.
|
|
994
|
-
|
|
995
|
-
That is why adopting conductor takes one merge before the gates can judge
|
|
996
|
-
anything, and it is not an oversight: the policy file can name a program to
|
|
997
|
-
run, so a run that read it from the pull request would let the pull request
|
|
998
|
-
choose its own judge on exactly the repositories that have no rules yet. See
|
|
999
|
-
"Adopting conductor" below for the sequence and for how to see what your
|
|
1000
|
-
policy will do before you merge it.
|
|
1001
|
-
|
|
1002
|
-
**Which gates are covered.** All five: dep-guard from **0.10.1**,
|
|
1003
|
-
intent-guard from **1.8.1**, vault-guard from **1.9.1**, and the two
|
|
1004
|
-
external gates at their command-line floors, gitleaks **8.19.0** and
|
|
1005
|
-
osv-scanner **2.0.0**. On a pull-request run an older family gate is
|
|
1006
|
-
could-not-run rather than run outside pull-request mode.
|
|
1007
|
-
|
|
1008
|
-
**The external gates get their pull-request mode from the umbrella.**
|
|
1009
|
-
Neither tool has a `--trust-base`, and both auto-load a config from the tree
|
|
1010
|
-
they scan, which on a pull request is the head: a pull request could add an
|
|
1011
|
-
allowlist entry for exactly the secret or advisory it introduces. So on a
|
|
1012
|
-
pull-request run the umbrella reads `.gitleaks.toml` and `osv-scanner.toml`
|
|
1013
|
-
from the base ref with `git show` and passes each tool that copy with
|
|
1014
|
-
`--config`. When the base has none, the tool gets a neutral one (gitleaks'
|
|
1015
|
-
built-in rules, an empty osv-scanner config) rather than nothing, because
|
|
1016
|
-
nothing would let it find the head's file on its own. gitleaks'
|
|
1017
|
-
`.gitleaksignore` is handled the same way, and because gitleaks also loads
|
|
1018
|
-
the ignore file at the root of whatever it scans, the umbrella scans the
|
|
1019
|
-
repository's git directory instead of the working tree on a pull request:
|
|
1020
|
-
the same history, without the head's ignore file. A head-side change to any
|
|
1021
|
-
of these files is reported as a proposal line and takes effect after merge,
|
|
1022
|
-
exactly like a change to `.guardrails.yaml`. History is scoped to
|
|
1023
|
-
`<base>..HEAD` on a pull request and to `HEAD` locally, so a secret on
|
|
1024
|
-
another branch never reddens this one. Merge commits are scanned by their
|
|
1025
|
-
first-parent diff, so a secret added inside a merge (while resolving a
|
|
1026
|
-
conflict, say) is found; the same leak seen in a pull request's commit and
|
|
1027
|
-
again in its merge is reported once, with the other commit listed.
|
|
1028
|
-
|
|
1029
|
-
A base `.gitleaks.toml` can name another file with `[extend] path`, which
|
|
1030
|
-
gitleaks resolves against its working directory. On a pull request
|
|
1031
|
-
conductor copies every file in that chain from the base ref into a
|
|
1032
|
-
directory of its own and runs gitleaks from there, so the head's copy of an
|
|
1033
|
-
extended file is never read; a head-side edit to one is a proposal, and an
|
|
1034
|
-
extended file the base does not have makes the gate could-not-run, naming
|
|
1035
|
-
it. gitleaks' log level is pinned at `info` and `log-level` is reserved,
|
|
1036
|
-
because conductor reads gitleaks' error lines to tell a failed scan from a
|
|
1037
|
-
clean one. Write the extend as a plain relative path in an `[extend]` table:
|
|
1038
|
-
a base `.gitleaks.toml` whose extend target is a symbolic link, or which
|
|
1039
|
-
writes the extend as an inline table or a quoted key, fails closed on every
|
|
1040
|
-
pull request until it is rewritten that way.
|
|
1041
|
-
|
|
1042
|
-
**Local runs and `.gitattributes`.** On a pull request gitleaks scans the
|
|
1043
|
-
repository's git directory, where the head's `.gitattributes` is not read.
|
|
1044
|
-
A local run scans the working tree, so a file your own `.gitattributes`
|
|
1045
|
-
marks `binary` is skipped by gitleaks there. Pull requests are not affected.
|
|
1046
|
-
|
|
1047
|
-
On a pull request gitleaks is also passed `--ignore-gitleaks-allow`, so an
|
|
1048
|
-
inline `gitleaks:allow` comment does not hide a secret: an inline allow
|
|
1049
|
-
lives in the tree being judged, so the pull request controls it. A
|
|
1050
|
-
legitimate allow belongs in the base branch's `.gitleaks.toml` allowlist or
|
|
1051
|
-
`.gitleaksignore`, both of which conductor already reads from the base.
|
|
1052
|
-
Local runs keep inline allows.
|
|
1053
|
-
|
|
1054
|
-
osv-scanner is never pointed at a directory to walk, because its own walk
|
|
1055
|
-
skips anything `.gitignore` matches, tracked or not, so one ignore line in a
|
|
1056
|
-
pull request could hide a committed lockfile. conductor lists the tracked
|
|
1057
|
-
lockfiles with `git ls-files` and hands each one over with `--lockfile`. On
|
|
1058
|
-
a pull request that list comes from the head's index, not the base ref: the
|
|
1059
|
-
lockfiles are the tree being judged, and adding or removing one is visible
|
|
1060
|
-
in the diff. Only the root `osv-scanner.toml` is read from the base and
|
|
1061
|
-
passed with `--config`, which overrides any nested one for the run; a
|
|
1062
|
-
nested one the pull request adds or edits is reported as a proposal.
|
|
1063
|
-
|
|
1064
|
-
The umbrella asks each gate its version before it runs it. On a run with a
|
|
1065
|
-
trust base, a gate older than its pull-request-mode minimum (intent-guard
|
|
1066
|
-
1.8.1, vault-guard 1.9.1, dep-guard 0.10.1) is could-not-run (exit 2),
|
|
1067
|
-
never run without the flag: without it the gate would take its rules from
|
|
1068
|
-
the tree being judged. The fix is to install that minimum or newer, or to
|
|
1069
|
-
remove an explicit older version pin. A version that cannot be read at all
|
|
1070
|
-
is could-not-run too: the umbrella cannot establish that the gate would
|
|
1071
|
-
take its rules from the base ref. The one gate that runs without the flag
|
|
1072
|
-
is an intent gate judging a contract imported from the base for the run,
|
|
1073
|
-
whose project is a temporary directory with no repository to resolve a ref
|
|
1074
|
-
in; that is never silent: it gets a line in the report, a clause on the
|
|
1075
|
-
clean one-line summary, and a `conductor/trust-base-not-passed`
|
|
1076
|
-
notification in the SARIF log.
|
|
1077
|
-
|
|
1078
|
-
Outside pull-request mode nothing changes. A pre-commit hook and a direct run
|
|
1079
|
-
on your own checkout are already inside the trust boundary, and neither passes
|
|
1080
|
-
the flag.
|
|
1081
|
-
|
|
1082
|
-
**In CI, pull-request mode needs a trust base.** A run in GitHub Actions with
|
|
1083
|
-
`GITHUB_BASE_REF` set and no `--trust-base` is could-not-run (exit 2): its
|
|
1084
|
-
rules have to come from the base branch, and no base was named. Pass `--trust-base
|
|
1085
|
-
refs/remotes/origin/<base branch>` with `fetch-depth: 0`, or use the Action,
|
|
1086
|
-
which always passes one. A pre-commit hook run inside a pull-request job hits
|
|
1087
|
-
this too: skip the hook in CI, or pass the trust base to it.
|
|
1088
|
-
|
|
1089
|
-
**On a pull-request run PATH holds only absolute entries, and conductor's own
|
|
1090
|
-
git comes from outside the repository.** Empty and relative entries are
|
|
1091
|
-
removed for conductor and every gate it starts, with one notice naming them,
|
|
1092
|
-
and conductor runs the first git on PATH that lives outside the repository's
|
|
1093
|
-
work tree; with none, the run is could-not-run and says to put git's own
|
|
1094
|
-
directory on PATH. A gate found only through a removed entry is reported
|
|
1095
|
-
missing; put it on an absolute PATH entry or name it with an absolute
|
|
1096
|
-
`command:`. Every gate conductor starts, and everything a gate starts, gets
|
|
1097
|
-
a PATH whose first entry is a private directory outside the repository
|
|
1098
|
-
holding only that same git, so a gate that runs git by name runs it too; on
|
|
1099
|
-
Windows no such directory is made and the gates look git up through the
|
|
1100
|
-
cleaned PATH, and a system temp directory inside the repository is
|
|
1101
|
-
could-not-run until TMPDIR names one outside it.
|
|
1102
|
-
|
|
1103
|
-
**git 2.31 or later** is needed on a pull-request run with the secrets-history
|
|
1104
|
-
gate (gitleaks) enabled, because conductor hands it `git log --diff-merges`,
|
|
1105
|
-
which arrived in git 2.31. Only that gate checks: an older git makes it
|
|
1106
|
-
could-not-run, naming the version, and the other gates run.
|
|
1107
|
-
|
|
1108
|
-
### Trying pull-request mode locally
|
|
1109
|
-
|
|
1110
|
-
To see roughly what CI would say about a branch, check it out and name the
|
|
1111
|
-
base as the trust base:
|
|
1112
|
-
|
|
1113
|
-
```
|
|
1114
|
-
conductor run --trust-base refs/remotes/origin/main --verbose
|
|
1115
|
-
```
|
|
1116
|
-
|
|
1117
|
-
`--trust-base` takes any ref git resolves in your clone, so use a clone with
|
|
1118
|
-
the base branch present (the CI recipes use `fetch-depth: 0` for the same
|
|
1119
|
-
reason). With no `GITHUB_BASE_REF` set, as on a laptop, the change set for the
|
|
1120
|
-
intent gate is measured from the trust base, so `--base` is optional; add
|
|
1121
|
-
`--base <ref>` to measure from a different ref. Add `--stage ci` to run at
|
|
1122
|
-
the stage the Action runs at.
|
|
1123
|
-
|
|
1124
|
-
The gotcha is the same locally as in CI: the policy and the other control
|
|
1125
|
-
files are read from the base ref, not from your working tree. A local edit to
|
|
1126
|
-
`.guardrails.yaml` has no effect on a `--trust-base` run until the change is
|
|
1127
|
-
on the base; it shows up as a proposal line in the report instead. To preview
|
|
1128
|
-
a policy edit, run `conductor run` without `--trust-base`, as in "Adopting
|
|
1129
|
-
conductor" above.
|
|
1130
|
-
|
|
1131
|
-
Where the proposals appear under the Action: the job log gets a
|
|
1132
|
-
`conductor: N control change(s) proposed in this pull request.` line followed
|
|
1133
|
-
by one `conductor: proposed <product> <line>` line per proposal, and the step
|
|
1134
|
-
summary gets the same count and up to 50 proposed lines under `control
|
|
1135
|
-
changes:` in a text block, with a `(n more in the report)` line when there are
|
|
1136
|
-
more. This does not depend on `pr-comment`. A proposed line that holds a
|
|
1137
|
-
backtick or a character outside printable ASCII is replaced by a placeholder.
|
|
1138
|
-
|
|
1139
|
-
### The preview under the proposed rules
|
|
1140
|
-
|
|
1141
|
-
A pull request that switches a gate on or off, or moves its `stage`, is judged
|
|
1142
|
-
under the base's rules, so the author would not otherwise see what the
|
|
1143
|
-
proposed rules say until after merge. With the preview, each role whose
|
|
1144
|
-
`enabled` or `stage` changed runs once more (a role the head switches off is skipped), after the verdict, under the base
|
|
1145
|
-
policy with only `enabled`, `stage` and `enforce` taken from the head. Every
|
|
1146
|
-
other head value, `command:`, `args:`, `options` and `timeout-seconds`
|
|
1147
|
-
included, never reaches it: the base's command and the base's limit are what
|
|
1148
|
-
run, and a base `command:` that resolves inside the working tree is refused
|
|
1149
|
-
there. A gate's own config is another matter: in the preview, dep-guard and
|
|
1150
|
-
vault-guard read their own `.dep-guard.json` and `.vault-guard.json` from the
|
|
1151
|
-
head, because previewing the proposed rules means their rules too, while
|
|
1152
|
-
gitleaks and osv-scanner keep the base's config. osv-scanner call analysis is
|
|
1153
|
-
refused in the preview, because it would build the head's code. The intent
|
|
1154
|
-
gate is deferred and not previewed.
|
|
1155
|
-
|
|
1156
|
-
**The preview decides nothing.** The exit code, the verdict token and the SARIF
|
|
1157
|
-
results are those of the run under the base rules, whatever the preview finds
|
|
1158
|
-
or however it fails. In the full report (`--verbose`, the form the Action
|
|
1159
|
-
reads) the first four lines are untouched; in the one-line clean form the
|
|
1160
|
-
primary report is a byte-for-byte prefix and the preview follows it. It prints after
|
|
1161
|
-
the verdict under `Preview under the proposed rules (does not affect the
|
|
1162
|
-
verdict)`, as `conductor: preview ...` lines in the job log, as note-level
|
|
1163
|
-
`conductor/preview-under-proposed-rules` notifications on the umbrella's SARIF
|
|
1164
|
-
run, and as one `preview: N gate(s), M finding(s), K could-not-run` line in
|
|
1165
|
-
the step summary. The whole preview has a hard deadline of 300 seconds; a
|
|
1166
|
-
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
|
|
1167
|
-
uses the same words as a primary section, so a finding may read `BLOCKING`
|
|
1168
|
-
there: it means the finding would block under the proposed rules, and it does
|
|
1169
|
-
not affect this run. A pull-request comment is cut at 60000 characters, the
|
|
1170
|
-
preview block first.
|
|
1171
|
-
|
|
1172
|
-
Ask for it with `--preview` on `conductor run`, or with the Action's `preview`
|
|
1173
|
-
input, which defaults to `true`; any other value turns it off. There is no
|
|
1174
|
-
preview when the head `.guardrails.yaml` does not parse.
|
|
1175
|
-
|
|
1176
|
-
## Intent at a pull request
|
|
1177
|
-
|
|
1178
|
-
The intent gate is the only one of the five with any ceremony: its native
|
|
1179
|
-
flow wants a contract approved before the work starts, which is a per-task
|
|
1180
|
-
human step. That step is exactly what a pull request cannot carry, so at the
|
|
1181
|
-
`ci` stage the umbrella stands in for it.
|
|
1182
|
-
|
|
1183
|
-
**What it measures.** With `--base <ref>`, the changed-path set is what this
|
|
1184
|
-
branch changed since it forked, from
|
|
1185
|
-
`git diff --name-only --no-renames <base>...HEAD` in the repository root.
|
|
1186
|
-
|
|
1187
|
-
With no `--base`, `GITHUB_BASE_REF` is used when it is set, spelled in full:
|
|
1188
|
-
`refs/conductor/trust-base` (the Action's private fetch of the base) if that
|
|
1189
|
-
exists, else `refs/remotes/origin/<value>`, so a tag of that name cannot
|
|
1190
|
-
shadow it. The text report says which. An explicit `--base` that matches both
|
|
1191
|
-
a tag and a branch is refused as ambiguous. With neither but a `--trust-base`
|
|
1192
|
-
(merge_group, workflow_dispatch, a CLI run), the change set is measured from
|
|
1193
|
-
the trust base. With none of the three, the intent gate runs the way
|
|
1194
|
-
it does at a commit: against the staged index, or the paths you name.
|
|
1195
|
-
|
|
1196
|
-
**This is why a local preview and a pull-request run can disagree about a
|
|
1197
|
-
missing contract.** The contract-discovery rules below (`--spec`, a frozen
|
|
1198
|
-
native contract, a `Spec:` line, the `docs/superpowers/specs` convention)
|
|
1199
|
-
only engage once `--base` resolves to something, or `--spec` is given.
|
|
1200
|
-
Neither is true of a plain `conductor run` on your own checkout, so a
|
|
1201
|
-
repository with no contract gets intent-guard's own native answer instead:
|
|
1202
|
-
`BLOCKING critical intent-guard/gate-blocked`, because that flow wants an
|
|
1203
|
-
approved contract and none exists. On a pull request `--base` is set, this
|
|
1204
|
-
whole section's machinery engages, and a branch with nothing to import
|
|
1205
|
-
lands in the no-contract state below instead: reported, and never reaching
|
|
1206
|
-
the exit code. Read a local `BLOCKING` line on the intent gate as "there is
|
|
1207
|
-
no contract for the umbrella to import here yet," not as "this pull request
|
|
1208
|
-
will fail."
|
|
1209
|
-
|
|
1210
|
-
A git failure here is **fail-closed**: could-not-run, so exit 2 for an
|
|
1211
|
-
enforced gate and a note for an unenforced one. There is deliberately no
|
|
1212
|
-
fallback to an empty path set, because an empty path set is what a passing
|
|
1213
|
-
gate looks like. In Actions this is almost always a shallow checkout, so
|
|
1214
|
-
**`actions/checkout` needs `fetch-depth: 0`** for the merge base to exist.
|
|
1215
|
-
|
|
1216
|
-
**On a pull-request run the base decides.** With `--trust-base`, whether a
|
|
1217
|
-
frozen contract governs the pull request is read from the base ref alone. A
|
|
1218
|
-
frozen contract on the base is used, ahead of everything in the list below,
|
|
1219
|
-
`--spec` included (the report says so when `--spec` was given), and the gate
|
|
1220
|
-
judges any edit to it against the base copy. That holds for every
|
|
1221
|
-
intent-guard that can run on a pull-request run, since one older than its
|
|
1222
|
-
pull-request-mode minimum is could-not-run rather than run without the base
|
|
1223
|
-
ref. With no frozen contract on the
|
|
1224
|
-
base, nothing in the pull request becomes the contract: a spec on the base,
|
|
1225
|
-
found by rules 1, 3 and 4 below, is imported from its base copy (so on such a
|
|
1226
|
-
run `--spec` must be a plain path inside the repository that the base
|
|
1227
|
-
carries), and otherwise
|
|
1228
|
-
the gate is skipped with "No contract on the base". A contract or spec the
|
|
1229
|
-
pull request adds is reported as a proposal, so adopting the intent gate
|
|
1230
|
-
merges, and the next pull request is judged against it. Retiring or replacing
|
|
1231
|
-
a frozen contract through a judged pull request is refused by the intent gate
|
|
1232
|
-
itself and needs an administrator to merge it.
|
|
1233
|
-
|
|
1234
|
-
**Where the contract comes from**, in order:
|
|
1235
|
-
|
|
1236
|
-
1. `--spec <path>` on the umbrella's own command line. Typed just now, so it
|
|
1237
|
-
outranks everything else in this list, and a path here that is not on
|
|
1238
|
-
disk is reported rather than replaced: running a different contract than
|
|
1239
|
-
the one somebody named is the wrong kindness. On a pull-request run it is
|
|
1240
|
-
read from the base, and a frozen contract on the base takes precedence.
|
|
1241
|
-
2. `<repo>/.intent-guard/intent-contract.yaml`, when it is **frozen**, and
|
|
1242
|
-
`<repo>/.conductor/intent-contract.yaml` after it. The native flow wins
|
|
1243
|
-
wherever a team has done it. Frozen is the test rather than present: an
|
|
1244
|
-
unfrozen contract is a draft somebody left behind, and running the gate
|
|
1245
|
-
against it fails every pull request on "not frozen by user" without
|
|
1246
|
-
checking anything.
|
|
1247
|
-
|
|
1248
|
-
The second path is the directory intent-guard used before 1.3.0, which
|
|
1249
|
-
renamed it because `.conductor` had become the name of a different product
|
|
1250
|
-
in this family. Both are read, so a repository on either version is
|
|
1251
|
-
checked rather than blocked, and a run that used the old one says so: one
|
|
1252
|
-
line on the gate's contract line in the text report, and an
|
|
1253
|
-
`intent-guard/legacy-state-dir` notification in the SARIF log. If the
|
|
1254
|
-
repository holds **both** directories, the gate does not run and says so,
|
|
1255
|
-
naming both: that is the state intent-guard itself refuses every command
|
|
1256
|
-
in, so the umbrella refuses on exactly the gate's rule rather than a
|
|
1257
|
-
softer one. A `.conductor` holding nothing intent-guard wrote belongs to
|
|
1258
|
-
something else and is ignored.
|
|
1259
|
-
3. The **first** `Spec: <path>` line in the pull request body, read from the
|
|
1260
|
-
event payload at `GITHUB_EVENT_PATH`. A path here that is not on disk, or
|
|
1261
|
-
one that leaves the repository, falls through to the next rule.
|
|
1262
|
-
`Spec: none` is a **waiver**: it says this pull request deliberately has
|
|
1263
|
-
no spec, so rule 4 is not tried and the gate reports itself skipped with
|
|
1264
|
-
`intent-guard/contract-waived` instead of `intent-guard/no-contract`. The
|
|
1265
|
-
token is exact and lowercase, a frozen contract at rule 2 still wins over
|
|
1266
|
-
it, and `--spec` at rule 1 still overrides it.
|
|
1267
|
-
4. A markdown file **directly under** `docs/superpowers/specs` whose name
|
|
1268
|
-
matches the branch on **whole words**. The branch slug is the branch name
|
|
1269
|
-
with its first segment (`feat/`, `fix/`) removed; a filename is reduced by
|
|
1270
|
-
stripping a `YYYY-MM-DD-` prefix and a trailing `-design`. Both have their
|
|
1271
|
-
ASCII letters lower-cased and are split into words on `-`, `_`, `/` and
|
|
1272
|
-
spaces. A spec is a candidate when one name's words appear, in order and
|
|
1273
|
-
together, inside the other's, and at least one shared word is three or
|
|
1274
|
-
more characters, contains a letter, and is not a common branch word
|
|
1275
|
-
(`fix`, `feat`, `wip`, `docs`, and the rest of the list in
|
|
1276
|
-
`src/intent-spec.ts`). Candidates are ranked by an equal name first, then
|
|
1277
|
-
the most shared words, then the longest shared word, then the lexically
|
|
1278
|
-
greatest filename among files with the same name (the newest date when
|
|
1279
|
-
every spec is dated `YYYY-MM-DD-`, so **date every spec** in that form).
|
|
1280
|
-
Two different specs that tie are **not** guessed between: the gate is
|
|
1281
|
-
skipped as `intent-guard/spec-ambiguous`, naming both. A spec chosen on
|
|
1282
|
-
one shared word, or on word length alone, is used and the report says the
|
|
1283
|
-
match is weak. Branch names like `pr` or `fix/wip` choose nothing. When
|
|
1284
|
-
the choice matters, say it: a `Spec:` line in the pull request body, or a
|
|
1285
|
-
branch named after the spec.
|
|
1286
|
-
|
|
1287
|
-
**A branch with neither** is a third state beside deferred and could-not-run:
|
|
1288
|
-
the gate is switched on, it ran, and it had nothing to check. It gets one
|
|
1289
|
-
line in the text report and one `intent-guard/no-contract` notification
|
|
1290
|
-
in the `conductor` run, and it **never** reaches the exit code, enforced or
|
|
1291
|
-
not. A branch with no spec is a branch this gate has no opinion about, and
|
|
1292
|
-
turning that into a failed build is how a gate gets switched off across a
|
|
1293
|
-
repository. A waived pull request lands in the same state and is reported
|
|
1294
|
-
under its own `intent-guard/contract-waived` id, with its own wording on the
|
|
1295
|
-
skipped line, in the verdict and on the one-line summary of a clean run, so a
|
|
1296
|
-
reader can tell "nobody has written one" from "somebody decided against one"
|
|
1297
|
-
wherever they meet it. An ambiguous branch, one two specs match equally,
|
|
1298
|
-
lands in the same advisory state under its own `intent-guard/spec-ambiguous`
|
|
1299
|
-
id, and never reaches the exit code either.
|
|
1300
|
-
|
|
1301
|
-
**A repository with no contract yet is not a repository this gate can act
|
|
1302
|
-
on**, and the no-contract skip line names `docs/superpowers/specs`, which is
|
|
1303
|
-
a convention from this family's own tooling and not one an outside adopter
|
|
1304
|
-
has reason to recognise. The next step, if you want this gate to have an
|
|
1305
|
-
opinion here, is the one intent-guard's own documentation describes: draft a
|
|
1306
|
-
contract naming the paths worth protecting, then freeze it, and keep the
|
|
1307
|
-
frozen file committed so rule 2 above finds it on every pull request from
|
|
1308
|
-
then on. Until you do that, a project rule that lives only in `AGENTS.md`
|
|
1309
|
-
never blocks anything through this gate. intent-guard does read prose rules
|
|
1310
|
-
files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, cursor rules) as constraint
|
|
1311
|
-
sources, but by its own design a constraint from that source is advisory
|
|
1312
|
-
and leaves the exit code alone; only a user-stated constraint, or one
|
|
1313
|
-
promoted with `intent-guard correct --promote`, can block. Conductor itself
|
|
1314
|
-
never opens that file. What is enforced is the frozen contract or the
|
|
1315
|
-
imported spec, never project convention documented in prose.
|
|
1316
|
-
|
|
1317
|
-
**A waiver is a decision, recorded by whoever wrote the pull request body,
|
|
1318
|
-
and that includes a contributor from a fork.** On the ordinary path, where a
|
|
1319
|
-
repository has no frozen contract of its own, `Spec: none` means the intent
|
|
1320
|
-
gate does not run at all on that pull request, and budget breaches are the
|
|
1321
|
-
thing this gate blocks on. The one thing a waiver cannot override is a frozen
|
|
1322
|
-
native contract, under either of the two paths above, which is checked first:
|
|
1323
|
-
a repository that wants the gate to be non-waivable freezes a native contract
|
|
1324
|
-
and keeps it committed. The branch-name convention is not a control either:
|
|
1325
|
-
whoever names the branch chooses among the base's specs.
|
|
1326
|
-
|
|
1327
|
-
**What blocks is unchanged.** Blocking stays where intent-guard puts it:
|
|
1328
|
-
budget breaches block, subject to `enforce`. Drift on its own is reported and
|
|
1329
|
-
not blocked, which is already intent-guard's own behaviour. The umbrella adds
|
|
1330
|
-
no severity threshold of its own here either, and intent-guard 1.7.0's own
|
|
1331
|
-
advance-notice warnings about an unmatchable `protected_paths` or
|
|
1332
|
-
`allowed_paths` entry never reach the exit code either, right up until the
|
|
1333
|
-
2.0.0 release where intent-guard turns that same shape into a blocking
|
|
1334
|
-
reason. Where they print depends on how much of the report is showing: as a
|
|
1335
|
-
note under the intent gate in the full report (`--verbose`, a non-clean run,
|
|
1336
|
-
or the pull-request comment, which the Action always renders with
|
|
1337
|
-
`--verbose`), and, on an otherwise-clean run with neither, counted without
|
|
1338
|
-
their text in the one-line summary's own note count instead.
|
|
1339
|
-
|
|
1340
|
-
**A prose-sourced constraint finding is never marked blocking, even when the
|
|
1341
|
-
run blocks for an unrelated reason.** intent-guard 1.6.0 caps a constraint
|
|
1342
|
-
whose source is one of those same prose rules files at advisory: a strong
|
|
1343
|
-
match is still reported, but it never raises the gate's own exit code. A run
|
|
1344
|
-
that blocks on scope creep alone still carries that capped finding in its
|
|
1345
|
-
report, and it is rendered as a non-blocking, lower-severity line in the text
|
|
1346
|
-
report and with `properties.blocking: false` in SARIF, rather than inheriting
|
|
1347
|
-
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.
|
|
1348
410
|
|
|
1349
411
|
## The Action
|
|
1350
412
|
|
|
@@ -1441,7 +503,8 @@ rather than running without a trust base; the token exists only in that fetch
|
|
|
1441
503
|
step and never in the gates), so the run takes
|
|
1442
504
|
its configuration from the base branch and the pull request cannot change the
|
|
1443
505
|
rules it is judged by; a change to the rules shows as a proposal line and
|
|
1444
|
-
takes effect after merge. See
|
|
506
|
+
takes effect after merge. See
|
|
507
|
+
[The pull-request trust boundary](docs/pull-request-trust-boundary.md). On any
|
|
1445
508
|
other event it passes nothing and behaviour is unchanged. The `trust-base`
|
|
1446
509
|
input names the ref explicitly, for a platform where `GITHUB_BASE_REF` is not
|
|
1447
510
|
set. **On a `pull_request` or `pull_request_target` event this input is
|
|
@@ -1469,7 +532,8 @@ request being judged, and the version-pin protection described above
|
|
|
1469
532
|
"protects nothing" against a tree that controls its own judge (the
|
|
1470
533
|
validate step's own comment in `action.yml` says so in those words). A tag
|
|
1471
534
|
moves when someone pushes it. Name this action by owner and the full commit
|
|
1472
|
-
SHA instead. The recipes in this README name
|
|
535
|
+
SHA instead. The recipes in this README name v0.15.0 that way, as
|
|
536
|
+
`vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0`.
|
|
1473
537
|
|
|
1474
538
|
```yaml
|
|
1475
539
|
name: guardrails
|
|
@@ -1489,9 +553,9 @@ jobs:
|
|
|
1489
553
|
fetch-depth: 0
|
|
1490
554
|
- uses: actions/setup-node@v7
|
|
1491
555
|
with:
|
|
1492
|
-
node-version: '22.
|
|
556
|
+
node-version: '22.23.4'
|
|
1493
557
|
- id: conductor
|
|
1494
|
-
uses: vaultcompasshq/conductor@v0.
|
|
558
|
+
uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
|
|
1495
559
|
with:
|
|
1496
560
|
output: conductor.sarif
|
|
1497
561
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -1523,10 +587,32 @@ pinned `action.yml`, which is the version that commit ships, so the installed
|
|
|
1523
587
|
umbrella follows the pin and a Dependabot bump is the one `uses` line. If the
|
|
1524
588
|
input is set and is older than the constants in that pinned action.yml, a
|
|
1525
589
|
pull request run is refused and the validate step says to remove the input. A
|
|
1526
|
-
newer value is accepted and is what gets installed.
|
|
1527
|
-
|
|
1528
|
-
|
|
1529
|
-
|
|
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.
|
|
1530
616
|
|
|
1531
617
|
```yaml
|
|
1532
618
|
name: guardrails
|
|
@@ -1554,8 +640,10 @@ jobs:
|
|
|
1554
640
|
# Not a bare major: Node 22.0.0 ships npm 10.5.1, which the action
|
|
1555
641
|
# refuses because that client reports a clean install as tampered
|
|
1556
642
|
# with. 22.1.0 or later, or 20.13.0 or later, carries an npm that
|
|
1557
|
-
# can verify.
|
|
1558
|
-
|
|
643
|
+
# can verify. 22.23.4 is the patched release this repository's own
|
|
644
|
+
# release job pins after the 2026-10-21 Node security release; the
|
|
645
|
+
# gates run over pull-request content under whatever Node you pick.
|
|
646
|
+
node-version: '22.23.4'
|
|
1559
647
|
# NOTHING FROM THE PULL REQUEST RUNS BEFORE THE ACTION IN THIS JOB.
|
|
1560
648
|
# No `pnpm install`, `npm ci`, build or test step: an install runs the
|
|
1561
649
|
# repository's own lifecycle scripts (a root postinstall), and that code
|
|
@@ -1566,7 +654,7 @@ jobs:
|
|
|
1566
654
|
# installs those itself, globally. Leave conductor-version unset so the
|
|
1567
655
|
# umbrella is the default in the pinned action.yml.
|
|
1568
656
|
- id: conductor
|
|
1569
|
-
uses: vaultcompasshq/conductor@v0.
|
|
657
|
+
uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
|
|
1570
658
|
with:
|
|
1571
659
|
output: conductor.sarif
|
|
1572
660
|
# Exact versions, never a range and never "latest". These three
|
|
@@ -1577,9 +665,9 @@ jobs:
|
|
|
1577
665
|
# request of their own. On a pull request the action refuses a pin
|
|
1578
666
|
# below what the pinned action.yml ships, and the three lines can
|
|
1579
667
|
# be left out entirely to take that action's own versions.
|
|
1580
|
-
dep-guard-version: 0.
|
|
1581
|
-
vault-guard-version: 1.
|
|
1582
|
-
intent-guard-version: 1.10.
|
|
668
|
+
dep-guard-version: 0.18.0
|
|
669
|
+
vault-guard-version: 1.13.0
|
|
670
|
+
intent-guard-version: 1.10.3
|
|
1583
671
|
- uses: github/codeql-action/upload-sarif@v3
|
|
1584
672
|
# Always: the log is most worth having on the run that failed.
|
|
1585
673
|
if: always()
|
|
@@ -1603,7 +691,7 @@ jobs:
|
|
|
1603
691
|
- uses: pnpm/action-setup@v4
|
|
1604
692
|
- uses: actions/setup-node@v7
|
|
1605
693
|
with:
|
|
1606
|
-
node-version: '22.
|
|
694
|
+
node-version: '22.23.4'
|
|
1607
695
|
cache: pnpm
|
|
1608
696
|
- run: pnpm install --frozen-lockfile
|
|
1609
697
|
- run: pnpm test
|
|
@@ -1745,12 +833,19 @@ days (issue #36) because the step's exit code was swallowed regardless of
|
|
|
1745
833
|
which of the two reasons produced it. `advisory` fixes the failure that
|
|
1746
834
|
caused that; `continue-on-error` is the thing that let it happen, so the two
|
|
1747
835
|
do not belong in the same recipe. Set a step `timeout-minutes` as well: the
|
|
1748
|
-
Action already caps each gate's own subprocess
|
|
1749
|
-
|
|
1750
|
-
|
|
1751
|
-
|
|
1752
|
-
|
|
1753
|
-
|
|
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
|
|
1754
849
|
out with `persist-credentials: false` so the gates never run with a token
|
|
1755
850
|
left in the checkout's git config.
|
|
1756
851
|
|
|
@@ -1775,11 +870,13 @@ jobs:
|
|
|
1775
870
|
persist-credentials: false
|
|
1776
871
|
- uses: actions/setup-node@v7
|
|
1777
872
|
with:
|
|
1778
|
-
node-version: '22.
|
|
873
|
+
node-version: '22.23.4'
|
|
1779
874
|
- id: conductor
|
|
1780
|
-
# The
|
|
1781
|
-
|
|
1782
|
-
|
|
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@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
|
|
1783
880
|
with:
|
|
1784
881
|
pr-comment: true
|
|
1785
882
|
advisory: true
|
|
@@ -1865,7 +962,7 @@ change and forget the other half.
|
|
|
1865
962
|
|
|
1866
963
|
### Adopting conductor
|
|
1867
964
|
|
|
1868
|
-
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
|
|
1869
966
|
walkthrough: init, a first pull request in advisory mode, merge, then go
|
|
1870
967
|
required. This subsection is the mechanism behind two of those steps.
|
|
1871
968
|
|
|
@@ -1915,7 +1012,7 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1915
1012
|
# the pull request runs before the action in this job: no install, build
|
|
1916
1013
|
# or test step here; those belong in a separate job. ...
|
|
1917
1014
|
- id: conductor
|
|
1918
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1015
|
+
uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
|
|
1919
1016
|
with:
|
|
1920
1017
|
output: conductor.sarif
|
|
1921
1018
|
pr-comment: true
|
|
@@ -1937,7 +1034,7 @@ comment every time, the way the manual recipe below does. It runs on a
|
|
|
1937
1034
|
gates step passed or failed, since a blocking run is the one an advisory
|
|
1938
1035
|
check most needs a developer to actually see. The first line of every
|
|
1939
1036
|
comment carries the version of conductor that produced it, the second line
|
|
1940
|
-
carries the verdict token (see
|
|
1037
|
+
carries the verdict token (see [The verdict token](docs/commands.md#the-verdict-token)), and when the
|
|
1941
1038
|
trust base was refused and no gate ran at all, the comment shrinks to the
|
|
1942
1039
|
version, the verdict, and the refusal reason (with its remedy, when one
|
|
1943
1040
|
applies) rather than the full per-gate report, so an adopter with no policy
|
|
@@ -1994,12 +1091,12 @@ per pull request.
|
|
|
1994
1091
|
|
|
1995
1092
|
```yaml
|
|
1996
1093
|
- id: conductor-package-a
|
|
1997
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1094
|
+
uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
|
|
1998
1095
|
with:
|
|
1999
1096
|
pr-comment: true
|
|
2000
1097
|
pr-comment-marker: 'package-a'
|
|
2001
1098
|
- id: conductor-package-b
|
|
2002
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1099
|
+
uses: vaultcompasshq/conductor@257830bd4b94a81419189b641508f1dda0950d00 # v0.15.0
|
|
2003
1100
|
with:
|
|
2004
1101
|
pr-comment: true
|
|
2005
1102
|
pr-comment-marker: 'package-b'
|
|
@@ -2099,67 +1196,6 @@ is one snapshot of one run: no per-finding state, nothing to dismiss, no
|
|
|
2099
1196
|
history between runs, and a new comment every time rather than an alert that
|
|
2100
1197
|
closes when the finding goes away.
|
|
2101
1198
|
|
|
2102
|
-
## Upgrading
|
|
2103
|
-
|
|
2104
|
-
An adopter pins two numbers, and they control different things.
|
|
2105
|
-
|
|
2106
|
-
- **The action ref**, `uses: vaultcompasshq/conductor@<tag or SHA>`, picks
|
|
2107
|
-
which `action.yml` runs. That file carries the defaults for the four
|
|
2108
|
-
version inputs and the constants the pull-request backward-pin rule
|
|
2109
|
-
measures a pin against.
|
|
2110
|
-
- **The `conductor-version` input** picks which `@vaultcompass/conductor`
|
|
2111
|
-
the install step installs. The same step installs the three gates at
|
|
2112
|
-
`dep-guard-version`, `vault-guard-version` and `intent-guard-version`.
|
|
2113
|
-
Each input defaults to the version the tag shipped.
|
|
2114
|
-
|
|
2115
|
-
**The recommended shape is to leave all four version inputs unset** and move
|
|
2116
|
-
only the action ref. On a pull request, the validate step refuses an input
|
|
2117
|
-
naming a version below the one the tag ships, so an explicit old pin breaks
|
|
2118
|
-
the day you upgrade the ref (see "The Action" above). Outside a pull request
|
|
2119
|
-
an explicit pin is unaffected, which is how a stale pin can sit unnoticed
|
|
2120
|
-
until the first pull request after the upgrade.
|
|
2121
|
-
|
|
2122
|
-
**Pin the action ref to a full commit SHA** with the tag as a comment, for
|
|
2123
|
-
example `uses: vaultcompasshq/conductor@<40-character SHA> # v0.14.0`. To
|
|
2124
|
-
find the SHA for a tag, run
|
|
2125
|
-
`gh api repos/vaultcompasshq/conductor/git/ref/tags/v0.12.0` or read it off
|
|
2126
|
-
the Releases page.
|
|
2127
|
-
|
|
2128
|
-
**Dependabot or Renovate bumping that SHA changes the action ref only.** It
|
|
2129
|
-
does not touch a `dep-guard-version`, `vault-guard-version`,
|
|
2130
|
-
`intent-guard-version` or `conductor-version` you set by hand, so such a pin
|
|
2131
|
-
must be raised or removed by hand in the same pull request, or that pull
|
|
2132
|
-
request is refused by the rule above.
|
|
2133
|
-
|
|
2134
|
-
**An action-only tag moves the tag while the npm package stays.** The
|
|
2135
|
-
CHANGELOG marks these as "An action-only release" and says which
|
|
2136
|
-
`conductor-version` default stays. `@vaultcompass/conductor` does not change
|
|
2137
|
-
on those, so `conductor-version` need not change either; the gate defaults
|
|
2138
|
-
may.
|
|
2139
|
-
|
|
2140
|
-
Defaults per tag, taken only from CHANGELOG.md entries that state them. A
|
|
2141
|
-
tag with no row here has an entry that does not state its defaults; read
|
|
2142
|
-
`action.yml` at that tag.
|
|
2143
|
-
|
|
2144
|
-
| Action tag | Kind | `conductor-version` default | Gate defaults the entry says moved |
|
|
2145
|
-
| --- | --- | --- | --- |
|
|
2146
|
-
| v0.14.0 | package | 0.14.0 | none (gate defaults unchanged) |
|
|
2147
|
-
| v0.13.2 | package | 0.13.2 | none (gate defaults unchanged) |
|
|
2148
|
-
| v0.13.1 | action-only | 0.13.0 | dep-guard 0.16.1 (from 0.15.0) |
|
|
2149
|
-
| v0.13.0 | package | 0.13.0 | none (gate defaults unchanged) |
|
|
2150
|
-
| 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) |
|
|
2151
|
-
| 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) |
|
|
2152
|
-
| v0.11.0 | package | 0.11.0 | dep-guard 0.14.0, intent-guard 1.10.0 |
|
|
2153
|
-
| v0.10.0 | package | 0.10.0 | dep-guard 0.13.0, vault-guard 1.11.0 |
|
|
2154
|
-
| v0.8.2 | action-only | 0.8.1 | dep-guard 0.11.1 (from 0.10.1) |
|
|
2155
|
-
| v0.8.1 | package | 0.8.1 | dep-guard 0.10.1, vault-guard 1.9.1, intent-guard 1.8.1 |
|
|
2156
|
-
| v0.8.0 | package | 0.8.0 | dep-guard 0.10.0, vault-guard 1.9.0, intent-guard 1.8.0 |
|
|
2157
|
-
| v0.7.0 | package | 0.7.0 | none |
|
|
2158
|
-
| 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) |
|
|
2159
|
-
| 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) |
|
|
2160
|
-
| 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) |
|
|
2161
|
-
| v0.4.3 | action-only | 0.4.0 | intent-guard 1.5.2 (from 1.4.0) |
|
|
2162
|
-
|
|
2163
1199
|
## What is in and what is out
|
|
2164
1200
|
|
|
2165
1201
|
In: the policy file and its schema, `init` with dry-run, revert, and adopt,
|