@vaultcompass/conductor 0.4.7 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +658 -145
- package/dist/cli.js +185 -46
- 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 +474 -38
- 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 +19 -2
- package/dist/normalize.js +444 -11
- package/dist/output-sarif.js +61 -2
- package/dist/output-text.d.ts +26 -0
- package/dist/output-text.js +91 -20
- package/dist/policy.d.ts +10 -4
- package/dist/policy.js +100 -14
- package/dist/products.d.ts +107 -0
- package/dist/products.js +132 -0
- package/dist/resolve.js +18 -4
- package/dist/run.d.ts +40 -0
- package/dist/run.js +42 -1
- package/dist/trust-base.d.ts +68 -0
- package/dist/trust-base.js +152 -0
- package/package.json +4 -3
- package/schema/guardrails.schema.json +7 -5
package/README.md
CHANGED
|
@@ -1,8 +1,37 @@
|
|
|
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 six 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
|
+
| [A credential-shaped string committed, then replaced, so only history carries it](https://github.com/vaultcompasshq/conductor-proof/pull/15) | fail | fail |
|
|
29
|
+
| [A dependency at a version with a known advisory](https://github.com/vaultcompasshq/conductor-proof/pull/16) | fail | fail |
|
|
30
|
+
|
|
31
|
+
The rows where both fail are parity, not a catch: both jobs run gitleaks
|
|
32
|
+
and osv-scanner, so both see a credential shape, a credential in history,
|
|
33
|
+
and a known advisory. The other three are what a scanner that only knows
|
|
34
|
+
about vulnerabilities and secrets has no way to know.
|
|
6
35
|
|
|
7
36
|
<!-- guardrails-family: shared block, keep it identical in dep-guard, vault-guard, intent-guard and conductor -->
|
|
8
37
|
The Vault & Compass guardrails are three gates over an AI-assisted coding
|
|
@@ -17,20 +46,212 @@ contract, and change budgets). Each one installs, configures and runs on its
|
|
|
17
46
|
own;
|
|
18
47
|
[conductor](https://www.npmjs.com/package/@vaultcompass/conductor) is the
|
|
19
48
|
optional umbrella that runs them from one policy file, one hook and one
|
|
20
|
-
report
|
|
49
|
+
report, beside two scanners you install yourself:
|
|
50
|
+
[gitleaks](https://github.com/gitleaks/gitleaks) for secrets anywhere in git
|
|
51
|
+
history and [osv-scanner](https://github.com/google/osv-scanner) for known
|
|
52
|
+
vulnerabilities. conductor scans nothing itself and installs nothing that
|
|
53
|
+
is not its own.
|
|
21
54
|
<!-- /guardrails-family -->
|
|
22
55
|
|
|
56
|
+
## Adopting conductor
|
|
57
|
+
|
|
58
|
+
The first pull request under a policy conductor just added cannot be judged
|
|
59
|
+
by that policy, so plan for a short, ordered sequence rather than one
|
|
60
|
+
command: init, a first pull request in advisory mode, merge, then go
|
|
61
|
+
required.
|
|
62
|
+
|
|
63
|
+
1. **Init.** Install the gates. Each of them is a working tool on its own,
|
|
64
|
+
and none of them needs this one:
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
npm install -g @vaultcompass/dep-guard @vaultcompass/vault-guard @vaultcompass/intent-guard
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
The umbrella is optional. Install it when running the three separately
|
|
71
|
+
has become the annoying part:
|
|
72
|
+
|
|
73
|
+
```
|
|
74
|
+
npm install -g @vaultcompass/conductor
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
The two external gates are installed by you, on your machine and in your
|
|
78
|
+
workflow, from their own releases: [gitleaks](https://github.com/gitleaks/gitleaks)
|
|
79
|
+
8.19 or later and [osv-scanner](https://github.com/google/osv-scanner)
|
|
80
|
+
2.x. conductor never downloads either one. It finds them on `PATH`, and
|
|
81
|
+
when one is enabled in the policy and missing, the run reports
|
|
82
|
+
could-not-run (exit 2) with the install step in the report. Two policy
|
|
83
|
+
lines switch them on:
|
|
84
|
+
|
|
85
|
+
```yaml
|
|
86
|
+
gates:
|
|
87
|
+
secrets-history:
|
|
88
|
+
product: gitleaks
|
|
89
|
+
vulnerabilities:
|
|
90
|
+
product: osv-scanner
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
**Globally, and that is the guidance for CI too.** A devDependency is
|
|
94
|
+
fine beside it for your own pre-commit hook, and nothing about a local
|
|
95
|
+
run changed. It is not what gates your pull requests: on a pull-request
|
|
96
|
+
run the umbrella never looks in `node_modules/.bin` at all, because what
|
|
97
|
+
is installed there is chosen by the head's own manifest and lockfile. The
|
|
98
|
+
Action installs all four packages itself, globally, at versions pinned in
|
|
99
|
+
your workflow file. See "The pull-request trust boundary" and "The
|
|
100
|
+
Action" below.
|
|
101
|
+
|
|
102
|
+
From the repository root, look before you write:
|
|
103
|
+
|
|
104
|
+
```
|
|
105
|
+
conductor init --dry-run
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
That prints every file it would write or change and writes nothing. Then:
|
|
109
|
+
|
|
110
|
+
```
|
|
111
|
+
conductor init
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
which writes `.guardrails.yaml` with every gate listed and only the ones
|
|
115
|
+
it found switched on, and `.guardrails/manifest.json`, the record init
|
|
116
|
+
reads back on a later `--revert`. The intent gate is written unenforced
|
|
117
|
+
unless a frozen contract already exists at `.intent-guard/intent-contract.yaml`,
|
|
118
|
+
in which case init enforces it from the start rather than leaving a
|
|
119
|
+
frozen contract's protected paths reporting without blocking. **It writes
|
|
120
|
+
no pre-commit hook unless you ask for one:**
|
|
121
|
+
|
|
122
|
+
```
|
|
123
|
+
conductor init --hook
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
adds one pre-commit hook on top of that, running every enabled gate whose
|
|
127
|
+
stage is `commit`. A CI-only adopter that never runs conductor locally can
|
|
128
|
+
stop at the first `conductor init`, with no hook at all.
|
|
129
|
+
|
|
130
|
+
**`.git/hooks` is never part of a clone**, so a hook one checkout has does
|
|
131
|
+
not follow a teammate's clone, or a fresh clone of your own: hooks are per
|
|
132
|
+
clone and per machine. Each clone that wants the hook runs
|
|
133
|
+
`conductor init --hook` once; a repository that already has
|
|
134
|
+
`.guardrails.yaml` gets only the hook from that run, since init never
|
|
135
|
+
rewrites a policy file that already exists.
|
|
136
|
+
|
|
137
|
+
Do not wire this into a `package.json` `prepare` script. A failing init
|
|
138
|
+
(no `.git` in a Docker build, a foreign hook already installed, husky's
|
|
139
|
+
own `prepare` key, or conductor not yet installed at install time) would
|
|
140
|
+
fail `npm install` itself for everyone who runs it, not only for the
|
|
141
|
+
person who wanted the hook.
|
|
142
|
+
|
|
143
|
+
**`.guardrails/manifest.json` records the absolute path on the machine
|
|
144
|
+
that ran `init`**, for the hook, when there is one, and for the policy
|
|
145
|
+
file alike, and
|
|
146
|
+
conductor does not add a `.gitignore` entry for it. That path is specific
|
|
147
|
+
to your checkout, so do not commit the file: add
|
|
148
|
+
`.guardrails/manifest.json` to your own `.gitignore` today. The file
|
|
149
|
+
lives inside your working tree so `--revert` can find it later, and
|
|
150
|
+
recording repo-relative paths there instead of absolute ones is a known
|
|
151
|
+
gap, not a design; it has not been fixed yet.
|
|
152
|
+
|
|
153
|
+
Commit something, now that `--hook` above has installed the pre-commit
|
|
154
|
+
hook (this walkthrough's output below only appears when the hook is
|
|
155
|
+
installed; a bare `conductor init` with no `--hook` runs no gate on
|
|
156
|
+
commit at all). A clean commit prints one line:
|
|
157
|
+
|
|
158
|
+
```
|
|
159
|
+
conductor: clean, nothing blocked. 2 gate(s) ran: dependencies (dep-guard), secrets (vault-guard). Deferred to a later stage: intent (intent-guard) from stage ci. 0 gate(s) left out by --gate. 0 gate(s) not enforced. 1 note(s). 0 suppressed across all gates. Re-run with --verbose for the full report.
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
The line names every disposition a gate can have on that run, with its
|
|
163
|
+
count, even when the count is zero: ran, deferred to a later stage, left
|
|
164
|
+
out by `--gate`, not enforced, and suppressed findings. Which gates appear
|
|
165
|
+
in each depends on your policy file.
|
|
166
|
+
|
|
167
|
+
A commit with a staged credential in it prints the full report and exits 1:
|
|
168
|
+
|
|
169
|
+
```
|
|
170
|
+
conductor 0.6.0
|
|
171
|
+
conductor run: 2 gate(s), 1 finding(s)
|
|
172
|
+
|
|
173
|
+
dependencies dep-guard 0.7.0 exit 0 153ms via dep-guard on path
|
|
174
|
+
threshold medium suppressed 0 ignored 0
|
|
175
|
+
mode staged corpusBuiltAt 2026-09-20T06:16:40.340Z lockfileFormat npm online-flag not passed
|
|
176
|
+
|
|
177
|
+
secrets vault-guard 1.8.0 exit 1 105ms via vault-guard on path
|
|
178
|
+
BLOCKING critical vault-guard/anthropic jest.config.mjs:14:12
|
|
179
|
+
Possible secret of type 'anthropic'
|
|
180
|
+
threshold medium suppressed 0 ignored not reported
|
|
181
|
+
filesScanned 1 patternsActive 59
|
|
182
|
+
|
|
183
|
+
deferred intent intent-guard did not run here; it runs from stage ci onwards
|
|
184
|
+
|
|
185
|
+
verdict: exit 1, 1 blocking finding(s) across 2 gate(s).
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
The `mode`, `corpusBuiltAt`, `lockfileFormat` and `online-flag` line under
|
|
189
|
+
`dependencies`, and the `filesScanned`/`patternsActive` line under
|
|
190
|
+
`secrets`, are each gate's own run facts, one line per gate, added to the
|
|
191
|
+
full report so a reader can see what a gate actually scanned and with
|
|
192
|
+
what, not only its verdict.
|
|
193
|
+
|
|
194
|
+
Both gates there are the ones you installed a moment ago, running with
|
|
195
|
+
their own thresholds and their own baselines. The umbrella found nothing
|
|
196
|
+
of its own, because it looks for nothing of its own.
|
|
197
|
+
|
|
198
|
+
Before opening anything, run `conductor run --verbose` on this same
|
|
199
|
+
checkout. That is the full report your policy will produce for the
|
|
200
|
+
dependency and secrets gates, with no `--trust-base` involved: a direct
|
|
201
|
+
run on your own checkout is already inside the trust boundary, so it
|
|
202
|
+
reads the policy you just wrote. **It is not the full preview for the
|
|
203
|
+
intent gate.** Locally, with no `--base`, the intent gate runs the way it
|
|
204
|
+
runs at a commit: intent-guard's own native flow, which wants an approved
|
|
205
|
+
contract and reports `BLOCKING critical intent-guard/gate-blocked` when
|
|
206
|
+
there is none. On a pull request a base ref resolves (conductor reads
|
|
207
|
+
`GITHUB_BASE_REF`, which GitHub sets for the whole job on a
|
|
208
|
+
`pull_request` event), and the umbrella instead prepares a contract for the
|
|
209
|
+
intent gate itself; with no contract to import, that path reports the
|
|
210
|
+
gate `skipped ... no contract` and never reaches the exit code. So a
|
|
211
|
+
first pull request with no contract yet is not blocked by the intent gate
|
|
212
|
+
on the pull request, whatever the local preview showed a moment before.
|
|
213
|
+
See "Intent at a pull request" below for the full mechanism.
|
|
214
|
+
|
|
215
|
+
2. **Open the first pull request in advisory mode.** Add `.guardrails.yaml`
|
|
216
|
+
and the workflow together, with `advisory: true` and `pr-comment: true`
|
|
217
|
+
on the conductor step -- the recipe under "Running the gates as an
|
|
218
|
+
advisory check" below is a complete copy-paste job -- and leave the check
|
|
219
|
+
out of branch protection for this one pull request. The step still exits
|
|
220
|
+
2 on this pull request even with `advisory: true`: the base branch has no
|
|
221
|
+
policy yet, so the run has no rules, and `advisory` never touches that
|
|
222
|
+
exit code, only a blocking finding's. Leaving the check out of branch
|
|
223
|
+
protection is what keeps that expected exit 2 from blocking the merge;
|
|
224
|
+
the step posts a comment saying so with the remedy on it, which is the
|
|
225
|
+
honest report of an unfinished adoption, not a broken tool.
|
|
226
|
+
|
|
227
|
+
3. **Merge.** Every pull request after that is judged by the policy on the
|
|
228
|
+
base branch, and a change to that policy shows up as a proposal line and
|
|
229
|
+
takes effect after its own merge.
|
|
230
|
+
|
|
231
|
+
4. **Go required.** Once a few ordinary pull requests have shown the report
|
|
232
|
+
reads the way you expect, remove `advisory: true` from the conductor step
|
|
233
|
+
and require the job's own check context in branch protection -- `gates`
|
|
234
|
+
in the recipes below, the job name, never the context the SARIF-upload
|
|
235
|
+
step reports under. That is the whole of turning this from an advisory
|
|
236
|
+
job into the one required check.
|
|
237
|
+
|
|
238
|
+
There is deliberately no mode in which the pull request's own policy file
|
|
239
|
+
decides the run, not even as a preview: step 1's preview gives you the same
|
|
240
|
+
report without putting a file the pull request controls behind a verdict on
|
|
241
|
+
the pull request page.
|
|
242
|
+
|
|
23
243
|
## Why
|
|
24
244
|
|
|
25
|
-
Run all three and you have three inits, three config files,
|
|
26
|
-
shapes, and three pre-commit hooks fighting over one file
|
|
245
|
+
Run all three family gates and you have three inits, three config files,
|
|
246
|
+
three output shapes, and three pre-commit hooks fighting over one file, and
|
|
247
|
+
a separate job for the two external scanners. That is the
|
|
27
248
|
friction this repository removes, and that is all it removes:
|
|
28
249
|
|
|
29
250
|
- **one policy file**, `.guardrails.yaml`, keyed by the role each gate
|
|
30
251
|
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;
|
|
252
|
+
- **one init**, which writes that file, and with `--hook` a single
|
|
253
|
+
pre-commit hook running every enabled gate whose stage is `commit`, which
|
|
254
|
+
by default is every gate but the intent one;
|
|
34
255
|
- **one report**, as text for a terminal or as a single SARIF 2.1.0 log
|
|
35
256
|
with one run per gate.
|
|
36
257
|
|
|
@@ -40,79 +261,10 @@ with ceremony rather than runtime named as the cost. A screenful of per-gate
|
|
|
40
261
|
detail on a commit that found nothing is that cost, paid on every commit, and
|
|
41
262
|
it is what makes a team switch a hook off.
|
|
42
263
|
|
|
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.7
|
|
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
264
|
## What it deliberately is not
|
|
113
265
|
|
|
114
|
-
It is not a
|
|
115
|
-
Every finding about your code came from one of the
|
|
266
|
+
It is not a sixth gate. It finds no bugs of its own and scans nothing.
|
|
267
|
+
Every finding about your code came from one of the five gates and is
|
|
116
268
|
labelled with which one. The only findings it adds are about the gates
|
|
117
269
|
themselves, and they are labelled `conductor`: a gate that is switched on
|
|
118
270
|
and could not run, and a gate whose output it could not read. Those exist
|
|
@@ -122,8 +274,8 @@ whole family exists to prevent.
|
|
|
122
274
|
It is not something you adopt before the gates are useful. Each gate keeps
|
|
123
275
|
its own config file, its own baseline, its own thresholds, and its own exit
|
|
124
276
|
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
|
-
|
|
277
|
+
each gate as command-line flags, which every one of them already treats as
|
|
278
|
+
higher precedence than its own config. Delete this tool and every
|
|
127
279
|
gate still runs, with exactly the configuration it had, because nothing
|
|
128
280
|
here ever touched it.
|
|
129
281
|
|
|
@@ -161,13 +313,26 @@ gates:
|
|
|
161
313
|
enforce: false
|
|
162
314
|
options:
|
|
163
315
|
require-frozen: false
|
|
316
|
+
secrets-history:
|
|
317
|
+
product: gitleaks
|
|
318
|
+
enabled: true
|
|
319
|
+
stage: ci
|
|
320
|
+
enforce: true
|
|
321
|
+
vulnerabilities:
|
|
322
|
+
product: osv-scanner
|
|
323
|
+
enabled: true
|
|
324
|
+
stage: ci
|
|
325
|
+
enforce: true
|
|
164
326
|
|
|
165
327
|
report:
|
|
166
328
|
format: text
|
|
167
329
|
```
|
|
168
330
|
|
|
169
|
-
**Gates are keyed by role**, not by product. `dependencies
|
|
170
|
-
`
|
|
331
|
+
**Gates are keyed by role**, not by product. `dependencies` (dep-guard),
|
|
332
|
+
`secrets` (vault-guard), `intent` (intent-guard), `secrets-history`
|
|
333
|
+
(gitleaks, scanning git history) and `vulnerabilities` (osv-scanner, over
|
|
334
|
+
the resolved dependency tree). The `product` field says which binary fills
|
|
335
|
+
that role today. The last two are external tools you install yourself.
|
|
171
336
|
|
|
172
337
|
**`enabled`** defaults to true. A gate that is enabled and whose binary
|
|
173
338
|
cannot be found is a blocking finding of the umbrella's own
|
|
@@ -176,7 +341,9 @@ cannot be found is a blocking finding of the umbrella's own
|
|
|
176
341
|
**`stage`** says when a gate runs: `commit`, `push`, or `ci`. Stages are
|
|
177
342
|
**cumulative** in that order, so a gate runs at its own stage and at every
|
|
178
343
|
later one, and a run at `ci` runs everything that is enabled. The defaults
|
|
179
|
-
are `commit` for `dependencies` and `secrets
|
|
344
|
+
are `commit` for `dependencies` and `secrets`, and `ci` for `intent`,
|
|
345
|
+
`secrets-history` and `vulnerabilities`: a history scan and a registry
|
|
346
|
+
lookup are pull-request work, not commit-time work.
|
|
180
347
|
|
|
181
348
|
A gate held back by the stage filter is never silent. It is one line in the
|
|
182
349
|
text report naming the stage it is waiting for, and a `conductor/gate-deferred`
|
|
@@ -190,7 +357,14 @@ enforced gate's do. The only thing it cannot do is change the exit code: its
|
|
|
190
357
|
blocking findings do not raise it, and its failing to run at all does not
|
|
191
358
|
make the run exit 2. That is the adoption ramp, so a gate can be switched on
|
|
192
359
|
and read for a few weeks before it is allowed to refuse anybody's commit.
|
|
193
|
-
`init` writes it out for every gate
|
|
360
|
+
`init` writes it out for every gate. For the intent gate it writes `true`
|
|
361
|
+
when a frozen contract already exists at init time
|
|
362
|
+
(`.intent-guard/intent-contract.yaml`, or the pre-1.3.0
|
|
363
|
+
`.conductor/intent-contract.yaml`), since the ramp is already climbed by
|
|
364
|
+
then, and leaving it unenforced would silently let a frozen contract's
|
|
365
|
+
protected paths produce findings that never fail the check. It writes
|
|
366
|
+
`false`, with a comment explaining why, when there is no contract yet to
|
|
367
|
+
enforce against.
|
|
194
368
|
|
|
195
369
|
**`options`** is handed to that gate unchanged. Each key is one of that
|
|
196
370
|
gate's own long flags with the leading dashes stripped: `fail-on: high`
|
|
@@ -198,10 +372,18 @@ becomes `--fail-on high`, `online: true` becomes `--online`,
|
|
|
198
372
|
`require-frozen: false` becomes `--no-require-frozen`, and a list becomes
|
|
199
373
|
one flag per entry. The handful of flags the umbrella supplies itself (the
|
|
200
374
|
JSON format flag, `--staged`, and the intent gate's `--project`) are
|
|
201
|
-
rejected if you also set them, rather than being silently overridden.
|
|
375
|
+
rejected if you also set them, rather than being silently overridden. For
|
|
376
|
+
the external gates the umbrella writes `--report-format`, `--report-path`,
|
|
377
|
+
`--exit-code`, `--log-opts`, `--config`, `--gitleaks-ignore-path`,
|
|
378
|
+
`--ignore-gitleaks-allow`, `--log-level`, `--redact` and `--no-banner` to
|
|
379
|
+
gitleaks, and
|
|
380
|
+
`--format`, `--config` and `--lockfile` to osv-scanner, so those are
|
|
381
|
+
reserved too. Narrow what either
|
|
382
|
+
tool reports in its own config file (`.gitleaks.toml`, `osv-scanner.toml`)
|
|
383
|
+
instead.
|
|
202
384
|
|
|
203
385
|
**There is no shared severity threshold, on purpose.** One top-level
|
|
204
|
-
`failOn` would read as one decision and mean
|
|
386
|
+
`failOn` would read as one decision and mean five different things, so
|
|
205
387
|
setting one is an error rather than a knob that half works. Each gate keeps
|
|
206
388
|
its own threshold in its own `options` block, spelled the way that gate
|
|
207
389
|
spells it.
|
|
@@ -213,21 +395,45 @@ that gate, for pointing at a build that is not installed anywhere.
|
|
|
213
395
|
|
|
214
396
|
## Commands
|
|
215
397
|
|
|
216
|
-
`conductor init` writes the policy file and
|
|
217
|
-
|
|
398
|
+
`conductor init` writes the policy file and `.guardrails/manifest.json`, the
|
|
399
|
+
record `--revert` reads back later. The manifest currently records absolute
|
|
400
|
+
machine paths rather than repo-relative ones (see "Adopting conductor"
|
|
401
|
+
above); do not commit it.
|
|
402
|
+
|
|
403
|
+
- `--hook` also writes one pre-commit hook running every enabled gate whose
|
|
404
|
+
stage is `commit`. Without it, init writes only the policy file and the
|
|
405
|
+
manifest: no hook, and none of the hook-manager detection below runs
|
|
406
|
+
either. `.git/hooks` is never part of a clone, so a hook one checkout has
|
|
407
|
+
does not follow a teammate's clone, or a fresh clone of your own; each
|
|
408
|
+
needs its own `conductor init --hook`. `--revert` still removes a hook a
|
|
409
|
+
previous `--hook` run left behind, whether or not this invocation passes
|
|
410
|
+
`--hook` itself.
|
|
218
411
|
- `--dry-run` prints every file it would write or change and writes nothing.
|
|
219
412
|
- `--revert` removes exactly what a previous init wrote, and nothing else.
|
|
220
413
|
A file changed since init is reported and left alone.
|
|
221
414
|
- `--adopt` replaces one gate's own pre-commit hook with the umbrella hook.
|
|
222
415
|
Without it, init reports the collision and stops rather than stacking a
|
|
223
416
|
second invocation of a gate that is already hooked. A hook the umbrella
|
|
224
|
-
does not recognise is never replaced, with or without `--adopt`.
|
|
417
|
+
does not recognise is never replaced, with or without `--adopt`. Only
|
|
418
|
+
meaningful together with `--hook`; without it, init errors rather than
|
|
419
|
+
silently ignoring the flag, because there is no hook for it to act on.
|
|
225
420
|
- `--force` acts on a file **conductor itself wrote** and that has changed
|
|
226
421
|
since: on its own it replaces a managed hook somebody has edited, and with
|
|
227
422
|
`--revert` it removes one, restoring an adopted hook if there was one. It
|
|
228
423
|
never overrides a foreign-hook or gate-hook refusal, with or without
|
|
229
424
|
`--adopt`: those hooks were never conductor's, and no flag here turns
|
|
230
|
-
somebody else's file into one this tool may overwrite.
|
|
425
|
+
somebody else's file into one this tool may overwrite. Like `--adopt`,
|
|
426
|
+
only meaningful together with `--hook` on an init (not on a `--revert`);
|
|
427
|
+
without it, init errors.
|
|
428
|
+
- `--project <dir>` writes into that repository instead of the current
|
|
429
|
+
directory, resolved to its git top level the same way the current
|
|
430
|
+
directory already is, so a script can point init at a repository without a
|
|
431
|
+
`cd` compound.
|
|
432
|
+
|
|
433
|
+
The rest of this section, on hook managers already wired into the
|
|
434
|
+
repository, applies only when `--hook` is given: none of it is consulted,
|
|
435
|
+
and none of it can block the policy file from being written, on a plain
|
|
436
|
+
`conductor init`.
|
|
231
437
|
|
|
232
438
|
Init recognises the hook manager already wired into the repository. husky is
|
|
233
439
|
redirected to the tracked hook it maintains rather than the generated
|
|
@@ -262,13 +468,21 @@ proceeds normally without mentioning them.
|
|
|
262
468
|
control input of the gates that support it. See "The pull-request trust
|
|
263
469
|
boundary" below. `--base` and `--trust-base` are independent and a
|
|
264
470
|
pull-request run passes both: `--base` decides which paths are judged,
|
|
265
|
-
`--trust-base` decides what they are judged by.
|
|
471
|
+
`--trust-base` decides what they are judged by. When `GITHUB_BASE_REF` is
|
|
472
|
+
set, an explicit `--trust-base` is accepted only when it resolves to the
|
|
473
|
+
same commit as `origin/$GITHUB_BASE_REF` (issue #58); anyone invoking the
|
|
474
|
+
CLI directly on a pull request, rather than through the Action, gets this
|
|
475
|
+
as its own refusal, named below.
|
|
266
476
|
- `--spec <path>` names the spec the intent gate imports its contract from.
|
|
267
477
|
- `--output <path>` writes the report to a file instead of to stdout, for a
|
|
268
478
|
CI step that uploads it. One line still goes to stdout, because a job whose
|
|
269
479
|
only product is an uploaded artifact otherwise reads as a job that did
|
|
270
480
|
nothing. A path that cannot be written is exit 2, not a green run beside a
|
|
271
|
-
report nobody can read.
|
|
481
|
+
report nobody can read. A relative value resolves against the current
|
|
482
|
+
directory the command was invoked from, not against `--project` or the
|
|
483
|
+
repository root: with `--project` pointing elsewhere, a relative
|
|
484
|
+
`--output` still lands next to where you are, not next to the repository
|
|
485
|
+
being judged.
|
|
272
486
|
- `--verbose` prints the full per-gate report even when the run is clean.
|
|
273
487
|
Text output only; the SARIF log never changes shape with it.
|
|
274
488
|
- `--compact-on-refusal` shrinks the report to the version, the verdict and
|
|
@@ -290,6 +504,13 @@ proceeds normally without mentioning them.
|
|
|
290
504
|
verdict line's own wording (it says findings were advisory and did not
|
|
291
505
|
block) change. Text output only; the SARIF log has no verdict line to
|
|
292
506
|
change and its `properties.blocking` on each result is unaffected.
|
|
507
|
+
- `--project <dir>` runs against that repository instead of the current
|
|
508
|
+
directory, resolved to its git top level the same way the current
|
|
509
|
+
directory already is, so a subdirectory resolves to that repository's top
|
|
510
|
+
level. A relative value resolves against the current directory. A path
|
|
511
|
+
that does not exist, is not a directory, or is not inside a git repository
|
|
512
|
+
is a usage error naming the path and exits 2 rather than falling back to
|
|
513
|
+
the current directory.
|
|
293
514
|
|
|
294
515
|
### Exit codes
|
|
295
516
|
|
|
@@ -298,7 +519,29 @@ proceeds normally without mentioning them.
|
|
|
298
519
|
- **2** an enabled gate could not run: its binary is missing, it exited with
|
|
299
520
|
its own could-not-run code, or it exited 1 with nothing parseable on
|
|
300
521
|
stdout, which is what a rejected config file looks like from two of the
|
|
301
|
-
three.
|
|
522
|
+
three family gates.
|
|
523
|
+
|
|
524
|
+
The external gates' exits are read per tool. gitleaks exits 1 for an error
|
|
525
|
+
as well as for a leak, so the umbrella hands it `--exit-code 3`: 3 is a leak
|
|
526
|
+
(blocked), 1 is could-not-run. gitleaks also exits 0 with an empty report
|
|
527
|
+
when git itself fails (a base ref the checkout never fetched), so a clean
|
|
528
|
+
exit that logged an `ERR` line is could-not-run too, never a pass. A
|
|
529
|
+
gitleaks exit with no report file behind it is could-not-run. osv-scanner is
|
|
530
|
+
handed every tracked lockfile by name (`package-lock.json`,
|
|
531
|
+
`npm-shrinkwrap.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock`, at any
|
|
532
|
+
depth, never under `node_modules`); when the repository tracks none, it is
|
|
533
|
+
not spawned at all and the gate is reported clean with a
|
|
534
|
+
`conductor/nothing-to-scan` note, so a docs-only repository is not red on
|
|
535
|
+
every pull request. Its 1 is blocked. Its own 128 ("no package sources
|
|
536
|
+
found") on lockfiles it WAS handed means they parsed to no packages; that is
|
|
537
|
+
clean too, with a distinct `conductor/lockfiles-empty` note naming the
|
|
538
|
+
files. Only those npm-family names are handed over today: a repository
|
|
539
|
+
whose only lockfile belongs to another ecosystem gets nothing-to-scan from
|
|
540
|
+
this gate. Lockfiles inside git submodules are never listed. In a sparse
|
|
541
|
+
checkout a tracked lockfile that is not on disk is still handed over and
|
|
542
|
+
osv-scanner exits 127 on it, a false could-not-run that fails closed. Any other osv-scanner exit
|
|
543
|
+
(127 is its error code) is could-not-run. A gitleaks older than 8.19 or an
|
|
544
|
+
osv-scanner older than 2.0 is could-not-run, naming the floor.
|
|
302
545
|
|
|
303
546
|
`run --advisory` maps exit 1 to exit 0. It never touches exit 2: a gate that
|
|
304
547
|
could not run is a different failure from a blocking finding, and advisory
|
|
@@ -432,6 +675,46 @@ one-line summary and on the verdict, with a line each under `--verbose` and a
|
|
|
432
675
|
reflow, a re-quote or an edited comment is not a proposal: the two files are
|
|
433
676
|
compared as parsed documents.
|
|
434
677
|
|
|
678
|
+
**An explicit `--trust-base` redirect gets a refusal on a pull request, at two
|
|
679
|
+
places (issue #58), and neither closes the whole hole by itself.**
|
|
680
|
+
`refuseTrustBaseRef` above only refuses a ref that resolves to HEAD's own
|
|
681
|
+
commit or to HEAD's own tree, which covers HEAD itself and an *unmoved*
|
|
682
|
+
`origin/<pr-branch>`. Once the base branch has moved, `origin/<pr-branch>` no
|
|
683
|
+
longer matches either test, so a same-repo pull request could set
|
|
684
|
+
`trust-base` to its own branch, in its own workflow file, and have conductor
|
|
685
|
+
read `.guardrails.yaml` from the pull request after all, at which point the
|
|
686
|
+
pull request controls the whole policy. dep-guard's own base input took the
|
|
687
|
+
stronger line for its base input in 0.8.0: on a `pull_request` event an
|
|
688
|
+
explicit value is refused outright.
|
|
689
|
+
|
|
690
|
+
**The Action refuses an explicit redirect on `pull_request` and
|
|
691
|
+
`pull_request_target` events.** Its validate step refuses a `trust-base`
|
|
692
|
+
input outright on those events, naming the value given and the fix, which is
|
|
693
|
+
to remove the input; see "The Action" below.
|
|
694
|
+
|
|
695
|
+
**The CLI check catches a misconfigured or innocent-looking redirect when
|
|
696
|
+
`GITHUB_BASE_REF` is set**, for anyone invoking the CLI directly in CI. When
|
|
697
|
+
that variable is set, an explicit `--trust-base` is accepted only when it
|
|
698
|
+
resolves to the same commit as `origin/$GITHUB_BASE_REF`, which is exactly
|
|
699
|
+
what the Action itself always passes, so an ordinary pull-request run is
|
|
700
|
+
unaffected. A ref naming the pull request's own branch, or anything else that
|
|
701
|
+
disagrees, is refused with both refs and both commits named, through the same
|
|
702
|
+
could-not-run path as every other trust-base refusal: exit 2, the report
|
|
703
|
+
leads with the reason, and nothing is checked. When `origin/$GITHUB_BASE_REF`
|
|
704
|
+
itself does not resolve, this fails closed too, naming it, for the same
|
|
705
|
+
reason the fetch-depth remedy below exists.
|
|
706
|
+
|
|
707
|
+
**Neither layer closes anything against a pull request that edits its own
|
|
708
|
+
workflow file.** A CLI invocation on a pull request can simply omit
|
|
709
|
+
`--trust-base`, or a workflow step can blank `GITHUB_BASE_REF` in its own env,
|
|
710
|
+
and nothing here refuses either; the Action has the matching gap, since a
|
|
711
|
+
pull request can pin `uses:` to a tag published before this fix, in its own
|
|
712
|
+
workflow file. This is exactly the boundary "On a pull request those four
|
|
713
|
+
inputs may not pin backward" (below, under "The Action") already draws for
|
|
714
|
+
the four `*-version` inputs: the control for a workflow edit is branch
|
|
715
|
+
protection on the base branch with review required for `.github/workflows`,
|
|
716
|
+
and nothing in this section, or in that one, substitutes for it.
|
|
717
|
+
|
|
435
718
|
**It fails closed.** A `--trust-base` that does not resolve is not a reason to
|
|
436
719
|
fall back to the pull request's own file, because that fallback is the hole:
|
|
437
720
|
the run exits 2 and the report **leads with the refusal**, naming the ref and
|
|
@@ -445,6 +728,39 @@ judged while still reporting pull-request mode as on. Pass the base
|
|
|
445
728
|
commit, which is HEAD. If the base branch has no `.guardrails.yaml` at all,
|
|
446
729
|
the run has no rules and exits 2 rather than using the pull request's; the
|
|
447
730
|
file the pull request adds decides what runs once it is on the base branch.
|
|
731
|
+
|
|
732
|
+
**One narrow exception to the equal-tree refusal (issue #69).** When a pull
|
|
733
|
+
request's net diff is empty -- a value committed and then backed out inside
|
|
734
|
+
the same pull request -- the merge ref GitHub builds has a tree
|
|
735
|
+
byte-identical to the base's, and the refusal above would stop
|
|
736
|
+
secrets-history from running on exactly the shape it exists to catch: the
|
|
737
|
+
value is gone from the tree but still in the history between the base and
|
|
738
|
+
HEAD. So the refusal makes one exception, and only one: when HEAD is a real
|
|
739
|
+
merge commit (two or more parents) and `--trust-base` resolves to HEAD's
|
|
740
|
+
**first** parent, the run is not refused. First-parent identity is the
|
|
741
|
+
discriminator, not ancestry, because GitHub always builds the merge ref with
|
|
742
|
+
the base branch as the first parent and the pull request's own head as the
|
|
743
|
+
second: a trust base resolving to HEAD's **second** parent is also an
|
|
744
|
+
ancestor and also carries the same tree, and it is exactly the ref this rule
|
|
745
|
+
must keep refusing. In the accepted shape the umbrella still does not judge
|
|
746
|
+
the unchanged tree as if it were the change: it runs every enabled gate
|
|
747
|
+
whose input is git history rather than the tree -- gitleaks today -- with its
|
|
748
|
+
ordinary arguments (already scoped to `<base>..HEAD`), and every other
|
|
749
|
+
enabled gate is reported as tree-unchanged rather than spawned: one line in
|
|
750
|
+
the full report, a clause on the one-line summary, and a
|
|
751
|
+
`conductor/tree-unchanged` notification in the SARIF log, never reaching the
|
|
752
|
+
exit code. Every other equal-tree shape -- a non-merge HEAD, the second
|
|
753
|
+
parent, any other ancestor -- keeps refusing exactly as before.
|
|
754
|
+
|
|
755
|
+
The exception needs HEAD's own parents, so it needs the same non-shallow
|
|
756
|
+
checkout the rest of pull-request mode already requires: `fetch-depth: 0`
|
|
757
|
+
(see below). On a depth-1 checkout git reports the merge commit with no
|
|
758
|
+
parents at all, so the first-parent check cannot match and the run keeps
|
|
759
|
+
refusing with the ordinary equal-tree message -- it fails closed rather than
|
|
760
|
+
guessing. That loss costs nothing real: at depth 1 gitleaks could not have
|
|
761
|
+
seen the backed-out commit either, since its own history scan has nothing
|
|
762
|
+
before HEAD to scope `<base>..HEAD` against.
|
|
763
|
+
|
|
448
764
|
That is why adopting conductor takes one merge before the gates can judge
|
|
449
765
|
anything, and it is not an oversight: the policy file can name a program to
|
|
450
766
|
run, so a run that read it from the pull request would let the pull request
|
|
@@ -452,8 +768,66 @@ choose its own judge on exactly the repositories that have no rules yet. See
|
|
|
452
768
|
"Adopting conductor" below for the sequence and for how to see what your
|
|
453
769
|
policy will do before you merge it.
|
|
454
770
|
|
|
455
|
-
**Which gates are covered.** All
|
|
456
|
-
intent-guard from **1.4.0**, vault-guard from **1.7.0
|
|
771
|
+
**Which gates are covered.** All five: dep-guard from **0.6.0**,
|
|
772
|
+
intent-guard from **1.4.0**, vault-guard from **1.7.0**, and the two
|
|
773
|
+
external gates at their command-line floors, gitleaks **8.19.0** and
|
|
774
|
+
osv-scanner **2.0.0**.
|
|
775
|
+
|
|
776
|
+
**The external gates get their pull-request mode from the umbrella.**
|
|
777
|
+
Neither tool has a `--trust-base`, and both auto-load a config from the tree
|
|
778
|
+
they scan, which on a pull request is the head: a pull request could add an
|
|
779
|
+
allowlist entry for exactly the secret or advisory it introduces. So on a
|
|
780
|
+
pull-request run the umbrella reads `.gitleaks.toml` and `osv-scanner.toml`
|
|
781
|
+
from the base ref with `git show` and passes each tool that copy with
|
|
782
|
+
`--config`. When the base has none, the tool gets a neutral one (gitleaks'
|
|
783
|
+
built-in rules, an empty osv-scanner config) rather than nothing, because
|
|
784
|
+
nothing would let it find the head's file on its own. gitleaks'
|
|
785
|
+
`.gitleaksignore` is handled the same way, and because gitleaks also loads
|
|
786
|
+
the ignore file at the root of whatever it scans, the umbrella scans the
|
|
787
|
+
repository's git directory instead of the working tree on a pull request:
|
|
788
|
+
the same history, without the head's ignore file. A head-side change to any
|
|
789
|
+
of these files is reported as a proposal line and takes effect after merge,
|
|
790
|
+
exactly like a change to `.guardrails.yaml`. History is scoped to
|
|
791
|
+
`<base>..HEAD` on a pull request and to `HEAD` locally, so a secret on
|
|
792
|
+
another branch never reddens this one. Merge commits are scanned by their
|
|
793
|
+
first-parent diff, so a secret added inside a merge (while resolving a
|
|
794
|
+
conflict, say) is found; the same leak seen in a pull request's commit and
|
|
795
|
+
again in its merge is reported once, with the other commit listed.
|
|
796
|
+
|
|
797
|
+
A base `.gitleaks.toml` can name another file with `[extend] path`, which
|
|
798
|
+
gitleaks resolves against its working directory. On a pull request
|
|
799
|
+
conductor copies every file in that chain from the base ref into a
|
|
800
|
+
directory of its own and runs gitleaks from there, so the head's copy of an
|
|
801
|
+
extended file is never read; a head-side edit to one is a proposal, and an
|
|
802
|
+
extended file the base does not have makes the gate could-not-run, naming
|
|
803
|
+
it. gitleaks' log level is pinned at `info` and `log-level` is reserved,
|
|
804
|
+
because conductor reads gitleaks' error lines to tell a failed scan from a
|
|
805
|
+
clean one. Write the extend as a plain relative path in an `[extend]` table:
|
|
806
|
+
a base `.gitleaks.toml` whose extend target is a symbolic link, or which
|
|
807
|
+
writes the extend as an inline table or a quoted key, fails closed on every
|
|
808
|
+
pull request until it is rewritten that way.
|
|
809
|
+
|
|
810
|
+
**Local runs and `.gitattributes`.** On a pull request gitleaks scans the
|
|
811
|
+
repository's git directory, where the head's `.gitattributes` is not read.
|
|
812
|
+
A local run scans the working tree, so a file your own `.gitattributes`
|
|
813
|
+
marks `binary` is skipped by gitleaks there. Pull requests are not affected.
|
|
814
|
+
|
|
815
|
+
On a pull request gitleaks is also passed `--ignore-gitleaks-allow`, so an
|
|
816
|
+
inline `gitleaks:allow` comment does not hide a secret: an inline allow
|
|
817
|
+
lives in the tree being judged, so the pull request controls it. A
|
|
818
|
+
legitimate allow belongs in the base branch's `.gitleaks.toml` allowlist or
|
|
819
|
+
`.gitleaksignore`, both of which conductor already reads from the base.
|
|
820
|
+
Local runs keep inline allows.
|
|
821
|
+
|
|
822
|
+
osv-scanner is never pointed at a directory to walk, because its own walk
|
|
823
|
+
skips anything `.gitignore` matches, tracked or not, so one ignore line in a
|
|
824
|
+
pull request could hide a committed lockfile. conductor lists the tracked
|
|
825
|
+
lockfiles with `git ls-files` and hands each one over with `--lockfile`. On
|
|
826
|
+
a pull request that list comes from the head's index, not the base ref: the
|
|
827
|
+
lockfiles are the tree being judged, and adding or removing one is visible
|
|
828
|
+
in the diff. Only the root `osv-scanner.toml` is read from the base and
|
|
829
|
+
passed with `--config`, which overrides any nested one for the run; a
|
|
830
|
+
nested one the pull request adds or edits is reported as a proposal.
|
|
457
831
|
|
|
458
832
|
The umbrella asks each gate its version and passes the flag only to a build
|
|
459
833
|
that understands it, so an older gate is not handed a flag it would reject. A
|
|
@@ -473,7 +847,7 @@ the flag.
|
|
|
473
847
|
|
|
474
848
|
## Intent at a pull request
|
|
475
849
|
|
|
476
|
-
The intent gate is the only one of the
|
|
850
|
+
The intent gate is the only one of the five with any ceremony: its native
|
|
477
851
|
flow wants a contract approved before the work starts, which is a per-task
|
|
478
852
|
human step. That step is exactly what a pull request cannot carry, so at the
|
|
479
853
|
`ci` stage the umbrella stands in for it.
|
|
@@ -486,6 +860,20 @@ With no `--base`, `GITHUB_BASE_REF` is used as `origin/<value>` when it is
|
|
|
486
860
|
set, and the text report says so. With neither, the intent gate runs the way
|
|
487
861
|
it does at a commit: against the staged index, or the paths you name.
|
|
488
862
|
|
|
863
|
+
**This is why a local preview and a pull-request run can disagree about a
|
|
864
|
+
missing contract.** The contract-discovery rules below (`--spec`, a frozen
|
|
865
|
+
native contract, a `Spec:` line, the `docs/superpowers/specs` convention)
|
|
866
|
+
only engage once `--base` resolves to something, or `--spec` is given.
|
|
867
|
+
Neither is true of a plain `conductor run` on your own checkout, so a
|
|
868
|
+
repository with no contract gets intent-guard's own native answer instead:
|
|
869
|
+
`BLOCKING critical intent-guard/gate-blocked`, because that flow wants an
|
|
870
|
+
approved contract and none exists. On a pull request `--base` is set, this
|
|
871
|
+
whole section's machinery engages, and a branch with nothing to import
|
|
872
|
+
lands in the no-contract state below instead: reported, and never reaching
|
|
873
|
+
the exit code. Read a local `BLOCKING` line on the intent gate as "there is
|
|
874
|
+
no contract for the umbrella to import here yet," not as "this pull request
|
|
875
|
+
will fail."
|
|
876
|
+
|
|
489
877
|
A git failure here is **fail-closed**: could-not-run, so exit 2 for an
|
|
490
878
|
enforced gate and a note for an unenforced one. There is deliberately no
|
|
491
879
|
fallback to an empty path set, because an empty path set is what a passing
|
|
@@ -544,6 +932,22 @@ skipped line, in the verdict and on the one-line summary of a clean run, so a
|
|
|
544
932
|
reader can tell "nobody has written one" from "somebody decided against one"
|
|
545
933
|
wherever they meet it.
|
|
546
934
|
|
|
935
|
+
**A repository with no contract yet is not a repository this gate can act
|
|
936
|
+
on**, and the no-contract skip line names `docs/superpowers/specs`, which is
|
|
937
|
+
a convention from this family's own tooling and not one an outside adopter
|
|
938
|
+
has reason to recognise. The next step, if you want this gate to have an
|
|
939
|
+
opinion here, is the one intent-guard's own documentation describes: draft a
|
|
940
|
+
contract naming the paths worth protecting, then freeze it, and keep the
|
|
941
|
+
frozen file committed so rule 2 above finds it on every pull request from
|
|
942
|
+
then on. Until you do that, a project rule that lives only in `AGENTS.md`
|
|
943
|
+
never blocks anything through this gate. intent-guard does read prose rules
|
|
944
|
+
files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, cursor rules) as constraint
|
|
945
|
+
sources, but by its own design a constraint from that source is advisory
|
|
946
|
+
and leaves the exit code alone; only a user-stated constraint, or one
|
|
947
|
+
promoted with `intent-guard correct --promote`, can block. Conductor itself
|
|
948
|
+
never opens that file. What is enforced is the frozen contract or the
|
|
949
|
+
imported spec, never project convention documented in prose.
|
|
950
|
+
|
|
547
951
|
**A waiver is a decision, recorded by whoever wrote the pull request body,
|
|
548
952
|
and that includes a contributor from a fork.** On the ordinary path, where a
|
|
549
953
|
repository has no frozen contract of its own, `Spec: none` means the intent
|
|
@@ -556,7 +960,24 @@ and keeps it committed.
|
|
|
556
960
|
**What blocks is unchanged.** Blocking stays where intent-guard puts it:
|
|
557
961
|
budget breaches block, subject to `enforce`. Drift on its own is reported and
|
|
558
962
|
not blocked, which is already intent-guard's own behaviour. The umbrella adds
|
|
559
|
-
no severity threshold of its own here either.
|
|
963
|
+
no severity threshold of its own here either, and intent-guard 1.7.0's own
|
|
964
|
+
advance-notice warnings about an unmatchable `protected_paths` or
|
|
965
|
+
`allowed_paths` entry never reach the exit code either, right up until the
|
|
966
|
+
2.0.0 release where intent-guard turns that same shape into a blocking
|
|
967
|
+
reason. Where they print depends on how much of the report is showing: as a
|
|
968
|
+
note under the intent gate in the full report (`--verbose`, a non-clean run,
|
|
969
|
+
or the pull-request comment, which the Action always renders with
|
|
970
|
+
`--verbose`), and, on an otherwise-clean run with neither, counted without
|
|
971
|
+
their text in the one-line summary's own note count instead.
|
|
972
|
+
|
|
973
|
+
**A prose-sourced constraint finding is never marked blocking, even when the
|
|
974
|
+
run blocks for an unrelated reason.** intent-guard 1.6.0 caps a constraint
|
|
975
|
+
whose source is one of those same prose rules files at advisory: a strong
|
|
976
|
+
match is still reported, but it never raises the gate's own exit code. A run
|
|
977
|
+
that blocks on scope creep alone still carries that capped finding in its
|
|
978
|
+
report, and it is rendered as a non-blocking, lower-severity line in the text
|
|
979
|
+
report and with `properties.blocking: false` in SARIF, rather than inheriting
|
|
980
|
+
the run's own blocking flag the way every other drift finding does.
|
|
560
981
|
|
|
561
982
|
## The Action
|
|
562
983
|
|
|
@@ -640,7 +1061,15 @@ rules it is judged by; a change to the rules shows as a proposal line and
|
|
|
640
1061
|
takes effect after merge. See "The pull-request trust boundary" above. On any
|
|
641
1062
|
other event it passes nothing and behaviour is unchanged. The `trust-base`
|
|
642
1063
|
input names the ref explicitly, for a platform where `GITHUB_BASE_REF` is not
|
|
643
|
-
set.
|
|
1064
|
+
set. **On a `pull_request` or `pull_request_target` event this input is
|
|
1065
|
+
refused outright, in the validate step** (issue #58). On `pull_request` the
|
|
1066
|
+
workflow file is the pull request's own, so a value here that redirects the
|
|
1067
|
+
trust base is settable by the thing it judges; on `pull_request_target` the
|
|
1068
|
+
workflow file is the *base* branch's own instead, but the input is refused
|
|
1069
|
+
there too, because pull-request mode already derives the trust base on both
|
|
1070
|
+
events and an explicit redirect has no legitimate use on either. The refusal
|
|
1071
|
+
names the value that was given and the fix, which is to remove the input: the
|
|
1072
|
+
action already derives `origin/$GITHUB_BASE_REF` itself on that event.
|
|
644
1073
|
|
|
645
1074
|
There is deliberately **no input that turns pull-request mode off**.
|
|
646
1075
|
Base-ref judging is the floor rather than a knob, and on a `pull_request`
|
|
@@ -668,14 +1097,14 @@ jobs:
|
|
|
668
1097
|
contents: read
|
|
669
1098
|
security-events: write
|
|
670
1099
|
steps:
|
|
671
|
-
- uses: actions/checkout@
|
|
1100
|
+
- uses: actions/checkout@v7
|
|
672
1101
|
with:
|
|
673
1102
|
fetch-depth: 0
|
|
674
|
-
- uses: actions/setup-node@
|
|
1103
|
+
- uses: actions/setup-node@v7
|
|
675
1104
|
with:
|
|
676
1105
|
node-version: '22.11.0'
|
|
677
1106
|
- id: conductor
|
|
678
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1107
|
+
uses: vaultcompasshq/conductor@v0.6.0
|
|
679
1108
|
with:
|
|
680
1109
|
output: conductor.sarif
|
|
681
1110
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -702,7 +1131,7 @@ jobs:
|
|
|
702
1131
|
contents: read
|
|
703
1132
|
security-events: write
|
|
704
1133
|
steps:
|
|
705
|
-
- uses: actions/checkout@
|
|
1134
|
+
- uses: actions/checkout@v7
|
|
706
1135
|
with:
|
|
707
1136
|
# Required, for two reasons now. Without it there is no merge base
|
|
708
1137
|
# to diff against, and the intent gate fails closed rather than
|
|
@@ -711,7 +1140,7 @@ jobs:
|
|
|
711
1140
|
# base ref that will not resolve is exit 2 for every enabled gate.
|
|
712
1141
|
fetch-depth: 0
|
|
713
1142
|
- uses: pnpm/action-setup@v4
|
|
714
|
-
- uses: actions/setup-node@
|
|
1143
|
+
- uses: actions/setup-node@v7
|
|
715
1144
|
with:
|
|
716
1145
|
# Not a bare major: Node 22.0.0 ships npm 10.5.1, which the action
|
|
717
1146
|
# refuses because that client reports a clean install as tampered
|
|
@@ -724,7 +1153,7 @@ jobs:
|
|
|
724
1153
|
# pinned below.
|
|
725
1154
|
- run: pnpm install --frozen-lockfile
|
|
726
1155
|
- id: conductor
|
|
727
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1156
|
+
uses: vaultcompasshq/conductor@v0.6.0
|
|
728
1157
|
with:
|
|
729
1158
|
output: conductor.sarif
|
|
730
1159
|
# Exact versions, never a range and never "latest". These four
|
|
@@ -735,10 +1164,10 @@ jobs:
|
|
|
735
1164
|
# request of their own. Forward only on a pull request: the action
|
|
736
1165
|
# refuses a pin below what its tag ships, and the four lines can be
|
|
737
1166
|
# left out entirely to take that tag's own versions.
|
|
738
|
-
conductor-version: 0.
|
|
739
|
-
dep-guard-version: 0.
|
|
1167
|
+
conductor-version: 0.6.0
|
|
1168
|
+
dep-guard-version: 0.9.0
|
|
740
1169
|
vault-guard-version: 1.8.0
|
|
741
|
-
intent-guard-version: 1.
|
|
1170
|
+
intent-guard-version: 1.7.0
|
|
742
1171
|
- uses: github/codeql-action/upload-sarif@v3
|
|
743
1172
|
# Always: the log is most worth having on the run that failed.
|
|
744
1173
|
if: always()
|
|
@@ -754,6 +1183,37 @@ jobs:
|
|
|
754
1183
|
sarif_file: ${{ steps.conductor.outputs.sarif }}
|
|
755
1184
|
```
|
|
756
1185
|
|
|
1186
|
+
**The two external gates are installed by your workflow, not by the
|
|
1187
|
+
Action.** The Action still installs exactly its four npm packages and has no
|
|
1188
|
+
input for gitleaks or osv-scanner; conductor downloads, pins and checksums
|
|
1189
|
+
no third-party binary. If the policy enables `secrets-history` or
|
|
1190
|
+
`vulnerabilities`, add a step before the conductor step that puts both tools
|
|
1191
|
+
on `PATH`, pinned by version and checked against the release's own
|
|
1192
|
+
checksum, the same way you would for a standalone security job:
|
|
1193
|
+
|
|
1194
|
+
```yaml
|
|
1195
|
+
- name: Install gitleaks and osv-scanner
|
|
1196
|
+
run: |
|
|
1197
|
+
set -euo pipefail
|
|
1198
|
+
bin="$RUNNER_TEMP/external-gates"
|
|
1199
|
+
mkdir -p "$bin"
|
|
1200
|
+
cd "$RUNNER_TEMP"
|
|
1201
|
+
curl -sSLO https://github.com/gitleaks/gitleaks/releases/download/v8.30.1/gitleaks_8.30.1_linux_x64.tar.gz
|
|
1202
|
+
echo "551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb gitleaks_8.30.1_linux_x64.tar.gz" | sha256sum -c -
|
|
1203
|
+
tar -xzf gitleaks_8.30.1_linux_x64.tar.gz -C "$bin" gitleaks
|
|
1204
|
+
curl -sSL -o "$bin/osv-scanner" https://github.com/google/osv-scanner/releases/download/v2.6.0/osv-scanner_linux_amd64
|
|
1205
|
+
echo "ca69b3d3cd08f889a49dc0a383122f71cc528b83803671df5fd874d97485b108 $bin/osv-scanner" | sha256sum -c -
|
|
1206
|
+
chmod +x "$bin/osv-scanner"
|
|
1207
|
+
echo "$bin" >> "$GITHUB_PATH"
|
|
1208
|
+
```
|
|
1209
|
+
|
|
1210
|
+
`fetch-depth: 0` on the checkout matters more with gitleaks enabled: on a
|
|
1211
|
+
pull request conductor scans `<base>..HEAD`, and a base that was never
|
|
1212
|
+
fetched is a git error gitleaks itself would report as a clean scan of
|
|
1213
|
+
nothing. conductor reads that error off gitleaks' log and reports the gate
|
|
1214
|
+
as could-not-run instead. A missing tool is could-not-run as well, with the
|
|
1215
|
+
install step named in the report.
|
|
1216
|
+
|
|
757
1217
|
The `@v4` pins there are readable, not safe: a tag moves, so pinning by one
|
|
758
1218
|
runs whatever its author pushes to it next. Pin every third-party action by
|
|
759
1219
|
commit digest in a workflow you actually run, the way this repository's own
|
|
@@ -791,15 +1251,15 @@ jobs:
|
|
|
791
1251
|
contents: read
|
|
792
1252
|
pull-requests: write
|
|
793
1253
|
steps:
|
|
794
|
-
- uses: actions/checkout@
|
|
1254
|
+
- uses: actions/checkout@v7
|
|
795
1255
|
with:
|
|
796
1256
|
fetch-depth: 0
|
|
797
|
-
- uses: actions/setup-node@
|
|
1257
|
+
- uses: actions/setup-node@v7
|
|
798
1258
|
with:
|
|
799
1259
|
node-version: '22.11.0'
|
|
800
1260
|
- id: conductor
|
|
801
1261
|
timeout-minutes: 5
|
|
802
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1262
|
+
uses: vaultcompasshq/conductor@v0.6.0
|
|
803
1263
|
with:
|
|
804
1264
|
pr-comment: true
|
|
805
1265
|
advisory: true
|
|
@@ -830,34 +1290,82 @@ author nothing they could not already do by editing the workflow to add
|
|
|
830
1290
|
edit, is branch protection requiring review on `.github/workflows`, not
|
|
831
1291
|
anything in `action.yml`.
|
|
832
1292
|
|
|
833
|
-
|
|
1293
|
+
**A `paths:` filter on this job is a real trade, not a free speedup, and the
|
|
1294
|
+
honest default is to skip it.** The biggest reason is not about coverage, it
|
|
1295
|
+
is about merging at all: `paths:` applies to the workflow's own trigger, and
|
|
1296
|
+
a required check whose workflow a `paths:` filter kept from running is
|
|
1297
|
+
reported as never having run at all, not as passed. That check then sits
|
|
1298
|
+
**pending**, and a pull request cannot merge while a required check is
|
|
1299
|
+
pending, regardless of how trivial the change is. GitHub's own documentation
|
|
1300
|
+
describes exactly this failure mode for a required, `paths:`-filtered
|
|
1301
|
+
workflow, and its usual workaround: a job that always runs, regardless of
|
|
1302
|
+
what changed, and reports success or failure on its own rather than relying
|
|
1303
|
+
on the whole workflow being skipped or not.
|
|
1304
|
+
|
|
1305
|
+
The coverage cost is real too, separately from the merge-blocking one. Every
|
|
1306
|
+
gate in the default policy reads the whole changed set, not a slice of it:
|
|
1307
|
+
gitleaks scans git history, so a secret can land in any file regardless of
|
|
1308
|
+
what kind of pull request carries it; vault-guard's own staged scan is the
|
|
1309
|
+
same, over whatever paths changed; dep-guard and osv-scanner only care about
|
|
1310
|
+
manifests and lockfiles, but they still need to see a pull request touch one
|
|
1311
|
+
to react to it; and intent-guard's drift and budget checks are evaluated
|
|
1312
|
+
against every changed path, not only source. A `paths:` filter keyed on
|
|
1313
|
+
`package.json`, the lockfile, and your source globs is exactly right for
|
|
1314
|
+
dep-guard and osv-scanner and exactly wrong for the two secrets gates: it
|
|
1315
|
+
makes a docs-only pull request skip the whole job, gitleaks and vault-guard
|
|
1316
|
+
included, which means a secret pasted into a docs-only change, a comment, or
|
|
1317
|
+
a config file the filter did not list is never scanned at all. That is the
|
|
1318
|
+
cost, plainly: fewer runs bought by turning off secrets scanning on the pull
|
|
1319
|
+
requests the filter excludes.
|
|
1320
|
+
|
|
1321
|
+
If your workflow already has its own required security job and you only
|
|
1322
|
+
want this one to skip clean docs-only changes, add GitHub's own `paths:`
|
|
1323
|
+
(or `paths-ignore:`) to the `on: pull_request` block, the same syntax GitHub
|
|
1324
|
+
documents for any workflow trigger, and account for both traps above before
|
|
1325
|
+
you make the job required: the pull requests it would leave permanently
|
|
1326
|
+
pending, and the coverage this recipe would then lose on exactly the pull
|
|
1327
|
+
requests it skips. The alternative this README recommends is to leave
|
|
1328
|
+
the job triggering on every pull request: a run with nothing to report is
|
|
1329
|
+
not a run worth avoiding, and this recipe has no documented time budget to
|
|
1330
|
+
promise you here, because that number depends on your repository's size and
|
|
1331
|
+
the gates you enable, not on anything conductor fixes. Measure it once on
|
|
1332
|
+
your own repository if you need a number to plan around.
|
|
1333
|
+
|
|
1334
|
+
**Renaming the job changes what branch protection is watching for.** GitHub
|
|
1335
|
+
matches a required check by its context, which is the JOB's name (`gates`
|
|
1336
|
+
here), never the workflow's name (`guardrails-advisory`). If you split this
|
|
1337
|
+
into a paths-filtered job with a different name, or rename the job for any
|
|
1338
|
+
other reason, a pull request that no longer produces the old context name
|
|
1339
|
+
will sit waiting on a check that will never report, until you also update
|
|
1340
|
+
the required-checks list in
|
|
1341
|
+
the branch protection ruleset to match. That edit lives on the repository's
|
|
1342
|
+
settings, not in the workflow file, so it is easy to make the workflow
|
|
1343
|
+
change and forget the other half.
|
|
834
1344
|
|
|
835
|
-
|
|
836
|
-
steps rather than being surprised by one:
|
|
837
|
-
|
|
838
|
-
1. On a branch, run `conductor init`, then run `conductor run --verbose` on
|
|
839
|
-
your own checkout. That is the full report your policy will produce, with
|
|
840
|
-
no `--trust-base` involved: a direct run on your own checkout is already
|
|
841
|
-
inside the trust boundary, so it reads the policy you just wrote. This is
|
|
842
|
-
where you tune thresholds, not on a pull request.
|
|
843
|
-
2. Open the pull request with `.guardrails.yaml` and the workflow together,
|
|
844
|
-
and set `advisory: true` on the conductor step, the same as the advisory
|
|
845
|
-
recipe above, and leave the check not required in branch protection for
|
|
846
|
-
this one pull request. The step still exits 2 on this pull request even
|
|
847
|
-
with `advisory: true`: the base branch has no policy yet, so the run has
|
|
848
|
-
no rules, and `advisory` never touches that exit code, only a blocking
|
|
849
|
-
finding's. Leaving the check unrequired is what keeps that expected exit 2
|
|
850
|
-
from blocking the merge; the step posts a comment saying so with the
|
|
851
|
-
remedy on it, which is the honest report of an unfinished adoption, not a
|
|
852
|
-
broken tool.
|
|
853
|
-
3. Merge. Every pull request after that is judged by the policy on the base
|
|
854
|
-
branch, and a change to that policy shows up as a proposal line and takes
|
|
855
|
-
effect after its own merge.
|
|
1345
|
+
### Adopting conductor
|
|
856
1346
|
|
|
857
|
-
|
|
858
|
-
|
|
859
|
-
|
|
860
|
-
|
|
1347
|
+
See "Adopting conductor" near the top of this README for the ordered
|
|
1348
|
+
walkthrough: init, a first pull request in advisory mode, merge, then go
|
|
1349
|
+
required. This subsection is the mechanism behind two of those steps.
|
|
1350
|
+
|
|
1351
|
+
**Why the first pull request still exits 2 under `advisory: true`.**
|
|
1352
|
+
`advisory: true` maps a blocking **finding** to exit 0; it has no opinion
|
|
1353
|
+
about a run that never had a policy to be judged by. The pull request that
|
|
1354
|
+
first adds `.guardrails.yaml` is judged against the base branch, which has
|
|
1355
|
+
none yet, so the run is refused outright before any gate produces a finding
|
|
1356
|
+
for `advisory` to act on. Leaving the check out of branch protection for
|
|
1357
|
+
that one pull request is what keeps the expected exit 2 from blocking the
|
|
1358
|
+
merge; the step posts a comment naming the ref and the remedy.
|
|
1359
|
+
|
|
1360
|
+
**Why "go required" means the job's own context, never the SARIF-upload
|
|
1361
|
+
row.** The recipes above upload conductor's SARIF log with
|
|
1362
|
+
`github/codeql-action/upload-sarif`, which can add its own code-scanning
|
|
1363
|
+
check to a pull request's checks list alongside the workflow job's own
|
|
1364
|
+
check. Branch protection's required-checks picker can then show both. Only
|
|
1365
|
+
the job's own context (`gates` in the recipes above, the job key, not any
|
|
1366
|
+
step name) carries conductor's actual exit code; a code-scanning check can
|
|
1367
|
+
read green from an old scan, or from `continue-on-error` on the upload step
|
|
1368
|
+
itself, independent of whether the gates step passed. Require the job.
|
|
861
1369
|
|
|
862
1370
|
### The report as a pull request comment
|
|
863
1371
|
|
|
@@ -875,7 +1383,7 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
875
1383
|
steps:
|
|
876
1384
|
# ... checkout, pnpm, setup-node, install, as in the example above ...
|
|
877
1385
|
- id: conductor
|
|
878
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1386
|
+
uses: vaultcompasshq/conductor@v0.6.0
|
|
879
1387
|
with:
|
|
880
1388
|
output: conductor.sarif
|
|
881
1389
|
pr-comment: true
|
|
@@ -927,12 +1435,12 @@ per pull request.
|
|
|
927
1435
|
|
|
928
1436
|
```yaml
|
|
929
1437
|
- id: conductor-package-a
|
|
930
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1438
|
+
uses: vaultcompasshq/conductor@v0.6.0
|
|
931
1439
|
with:
|
|
932
1440
|
pr-comment: true
|
|
933
1441
|
pr-comment-marker: 'package-a'
|
|
934
1442
|
- id: conductor-package-b
|
|
935
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1443
|
+
uses: vaultcompasshq/conductor@v0.6.0
|
|
936
1444
|
with:
|
|
937
1445
|
pr-comment: true
|
|
938
1446
|
pr-comment-marker: 'package-b'
|
|
@@ -1035,12 +1543,16 @@ In: the policy file and its schema, `init` with dry-run, revert, and adopt,
|
|
|
1035
1543
|
`run` producing the combined text report and a combined SARIF log, the
|
|
1036
1544
|
composed exit code, per-gate `stage` and `enforce`, `run --stage`, the intent
|
|
1037
1545
|
gate at a pull request (`--base`, `--spec`, the imported contract, the
|
|
1038
|
-
no-contract advisory),
|
|
1546
|
+
no-contract advisory), the two external gates (gitleaks over git history and
|
|
1547
|
+
osv-scanner over the dependency tree, run from `PATH`, their config read
|
|
1548
|
+
from the base ref on a pull request), and the composite Action.
|
|
1039
1549
|
|
|
1040
1550
|
Out, deliberately: a unified baseline or ledger (each gate keeps its own, and
|
|
1041
1551
|
their fingerprints are not equally durable, so one shared file would expire
|
|
1042
1552
|
entries silently for one product and not another), an MCP registration,
|
|
1043
|
-
running the gates concurrently,
|
|
1553
|
+
running the gates concurrently, downloading or pinning any third-party
|
|
1554
|
+
binary (the adopter installs gitleaks and osv-scanner), and any finding of
|
|
1555
|
+
the umbrella's own about
|
|
1044
1556
|
anybody's CODE. The findings it does raise are all about the gates
|
|
1045
1557
|
themselves: `conductor/gate-missing`, `conductor/gate-output-unparseable`
|
|
1046
1558
|
and `conductor/gate-failed`, plus the two diagnostics
|
|
@@ -1053,7 +1565,8 @@ runs inside an agent session or on save, which intent-guard's own optional
|
|
|
1053
1565
|
session hooks already cover.
|
|
1054
1566
|
|
|
1055
1567
|
This is a young tool rather than a finished one. The gates are still the
|
|
1056
|
-
product
|
|
1568
|
+
product, two of them are not this family's, and this is the layer that
|
|
1569
|
+
makes them one required check.
|
|
1057
1570
|
|
|
1058
1571
|
## Design notes
|
|
1059
1572
|
|
|
@@ -1070,4 +1583,4 @@ Adopter feedback is a row in [FINDINGS.md](FINDINGS.md). How to change this repo
|
|
|
1070
1583
|
|
|
1071
1584
|
## License
|
|
1072
1585
|
|
|
1073
|
-
MIT
|
|
1586
|
+
MIT. Built by [Vault & Compass](https://vaultcompass.io).
|