@vaultcompass/conductor 0.18.0 → 0.19.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 +204 -61
- package/dist/adoption-proposal.d.ts +36 -0
- package/dist/adoption-proposal.js +260 -0
- package/dist/cli.d.ts +25 -7
- package/dist/cli.js +181 -47
- package/dist/escape.d.ts +36 -0
- package/dist/escape.js +49 -0
- package/dist/existing-findings.d.ts +38 -0
- package/dist/existing-findings.js +206 -0
- package/dist/gate-runner.d.ts +13 -9
- package/dist/gate-runner.js +145 -37
- package/dist/git.d.ts +70 -0
- package/dist/git.js +141 -6
- package/dist/init.js +9 -0
- package/dist/intent-prepare.js +4 -0
- package/dist/osv-coverage.js +6 -5
- package/dist/output-sarif.js +52 -8
- package/dist/output-text.d.ts +117 -8
- package/dist/output-text.js +374 -39
- package/dist/policy-diff.d.ts +2 -9
- package/dist/policy-diff.js +4 -11
- package/dist/policy.d.ts +9 -0
- package/dist/policy.js +21 -3
- package/dist/rule-ids.d.ts +42 -0
- package/dist/rule-ids.js +100 -0
- package/dist/run.d.ts +80 -0
- package/dist/run.js +70 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -48,11 +48,18 @@ The hook runs every enabled gate on each commit and, when the commit is
|
|
|
48
48
|
clean, prints one summary line, plus one status line per gate on stderr.
|
|
49
49
|
Each gate can also be installed and run on its own.
|
|
50
50
|
|
|
51
|
-
Then the same gates on every pull request,
|
|
51
|
+
Then the same gates on every pull request, a lighter run on each push to
|
|
52
|
+
main, and a full scan every day, as one pinned workflow:
|
|
52
53
|
|
|
53
54
|
```yaml
|
|
54
55
|
name: guardrails
|
|
55
|
-
on:
|
|
56
|
+
on:
|
|
57
|
+
pull_request:
|
|
58
|
+
push:
|
|
59
|
+
branches: [main]
|
|
60
|
+
schedule:
|
|
61
|
+
- cron: '17 4 * * *'
|
|
62
|
+
workflow_dispatch:
|
|
56
63
|
permissions:
|
|
57
64
|
contents: read
|
|
58
65
|
security-events: write
|
|
@@ -76,7 +83,9 @@ jobs:
|
|
|
76
83
|
echo "ca69b3d3cd08f889a49dc0a383122f71cc528b83803671df5fd874d97485b108 $bin/osv-scanner" | sha256sum -c -
|
|
77
84
|
chmod +x "$bin/osv-scanner"
|
|
78
85
|
echo "$bin" >> "$GITHUB_PATH"
|
|
79
|
-
- uses: vaultcompasshq/conductor@
|
|
86
|
+
- uses: vaultcompasshq/conductor@1b1920983f0e2231c2eabc23fc8c258ca52f9613 # v0.18.1
|
|
87
|
+
with:
|
|
88
|
+
stage: ${{ github.event_name == 'push' && 'push' || 'ci' }}
|
|
80
89
|
- uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
|
|
81
90
|
if: always()
|
|
82
91
|
with:
|
|
@@ -89,8 +98,41 @@ needed when the policy enables the secrets-history and vulnerabilities gates,
|
|
|
89
98
|
and it pins both by version and checksum. On a pull request every gate reads
|
|
90
99
|
its rules from the base branch, so a change cannot turn off the check that
|
|
91
100
|
exists to catch it. The first pull request under a new policy cannot be judged
|
|
92
|
-
by that policy
|
|
93
|
-
|
|
101
|
+
by that policy: into the default branch it is reported as a proposal, exit 0
|
|
102
|
+
with nothing enforced, so read the careful path below before you make the
|
|
103
|
+
check required.
|
|
104
|
+
|
|
105
|
+
What each trigger runs. A pull request runs every gate at stage `ci`, and the
|
|
106
|
+
history scan reads only that pull request's own range, so a pull request is
|
|
107
|
+
judged on what it changes. A push to main runs at stage `push`: the
|
|
108
|
+
dependencies and secrets gates over the tree, and not the history scan or
|
|
109
|
+
osv-scanner, which are named as deferred in the report. The daily schedule
|
|
110
|
+
and a manual run have no base, so they run at stage `ci` over the whole of git
|
|
111
|
+
history and every tracked lockfile. The `fetch-depth: 0` above is what makes
|
|
112
|
+
that history scan possible: a shallow checkout makes the history gate
|
|
113
|
+
could-not-run on a pull request or a scheduled run alike, and exit 2 when the
|
|
114
|
+
gate is enforced (on a pull request it is always enforced).
|
|
115
|
+
|
|
116
|
+
What this gives up. A secret pushed straight to main with no pull request, and
|
|
117
|
+
a new advisory against a dependency already on main, are seen at the next
|
|
118
|
+
scheduled run, up to a day later, rather than on the push. Every change that
|
|
119
|
+
goes through a pull request is still fully judged.
|
|
120
|
+
|
|
121
|
+
Expect the scheduled run to be red at first. It judges the history and the
|
|
122
|
+
lockfiles as they stand, including what was there before conductor, and every
|
|
123
|
+
finding blocks. When it blocks, the report says how many of the findings
|
|
124
|
+
predate the policy file and lists each tool's own ignore file as the way to
|
|
125
|
+
record a reviewed one; see "Adoption ramp" below. A scheduled run is not a
|
|
126
|
+
required check, and a red one is the backlog, shown honestly. GitHub disables
|
|
127
|
+
scheduled workflows in a public repository after a period without repository
|
|
128
|
+
activity, and a failing scheduled run notifies whoever last edited the
|
|
129
|
+
schedule, so check that the schedule is still running.
|
|
130
|
+
|
|
131
|
+
The expression that picks the stage (`github.event_name == 'push' && 'push' ||
|
|
132
|
+
'ci'`) is standard Actions syntax but has not been run on a real runner for
|
|
133
|
+
this recipe. Check that the first push run's report lists secrets-history and
|
|
134
|
+
vulnerabilities as deferred, and that the first scheduled run does not, before
|
|
135
|
+
you rely on it.
|
|
94
136
|
|
|
95
137
|
## Part of the Vault & Compass guardrails
|
|
96
138
|
|
|
@@ -191,6 +233,15 @@ required.
|
|
|
191
233
|
stage is `commit`. A CI-only adopter that never runs conductor locally can
|
|
192
234
|
stop at the first `conductor init`, with no hook at all.
|
|
193
235
|
|
|
236
|
+
The first run with no base (a local `conductor run`, a push, a scheduled
|
|
237
|
+
run) judges all of git history and every tracked lockfile, so on a
|
|
238
|
+
repository with history it can block on findings that were there before
|
|
239
|
+
conductor. It still exits 1 and every finding still blocks; when the
|
|
240
|
+
history or vulnerabilities gate blocks, the report adds an "existing
|
|
241
|
+
findings" section saying how many predate the policy file, how many are in
|
|
242
|
+
files that are gone, and what to do. A pull request is judged only on its
|
|
243
|
+
own change.
|
|
244
|
+
|
|
194
245
|
**`.git/hooks` is never part of a clone**, so a hook one checkout has does
|
|
195
246
|
not follow a teammate's clone, or a fresh clone of your own: hooks are per
|
|
196
247
|
clone and per machine. Each clone that wants the hook runs
|
|
@@ -229,7 +280,7 @@ required.
|
|
|
229
280
|
|
|
230
281
|
Your terminal also shows one status line per gate, written to stderr so a
|
|
231
282
|
CI job log has a per-gate record even when the report goes to a file,
|
|
232
|
-
such as `conductor: gate dependencies (dep-guard 0.
|
|
283
|
+
such as `conductor: gate dependencies (dep-guard 0.20.0): ok, exit 0` or
|
|
233
284
|
a `skipped (deferred to stage ci)` line for a deferred gate. They carry
|
|
234
285
|
nothing the summary does not; to see only the summary, redirect stderr
|
|
235
286
|
(`conductor run --staged --stage commit 2>/dev/null` in the hook).
|
|
@@ -237,15 +288,20 @@ required.
|
|
|
237
288
|
A commit with a staged credential in it prints the full report and exits 1:
|
|
238
289
|
|
|
239
290
|
```
|
|
240
|
-
conductor 0.18.
|
|
291
|
+
conductor 0.18.1
|
|
241
292
|
verdict-token: blocked (1)
|
|
293
|
+
gate dependencies (dep-guard 0.20.0): ran, exit 0, 0 blocking
|
|
294
|
+
gate secrets (vault-guard 1.13.3): ran, exit 1, 1 blocking
|
|
295
|
+
gate intent (intent-guard): skipped (deferred to stage ci)
|
|
296
|
+
findings: 1 (1 blocking):
|
|
297
|
+
finding: BLOCKING vault-guard vault-guard/anthropic jest.config.mjs:14: Possible secret of type 'anthropic'
|
|
242
298
|
conductor run: 2 gate(s), 1 finding(s)
|
|
243
299
|
|
|
244
|
-
dependencies dep-guard 0.
|
|
300
|
+
dependencies dep-guard 0.20.0 exit 0 153ms via dep-guard on path
|
|
245
301
|
threshold medium suppressed 0 ignored 0
|
|
246
302
|
mode staged corpusBuiltAt 2026-09-20T06:16:40.340Z lockfileFormat npm online false lookups 0 skipped-by-deadline 0
|
|
247
303
|
|
|
248
|
-
secrets vault-guard 1.13.
|
|
304
|
+
secrets vault-guard 1.13.3 exit 1 105ms via vault-guard on path
|
|
249
305
|
BLOCKING critical vault-guard/anthropic jest.config.mjs:14:12
|
|
250
306
|
Possible secret of type 'anthropic'
|
|
251
307
|
threshold medium suppressed 0 ignored not reported
|
|
@@ -256,6 +312,11 @@ required.
|
|
|
256
312
|
verdict: exit 1, 1 blocking finding(s) in 1 of 2 enforced gate(s).
|
|
257
313
|
```
|
|
258
314
|
|
|
315
|
+
The lines under the verdict token are the report's head: one line per
|
|
316
|
+
gate (ran, did not run, skipped or disabled), then how many findings
|
|
317
|
+
there are and the first ten that block, by name. The sections under them
|
|
318
|
+
carry the detail, and every finding that does not block.
|
|
319
|
+
|
|
259
320
|
The `mode`, `corpusBuiltAt`, `lockfileFormat`, `online`, `lookups` and
|
|
260
321
|
`skipped-by-deadline` line under
|
|
261
322
|
`dependencies`, and the `filesScanned`/`patternsActive` line under
|
|
@@ -289,15 +350,18 @@ required.
|
|
|
289
350
|
and the workflow together, with `advisory: true` and `pr-comment: true`
|
|
290
351
|
on the conductor step (the recipe under "Running the gates as an
|
|
291
352
|
advisory check" below is a complete copy-paste job), and leave the check
|
|
292
|
-
out of branch protection for this one pull request.
|
|
293
|
-
|
|
294
|
-
policy yet, so
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
353
|
+
out of branch protection for this one pull request. Into the default
|
|
354
|
+
branch, this pull request is reported as a **proposal**: the base branch
|
|
355
|
+
has no policy yet, so nothing can be enforced, and conductor runs the
|
|
356
|
+
policy the pull request adds and says what it would do. The step exits 0,
|
|
357
|
+
the verdict is `proposal (N)`, never `pass`, and the summary and the
|
|
358
|
+
comment say that nothing was enforced and how many findings would block
|
|
359
|
+
once the policy is merged. A green check on this one pull request means
|
|
360
|
+
the gates the new policy enforces could all run, and nothing more. The
|
|
361
|
+
step exits 2 when one of them could not run (a scanner that is not
|
|
362
|
+
installed, say), which is the fault to fix before merging, and it exits 2
|
|
363
|
+
when the pull request is not a first adoption; see "What the first pull
|
|
364
|
+
request reports" below.
|
|
301
365
|
|
|
302
366
|
3. **Merge.** Every pull request after that is judged by the policy on the
|
|
303
367
|
base branch, and a change to that policy shows up as a proposal line and
|
|
@@ -311,9 +375,10 @@ required.
|
|
|
311
375
|
job into the one required check.
|
|
312
376
|
|
|
313
377
|
There is deliberately no mode in which the pull request's own policy file
|
|
314
|
-
decides
|
|
315
|
-
|
|
316
|
-
the
|
|
378
|
+
decides a verdict. The proposal in step 2 is the one run that reads it, and
|
|
379
|
+
it takes three keys from it (`enabled`, `stage`, `enforce`), enforces
|
|
380
|
+
nothing, and is labelled a proposal on every surface; once the base branch
|
|
381
|
+
has a policy, every rule comes from the base.
|
|
317
382
|
|
|
318
383
|
## Adoption ramp
|
|
319
384
|
|
|
@@ -348,7 +413,15 @@ first pull request gets switched off. The order that works:
|
|
|
348
413
|
|
|
349
414
|
conductor reads `.gitleaksignore` from the base branch on a pull request,
|
|
350
415
|
so adding the line takes effect after its own merge, like any other
|
|
351
|
-
control change.
|
|
416
|
+
control change. A finding the report lists as "also in" other commits is
|
|
417
|
+
one secret seen in several commits (a merge reports a pull request's change
|
|
418
|
+
again), and each of those commits has its own fingerprint: put one line per
|
|
419
|
+
commit the finding lists, its own and each "also in", or the copy comes
|
|
420
|
+
back under another fingerprint. Two cautions. gitleaks drops an ignored
|
|
421
|
+
finding without reporting it, so conductor does not count it: unlike an
|
|
422
|
+
osv-scanner suppression, nothing in the report shows it. And one line
|
|
423
|
+
silences every secret on that line in that commit that the same rule
|
|
424
|
+
matches, not only the one you reviewed.
|
|
352
425
|
|
|
353
426
|
4. **Switch to enforce.** When a few ordinary pull requests report only what
|
|
354
427
|
you expect, remove `advisory: true`, and set `enforce: true` on the gates
|
|
@@ -542,8 +615,8 @@ request being judged, and the version-pin protection described above
|
|
|
542
615
|
"protects nothing" against a tree that controls its own judge (the
|
|
543
616
|
validate step's own comment in `action.yml` says so in those words). A tag
|
|
544
617
|
moves when someone pushes it. Name this action by owner and the full commit
|
|
545
|
-
SHA instead. The recipes in this README name v0.
|
|
546
|
-
`vaultcompasshq/conductor@
|
|
618
|
+
SHA instead. The recipes in this README name v0.18.1 that way, as
|
|
619
|
+
`vaultcompasshq/conductor@1b1920983f0e2231c2eabc23fc8c258ca52f9613 # v0.18.1`.
|
|
547
620
|
|
|
548
621
|
```yaml
|
|
549
622
|
name: guardrails
|
|
@@ -565,7 +638,7 @@ jobs:
|
|
|
565
638
|
with:
|
|
566
639
|
node-version: '22.23.4'
|
|
567
640
|
- id: conductor
|
|
568
|
-
uses: vaultcompasshq/conductor@
|
|
641
|
+
uses: vaultcompasshq/conductor@1b1920983f0e2231c2eabc23fc8c258ca52f9613 # v0.18.1
|
|
569
642
|
with:
|
|
570
643
|
output: conductor.sarif
|
|
571
644
|
- uses: github/codeql-action/upload-sarif@9b3254085494b55a0f7c4c2b3d2d52cc712ce370 # v4.39.1
|
|
@@ -664,7 +737,7 @@ jobs:
|
|
|
664
737
|
# installs those itself, globally. Leave conductor-version unset so the
|
|
665
738
|
# umbrella is the default in the pinned action.yml.
|
|
666
739
|
- id: conductor
|
|
667
|
-
uses: vaultcompasshq/conductor@
|
|
740
|
+
uses: vaultcompasshq/conductor@1b1920983f0e2231c2eabc23fc8c258ca52f9613 # v0.18.1
|
|
668
741
|
with:
|
|
669
742
|
output: conductor.sarif
|
|
670
743
|
# The gate versions are left out on purpose: the defaults travel
|
|
@@ -720,8 +793,9 @@ credential helpers, `core.sshCommand`), git hooks such as
|
|
|
720
793
|
`reference-transaction`, and replace refs or grafts. (The action's fetch, gates
|
|
721
794
|
and fallback render steps set `GIT_NO_REPLACE_OBJECTS=1` for themselves and
|
|
722
795
|
for the gates they run, which narrows replace refs. The fetch step alone also
|
|
723
|
-
reads through a graft file, for its decision to move the trust base
|
|
724
|
-
|
|
796
|
+
reads through a graft file, for its decision to move the trust base, and
|
|
797
|
+
since issue 101 so does every git call the CLI makes itself; a gate's own
|
|
798
|
+
git calls still read one.)
|
|
725
799
|
Say it plainly: package.json lifecycle scripts (`preinstall`, `install`, `postinstall`,
|
|
726
800
|
`prepare`) run by an install bypass "require review on `.github/workflows`",
|
|
727
801
|
because the pull request supplies them, not the workflow file. Branch
|
|
@@ -733,7 +807,10 @@ shallow checkout on a pull-request run is could-not-run for the history gate,
|
|
|
733
807
|
naming `fetch-depth: 0` (exit 2, whatever `enforce` says). At the default
|
|
734
808
|
depth of 1 the checkout is shallow, the range from the base to HEAD holds one
|
|
735
809
|
grafted commit, and a secret added and then removed inside the pull request
|
|
736
|
-
would never be seen. conductor does not deepen the checkout for you.
|
|
810
|
+
would never be seen. conductor does not deepen the checkout for you. A run
|
|
811
|
+
with no base (a push, a scheduled run, a local run) has the same need: a
|
|
812
|
+
shallow checkout cuts the whole history it reads off at the graft, and the
|
|
813
|
+
history gate is could-not-run there too.
|
|
737
814
|
|
|
738
815
|
**The two external gates are installed by your workflow, not by the
|
|
739
816
|
Action.** The Action still installs exactly its four npm packages and has no
|
|
@@ -802,9 +879,10 @@ could-not-run (`timed-out`), never a pass.
|
|
|
802
879
|
job before it can fire. Keep it well under.
|
|
803
880
|
|
|
804
881
|
Measure your own full scan once, on the runner it will run on, and set the
|
|
805
|
-
limit with headroom. The recommended split
|
|
806
|
-
|
|
807
|
-
|
|
882
|
+
limit with headroom. The recommended split, and the one the quick start
|
|
883
|
+
above uses: every pull request scans its own range, pushes to main run at
|
|
884
|
+
stage `push`, and the full history is scanned on a daily schedule with a limit
|
|
885
|
+
sized for it. Two existing ways to make it: by stage, since `secrets-history` defaults
|
|
808
886
|
to stage `ci` and a push workflow run with the Action's `stage: push` input
|
|
809
887
|
(or `conductor run --stage push`) leaves ci-stage gates out; or by trigger,
|
|
810
888
|
running the workflow on pull requests and a schedule and not on push. With
|
|
@@ -887,7 +965,7 @@ jobs:
|
|
|
887
965
|
# seconds) plus 300 seconds for the preview, rounded up. A step
|
|
888
966
|
# timeout below that can kill a full gitleaks scan and leave no verdict.
|
|
889
967
|
timeout-minutes: 30
|
|
890
|
-
uses: vaultcompasshq/conductor@
|
|
968
|
+
uses: vaultcompasshq/conductor@1b1920983f0e2231c2eabc23fc8c258ca52f9613 # v0.18.1
|
|
891
969
|
with:
|
|
892
970
|
pr-comment: true
|
|
893
971
|
advisory: true
|
|
@@ -977,23 +1055,40 @@ See "Adopting conductor: the careful path" near the top of this README for the o
|
|
|
977
1055
|
walkthrough: init, a first pull request in advisory mode, merge, then go
|
|
978
1056
|
required. This subsection is the mechanism behind two of those steps.
|
|
979
1057
|
|
|
980
|
-
**
|
|
981
|
-
`
|
|
982
|
-
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|
|
987
|
-
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
|
|
992
|
-
|
|
993
|
-
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
|
|
1058
|
+
**What the first pull request reports.** The pull request that first adds
|
|
1059
|
+
`.guardrails.yaml` is judged against the base branch, which has no policy
|
|
1060
|
+
yet, so nothing in it can be enforced. On a pull request into the
|
|
1061
|
+
repository's default branch the Action passes `--adoption-proposal`, and
|
|
1062
|
+
the run is a proposal: conductor runs the policy the pull request adds,
|
|
1063
|
+
taking only `enabled`, `stage` and `enforce` from the committed file, and
|
|
1064
|
+
exits 0 with the verdict `proposal (N)` and the line `proposal: no
|
|
1065
|
+
.guardrails.yaml on the base branch, so nothing here was enforced; N would
|
|
1066
|
+
block once this policy is on the base branch`. It exits 2 when a gate that
|
|
1067
|
+
policy enforces could not run. `advisory` has no part in either outcome.
|
|
1068
|
+
The full rules are under [A proposal](docs/commands.md#a-proposal).
|
|
1069
|
+
|
|
1070
|
+
A proposal is only for a first adoption. The run is refused, exit 2, when
|
|
1071
|
+
the base branch has carried a policy before (one was deleted, and a later
|
|
1072
|
+
pull request adds one back), when the pull request inherited its policy
|
|
1073
|
+
from a base that has since dropped it, in a shallow checkout, or when the
|
|
1074
|
+
workflow has no policy on either side (the summary then says `no-policy:
|
|
1075
|
+
this workflow checks nothing until .guardrails.yaml is on the base branch`).
|
|
1076
|
+
After a deletion, the policy has to be landed on the base branch by someone
|
|
1077
|
+
allowed to merge without this check passing.
|
|
1078
|
+
|
|
1079
|
+
A pull request into any other branch gets no proposal, because rules are
|
|
1080
|
+
read from whatever branch the pull request targets and a missing policy
|
|
1081
|
+
there may be a gap. A release or release-candidate branch cut before the
|
|
1082
|
+
policy existed, or any long-lived branch that has never received
|
|
1083
|
+
`.guardrails.yaml`, refuses its first pull request with exit 2, under
|
|
1084
|
+
`advisory: true` as well: `advisory` maps a blocking **finding** to exit 0
|
|
1085
|
+
and has no opinion about a run with no policy to be judged by. There are
|
|
1086
|
+
two remedies. Carry the policy onto the branch before opening a pull
|
|
1087
|
+
request against it; a sync from the default branch does this. Or expect
|
|
1088
|
+
exactly one could-not-run run there, and leave the check out of that
|
|
1089
|
+
branch's protection for that one pull request.
|
|
1090
|
+
|
|
1091
|
+
A merge queue run (`merge_group`) never gets a proposal either.
|
|
997
1092
|
|
|
998
1093
|
**Why "go required" means the job's own context, never the SARIF-upload
|
|
999
1094
|
row.** The recipes above upload conductor's SARIF log with
|
|
@@ -1023,7 +1118,7 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1023
1118
|
# the pull request runs before the action in this job: no install, build
|
|
1024
1119
|
# or test step here; those belong in a separate job. ...
|
|
1025
1120
|
- id: conductor
|
|
1026
|
-
uses: vaultcompasshq/conductor@
|
|
1121
|
+
uses: vaultcompasshq/conductor@1b1920983f0e2231c2eabc23fc8c258ca52f9613 # v0.18.1
|
|
1027
1122
|
with:
|
|
1028
1123
|
output: conductor.sarif
|
|
1029
1124
|
pr-comment: true
|
|
@@ -1043,14 +1138,48 @@ a re-run find and update that same comment, so a push does not pile up a new
|
|
|
1043
1138
|
comment every time, the way the manual recipe below does. It runs on a
|
|
1044
1139
|
`pull_request` or `pull_request_target` event only, and it runs whether the
|
|
1045
1140
|
gates step passed or failed, since a blocking run is the one an advisory
|
|
1046
|
-
check most needs a developer to actually see.
|
|
1047
|
-
|
|
1048
|
-
|
|
1049
|
-
|
|
1050
|
-
|
|
1051
|
-
|
|
1052
|
-
|
|
1053
|
-
|
|
1141
|
+
check most needs a developer to actually see.
|
|
1142
|
+
|
|
1143
|
+
**What the comment looks like.** It leads with the verdict, then one row per
|
|
1144
|
+
gate, then the findings by name, and the whole report is collapsed under
|
|
1145
|
+
them, one click away:
|
|
1146
|
+
|
|
1147
|
+
```text
|
|
1148
|
+
conductor verdict: blocked (1)
|
|
1149
|
+
|
|
1150
|
+
gate dependencies (dep-guard 0.20.0): ran, exit 0, 0 blocking
|
|
1151
|
+
gate secrets (vault-guard 1.13.3): ran, exit 1, 1 blocking
|
|
1152
|
+
gate vulnerabilities (osv-scanner version unknown): did not run (binary-missing)
|
|
1153
|
+
|
|
1154
|
+
findings: 14 (12 blocking), the first 10:
|
|
1155
|
+
finding: BLOCKING vault-guard vault-guard/github-token src/config.js:2: Possible secret of type 'github-token'
|
|
1156
|
+
...
|
|
1157
|
+
and 2 more blocking
|
|
1158
|
+
```
|
|
1159
|
+
|
|
1160
|
+
A gate line says `ran`, with the gate's own version, its exit code and how
|
|
1161
|
+
many findings it marked blocking, or `did not run`, with the reason, or
|
|
1162
|
+
`skipped` or `disabled`, with why. A gate that did not run never reads as
|
|
1163
|
+
one that passed. A line such as `ran, exit 1, 0 blocking` under a `pass` is
|
|
1164
|
+
the gate's own exit code for findings that do not block this run: the
|
|
1165
|
+
vulnerabilities gate exits 1 on advisories that were already on the base
|
|
1166
|
+
branch, which conductor reports and does not block on. The findings line
|
|
1167
|
+
counts every finding and names only the ones that block, the first ten of
|
|
1168
|
+
them; when none blocks it is the count alone, `findings: 77 (0 blocking)`,
|
|
1169
|
+
and the rest are in the report. When the installed gate is not the version the action
|
|
1170
|
+
pinned, the line prints both (`did not run (version-skew), the action pinned
|
|
1171
|
+
0.20.0`). When the vulnerabilities gate compared the pull request with the
|
|
1172
|
+
base branch, the comment leads with `new in this pull request: N
|
|
1173
|
+
(vulnerabilities gate; M already on the base)`; no other gate compares with
|
|
1174
|
+
the base, so the line is absent on a run where that comparison did not
|
|
1175
|
+
happen. Inside the collapsed report the first line carries the version of
|
|
1176
|
+
conductor that produced it and the second the verdict token (see
|
|
1177
|
+
[The verdict token](docs/commands.md#the-verdict-token)). When the trust
|
|
1178
|
+
base was refused and no gate ran at all, the report under the gate rows
|
|
1179
|
+
shrinks to the version, the verdict, and the refusal reason (with its
|
|
1180
|
+
remedy, when one applies) and starts open, so a refused run
|
|
1181
|
+
does not get a full sticky comment whose only content is "refused, nothing
|
|
1182
|
+
checked" on every push.
|
|
1054
1183
|
|
|
1055
1184
|
**It is a no-op on a pull request from a fork.** The default `GITHUB_TOKEN`
|
|
1056
1185
|
there is read-only regardless of the `pull-requests: write` permission you
|
|
@@ -1076,6 +1205,20 @@ could not be verified and no gate ran, the summary says
|
|
|
1076
1205
|
`could-not-run`. The output is empty when the installed `conductor-version`
|
|
1077
1206
|
predates the token.
|
|
1078
1207
|
|
|
1208
|
+
**The job summary names the gates and the findings too.** Under the verdict
|
|
1209
|
+
line the summary carries the same rows the comment leads with: one line per
|
|
1210
|
+
gate (`ran`, `did not run`, `skipped` or `disabled`, as above), then the
|
|
1211
|
+
count of findings and the first ten that block, by gate, rule, place and
|
|
1212
|
+
reason, then `and N more blocking`. The job log prints the same finding
|
|
1213
|
+
lines. So a run that blocked says what it
|
|
1214
|
+
caught without anybody opening the SARIF log, and a run where a gate could
|
|
1215
|
+
not run says which gate and why on the page a reviewer already looks at.
|
|
1216
|
+
Those lines are copied from the head of the text report, by position: a gate
|
|
1217
|
+
line only when the whole line is built from conductor's own words and
|
|
1218
|
+
numbers, and a finding line (whose path, package name and message come from
|
|
1219
|
+
the scanned repository) only inside a code block, after conductor has
|
|
1220
|
+
escaped and shortened each field.
|
|
1221
|
+
|
|
1079
1222
|
**The sticky match only ever adopts conductor's own comment.** On
|
|
1080
1223
|
`pull_request_target` this step runs with a write token even though the
|
|
1081
1224
|
pull request itself is untrusted, so anyone who can comment on the pull
|
|
@@ -1102,12 +1245,12 @@ per pull request.
|
|
|
1102
1245
|
|
|
1103
1246
|
```yaml
|
|
1104
1247
|
- id: conductor-package-a
|
|
1105
|
-
uses: vaultcompasshq/conductor@
|
|
1248
|
+
uses: vaultcompasshq/conductor@1b1920983f0e2231c2eabc23fc8c258ca52f9613 # v0.18.1
|
|
1106
1249
|
with:
|
|
1107
1250
|
pr-comment: true
|
|
1108
1251
|
pr-comment-marker: 'package-a'
|
|
1109
1252
|
- id: conductor-package-b
|
|
1110
|
-
uses: vaultcompasshq/conductor@
|
|
1253
|
+
uses: vaultcompasshq/conductor@1b1920983f0e2231c2eabc23fc8c258ca52f9613 # v0.18.1
|
|
1111
1254
|
with:
|
|
1112
1255
|
pr-comment: true
|
|
1113
1256
|
pr-comment-marker: 'package-b'
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Every GIT_ variable in `env` that is not on the allowlist, sorted. Matched
|
|
3
|
+
* on the upper-cased name, so a lower-case spelling (which Windows treats as
|
|
4
|
+
* the same variable) is caught, and present-but-empty counts: git treats
|
|
5
|
+
* several of these as set whatever they hold.
|
|
6
|
+
*/
|
|
7
|
+
export declare function disallowedGitVariables(env: NodeJS.ProcessEnv): string[];
|
|
8
|
+
/**
|
|
9
|
+
* The entries at the root of `commit`'s tree whose name is the policy file
|
|
10
|
+
* name under another spelling (`.Guardrails.yaml`), or the reason the root
|
|
11
|
+
* could not be listed.
|
|
12
|
+
*
|
|
13
|
+
* `src/policy.ts#loadPolicy` reads the policy from disk by name, so on a
|
|
14
|
+
* case-insensitive file system (the macOS runners) a push run finds and
|
|
15
|
+
* enforces `.Guardrails.yaml`, while every read from a ref here asks git for
|
|
16
|
+
* the exact name and is told there is none. Such a base has a policy.
|
|
17
|
+
*/
|
|
18
|
+
export declare function policyNameVariants(repoRoot: string, commit: string): {
|
|
19
|
+
kind: 'listed';
|
|
20
|
+
names: string[];
|
|
21
|
+
} | {
|
|
22
|
+
kind: 'error';
|
|
23
|
+
detail: string;
|
|
24
|
+
};
|
|
25
|
+
/**
|
|
26
|
+
* Why this run is NOT an adoption proposal, or null when every condition
|
|
27
|
+
* holds. Called only after the caller has established that the flag was
|
|
28
|
+
* given, that the trust base passed its own checks, that the exact policy
|
|
29
|
+
* file name is absent in the trust base's tree, and that the HEAD blob
|
|
30
|
+
* parses.
|
|
31
|
+
*
|
|
32
|
+
* The reason is one or two sentences for the refusal the caller reports;
|
|
33
|
+
* every enabled gate is then could-not-run and the run exits 2, exactly as
|
|
34
|
+
* on a base without a policy before this file existed.
|
|
35
|
+
*/
|
|
36
|
+
export declare function refuseAdoptionProposal(repoRoot: string, trustBase: string, env?: NodeJS.ProcessEnv): string | null;
|