@vaultcompass/conductor 0.4.6 → 0.5.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 +526 -169
- package/dist/cli.js +47 -9
- package/dist/envelope.js +1 -1
- package/dist/exit-codes.js +5 -1
- package/dist/external-config.d.ts +54 -0
- package/dist/external-config.js +171 -0
- package/dist/gate-runner.d.ts +43 -3
- package/dist/gate-runner.js +463 -37
- package/dist/init-policy.d.ts +19 -1
- package/dist/init-policy.js +42 -8
- package/dist/init.d.ts +30 -1
- package/dist/init.js +108 -19
- package/dist/normalize.d.ts +7 -1
- package/dist/normalize.js +309 -5
- package/dist/output-sarif.js +3 -2
- package/dist/output-text.d.ts +41 -0
- package/dist/output-text.js +68 -9
- package/dist/policy.d.ts +10 -4
- package/dist/policy.js +100 -14
- package/dist/products.d.ts +91 -0
- package/dist/products.js +123 -0
- package/dist/resolve.js +18 -4
- package/dist/run.js +3 -0
- package/package.json +1 -1
- package/schema/guardrails.schema.json +7 -5
package/README.md
CHANGED
|
@@ -1,8 +1,34 @@
|
|
|
1
1
|
# conductor
|
|
2
2
|
|
|
3
|
-
conductor is the
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
conductor is the one required check for a repository an AI agent edits. It
|
|
4
|
+
runs the scanners a maintainer already trusts, and adds the checks those
|
|
5
|
+
scanners cannot do on their own: a hallucinated package name, a credential
|
|
6
|
+
caught before the edit lands, a pull request that edits its own gate, a
|
|
7
|
+
change that reaches outside what was approved for it.
|
|
8
|
+
|
|
9
|
+
It does that by running five gates over one policy file, one init, one
|
|
10
|
+
hook and one report: three from this family, and two the adopter already
|
|
11
|
+
installs, gitleaks for secrets anywhere in git history and osv-scanner for
|
|
12
|
+
known vulnerabilities. conductor scans nothing itself and installs nothing
|
|
13
|
+
that is not its own. Delete conductor and every one of those five still
|
|
14
|
+
runs, with exactly the configuration it had.
|
|
15
|
+
|
|
16
|
+
The claim is checked in public. The
|
|
17
|
+
[conductor-proof](https://github.com/vaultcompasshq/conductor-proof)
|
|
18
|
+
repository runs an ordinary gitleaks and osv-scanner job beside conductor,
|
|
19
|
+
with four pull requests left open on purpose, one planted problem each.
|
|
20
|
+
Read the checks on each pull request rather than this table.
|
|
21
|
+
|
|
22
|
+
| Planted problem | Ordinary job | conductor |
|
|
23
|
+
| --- | --- | --- |
|
|
24
|
+
| [A dependency whose name does not exist on npm](https://github.com/vaultcompasshq/conductor-proof/pull/6) | pass | fail |
|
|
25
|
+
| [A pull request that turns off its own checks, then adds that dependency](https://github.com/vaultcompasshq/conductor-proof/pull/7) | skipped | fail |
|
|
26
|
+
| [A credential-shaped string in a test fixture](https://github.com/vaultcompasshq/conductor-proof/pull/8) | fail | fail |
|
|
27
|
+
| [An edit to a path the intent contract protects](https://github.com/vaultcompasshq/conductor-proof/pull/11) | pass | fail |
|
|
28
|
+
|
|
29
|
+
The third row is parity, not a catch: both jobs see a credential shape.
|
|
30
|
+
The other three are what a scanner that only knows about vulnerabilities
|
|
31
|
+
and secrets has no way to know.
|
|
6
32
|
|
|
7
33
|
<!-- guardrails-family: shared block, keep it identical in dep-guard, vault-guard, intent-guard and conductor -->
|
|
8
34
|
The Vault & Compass guardrails are three gates over an AI-assisted coding
|
|
@@ -20,17 +46,192 @@ optional umbrella that runs them from one policy file, one hook and one
|
|
|
20
46
|
report.
|
|
21
47
|
<!-- /guardrails-family -->
|
|
22
48
|
|
|
49
|
+
## Adopting conductor
|
|
50
|
+
|
|
51
|
+
The first pull request under a policy conductor just added cannot be judged
|
|
52
|
+
by that policy, so plan for a short, ordered sequence rather than one
|
|
53
|
+
command: init, a first pull request in advisory mode, merge, then go
|
|
54
|
+
required.
|
|
55
|
+
|
|
56
|
+
1. **Init.** Install the gates. Each of them is a working tool on its own,
|
|
57
|
+
and none of them needs this one:
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
npm install -g @vaultcompass/dep-guard @vaultcompass/vault-guard @vaultcompass/intent-guard
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The umbrella is optional. Install it when running the three separately
|
|
64
|
+
has become the annoying part:
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
npm install -g @vaultcompass/conductor
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
The two external gates are installed by you, on your machine and in your
|
|
71
|
+
workflow, from their own releases: [gitleaks](https://github.com/gitleaks/gitleaks)
|
|
72
|
+
8.19 or later and [osv-scanner](https://github.com/google/osv-scanner)
|
|
73
|
+
2.x. conductor never downloads either one. It finds them on `PATH`, and
|
|
74
|
+
when one is enabled in the policy and missing, the run reports
|
|
75
|
+
could-not-run (exit 2) with the install step in the report. Two policy
|
|
76
|
+
lines switch them on:
|
|
77
|
+
|
|
78
|
+
```yaml
|
|
79
|
+
gates:
|
|
80
|
+
secrets-history:
|
|
81
|
+
product: gitleaks
|
|
82
|
+
vulnerabilities:
|
|
83
|
+
product: osv-scanner
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**Globally, and that is the guidance for CI too.** A devDependency is
|
|
87
|
+
fine beside it for your own pre-commit hook, and nothing about a local
|
|
88
|
+
run changed. It is not what gates your pull requests: on a pull-request
|
|
89
|
+
run the umbrella never looks in `node_modules/.bin` at all, because what
|
|
90
|
+
is installed there is chosen by the head's own manifest and lockfile. The
|
|
91
|
+
Action installs all four packages itself, globally, at versions pinned in
|
|
92
|
+
your workflow file. See "The pull-request trust boundary" and "The
|
|
93
|
+
Action" below.
|
|
94
|
+
|
|
95
|
+
From the repository root, look before you write:
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
conductor init --dry-run
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
That prints every file it would write or change and writes nothing. Then:
|
|
102
|
+
|
|
103
|
+
```
|
|
104
|
+
conductor init
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
which writes `.guardrails.yaml` with every gate listed and only the ones
|
|
108
|
+
it found switched on, and `.guardrails/manifest.json`, the record init
|
|
109
|
+
reads back on a later `--revert`. The intent gate is written unenforced
|
|
110
|
+
unless a frozen contract already exists at `.intent-guard/intent-contract.yaml`,
|
|
111
|
+
in which case init enforces it from the start rather than leaving a
|
|
112
|
+
frozen contract's protected paths reporting without blocking. **It writes
|
|
113
|
+
no pre-commit hook unless you ask for one:**
|
|
114
|
+
|
|
115
|
+
```
|
|
116
|
+
conductor init --hook
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
adds one pre-commit hook on top of that, running every enabled gate whose
|
|
120
|
+
stage is `commit`. A CI-only adopter that never runs conductor locally can
|
|
121
|
+
stop at the first `conductor init`, with no hook at all.
|
|
122
|
+
|
|
123
|
+
**`.git/hooks` is never part of a clone**, so a hook one checkout has does
|
|
124
|
+
not follow a teammate's clone, or a fresh clone of your own: hooks are per
|
|
125
|
+
clone and per machine. Each clone that wants the hook runs
|
|
126
|
+
`conductor init --hook` once; a repository that already has
|
|
127
|
+
`.guardrails.yaml` gets only the hook from that run, since init never
|
|
128
|
+
rewrites a policy file that already exists.
|
|
129
|
+
|
|
130
|
+
Do not wire this into a `package.json` `prepare` script. A failing init
|
|
131
|
+
(no `.git` in a Docker build, a foreign hook already installed, husky's
|
|
132
|
+
own `prepare` key, or conductor not yet installed at install time) would
|
|
133
|
+
fail `npm install` itself for everyone who runs it, not only for the
|
|
134
|
+
person who wanted the hook.
|
|
135
|
+
|
|
136
|
+
**`.guardrails/manifest.json` records the absolute path on the machine
|
|
137
|
+
that ran `init`**, for the hook, when there is one, and for the policy
|
|
138
|
+
file alike, and
|
|
139
|
+
conductor does not add a `.gitignore` entry for it. That path is specific
|
|
140
|
+
to your checkout, so do not commit the file: add
|
|
141
|
+
`.guardrails/manifest.json` to your own `.gitignore` today. The file
|
|
142
|
+
lives inside your working tree so `--revert` can find it later, and
|
|
143
|
+
recording repo-relative paths there instead of absolute ones is a known
|
|
144
|
+
gap, not a design; it has not been fixed yet.
|
|
145
|
+
|
|
146
|
+
Commit something, now that `--hook` above has installed the pre-commit
|
|
147
|
+
hook (this walkthrough's output below only appears when the hook is
|
|
148
|
+
installed; a bare `conductor init` with no `--hook` runs no gate on
|
|
149
|
+
commit at all). A clean commit prints one line:
|
|
150
|
+
|
|
151
|
+
```
|
|
152
|
+
conductor: clean, nothing blocked. 2 gate(s) ran: dependencies (dep-guard), secrets (vault-guard). Deferred to a later stage: intent (intent-guard) from stage ci. 1 note(s). Re-run with --verbose for the full report.
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
A commit with a staged credential in it prints the full report and exits 1:
|
|
156
|
+
|
|
157
|
+
```
|
|
158
|
+
conductor 0.5.0
|
|
159
|
+
conductor run: 2 gate(s), 1 finding(s)
|
|
160
|
+
|
|
161
|
+
dependencies dep-guard 0.2.1 exit 0 251ms via dep-guard on path
|
|
162
|
+
threshold medium suppressed 0 ignored 0
|
|
163
|
+
|
|
164
|
+
secrets vault-guard 1.4.6 exit 1 97ms via vault-guard on path
|
|
165
|
+
BLOCKING critical vault-guard/anthropic jest.config.mjs:27:32
|
|
166
|
+
Possible secret of type 'anthropic'
|
|
167
|
+
threshold medium suppressed 0 ignored not reported
|
|
168
|
+
|
|
169
|
+
deferred intent intent-guard did not run here; it runs from stage ci onwards
|
|
170
|
+
|
|
171
|
+
verdict: exit 1, 1 blocking finding(s) across 2 gate(s).
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Both gates there are the ones you installed a moment ago, running with
|
|
175
|
+
their own thresholds and their own baselines. The umbrella found nothing
|
|
176
|
+
of its own, because it looks for nothing of its own.
|
|
177
|
+
|
|
178
|
+
Before opening anything, run `conductor run --verbose` on this same
|
|
179
|
+
checkout. That is the full report your policy will produce for the
|
|
180
|
+
dependency and secrets gates, with no `--trust-base` involved: a direct
|
|
181
|
+
run on your own checkout is already inside the trust boundary, so it
|
|
182
|
+
reads the policy you just wrote. **It is not the full preview for the
|
|
183
|
+
intent gate.** Locally, with no `--base`, the intent gate runs the way it
|
|
184
|
+
runs at a commit: intent-guard's own native flow, which wants an approved
|
|
185
|
+
contract and reports `BLOCKING critical intent-guard/gate-blocked` when
|
|
186
|
+
there is none. On a pull request a base ref resolves (conductor reads
|
|
187
|
+
`GITHUB_BASE_REF`, which GitHub sets for the whole job on a
|
|
188
|
+
`pull_request` event), and the umbrella instead prepares a contract for the
|
|
189
|
+
intent gate itself; with no contract to import, that path reports the
|
|
190
|
+
gate `skipped ... no contract` and never reaches the exit code. So a
|
|
191
|
+
first pull request with no contract yet is not blocked by the intent gate
|
|
192
|
+
on the pull request, whatever the local preview showed a moment before.
|
|
193
|
+
See "Intent at a pull request" below for the full mechanism.
|
|
194
|
+
|
|
195
|
+
2. **Open the first pull request in advisory mode.** Add `.guardrails.yaml`
|
|
196
|
+
and the workflow together, with `advisory: true` and `pr-comment: true`
|
|
197
|
+
on the conductor step -- the recipe under "Running the gates as an
|
|
198
|
+
advisory check" below is a complete copy-paste job -- and leave the check
|
|
199
|
+
out of branch protection for this one pull request. The step still exits
|
|
200
|
+
2 on this pull request even with `advisory: true`: the base branch has no
|
|
201
|
+
policy yet, so the run has no rules, and `advisory` never touches that
|
|
202
|
+
exit code, only a blocking finding's. Leaving the check out of branch
|
|
203
|
+
protection is what keeps that expected exit 2 from blocking the merge;
|
|
204
|
+
the step posts a comment saying so with the remedy on it, which is the
|
|
205
|
+
honest report of an unfinished adoption, not a broken tool.
|
|
206
|
+
|
|
207
|
+
3. **Merge.** Every pull request after that is judged by the policy on the
|
|
208
|
+
base branch, and a change to that policy shows up as a proposal line and
|
|
209
|
+
takes effect after its own merge.
|
|
210
|
+
|
|
211
|
+
4. **Go required.** Once a few ordinary pull requests have shown the report
|
|
212
|
+
reads the way you expect, remove `advisory: true` from the conductor step
|
|
213
|
+
and require the job's own check context in branch protection -- `gates`
|
|
214
|
+
in the recipes below, the job name, never the context the SARIF-upload
|
|
215
|
+
step reports under. That is the whole of turning this from an advisory
|
|
216
|
+
job into the one required check.
|
|
217
|
+
|
|
218
|
+
There is deliberately no mode in which the pull request's own policy file
|
|
219
|
+
decides the run, not even as a preview: step 1's preview gives you the same
|
|
220
|
+
report without putting a file the pull request controls behind a verdict on
|
|
221
|
+
the pull request page.
|
|
222
|
+
|
|
23
223
|
## Why
|
|
24
224
|
|
|
25
|
-
Run all three and you have three inits, three config files,
|
|
26
|
-
shapes, and three pre-commit hooks fighting over one file
|
|
225
|
+
Run all three family gates and you have three inits, three config files,
|
|
226
|
+
three output shapes, and three pre-commit hooks fighting over one file, and
|
|
227
|
+
a separate job for the two external scanners. That is the
|
|
27
228
|
friction this repository removes, and that is all it removes:
|
|
28
229
|
|
|
29
230
|
- **one policy file**, `.guardrails.yaml`, keyed by the role each gate
|
|
30
231
|
fills rather than by the product filling it;
|
|
31
|
-
- **one init**, which writes that file and a single
|
|
32
|
-
every enabled gate whose stage is `commit`, which
|
|
33
|
-
but the intent one;
|
|
232
|
+
- **one init**, which writes that file, and with `--hook` a single
|
|
233
|
+
pre-commit hook running every enabled gate whose stage is `commit`, which
|
|
234
|
+
by default is every gate but the intent one;
|
|
34
235
|
- **one report**, as text for a terminal or as a single SARIF 2.1.0 log
|
|
35
236
|
with one run per gate.
|
|
36
237
|
|
|
@@ -40,79 +241,10 @@ with ceremony rather than runtime named as the cost. A screenful of per-gate
|
|
|
40
241
|
detail on a commit that found nothing is that cost, paid on every commit, and
|
|
41
242
|
it is what makes a team switch a hook off.
|
|
42
243
|
|
|
43
|
-
## Quickstart
|
|
44
|
-
|
|
45
|
-
Install the gates. Each of them is a working tool on its own, and none of
|
|
46
|
-
them needs this one:
|
|
47
|
-
|
|
48
|
-
```
|
|
49
|
-
npm install -g @vaultcompass/dep-guard @vaultcompass/vault-guard @vaultcompass/intent-guard
|
|
50
|
-
```
|
|
51
|
-
|
|
52
|
-
The umbrella is optional. Install it when running the three separately has
|
|
53
|
-
become the annoying part:
|
|
54
|
-
|
|
55
|
-
```
|
|
56
|
-
npm install -g @vaultcompass/conductor
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
**Globally, and that is the guidance for CI too.** A devDependency is fine
|
|
60
|
-
beside it for your own pre-commit hook, and nothing about a local run changed.
|
|
61
|
-
It is not what gates your pull requests: on a pull-request run the umbrella
|
|
62
|
-
never looks in `node_modules/.bin` at all, because what is installed there is
|
|
63
|
-
chosen by the head's own manifest and lockfile. The Action installs all four
|
|
64
|
-
packages itself, globally, at versions pinned in your workflow file. See "The
|
|
65
|
-
pull-request trust boundary" and "The Action" below.
|
|
66
|
-
|
|
67
|
-
From the repository root, look before you write:
|
|
68
|
-
|
|
69
|
-
```
|
|
70
|
-
conductor init --dry-run
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
That prints every file it would write or change and writes nothing. Then:
|
|
74
|
-
|
|
75
|
-
```
|
|
76
|
-
conductor init
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
which writes `.guardrails.yaml` with every gate listed and only the ones it
|
|
80
|
-
found switched on, plus one pre-commit hook running every enabled gate whose
|
|
81
|
-
stage is `commit`.
|
|
82
|
-
|
|
83
|
-
Commit something. A clean commit prints one line:
|
|
84
|
-
|
|
85
|
-
```
|
|
86
|
-
conductor: clean, nothing blocked. 2 gate(s) ran: dependencies (dep-guard), secrets (vault-guard). Deferred to a later stage: intent (intent-guard) from stage ci. 1 note(s). Re-run with --verbose for the full report.
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
A commit with a staged credential in it prints the full report and exits 1:
|
|
90
|
-
|
|
91
|
-
```
|
|
92
|
-
conductor 0.4.6
|
|
93
|
-
conductor run: 2 gate(s), 1 finding(s)
|
|
94
|
-
|
|
95
|
-
dependencies dep-guard 0.2.1 exit 0 251ms via dep-guard on path
|
|
96
|
-
threshold medium suppressed 0 ignored 0
|
|
97
|
-
|
|
98
|
-
secrets vault-guard 1.4.6 exit 1 97ms via vault-guard on path
|
|
99
|
-
BLOCKING critical vault-guard/anthropic jest.config.mjs:27:32
|
|
100
|
-
Possible secret of type 'anthropic'
|
|
101
|
-
threshold medium suppressed 0 ignored not reported
|
|
102
|
-
|
|
103
|
-
deferred intent intent-guard did not run here; it runs from stage ci onwards
|
|
104
|
-
|
|
105
|
-
verdict: exit 1, 1 blocking finding(s) across 2 gate(s).
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
Both gates there are the ones you installed a moment ago, running with their
|
|
109
|
-
own thresholds and their own baselines. The umbrella found nothing of its
|
|
110
|
-
own, because it looks for nothing of its own.
|
|
111
|
-
|
|
112
244
|
## What it deliberately is not
|
|
113
245
|
|
|
114
|
-
It is not a
|
|
115
|
-
Every finding about your code came from one of the
|
|
246
|
+
It is not a sixth gate. It finds no bugs of its own and scans nothing.
|
|
247
|
+
Every finding about your code came from one of the five gates and is
|
|
116
248
|
labelled with which one. The only findings it adds are about the gates
|
|
117
249
|
themselves, and they are labelled `conductor`: a gate that is switched on
|
|
118
250
|
and could not run, and a gate whose output it could not read. Those exist
|
|
@@ -122,8 +254,8 @@ whole family exists to prevent.
|
|
|
122
254
|
It is not something you adopt before the gates are useful. Each gate keeps
|
|
123
255
|
its own config file, its own baseline, its own thresholds, and its own exit
|
|
124
256
|
codes. The umbrella never writes into any of them: it passes a policy to
|
|
125
|
-
each gate as command-line flags, which every one of
|
|
126
|
-
|
|
257
|
+
each gate as command-line flags, which every one of them already treats as
|
|
258
|
+
higher precedence than its own config. Delete this tool and every
|
|
127
259
|
gate still runs, with exactly the configuration it had, because nothing
|
|
128
260
|
here ever touched it.
|
|
129
261
|
|
|
@@ -161,13 +293,26 @@ gates:
|
|
|
161
293
|
enforce: false
|
|
162
294
|
options:
|
|
163
295
|
require-frozen: false
|
|
296
|
+
secrets-history:
|
|
297
|
+
product: gitleaks
|
|
298
|
+
enabled: true
|
|
299
|
+
stage: ci
|
|
300
|
+
enforce: true
|
|
301
|
+
vulnerabilities:
|
|
302
|
+
product: osv-scanner
|
|
303
|
+
enabled: true
|
|
304
|
+
stage: ci
|
|
305
|
+
enforce: true
|
|
164
306
|
|
|
165
307
|
report:
|
|
166
308
|
format: text
|
|
167
309
|
```
|
|
168
310
|
|
|
169
|
-
**Gates are keyed by role**, not by product. `dependencies
|
|
170
|
-
`
|
|
311
|
+
**Gates are keyed by role**, not by product. `dependencies` (dep-guard),
|
|
312
|
+
`secrets` (vault-guard), `intent` (intent-guard), `secrets-history`
|
|
313
|
+
(gitleaks, scanning git history) and `vulnerabilities` (osv-scanner, over
|
|
314
|
+
the resolved dependency tree). The `product` field says which binary fills
|
|
315
|
+
that role today. The last two are external tools you install yourself.
|
|
171
316
|
|
|
172
317
|
**`enabled`** defaults to true. A gate that is enabled and whose binary
|
|
173
318
|
cannot be found is a blocking finding of the umbrella's own
|
|
@@ -176,7 +321,9 @@ cannot be found is a blocking finding of the umbrella's own
|
|
|
176
321
|
**`stage`** says when a gate runs: `commit`, `push`, or `ci`. Stages are
|
|
177
322
|
**cumulative** in that order, so a gate runs at its own stage and at every
|
|
178
323
|
later one, and a run at `ci` runs everything that is enabled. The defaults
|
|
179
|
-
are `commit` for `dependencies` and `secrets
|
|
324
|
+
are `commit` for `dependencies` and `secrets`, and `ci` for `intent`,
|
|
325
|
+
`secrets-history` and `vulnerabilities`: a history scan and a registry
|
|
326
|
+
lookup are pull-request work, not commit-time work.
|
|
180
327
|
|
|
181
328
|
A gate held back by the stage filter is never silent. It is one line in the
|
|
182
329
|
text report naming the stage it is waiting for, and a `conductor/gate-deferred`
|
|
@@ -190,7 +337,14 @@ enforced gate's do. The only thing it cannot do is change the exit code: its
|
|
|
190
337
|
blocking findings do not raise it, and its failing to run at all does not
|
|
191
338
|
make the run exit 2. That is the adoption ramp, so a gate can be switched on
|
|
192
339
|
and read for a few weeks before it is allowed to refuse anybody's commit.
|
|
193
|
-
`init` writes it out for every gate
|
|
340
|
+
`init` writes it out for every gate. For the intent gate it writes `true`
|
|
341
|
+
when a frozen contract already exists at init time
|
|
342
|
+
(`.intent-guard/intent-contract.yaml`, or the pre-1.3.0
|
|
343
|
+
`.conductor/intent-contract.yaml`), since the ramp is already climbed by
|
|
344
|
+
then, and leaving it unenforced would silently let a frozen contract's
|
|
345
|
+
protected paths produce findings that never fail the check. It writes
|
|
346
|
+
`false`, with a comment explaining why, when there is no contract yet to
|
|
347
|
+
enforce against.
|
|
194
348
|
|
|
195
349
|
**`options`** is handed to that gate unchanged. Each key is one of that
|
|
196
350
|
gate's own long flags with the leading dashes stripped: `fail-on: high`
|
|
@@ -198,10 +352,18 @@ becomes `--fail-on high`, `online: true` becomes `--online`,
|
|
|
198
352
|
`require-frozen: false` becomes `--no-require-frozen`, and a list becomes
|
|
199
353
|
one flag per entry. The handful of flags the umbrella supplies itself (the
|
|
200
354
|
JSON format flag, `--staged`, and the intent gate's `--project`) are
|
|
201
|
-
rejected if you also set them, rather than being silently overridden.
|
|
355
|
+
rejected if you also set them, rather than being silently overridden. For
|
|
356
|
+
the external gates the umbrella writes `--report-format`, `--report-path`,
|
|
357
|
+
`--exit-code`, `--log-opts`, `--config`, `--gitleaks-ignore-path`,
|
|
358
|
+
`--ignore-gitleaks-allow`, `--log-level`, `--redact` and `--no-banner` to
|
|
359
|
+
gitleaks, and
|
|
360
|
+
`--format`, `--config` and `--lockfile` to osv-scanner, so those are
|
|
361
|
+
reserved too. Narrow what either
|
|
362
|
+
tool reports in its own config file (`.gitleaks.toml`, `osv-scanner.toml`)
|
|
363
|
+
instead.
|
|
202
364
|
|
|
203
365
|
**There is no shared severity threshold, on purpose.** One top-level
|
|
204
|
-
`failOn` would read as one decision and mean
|
|
366
|
+
`failOn` would read as one decision and mean five different things, so
|
|
205
367
|
setting one is an error rather than a knob that half works. Each gate keeps
|
|
206
368
|
its own threshold in its own `options` block, spelled the way that gate
|
|
207
369
|
spells it.
|
|
@@ -213,21 +375,41 @@ that gate, for pointing at a build that is not installed anywhere.
|
|
|
213
375
|
|
|
214
376
|
## Commands
|
|
215
377
|
|
|
216
|
-
`conductor init` writes the policy file and
|
|
217
|
-
|
|
378
|
+
`conductor init` writes the policy file and `.guardrails/manifest.json`, the
|
|
379
|
+
record `--revert` reads back later. The manifest currently records absolute
|
|
380
|
+
machine paths rather than repo-relative ones (see "Adopting conductor"
|
|
381
|
+
above); do not commit it.
|
|
382
|
+
|
|
383
|
+
- `--hook` also writes one pre-commit hook running every enabled gate whose
|
|
384
|
+
stage is `commit`. Without it, init writes only the policy file and the
|
|
385
|
+
manifest: no hook, and none of the hook-manager detection below runs
|
|
386
|
+
either. `.git/hooks` is never part of a clone, so a hook one checkout has
|
|
387
|
+
does not follow a teammate's clone, or a fresh clone of your own; each
|
|
388
|
+
needs its own `conductor init --hook`. `--revert` still removes a hook a
|
|
389
|
+
previous `--hook` run left behind, whether or not this invocation passes
|
|
390
|
+
`--hook` itself.
|
|
218
391
|
- `--dry-run` prints every file it would write or change and writes nothing.
|
|
219
392
|
- `--revert` removes exactly what a previous init wrote, and nothing else.
|
|
220
393
|
A file changed since init is reported and left alone.
|
|
221
394
|
- `--adopt` replaces one gate's own pre-commit hook with the umbrella hook.
|
|
222
395
|
Without it, init reports the collision and stops rather than stacking a
|
|
223
396
|
second invocation of a gate that is already hooked. A hook the umbrella
|
|
224
|
-
does not recognise is never replaced, with or without `--adopt`.
|
|
397
|
+
does not recognise is never replaced, with or without `--adopt`. Only
|
|
398
|
+
meaningful together with `--hook`; without it, init errors rather than
|
|
399
|
+
silently ignoring the flag, because there is no hook for it to act on.
|
|
225
400
|
- `--force` acts on a file **conductor itself wrote** and that has changed
|
|
226
401
|
since: on its own it replaces a managed hook somebody has edited, and with
|
|
227
402
|
`--revert` it removes one, restoring an adopted hook if there was one. It
|
|
228
403
|
never overrides a foreign-hook or gate-hook refusal, with or without
|
|
229
404
|
`--adopt`: those hooks were never conductor's, and no flag here turns
|
|
230
|
-
somebody else's file into one this tool may overwrite.
|
|
405
|
+
somebody else's file into one this tool may overwrite. Like `--adopt`,
|
|
406
|
+
only meaningful together with `--hook` on an init (not on a `--revert`);
|
|
407
|
+
without it, init errors.
|
|
408
|
+
|
|
409
|
+
The rest of this section, on hook managers already wired into the
|
|
410
|
+
repository, applies only when `--hook` is given: none of it is consulted,
|
|
411
|
+
and none of it can block the policy file from being written, on a plain
|
|
412
|
+
`conductor init`.
|
|
231
413
|
|
|
232
414
|
Init recognises the hook manager already wired into the repository. husky is
|
|
233
415
|
redirected to the tracked hook it maintains rather than the generated
|
|
@@ -281,6 +463,15 @@ proceeds normally without mentioning them.
|
|
|
281
463
|
leaves out is named as excluded, on one line in the text report and as a
|
|
282
464
|
`conductor/gate-excluded` notification in the SARIF log's `conductor` run.
|
|
283
465
|
It never reaches the exit code.
|
|
466
|
+
- `--advisory` maps exit 1 to exit 0: a run whose only failure is a blocking
|
|
467
|
+
finding no longer fails. A gate that could not run is unaffected and still
|
|
468
|
+
exits 2, so a crashed install or a missing policy still shows red rather
|
|
469
|
+
than a silent green: this flag changes what a **finding** does, never what
|
|
470
|
+
a **broken gate** does. The report is unchanged, a blocking finding still
|
|
471
|
+
prints with its `BLOCKING` marker, and only the process exit and the
|
|
472
|
+
verdict line's own wording (it says findings were advisory and did not
|
|
473
|
+
block) change. Text output only; the SARIF log has no verdict line to
|
|
474
|
+
change and its `properties.blocking` on each result is unaffected.
|
|
284
475
|
|
|
285
476
|
### Exit codes
|
|
286
477
|
|
|
@@ -289,7 +480,34 @@ proceeds normally without mentioning them.
|
|
|
289
480
|
- **2** an enabled gate could not run: its binary is missing, it exited with
|
|
290
481
|
its own could-not-run code, or it exited 1 with nothing parseable on
|
|
291
482
|
stdout, which is what a rejected config file looks like from two of the
|
|
292
|
-
three.
|
|
483
|
+
three family gates.
|
|
484
|
+
|
|
485
|
+
The external gates' exits are read per tool. gitleaks exits 1 for an error
|
|
486
|
+
as well as for a leak, so the umbrella hands it `--exit-code 3`: 3 is a leak
|
|
487
|
+
(blocked), 1 is could-not-run. gitleaks also exits 0 with an empty report
|
|
488
|
+
when git itself fails (a base ref the checkout never fetched), so a clean
|
|
489
|
+
exit that logged an `ERR` line is could-not-run too, never a pass. A
|
|
490
|
+
gitleaks exit with no report file behind it is could-not-run. osv-scanner is
|
|
491
|
+
handed every tracked lockfile by name (`package-lock.json`,
|
|
492
|
+
`npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, at any
|
|
493
|
+
depth, never under `node_modules`); when the repository tracks none, it is
|
|
494
|
+
not spawned at all and the gate is reported clean with a
|
|
495
|
+
`conductor/nothing-to-scan` note, so a docs-only repository is not red on
|
|
496
|
+
every pull request. Its 1 is blocked. Its own 128 ("no package sources
|
|
497
|
+
found") on lockfiles it WAS handed means they parsed to no packages; that is
|
|
498
|
+
clean too, with a distinct `conductor/lockfiles-empty` note naming the
|
|
499
|
+
files. Only those npm-family names are handed over today: a repository
|
|
500
|
+
whose only lockfile belongs to another ecosystem gets nothing-to-scan from
|
|
501
|
+
this gate. Lockfiles inside git submodules are never listed. In a sparse
|
|
502
|
+
checkout a tracked lockfile that is not on disk is still handed over and
|
|
503
|
+
osv-scanner exits 127 on it, a false could-not-run that fails closed. Any other osv-scanner exit
|
|
504
|
+
(127 is its error code) is could-not-run. A gitleaks older than 8.19 or an
|
|
505
|
+
osv-scanner older than 2.0 is could-not-run, naming the floor.
|
|
506
|
+
|
|
507
|
+
`run --advisory` maps exit 1 to exit 0. It never touches exit 2: a gate that
|
|
508
|
+
could not run is a different failure from a blocking finding, and advisory
|
|
509
|
+
mode exists to leave that one alone. See "Running the gates as an advisory
|
|
510
|
+
check" below.
|
|
293
511
|
|
|
294
512
|
## The pull-request trust boundary
|
|
295
513
|
|
|
@@ -438,8 +656,66 @@ choose its own judge on exactly the repositories that have no rules yet. See
|
|
|
438
656
|
"Adopting conductor" below for the sequence and for how to see what your
|
|
439
657
|
policy will do before you merge it.
|
|
440
658
|
|
|
441
|
-
**Which gates are covered.** All
|
|
442
|
-
intent-guard from **1.4.0**, vault-guard from **1.7.0
|
|
659
|
+
**Which gates are covered.** All five: dep-guard from **0.6.0**,
|
|
660
|
+
intent-guard from **1.4.0**, vault-guard from **1.7.0**, and the two
|
|
661
|
+
external gates at their command-line floors, gitleaks **8.19.0** and
|
|
662
|
+
osv-scanner **2.0.0**.
|
|
663
|
+
|
|
664
|
+
**The external gates get their pull-request mode from the umbrella.**
|
|
665
|
+
Neither tool has a `--trust-base`, and both auto-load a config from the tree
|
|
666
|
+
they scan, which on a pull request is the head: a pull request could add an
|
|
667
|
+
allowlist entry for exactly the secret or advisory it introduces. So on a
|
|
668
|
+
pull-request run the umbrella reads `.gitleaks.toml` and `osv-scanner.toml`
|
|
669
|
+
from the base ref with `git show` and passes each tool that copy with
|
|
670
|
+
`--config`. When the base has none, the tool gets a neutral one (gitleaks'
|
|
671
|
+
built-in rules, an empty osv-scanner config) rather than nothing, because
|
|
672
|
+
nothing would let it find the head's file on its own. gitleaks'
|
|
673
|
+
`.gitleaksignore` is handled the same way, and because gitleaks also loads
|
|
674
|
+
the ignore file at the root of whatever it scans, the umbrella scans the
|
|
675
|
+
repository's git directory instead of the working tree on a pull request:
|
|
676
|
+
the same history, without the head's ignore file. A head-side change to any
|
|
677
|
+
of these files is reported as a proposal line and takes effect after merge,
|
|
678
|
+
exactly like a change to `.guardrails.yaml`. History is scoped to
|
|
679
|
+
`<base>..HEAD` on a pull request and to `HEAD` locally, so a secret on
|
|
680
|
+
another branch never reddens this one. Merge commits are scanned by their
|
|
681
|
+
first-parent diff, so a secret added inside a merge (while resolving a
|
|
682
|
+
conflict, say) is found; the same leak seen in a pull request's commit and
|
|
683
|
+
again in its merge is reported once, with the other commit listed.
|
|
684
|
+
|
|
685
|
+
A base `.gitleaks.toml` can name another file with `[extend] path`, which
|
|
686
|
+
gitleaks resolves against its working directory. On a pull request
|
|
687
|
+
conductor copies every file in that chain from the base ref into a
|
|
688
|
+
directory of its own and runs gitleaks from there, so the head's copy of an
|
|
689
|
+
extended file is never read; a head-side edit to one is a proposal, and an
|
|
690
|
+
extended file the base does not have makes the gate could-not-run, naming
|
|
691
|
+
it. gitleaks' log level is pinned at `info` and `log-level` is reserved,
|
|
692
|
+
because conductor reads gitleaks' error lines to tell a failed scan from a
|
|
693
|
+
clean one. Write the extend as a plain relative path in an `[extend]` table:
|
|
694
|
+
a base `.gitleaks.toml` whose extend target is a symbolic link, or which
|
|
695
|
+
writes the extend as an inline table or a quoted key, fails closed on every
|
|
696
|
+
pull request until it is rewritten that way.
|
|
697
|
+
|
|
698
|
+
**Local runs and `.gitattributes`.** On a pull request gitleaks scans the
|
|
699
|
+
repository's git directory, where the head's `.gitattributes` is not read.
|
|
700
|
+
A local run scans the working tree, so a file your own `.gitattributes`
|
|
701
|
+
marks `binary` is skipped by gitleaks there. Pull requests are not affected.
|
|
702
|
+
|
|
703
|
+
On a pull request gitleaks is also passed `--ignore-gitleaks-allow`, so an
|
|
704
|
+
inline `gitleaks:allow` comment does not hide a secret: an inline allow
|
|
705
|
+
lives in the tree being judged, so the pull request controls it. A
|
|
706
|
+
legitimate allow belongs in the base branch's `.gitleaks.toml` allowlist or
|
|
707
|
+
`.gitleaksignore`, both of which conductor already reads from the base.
|
|
708
|
+
Local runs keep inline allows.
|
|
709
|
+
|
|
710
|
+
osv-scanner is never pointed at a directory to walk, because its own walk
|
|
711
|
+
skips anything `.gitignore` matches, tracked or not, so one ignore line in a
|
|
712
|
+
pull request could hide a committed lockfile. conductor lists the tracked
|
|
713
|
+
lockfiles with `git ls-files` and hands each one over with `--lockfile`. On
|
|
714
|
+
a pull request that list comes from the head's index, not the base ref: the
|
|
715
|
+
lockfiles are the tree being judged, and adding or removing one is visible
|
|
716
|
+
in the diff. Only the root `osv-scanner.toml` is read from the base and
|
|
717
|
+
passed with `--config`, which overrides any nested one for the run; a
|
|
718
|
+
nested one the pull request adds or edits is reported as a proposal.
|
|
443
719
|
|
|
444
720
|
The umbrella asks each gate its version and passes the flag only to a build
|
|
445
721
|
that understands it, so an older gate is not handed a flag it would reject. A
|
|
@@ -459,7 +735,7 @@ the flag.
|
|
|
459
735
|
|
|
460
736
|
## Intent at a pull request
|
|
461
737
|
|
|
462
|
-
The intent gate is the only one of the
|
|
738
|
+
The intent gate is the only one of the five with any ceremony: its native
|
|
463
739
|
flow wants a contract approved before the work starts, which is a per-task
|
|
464
740
|
human step. That step is exactly what a pull request cannot carry, so at the
|
|
465
741
|
`ci` stage the umbrella stands in for it.
|
|
@@ -472,6 +748,20 @@ With no `--base`, `GITHUB_BASE_REF` is used as `origin/<value>` when it is
|
|
|
472
748
|
set, and the text report says so. With neither, the intent gate runs the way
|
|
473
749
|
it does at a commit: against the staged index, or the paths you name.
|
|
474
750
|
|
|
751
|
+
**This is why a local preview and a pull-request run can disagree about a
|
|
752
|
+
missing contract.** The contract-discovery rules below (`--spec`, a frozen
|
|
753
|
+
native contract, a `Spec:` line, the `docs/superpowers/specs` convention)
|
|
754
|
+
only engage once `--base` resolves to something, or `--spec` is given.
|
|
755
|
+
Neither is true of a plain `conductor run` on your own checkout, so a
|
|
756
|
+
repository with no contract gets intent-guard's own native answer instead:
|
|
757
|
+
`BLOCKING critical intent-guard/gate-blocked`, because that flow wants an
|
|
758
|
+
approved contract and none exists. On a pull request `--base` is set, this
|
|
759
|
+
whole section's machinery engages, and a branch with nothing to import
|
|
760
|
+
lands in the no-contract state below instead: reported, and never reaching
|
|
761
|
+
the exit code. Read a local `BLOCKING` line on the intent gate as "there is
|
|
762
|
+
no contract for the umbrella to import here yet," not as "this pull request
|
|
763
|
+
will fail."
|
|
764
|
+
|
|
475
765
|
A git failure here is **fail-closed**: could-not-run, so exit 2 for an
|
|
476
766
|
enforced gate and a note for an unenforced one. There is deliberately no
|
|
477
767
|
fallback to an empty path set, because an empty path set is what a passing
|
|
@@ -530,6 +820,22 @@ skipped line, in the verdict and on the one-line summary of a clean run, so a
|
|
|
530
820
|
reader can tell "nobody has written one" from "somebody decided against one"
|
|
531
821
|
wherever they meet it.
|
|
532
822
|
|
|
823
|
+
**A repository with no contract yet is not a repository this gate can act
|
|
824
|
+
on**, and the no-contract skip line names `docs/superpowers/specs`, which is
|
|
825
|
+
a convention from this family's own tooling and not one an outside adopter
|
|
826
|
+
has reason to recognise. The next step, if you want this gate to have an
|
|
827
|
+
opinion here, is the one intent-guard's own documentation describes: draft a
|
|
828
|
+
contract naming the paths worth protecting, then freeze it, and keep the
|
|
829
|
+
frozen file committed so rule 2 above finds it on every pull request from
|
|
830
|
+
then on. Until you do that, a project rule that lives only in `AGENTS.md`
|
|
831
|
+
never blocks anything through this gate. intent-guard does read prose rules
|
|
832
|
+
files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, cursor rules) as constraint
|
|
833
|
+
sources, but by its own design a constraint from that source is advisory
|
|
834
|
+
and leaves the exit code alone; only a user-stated constraint, or one
|
|
835
|
+
promoted with `intent-guard correct --promote`, can block. Conductor itself
|
|
836
|
+
never opens that file. What is enforced is the frozen contract or the
|
|
837
|
+
imported spec, never project convention documented in prose.
|
|
838
|
+
|
|
533
839
|
**A waiver is a decision, recorded by whoever wrote the pull request body,
|
|
534
840
|
and that includes a contributor from a fork.** On the ordinary path, where a
|
|
535
841
|
repository has no frozen contract of its own, `Spec: none` means the intent
|
|
@@ -654,14 +960,14 @@ jobs:
|
|
|
654
960
|
contents: read
|
|
655
961
|
security-events: write
|
|
656
962
|
steps:
|
|
657
|
-
- uses: actions/checkout@
|
|
963
|
+
- uses: actions/checkout@v7
|
|
658
964
|
with:
|
|
659
965
|
fetch-depth: 0
|
|
660
|
-
- uses: actions/setup-node@
|
|
966
|
+
- uses: actions/setup-node@v7
|
|
661
967
|
with:
|
|
662
968
|
node-version: '22.11.0'
|
|
663
969
|
- id: conductor
|
|
664
|
-
uses: vaultcompasshq/conductor@v0.
|
|
970
|
+
uses: vaultcompasshq/conductor@v0.5.0
|
|
665
971
|
with:
|
|
666
972
|
output: conductor.sarif
|
|
667
973
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -688,7 +994,7 @@ jobs:
|
|
|
688
994
|
contents: read
|
|
689
995
|
security-events: write
|
|
690
996
|
steps:
|
|
691
|
-
- uses: actions/checkout@
|
|
997
|
+
- uses: actions/checkout@v7
|
|
692
998
|
with:
|
|
693
999
|
# Required, for two reasons now. Without it there is no merge base
|
|
694
1000
|
# to diff against, and the intent gate fails closed rather than
|
|
@@ -697,7 +1003,7 @@ jobs:
|
|
|
697
1003
|
# base ref that will not resolve is exit 2 for every enabled gate.
|
|
698
1004
|
fetch-depth: 0
|
|
699
1005
|
- uses: pnpm/action-setup@v4
|
|
700
|
-
- uses: actions/setup-node@
|
|
1006
|
+
- uses: actions/setup-node@v7
|
|
701
1007
|
with:
|
|
702
1008
|
# Not a bare major: Node 22.0.0 ships npm 10.5.1, which the action
|
|
703
1009
|
# refuses because that client reports a clean install as tampered
|
|
@@ -710,7 +1016,7 @@ jobs:
|
|
|
710
1016
|
# pinned below.
|
|
711
1017
|
- run: pnpm install --frozen-lockfile
|
|
712
1018
|
- id: conductor
|
|
713
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1019
|
+
uses: vaultcompasshq/conductor@v0.5.0
|
|
714
1020
|
with:
|
|
715
1021
|
output: conductor.sarif
|
|
716
1022
|
# Exact versions, never a range and never "latest". These four
|
|
@@ -721,7 +1027,7 @@ jobs:
|
|
|
721
1027
|
# request of their own. Forward only on a pull request: the action
|
|
722
1028
|
# refuses a pin below what its tag ships, and the four lines can be
|
|
723
1029
|
# left out entirely to take that tag's own versions.
|
|
724
|
-
conductor-version: 0.
|
|
1030
|
+
conductor-version: 0.5.0
|
|
725
1031
|
dep-guard-version: 0.7.0
|
|
726
1032
|
vault-guard-version: 1.8.0
|
|
727
1033
|
intent-guard-version: 1.5.2
|
|
@@ -740,6 +1046,37 @@ jobs:
|
|
|
740
1046
|
sarif_file: ${{ steps.conductor.outputs.sarif }}
|
|
741
1047
|
```
|
|
742
1048
|
|
|
1049
|
+
**The two external gates are installed by your workflow, not by the
|
|
1050
|
+
Action.** The Action still installs exactly its four npm packages and has no
|
|
1051
|
+
input for gitleaks or osv-scanner; conductor downloads, pins and checksums
|
|
1052
|
+
no third-party binary. If the policy enables `secrets-history` or
|
|
1053
|
+
`vulnerabilities`, add a step before the conductor step that puts both tools
|
|
1054
|
+
on `PATH`, pinned by version and checked against the release's own
|
|
1055
|
+
checksum, the same way you would for a standalone security job:
|
|
1056
|
+
|
|
1057
|
+
```yaml
|
|
1058
|
+
- name: Install gitleaks and osv-scanner
|
|
1059
|
+
run: |
|
|
1060
|
+
set -euo pipefail
|
|
1061
|
+
bin="$RUNNER_TEMP/external-gates"
|
|
1062
|
+
mkdir -p "$bin"
|
|
1063
|
+
cd "$RUNNER_TEMP"
|
|
1064
|
+
curl -sSLO https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz
|
|
1065
|
+
echo "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb gitleaks_8.30.1_linux_x64.tar.gz" | sha256sum -c -
|
|
1066
|
+
tar -xzf gitleaks_8.30.1_linux_x64.tar.gz -C "$bin" gitleaks
|
|
1067
|
+
curl -sSL -o "$bin/osv-scanner" https://github.com/google/osv-scanner/releases/download/v2.6.0/osv-scanner_linux_amd64
|
|
1068
|
+
echo "ca69b3d3cd08f889a49dc0a383122f71cc528b83803671df5fd874d97485b108 $bin/osv-scanner" | sha256sum -c -
|
|
1069
|
+
chmod +x "$bin/osv-scanner"
|
|
1070
|
+
echo "$bin" >> "$GITHUB_PATH"
|
|
1071
|
+
```
|
|
1072
|
+
|
|
1073
|
+
`fetch-depth: 0` on the checkout matters more with gitleaks enabled: on a
|
|
1074
|
+
pull request conductor scans `<base>..HEAD`, and a base that was never
|
|
1075
|
+
fetched is a git error gitleaks itself would report as a clean scan of
|
|
1076
|
+
nothing. conductor reads that error off gitleaks' log and reports the gate
|
|
1077
|
+
as could-not-run instead. A missing tool is could-not-run as well, with the
|
|
1078
|
+
install step named in the report.
|
|
1079
|
+
|
|
743
1080
|
The `@v4` pins there are readable, not safe: a tag moves, so pinning by one
|
|
744
1081
|
runs whatever its author pushes to it next. Pin every third-party action by
|
|
745
1082
|
commit digest in a workflow you actually run, the way this repository's own
|
|
@@ -747,15 +1084,22 @@ workflows do.
|
|
|
747
1084
|
|
|
748
1085
|
### Running the gates as an advisory check
|
|
749
1086
|
|
|
750
|
-
To run the gates without blocking a merge, set `
|
|
751
|
-
`conductor` step and leave the check not required in branch protection.
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
1087
|
+
To run the gates without blocking a merge, set `advisory: true` on the
|
|
1088
|
+
`conductor` step and leave the check not required in branch protection.
|
|
1089
|
+
`advisory: true` maps a blocking finding to exit 0, so it never fails this
|
|
1090
|
+
run; a gate that **could not run** is unaffected and still exits 2, so a
|
|
1091
|
+
crashed install or a missing policy on the base ref still shows red rather
|
|
1092
|
+
than a silent green. That distinction is why the recipe below carries no
|
|
1093
|
+
`continue-on-error` anywhere: an earlier version of this recipe put
|
|
1094
|
+
`continue-on-error: true` on every step, including the umbrella's own, and a
|
|
1095
|
+
transient `npm audit signatures` failure then read as nothing wrong for two
|
|
1096
|
+
days (issue #36) because the step's exit code was swallowed regardless of
|
|
1097
|
+
which of the two reasons produced it. `advisory` fixes the failure that
|
|
1098
|
+
caused that; `continue-on-error` is the thing that let it happen, so the two
|
|
1099
|
+
do not belong in the same recipe. Set a step `timeout-minutes` as well: the
|
|
1100
|
+
Action already caps each gate's own subprocess at 120 seconds and reports one
|
|
1101
|
+
that exceeds it as could-not-run, so the timeout is an outer bound around the
|
|
1102
|
+
whole run rather than the primary control.
|
|
759
1103
|
|
|
760
1104
|
A complete copy-paste job, rather than the one step above in isolation:
|
|
761
1105
|
|
|
@@ -770,65 +1114,69 @@ jobs:
|
|
|
770
1114
|
contents: read
|
|
771
1115
|
pull-requests: write
|
|
772
1116
|
steps:
|
|
773
|
-
- uses: actions/checkout@
|
|
774
|
-
continue-on-error: true
|
|
1117
|
+
- uses: actions/checkout@v7
|
|
775
1118
|
with:
|
|
776
1119
|
fetch-depth: 0
|
|
777
|
-
- uses: actions/setup-node@
|
|
778
|
-
continue-on-error: true
|
|
1120
|
+
- uses: actions/setup-node@v7
|
|
779
1121
|
with:
|
|
780
1122
|
node-version: '22.11.0'
|
|
781
|
-
- name: Fetch the base ref
|
|
782
|
-
continue-on-error: true
|
|
783
|
-
run: git fetch origin "$GITHUB_BASE_REF:refs/remotes/origin/$GITHUB_BASE_REF"
|
|
784
|
-
env:
|
|
785
|
-
GITHUB_BASE_REF: ${{ github.base_ref }}
|
|
786
1123
|
- id: conductor
|
|
787
|
-
continue-on-error: true
|
|
788
1124
|
timeout-minutes: 5
|
|
789
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1125
|
+
uses: vaultcompasshq/conductor@v0.5.0
|
|
790
1126
|
with:
|
|
791
1127
|
pr-comment: true
|
|
1128
|
+
advisory: true
|
|
792
1129
|
```
|
|
793
1130
|
|
|
794
|
-
Every fallible step above, the checkout, the node setup, the explicit fetch,
|
|
795
|
-
and the conductor step itself, carries `continue-on-error: true`, because a
|
|
796
|
-
required job must never go red over an advisory step that hung or failed.
|
|
797
1131
|
`action.yml` already shallow-fetches the trust base itself as of 0.4.5 when
|
|
798
1132
|
the checkout does not already carry it (see the changelog entry for that
|
|
799
|
-
version), so
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
1133
|
+
version), so this recipe needs no separate "fetch the base ref" step. None of
|
|
1134
|
+
the three steps above swallows its own exit code: a checkout or setup-node
|
|
1135
|
+
failure is an infrastructure problem this recipe should still surface, and
|
|
1136
|
+
the `conductor` step's own advisory behaviour comes from `advisory: true`
|
|
1137
|
+
rather than from hiding a failing step, for the reason above. `pr-comment:
|
|
1138
|
+
true` is what makes the advisory finding visible at all: a `pull_request`
|
|
1139
|
+
check that is not required posts nothing anywhere else a developer would
|
|
1140
|
+
look, so without it the run's only trace is a step that exited 0 and nobody
|
|
1141
|
+
opens. See "The report as a pull request comment" below for what that input
|
|
1142
|
+
needs and what it does on a fork.
|
|
1143
|
+
|
|
1144
|
+
`advisory` changes the umbrella's own process exit code only: it does not
|
|
1145
|
+
reach the SARIF log, so a GitHub Code Scanning tab shows the same results and
|
|
1146
|
+
the same alerts either way, and Code Scanning's own merge protection can
|
|
1147
|
+
still block on them regardless of what this step's exit code says. `advisory`
|
|
1148
|
+
is also an input on the `conductor` step, which means it is read from the
|
|
1149
|
+
pull request's own workflow file on a same-repo `pull_request` event, the
|
|
1150
|
+
same as every other input this Action takes; that gives a pull request
|
|
1151
|
+
author nothing they could not already do by editing the workflow to add
|
|
1152
|
+
`continue-on-error` themselves, and the control for that, as for any workflow
|
|
1153
|
+
edit, is branch protection requiring review on `.github/workflows`, not
|
|
1154
|
+
anything in `action.yml`.
|
|
807
1155
|
|
|
808
1156
|
### Adopting conductor
|
|
809
1157
|
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
|
|
823
|
-
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
1158
|
+
See "Adopting conductor" near the top of this README for the ordered
|
|
1159
|
+
walkthrough: init, a first pull request in advisory mode, merge, then go
|
|
1160
|
+
required. This subsection is the mechanism behind two of those steps.
|
|
1161
|
+
|
|
1162
|
+
**Why the first pull request still exits 2 under `advisory: true`.**
|
|
1163
|
+
`advisory: true` maps a blocking **finding** to exit 0; it has no opinion
|
|
1164
|
+
about a run that never had a policy to be judged by. The pull request that
|
|
1165
|
+
first adds `.guardrails.yaml` is judged against the base branch, which has
|
|
1166
|
+
none yet, so the run is refused outright before any gate produces a finding
|
|
1167
|
+
for `advisory` to act on. Leaving the check out of branch protection for
|
|
1168
|
+
that one pull request is what keeps the expected exit 2 from blocking the
|
|
1169
|
+
merge; the step posts a comment naming the ref and the remedy.
|
|
1170
|
+
|
|
1171
|
+
**Why "go required" means the job's own context, never the SARIF-upload
|
|
1172
|
+
row.** The recipes above upload conductor's SARIF log with
|
|
1173
|
+
`github/codeql-action/upload-sarif`, which can add its own code-scanning
|
|
1174
|
+
check to a pull request's checks list alongside the workflow job's own
|
|
1175
|
+
check. Branch protection's required-checks picker can then show both. Only
|
|
1176
|
+
the job's own context (`gates` in the recipes above, the job key, not any
|
|
1177
|
+
step name) carries conductor's actual exit code; a code-scanning check can
|
|
1178
|
+
read green from an old scan, or from `continue-on-error` on the upload step
|
|
1179
|
+
itself, independent of whether the gates step passed. Require the job.
|
|
832
1180
|
|
|
833
1181
|
### The report as a pull request comment
|
|
834
1182
|
|
|
@@ -846,7 +1194,7 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
846
1194
|
steps:
|
|
847
1195
|
# ... checkout, pnpm, setup-node, install, as in the example above ...
|
|
848
1196
|
- id: conductor
|
|
849
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1197
|
+
uses: vaultcompasshq/conductor@v0.5.0
|
|
850
1198
|
with:
|
|
851
1199
|
output: conductor.sarif
|
|
852
1200
|
pr-comment: true
|
|
@@ -898,12 +1246,12 @@ per pull request.
|
|
|
898
1246
|
|
|
899
1247
|
```yaml
|
|
900
1248
|
- id: conductor-package-a
|
|
901
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1249
|
+
uses: vaultcompasshq/conductor@v0.5.0
|
|
902
1250
|
with:
|
|
903
1251
|
pr-comment: true
|
|
904
1252
|
pr-comment-marker: 'package-a'
|
|
905
1253
|
- id: conductor-package-b
|
|
906
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1254
|
+
uses: vaultcompasshq/conductor@v0.5.0
|
|
907
1255
|
with:
|
|
908
1256
|
pr-comment: true
|
|
909
1257
|
pr-comment-marker: 'package-b'
|
|
@@ -976,13 +1324,17 @@ came from, so a pull request that plants one gets a clean comment beside a
|
|
|
976
1324
|
SARIF log that refused it.
|
|
977
1325
|
|
|
978
1326
|
**Mirror whatever you gave the Action**, or the two runs can report different
|
|
979
|
-
contracts. The step above matches the example, which
|
|
980
|
-
`base-ref`, `trust-base` nor `
|
|
981
|
-
the `Spec:` line out of the job environment
|
|
982
|
-
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
1327
|
+
contracts, or different verdicts. The step above matches the example, which
|
|
1328
|
+
passes neither `base-ref`, `trust-base`, `spec` nor `advisory`, so both runs
|
|
1329
|
+
read `GITHUB_BASE_REF` and the `Spec:` line out of the job environment
|
|
1330
|
+
themselves and land on the same contract and the same ref, and neither one
|
|
1331
|
+
maps a blocking finding to exit 0. If you set any of those inputs on the
|
|
1332
|
+
gates step, pass the same values here: `--base`, `--trust-base` and `--spec`
|
|
1333
|
+
for the first three, and `--advisory` if you set `advisory: true`. Missing
|
|
1334
|
+
one of the first three means the comment is a report of a contract source,
|
|
1335
|
+
or of a boundary, the uploaded log never used; missing `--advisory` means the
|
|
1336
|
+
comment's own verdict line reads "exit 1" underneath a gates step that just
|
|
1337
|
+
exited 0, which is confusing in the opposite direction from silence.
|
|
986
1338
|
|
|
987
1339
|
**On a pull request from a fork the token is read-only**, so `gh pr comment`
|
|
988
1340
|
fails, `continue-on-error` swallows the failure, and no comment appears on
|
|
@@ -1002,12 +1354,16 @@ In: the policy file and its schema, `init` with dry-run, revert, and adopt,
|
|
|
1002
1354
|
`run` producing the combined text report and a combined SARIF log, the
|
|
1003
1355
|
composed exit code, per-gate `stage` and `enforce`, `run --stage`, the intent
|
|
1004
1356
|
gate at a pull request (`--base`, `--spec`, the imported contract, the
|
|
1005
|
-
no-contract advisory),
|
|
1357
|
+
no-contract advisory), the two external gates (gitleaks over git history and
|
|
1358
|
+
osv-scanner over the dependency tree, run from `PATH`, their config read
|
|
1359
|
+
from the base ref on a pull request), and the composite Action.
|
|
1006
1360
|
|
|
1007
1361
|
Out, deliberately: a unified baseline or ledger (each gate keeps its own, and
|
|
1008
1362
|
their fingerprints are not equally durable, so one shared file would expire
|
|
1009
1363
|
entries silently for one product and not another), an MCP registration,
|
|
1010
|
-
running the gates concurrently,
|
|
1364
|
+
running the gates concurrently, downloading or pinning any third-party
|
|
1365
|
+
binary (the adopter installs gitleaks and osv-scanner), and any finding of
|
|
1366
|
+
the umbrella's own about
|
|
1011
1367
|
anybody's CODE. The findings it does raise are all about the gates
|
|
1012
1368
|
themselves: `conductor/gate-missing`, `conductor/gate-output-unparseable`
|
|
1013
1369
|
and `conductor/gate-failed`, plus the two diagnostics
|
|
@@ -1020,7 +1376,8 @@ runs inside an agent session or on save, which intent-guard's own optional
|
|
|
1020
1376
|
session hooks already cover.
|
|
1021
1377
|
|
|
1022
1378
|
This is a young tool rather than a finished one. The gates are still the
|
|
1023
|
-
product
|
|
1379
|
+
product, two of them are not this family's, and this is the layer that
|
|
1380
|
+
makes them one required check.
|
|
1024
1381
|
|
|
1025
1382
|
## Design notes
|
|
1026
1383
|
|
|
@@ -1037,4 +1394,4 @@ Adopter feedback is a row in [FINDINGS.md](FINDINGS.md). How to change this repo
|
|
|
1037
1394
|
|
|
1038
1395
|
## License
|
|
1039
1396
|
|
|
1040
|
-
MIT
|
|
1397
|
+
MIT. Built by [Vault & Compass](https://vaultcompass.io).
|