@vaultcompass/conductor 0.7.0 → 0.8.1
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 +223 -78
- package/dist/cli.js +204 -37
- package/dist/external-config.d.ts +2 -1
- package/dist/external-config.js +34 -13
- package/dist/gate-runner.d.ts +128 -17
- package/dist/gate-runner.js +365 -53
- package/dist/git.d.ts +80 -0
- package/dist/git.js +224 -0
- package/dist/init-policy.js +2 -1
- package/dist/init.js +40 -3
- package/dist/intent-base.d.ts +64 -1
- package/dist/intent-base.js +194 -40
- package/dist/intent-prepare.d.ts +33 -2
- package/dist/intent-prepare.js +448 -35
- package/dist/intent-spec.d.ts +28 -0
- package/dist/intent-spec.js +22 -5
- package/dist/normalize.d.ts +9 -0
- package/dist/normalize.js +19 -5
- package/dist/output-sarif.js +12 -13
- package/dist/output-text.d.ts +52 -2
- package/dist/output-text.js +150 -16
- package/dist/policy.js +9 -7
- package/dist/products.js +1 -1
- package/dist/resolve.d.ts +1 -0
- package/dist/resolve.js +1 -1
- package/dist/run.d.ts +8 -0
- package/dist/run.js +63 -13
- package/dist/trust-base.d.ts +133 -24
- package/dist/trust-base.js +353 -60
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -167,7 +167,7 @@ required.
|
|
|
167
167
|
A commit with a staged credential in it prints the full report and exits 1:
|
|
168
168
|
|
|
169
169
|
```
|
|
170
|
-
conductor 0.
|
|
170
|
+
conductor 0.8.0
|
|
171
171
|
verdict-token: blocked (1)
|
|
172
172
|
conductor run: 2 gate(s), 1 finding(s)
|
|
173
173
|
|
|
@@ -473,7 +473,8 @@ proceeds normally without mentioning them.
|
|
|
473
473
|
pull-request run passes both: `--base` decides which paths are judged,
|
|
474
474
|
`--trust-base` decides what they are judged by. When `GITHUB_BASE_REF` is
|
|
475
475
|
set, an explicit `--trust-base` is accepted only when it resolves to the
|
|
476
|
-
same commit as `origin/$GITHUB_BASE_REF
|
|
476
|
+
same commit as `refs/remotes/origin/$GITHUB_BASE_REF`, or is the Action's
|
|
477
|
+
private `refs/conductor/trust-base` (issue #58); anyone invoking the
|
|
477
478
|
CLI directly on a pull request, rather than through the Action, gets this
|
|
478
479
|
as its own refusal, named below.
|
|
479
480
|
- `--spec <path>` names the spec the intent gate imports its contract from.
|
|
@@ -571,6 +572,11 @@ code and the `enforce` flags the run already had.
|
|
|
571
572
|
|
|
572
573
|
- `pass`: exit 0, and no gate, enforced or not, has a blocking finding or
|
|
573
574
|
could not run.
|
|
575
|
+
- `nothing-checked`: exit 0, but no gate ran at all (none is enabled, or
|
|
576
|
+
every enabled one was deferred to a later stage, had nothing to judge, or
|
|
577
|
+
was skipped). The exit status is unchanged, since nothing failed, but this
|
|
578
|
+
is not a pass: nothing was verified. In the Action the `verdict` output
|
|
579
|
+
carries this token, so a workflow can tell it apart from `pass`.
|
|
574
580
|
- `advisory-blocked (N)`: the run would have exited 1, and `--advisory` made
|
|
575
581
|
it exit 0. N is the blocking findings on enforced gates.
|
|
576
582
|
- `unenforced-findings (N)`: exit 0, but a gate with `enforce: false` had
|
|
@@ -580,11 +586,13 @@ code and the `enforce` flags the run already had.
|
|
|
580
586
|
- `could-not-run`: exit 2, a refused trust base included.
|
|
581
587
|
|
|
582
588
|
When several apply the order is `could-not-run`, then `blocked` or
|
|
583
|
-
`advisory-blocked`, then `unenforced-findings`, then `
|
|
589
|
+
`advisory-blocked`, then `unenforced-findings`, then `nothing-checked` (no gate
|
|
590
|
+
ran) or `pass`. A run with
|
|
584
591
|
`--advisory` whose only blocking findings sit on an unenforced gate is
|
|
585
592
|
`unenforced-findings`, not `advisory-blocked`, because the flag did nothing
|
|
586
593
|
there. A gate skipped for want of a contract does not by itself move the token
|
|
587
|
-
off `pass
|
|
594
|
+
off `pass` when another gate ran; when no gate ran, the token is
|
|
595
|
+
`nothing-checked` and the verdict sentence says "nothing was checked". A
|
|
588
596
|
gate that exited non-zero with no finding marked blocking counts as one in N,
|
|
589
597
|
so a state that is not a pass never prints a count of zero. The one-line
|
|
590
598
|
summary of a clean, non-verbose run has no token line, since it is one line by
|
|
@@ -602,7 +610,12 @@ request could point a gate at a script it added in the same commit.
|
|
|
602
610
|
|
|
603
611
|
**On a pull-request run the rules come from the base branch.** With
|
|
604
612
|
`--trust-base <ref>` the umbrella reads `.guardrails.yaml` from that ref with
|
|
605
|
-
|
|
613
|
+
git and judges the head tree against it. A trusted file at the base that git
|
|
614
|
+
cannot read as a regular file (a symlink, a directory, a submodule, or a file
|
|
615
|
+
below a symlinked or submodule directory) is could-not-run, never replaced by
|
|
616
|
+
a default. Clear it by making the file a regular file on the base branch; the
|
|
617
|
+
pull request that does so is judged against that same base, so it has to be
|
|
618
|
+
merged by someone allowed to merge without this check passing. A `.guardrails.yaml` in the
|
|
606
619
|
pull request never takes effect for that run, `command:` and `args:`
|
|
607
620
|
included, so **a pull request cannot change the rules it is judged by, and
|
|
608
621
|
cannot choose the program that judges it, as long as that program is
|
|
@@ -737,15 +750,19 @@ to remove the input; see "The Action" below.
|
|
|
737
750
|
|
|
738
751
|
**The CLI check catches a misconfigured or innocent-looking redirect when
|
|
739
752
|
`GITHUB_BASE_REF` is set**, for anyone invoking the CLI directly in CI. When
|
|
740
|
-
that variable is set, an explicit `--trust-base` is accepted only when it
|
|
741
|
-
|
|
742
|
-
|
|
753
|
+
that variable is set, an explicit `--trust-base` is accepted only when it is
|
|
754
|
+
`refs/conductor/trust-base`, the private ref the Action fetches the base
|
|
755
|
+
branch into and always passes (that ref is the authority and is not compared
|
|
756
|
+
with anything), or resolves to the same commit as
|
|
757
|
+
`refs/remotes/origin/$GITHUB_BASE_REF`. So an ordinary pull-request run is
|
|
743
758
|
unaffected. A ref naming the pull request's own branch, or anything else that
|
|
744
759
|
disagrees, is refused with both refs and both commits named, through the same
|
|
745
760
|
could-not-run path as every other trust-base refusal: exit 2, the report
|
|
746
|
-
leads with the reason, and nothing is checked.
|
|
747
|
-
|
|
748
|
-
|
|
761
|
+
leads with the reason, and nothing is checked. A short name that matches both
|
|
762
|
+
a tag and a branch or remote-tracking ref (a tag named `origin/main`) is
|
|
763
|
+
refused as ambiguous: spell the ref in full. When neither resolves, this fails
|
|
764
|
+
closed too, naming it, for the same reason the fetch-depth remedy below
|
|
765
|
+
exists.
|
|
749
766
|
|
|
750
767
|
**Neither layer closes anything against a pull request that edits its own
|
|
751
768
|
workflow file.** A CLI invocation on a pull request can simply omit
|
|
@@ -811,10 +828,11 @@ choose its own judge on exactly the repositories that have no rules yet. See
|
|
|
811
828
|
"Adopting conductor" below for the sequence and for how to see what your
|
|
812
829
|
policy will do before you merge it.
|
|
813
830
|
|
|
814
|
-
**Which gates are covered.** All five: dep-guard from **0.
|
|
815
|
-
intent-guard from **1.
|
|
831
|
+
**Which gates are covered.** All five: dep-guard from **0.10.1**,
|
|
832
|
+
intent-guard from **1.8.1**, vault-guard from **1.9.1**, and the two
|
|
816
833
|
external gates at their command-line floors, gitleaks **8.19.0** and
|
|
817
|
-
osv-scanner **2.0.0**.
|
|
834
|
+
osv-scanner **2.0.0**. On a pull-request run an older family gate is
|
|
835
|
+
could-not-run rather than run outside pull-request mode.
|
|
818
836
|
|
|
819
837
|
**The external gates get their pull-request mode from the umbrella.**
|
|
820
838
|
Neither tool has a `--trust-base`, and both auto-load a config from the tree
|
|
@@ -872,22 +890,50 @@ in the diff. Only the root `osv-scanner.toml` is read from the base and
|
|
|
872
890
|
passed with `--config`, which overrides any nested one for the run; a
|
|
873
891
|
nested one the pull request adds or edits is reported as a proposal.
|
|
874
892
|
|
|
875
|
-
The umbrella asks each gate its version
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
|
|
883
|
-
|
|
884
|
-
|
|
885
|
-
|
|
893
|
+
The umbrella asks each gate its version before it runs it. On a run with a
|
|
894
|
+
trust base, a gate older than its pull-request-mode minimum (intent-guard
|
|
895
|
+
1.8.1, vault-guard 1.9.1, dep-guard 0.10.1) is could-not-run (exit 2),
|
|
896
|
+
never run without the flag: without it the gate would take its rules from
|
|
897
|
+
the tree being judged. The fix is to install that minimum or newer, or to
|
|
898
|
+
remove an explicit older version pin. A version that cannot be read at all
|
|
899
|
+
is could-not-run too: the umbrella cannot establish that the gate would
|
|
900
|
+
take its rules from the base ref. The one gate that runs without the flag
|
|
901
|
+
is an intent gate judging a contract imported from the base for the run,
|
|
902
|
+
whose project is a temporary directory with no repository to resolve a ref
|
|
903
|
+
in; that is never silent: it gets a line in the report, a clause on the
|
|
904
|
+
clean one-line summary, and a `conductor/trust-base-not-passed`
|
|
905
|
+
notification in the SARIF log.
|
|
886
906
|
|
|
887
907
|
Outside pull-request mode nothing changes. A pre-commit hook and a direct run
|
|
888
908
|
on your own checkout are already inside the trust boundary, and neither passes
|
|
889
909
|
the flag.
|
|
890
910
|
|
|
911
|
+
**In CI, pull-request mode needs a trust base.** A run in GitHub Actions with
|
|
912
|
+
`GITHUB_BASE_REF` set and no `--trust-base` is could-not-run (exit 2): its
|
|
913
|
+
rules have to come from the base branch, and no base was named. Pass `--trust-base
|
|
914
|
+
refs/remotes/origin/<base branch>` with `fetch-depth: 0`, or use the Action,
|
|
915
|
+
which always passes one. A pre-commit hook run inside a pull-request job hits
|
|
916
|
+
this too: skip the hook in CI, or pass the trust base to it.
|
|
917
|
+
|
|
918
|
+
**On a pull-request run PATH holds only absolute entries, and conductor's own
|
|
919
|
+
git comes from outside the repository.** Empty and relative entries are
|
|
920
|
+
removed for conductor and every gate it starts, with one notice naming them,
|
|
921
|
+
and conductor runs the first git on PATH that lives outside the repository's
|
|
922
|
+
work tree; with none, the run is could-not-run and says to put git's own
|
|
923
|
+
directory on PATH. A gate found only through a removed entry is reported
|
|
924
|
+
missing; put it on an absolute PATH entry or name it with an absolute
|
|
925
|
+
`command:`. Every gate conductor starts, and everything a gate starts, gets
|
|
926
|
+
a PATH whose first entry is a private directory outside the repository
|
|
927
|
+
holding only that same git, so a gate that runs git by name runs it too; on
|
|
928
|
+
Windows no such directory is made and the gates look git up through the
|
|
929
|
+
cleaned PATH, and a system temp directory inside the repository is
|
|
930
|
+
could-not-run until TMPDIR names one outside it.
|
|
931
|
+
|
|
932
|
+
**git 2.31 or later** is needed on a pull-request run with the secrets-history
|
|
933
|
+
gate (gitleaks) enabled, because conductor hands it `git log --diff-merges`,
|
|
934
|
+
which arrived in git 2.31. Only that gate checks: an older git makes it
|
|
935
|
+
could-not-run, naming the version, and the other gates run.
|
|
936
|
+
|
|
891
937
|
## Intent at a pull request
|
|
892
938
|
|
|
893
939
|
The intent gate is the only one of the five with any ceremony: its native
|
|
@@ -899,8 +945,13 @@ human step. That step is exactly what a pull request cannot carry, so at the
|
|
|
899
945
|
branch changed since it forked, from
|
|
900
946
|
`git diff --name-only --no-renames <base>...HEAD` in the repository root.
|
|
901
947
|
|
|
902
|
-
With no `--base`, `GITHUB_BASE_REF` is used
|
|
903
|
-
|
|
948
|
+
With no `--base`, `GITHUB_BASE_REF` is used when it is set, spelled in full:
|
|
949
|
+
`refs/conductor/trust-base` (the Action's private fetch of the base) if that
|
|
950
|
+
exists, else `refs/remotes/origin/<value>`, so a tag of that name cannot
|
|
951
|
+
shadow it. The text report says which. An explicit `--base` that matches both
|
|
952
|
+
a tag and a branch is refused as ambiguous. With neither but a `--trust-base`
|
|
953
|
+
(merge_group, workflow_dispatch, a CLI run), the change set is measured from
|
|
954
|
+
the trust base. With none of the three, the intent gate runs the way
|
|
904
955
|
it does at a commit: against the staged index, or the paths you name.
|
|
905
956
|
|
|
906
957
|
**This is why a local preview and a pull-request run can disagree about a
|
|
@@ -923,12 +974,31 @@ fallback to an empty path set, because an empty path set is what a passing
|
|
|
923
974
|
gate looks like. In Actions this is almost always a shallow checkout, so
|
|
924
975
|
**`actions/checkout` needs `fetch-depth: 0`** for the merge base to exist.
|
|
925
976
|
|
|
977
|
+
**On a pull-request run the base decides.** With `--trust-base`, whether a
|
|
978
|
+
frozen contract governs the pull request is read from the base ref alone. A
|
|
979
|
+
frozen contract on the base is used, ahead of everything in the list below,
|
|
980
|
+
`--spec` included (the report says so when `--spec` was given), and the gate
|
|
981
|
+
judges any edit to it against the base copy. That holds for every
|
|
982
|
+
intent-guard that can run on a pull-request run, since one older than its
|
|
983
|
+
pull-request-mode minimum is could-not-run rather than run without the base
|
|
984
|
+
ref. With no frozen contract on the
|
|
985
|
+
base, nothing in the pull request becomes the contract: a spec on the base,
|
|
986
|
+
found by rules 1, 3 and 4 below, is imported from its base copy (so on such a
|
|
987
|
+
run `--spec` must be a plain path inside the repository that the base
|
|
988
|
+
carries), and otherwise
|
|
989
|
+
the gate is skipped with "No contract on the base". A contract or spec the
|
|
990
|
+
pull request adds is reported as a proposal, so adopting the intent gate
|
|
991
|
+
merges, and the next pull request is judged against it. Retiring or replacing
|
|
992
|
+
a frozen contract through a judged pull request is refused by the intent gate
|
|
993
|
+
itself and needs an administrator to merge it.
|
|
994
|
+
|
|
926
995
|
**Where the contract comes from**, in order:
|
|
927
996
|
|
|
928
997
|
1. `--spec <path>` on the umbrella's own command line. Typed just now, so it
|
|
929
|
-
outranks everything, and a path here that is not on
|
|
930
|
-
rather than replaced: running a different contract than
|
|
931
|
-
named is the wrong kindness.
|
|
998
|
+
outranks everything else in this list, and a path here that is not on
|
|
999
|
+
disk is reported rather than replaced: running a different contract than
|
|
1000
|
+
the one somebody named is the wrong kindness. On a pull-request run it is
|
|
1001
|
+
read from the base, and a frozen contract on the base takes precedence.
|
|
932
1002
|
2. `<repo>/.intent-guard/intent-contract.yaml`, when it is **frozen**, and
|
|
933
1003
|
`<repo>/.conductor/intent-contract.yaml` after it. The native flow wins
|
|
934
1004
|
wherever a team has done it. Frozen is the test rather than present: an
|
|
@@ -1092,14 +1162,18 @@ provenance even though all four packages publish it.
|
|
|
1092
1162
|
> sigstore outage has the same effect. The audit is retried once after a short
|
|
1093
1163
|
> pause before the step fails, to absorb a one-off registry hiccup. It fails
|
|
1094
1164
|
> closed on purpose, so that is a red gate rather than a skipped check; pin to
|
|
1095
|
-
>
|
|
1165
|
+
> `45d2ecc2213244408495c22d0b8da1dc0f1ed288` (v0.4.0), which does not verify,
|
|
1166
|
+
> if it blocks you.
|
|
1096
1167
|
|
|
1097
1168
|
`--base` is passed only when the `base-ref` input names one; left empty, the
|
|
1098
1169
|
umbrella reads `GITHUB_BASE_REF` itself and treats an empty value as "not a
|
|
1099
1170
|
pull request", which is what a push build wants.
|
|
1100
1171
|
|
|
1101
|
-
On a `pull_request` event the
|
|
1102
|
-
|
|
1172
|
+
On a `pull_request` event a dedicated step fetches the base branch into a
|
|
1173
|
+
private ref and the action passes **`--trust-base <the fetched commit id>`**
|
|
1174
|
+
of its own accord (the job needs `contents: read`; a failed fetch fails the job
|
|
1175
|
+
rather than running without a trust base; the token exists only in that fetch
|
|
1176
|
+
step and never in the gates), so the run takes
|
|
1103
1177
|
its configuration from the base branch and the pull request cannot change the
|
|
1104
1178
|
rules it is judged by; a change to the rules shows as a proposal line and
|
|
1105
1179
|
takes effect after merge. See "The pull-request trust boundary" above. On any
|
|
@@ -1113,7 +1187,8 @@ workflow file is the *base* branch's own instead, but the input is refused
|
|
|
1113
1187
|
there too, because pull-request mode already derives the trust base on both
|
|
1114
1188
|
events and an explicit redirect has no legitimate use on either. The refusal
|
|
1115
1189
|
names the value that was given and the fix, which is to remove the input: the
|
|
1116
|
-
action already derives `
|
|
1190
|
+
action already derives the private `refs/conductor/trust-base` itself on that
|
|
1191
|
+
event.
|
|
1117
1192
|
|
|
1118
1193
|
There is deliberately **no input that turns pull-request mode off**.
|
|
1119
1194
|
Base-ref judging is the floor rather than a knob, and on a `pull_request`
|
|
@@ -1121,14 +1196,16 @@ event the workflow file itself runs from the pull request's own ref, so an
|
|
|
1121
1196
|
opt-out here would be settable by the very pull request the mode exists to
|
|
1122
1197
|
judge: the knob and the thing it protects against would be the same file.
|
|
1123
1198
|
|
|
1124
|
-
**
|
|
1199
|
+
**Pin the action by full commit SHA, with the version in a trailing comment, not by tag and not by path.** `uses: ./` reads
|
|
1125
1200
|
`action.yml` out of whichever tree the workflow runs against, which is
|
|
1126
1201
|
correct only for this repository's own workflows testing themselves; on a
|
|
1127
1202
|
pull request from anywhere else it would read `action.yml` out of the pull
|
|
1128
1203
|
request being judged, and the version-pin protection described above
|
|
1129
1204
|
"protects nothing" against a tree that controls its own judge (the
|
|
1130
|
-
validate step's own comment in `action.yml` says so in those words).
|
|
1131
|
-
this action by owner and
|
|
1205
|
+
validate step's own comment in `action.yml` says so in those words). A tag
|
|
1206
|
+
moves when someone pushes it. Name this action by owner and the full commit
|
|
1207
|
+
SHA instead. The recipes in this README pin the v0.8.0 commit and are
|
|
1208
|
+
updated to the v0.8.1 commit after that release is tagged.
|
|
1132
1209
|
|
|
1133
1210
|
```yaml
|
|
1134
1211
|
name: guardrails
|
|
@@ -1143,12 +1220,14 @@ jobs:
|
|
|
1143
1220
|
steps:
|
|
1144
1221
|
- uses: actions/checkout@v7
|
|
1145
1222
|
with:
|
|
1223
|
+
# From 0.8.0 a shallow checkout on a pull-request run is
|
|
1224
|
+
# could-not-run for the history gate.
|
|
1146
1225
|
fetch-depth: 0
|
|
1147
1226
|
- uses: actions/setup-node@v7
|
|
1148
1227
|
with:
|
|
1149
1228
|
node-version: '22.11.0'
|
|
1150
1229
|
- id: conductor
|
|
1151
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1230
|
+
uses: vaultcompasshq/conductor@566c7604b60137a7370a42a161f59b934aa1ad6d # v0.8.0
|
|
1152
1231
|
with:
|
|
1153
1232
|
output: conductor.sarif
|
|
1154
1233
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -1158,6 +1237,10 @@ jobs:
|
|
|
1158
1237
|
sarif_file: ${{ steps.conductor.outputs.sarif }}
|
|
1159
1238
|
```
|
|
1160
1239
|
|
|
1240
|
+
The job has `permissions: contents: read`. Add `pull-requests: write` only
|
|
1241
|
+
where the recipe posts a comment. `security-events: write` is there because
|
|
1242
|
+
the upload step publishes the SARIF log.
|
|
1243
|
+
|
|
1161
1244
|
The examples leave the trigger unnarrowed on purpose, so the job runs for a
|
|
1162
1245
|
pull request into any branch. If you narrow it with a `branches:` filter,
|
|
1163
1246
|
include every branch whose merges reach users, release branches and the
|
|
@@ -1166,11 +1249,20 @@ production]`. The pull request that promotes a release is where a bad
|
|
|
1166
1249
|
dependency or a leaked secret actually ships, and a job that is not triggered
|
|
1167
1250
|
leaves no red check and no report to notice.
|
|
1168
1251
|
|
|
1169
|
-
|
|
1170
|
-
|
|
1171
|
-
|
|
1172
|
-
|
|
1173
|
-
|
|
1252
|
+
A job marked `continue-on-error` always concludes green, so a crash of the
|
|
1253
|
+
action is invisible unless someone opens the log. A workflow triggered only
|
|
1254
|
+
on pull requests to main never runs on a stacked pull request whose base is
|
|
1255
|
+
another branch, and no comment on such a pull request does not mean clean.
|
|
1256
|
+
|
|
1257
|
+
Omit `conductor-version`. Left unset, the action installs the default in the
|
|
1258
|
+
pinned `action.yml`, which is the version that commit ships, so the installed
|
|
1259
|
+
umbrella follows the pin and a Dependabot bump is the one `uses` line. If the
|
|
1260
|
+
input is set and is older than the constants in that pinned action.yml, a
|
|
1261
|
+
pull request run is refused and the validate step says to remove the input. A
|
|
1262
|
+
newer value is accepted and is what gets installed. The three gate version
|
|
1263
|
+
inputs can be left out too: each one then takes the default in the pinned
|
|
1264
|
+
action.yml. The spelled-out example below names them when a workflow wants
|
|
1265
|
+
that transparency.
|
|
1174
1266
|
|
|
1175
1267
|
```yaml
|
|
1176
1268
|
name: guardrails
|
|
@@ -1185,13 +1277,14 @@ jobs:
|
|
|
1185
1277
|
steps:
|
|
1186
1278
|
- uses: actions/checkout@v7
|
|
1187
1279
|
with:
|
|
1188
|
-
# Required
|
|
1189
|
-
#
|
|
1190
|
-
#
|
|
1191
|
-
#
|
|
1192
|
-
#
|
|
1280
|
+
# Required. From 0.8.0 a shallow checkout on a pull-request run is
|
|
1281
|
+
# could-not-run for the history gate. Without a full history there
|
|
1282
|
+
# is no merge base to diff against, and the intent gate fails closed
|
|
1283
|
+
# rather than checking an empty set. And the base ref itself has to
|
|
1284
|
+
# be in the clone, because on a pull request the rules are read from
|
|
1285
|
+
# it: a base ref that will not resolve is exit 2 for every enabled
|
|
1286
|
+
# gate.
|
|
1193
1287
|
fetch-depth: 0
|
|
1194
|
-
- uses: pnpm/action-setup@v4
|
|
1195
1288
|
- uses: actions/setup-node@v7
|
|
1196
1289
|
with:
|
|
1197
1290
|
# Not a bare major: Node 22.0.0 ships npm 10.5.1, which the action
|
|
@@ -1199,27 +1292,30 @@ jobs:
|
|
|
1199
1292
|
# with. 22.1.0 or later, or 20.13.0 or later, carries an npm that
|
|
1200
1293
|
# can verify.
|
|
1201
1294
|
node-version: '22.11.0'
|
|
1202
|
-
|
|
1203
|
-
#
|
|
1204
|
-
#
|
|
1205
|
-
#
|
|
1206
|
-
|
|
1295
|
+
# NOTHING FROM THE PULL REQUEST RUNS BEFORE THE ACTION IN THIS JOB.
|
|
1296
|
+
# No `pnpm install`, `npm ci`, build or test step: an install runs the
|
|
1297
|
+
# repository's own lifecycle scripts (a root postinstall), and that code
|
|
1298
|
+
# could write the PATH the gates are resolved from, or the refs the
|
|
1299
|
+
# policy is read from, before the gates ever start. Your own
|
|
1300
|
+
# dependencies, build and tests belong in a separate job (see below).
|
|
1301
|
+
# The gates are not among the things that job has to install: the action
|
|
1302
|
+
# installs those itself, globally. Leave conductor-version unset so the
|
|
1303
|
+
# umbrella is the default in the pinned action.yml.
|
|
1207
1304
|
- id: conductor
|
|
1208
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1305
|
+
uses: vaultcompasshq/conductor@566c7604b60137a7370a42a161f59b934aa1ad6d # v0.8.0
|
|
1209
1306
|
with:
|
|
1210
1307
|
output: conductor.sarif
|
|
1211
|
-
# Exact versions, never a range and never "latest". These
|
|
1212
|
-
# lines decide which programs judge a pull request, so a pull
|
|
1308
|
+
# Exact versions, never a range and never "latest". These three
|
|
1309
|
+
# lines decide which gate programs judge a pull request, so a pull
|
|
1213
1310
|
# request's own lockfile no longer does. They are only as protected
|
|
1214
1311
|
# as this file is: require review on .github/workflows in your
|
|
1215
1312
|
# branch protection. Bump them like any other pin, in a pull
|
|
1216
|
-
# request of their own.
|
|
1217
|
-
#
|
|
1218
|
-
# left out entirely to take that
|
|
1219
|
-
|
|
1220
|
-
|
|
1221
|
-
|
|
1222
|
-
intent-guard-version: 1.7.0
|
|
1313
|
+
# request of their own. On a pull request the action refuses a pin
|
|
1314
|
+
# below what the pinned action.yml ships, and the three lines can
|
|
1315
|
+
# be left out entirely to take that action's own versions.
|
|
1316
|
+
dep-guard-version: 0.10.0
|
|
1317
|
+
vault-guard-version: 1.9.0
|
|
1318
|
+
intent-guard-version: 1.8.0
|
|
1223
1319
|
- uses: github/codeql-action/upload-sarif@v3
|
|
1224
1320
|
# Always: the log is most worth having on the run that failed.
|
|
1225
1321
|
if: always()
|
|
@@ -1233,8 +1329,49 @@ jobs:
|
|
|
1233
1329
|
continue-on-error: true
|
|
1234
1330
|
with:
|
|
1235
1331
|
sarif_file: ${{ steps.conductor.outputs.sarif }}
|
|
1332
|
+
|
|
1333
|
+
# Your own dependencies, build and tests: a different job, so the code they
|
|
1334
|
+
# run shares no runner, PATH or workspace with the gates.
|
|
1335
|
+
build:
|
|
1336
|
+
runs-on: ubuntu-latest
|
|
1337
|
+
steps:
|
|
1338
|
+
- uses: actions/checkout@v7
|
|
1339
|
+
- uses: pnpm/action-setup@v4
|
|
1340
|
+
- uses: actions/setup-node@v7
|
|
1341
|
+
with:
|
|
1342
|
+
node-version: '22.11.0'
|
|
1343
|
+
cache: pnpm
|
|
1344
|
+
- run: pnpm install --frozen-lockfile
|
|
1345
|
+
- run: pnpm test
|
|
1236
1346
|
```
|
|
1237
1347
|
|
|
1348
|
+
**Run the gates in a job that runs no code from the pull request.** Do not
|
|
1349
|
+
run `pnpm install`, `npm ci`, a build or a test step before the conductor
|
|
1350
|
+
action in the same job, and do not put the action in a job whose earlier steps
|
|
1351
|
+
run the repository's own scripts. Anything that runs first shares the runner
|
|
1352
|
+
with the gates: it can write to `GITHUB_PATH`, to the runner's temp directory
|
|
1353
|
+
where the action installs the gates, or to the git refs the base policy is
|
|
1354
|
+
read from, and then it is the pull request choosing the program that judges
|
|
1355
|
+
it. The action fetches the base branch into its own private ref and judges by
|
|
1356
|
+
that, which closes a moved or tag-shadowed base ref and nothing else. Only
|
|
1357
|
+
keeping pull-request code out of the job covers the rest: `GITHUB_ENV`
|
|
1358
|
+
(`NODE_OPTIONS=--require`, `GIT_CONFIG_*`, `GIT_DIR`), `GITHUB_PATH`,
|
|
1359
|
+
`.git/config` changes (a remote URL, `url.insteadOf`, `core.fsmonitor`,
|
|
1360
|
+
credential helpers, `core.sshCommand`), git hooks such as
|
|
1361
|
+
`reference-transaction`, and replace refs or grafts. Say it plainly:
|
|
1362
|
+
package.json lifecycle scripts (`preinstall`, `install`, `postinstall`,
|
|
1363
|
+
`prepare`) run by an install bypass "require review on `.github/workflows`",
|
|
1364
|
+
because the pull request supplies them, not the workflow file. Branch
|
|
1365
|
+
protection on the workflow directory does not stop them, so the gates must
|
|
1366
|
+
not share a job with head code that runs first.
|
|
1367
|
+
|
|
1368
|
+
**With gitleaks enabled the checkout must be `fetch-depth: 0`.** From 0.8.0 a
|
|
1369
|
+
shallow checkout on a pull-request run is could-not-run for the history gate,
|
|
1370
|
+
naming `fetch-depth: 0` (exit 2, whatever `enforce` says). At the default
|
|
1371
|
+
depth of 1 the checkout is shallow, the range from the base to HEAD holds one
|
|
1372
|
+
grafted commit, and a secret added and then removed inside the pull request
|
|
1373
|
+
would never be seen. conductor does not deepen the checkout for you.
|
|
1374
|
+
|
|
1238
1375
|
**The two external gates are installed by your workflow, not by the
|
|
1239
1376
|
Action.** The Action still installs exactly its four npm packages and has no
|
|
1240
1377
|
input for gitleaks or osv-scanner; conductor downloads, pins and checksums
|
|
@@ -1259,12 +1396,15 @@ checksum, the same way you would for a standalone security job:
|
|
|
1259
1396
|
echo "$bin" >> "$GITHUB_PATH"
|
|
1260
1397
|
```
|
|
1261
1398
|
|
|
1262
|
-
`fetch-depth: 0` on the checkout
|
|
1263
|
-
pull request conductor scans `<base>..HEAD
|
|
1264
|
-
|
|
1265
|
-
|
|
1266
|
-
|
|
1267
|
-
|
|
1399
|
+
`fetch-depth: 0` on the checkout is required with gitleaks enabled: on a
|
|
1400
|
+
pull request conductor scans `<base>..HEAD`. At depth 1 the checkout is
|
|
1401
|
+
shallow and that range holds a single commit, so a secret added and removed
|
|
1402
|
+
inside the pull request would go unseen; conductor detects the shallow
|
|
1403
|
+
checkout and reports the gate as could-not-run instead of scanning it. (A
|
|
1404
|
+
base that was never fetched at all is a git error gitleaks itself would
|
|
1405
|
+
report as a clean scan of nothing; conductor reads that error off gitleaks'
|
|
1406
|
+
log and reports the gate as could-not-run too.) A missing tool is
|
|
1407
|
+
could-not-run as well, with the install step named in the report.
|
|
1268
1408
|
|
|
1269
1409
|
The `@v4` pins there are readable, not safe: a tag moves, so pinning by one
|
|
1270
1410
|
runs whatever its author pushes to it next. Pin every third-party action by
|
|
@@ -1305,21 +1445,24 @@ jobs:
|
|
|
1305
1445
|
steps:
|
|
1306
1446
|
- uses: actions/checkout@v7
|
|
1307
1447
|
with:
|
|
1448
|
+
# From 0.8.0 a shallow checkout on a pull-request run is
|
|
1449
|
+
# could-not-run for the history gate.
|
|
1308
1450
|
fetch-depth: 0
|
|
1309
1451
|
- uses: actions/setup-node@v7
|
|
1310
1452
|
with:
|
|
1311
1453
|
node-version: '22.11.0'
|
|
1312
1454
|
- id: conductor
|
|
1313
1455
|
timeout-minutes: 5
|
|
1314
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1456
|
+
uses: vaultcompasshq/conductor@566c7604b60137a7370a42a161f59b934aa1ad6d # v0.8.0
|
|
1315
1457
|
with:
|
|
1316
1458
|
pr-comment: true
|
|
1317
1459
|
advisory: true
|
|
1318
1460
|
```
|
|
1319
1461
|
|
|
1320
|
-
`action.yml`
|
|
1321
|
-
|
|
1322
|
-
|
|
1462
|
+
`action.yml` fetches the trust base itself on every pull-request run, into its
|
|
1463
|
+
own private ref (depth 1 only when the checkout is already shallow, and always,
|
|
1464
|
+
whether or not the checkout carries the base), so this recipe needs no separate
|
|
1465
|
+
"fetch the base ref" step. None of
|
|
1323
1466
|
the three steps above swallows its own exit code: a checkout or setup-node
|
|
1324
1467
|
failure is an infrastructure problem this recipe should still surface, and
|
|
1325
1468
|
the `conductor` step's own advisory behaviour comes from `advisory: true`
|
|
@@ -1442,9 +1585,11 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1442
1585
|
security-events: write
|
|
1443
1586
|
pull-requests: write
|
|
1444
1587
|
steps:
|
|
1445
|
-
# ... checkout
|
|
1588
|
+
# ... checkout and setup-node, as in the example above. Nothing from
|
|
1589
|
+
# the pull request runs before the action in this job: no install, build
|
|
1590
|
+
# or test step here; those belong in a separate job. ...
|
|
1446
1591
|
- id: conductor
|
|
1447
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1592
|
+
uses: vaultcompasshq/conductor@566c7604b60137a7370a42a161f59b934aa1ad6d # v0.8.0
|
|
1448
1593
|
with:
|
|
1449
1594
|
output: conductor.sarif
|
|
1450
1595
|
pr-comment: true
|
|
@@ -1516,12 +1661,12 @@ per pull request.
|
|
|
1516
1661
|
|
|
1517
1662
|
```yaml
|
|
1518
1663
|
- id: conductor-package-a
|
|
1519
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1664
|
+
uses: vaultcompasshq/conductor@566c7604b60137a7370a42a161f59b934aa1ad6d # v0.8.0
|
|
1520
1665
|
with:
|
|
1521
1666
|
pr-comment: true
|
|
1522
1667
|
pr-comment-marker: 'package-a'
|
|
1523
1668
|
- id: conductor-package-b
|
|
1524
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1669
|
+
uses: vaultcompasshq/conductor@566c7604b60137a7370a42a161f59b934aa1ad6d # v0.8.0
|
|
1525
1670
|
with:
|
|
1526
1671
|
pr-comment: true
|
|
1527
1672
|
pr-comment-marker: 'package-b'
|