@vaultcompass/conductor 0.4.0 → 0.4.5

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.
Files changed (3) hide show
  1. package/README.md +227 -21
  2. package/dist/cli.js +69 -29
  3. package/package.json +14 -1
package/README.md CHANGED
@@ -328,10 +328,27 @@ and your pre-commit hook still run the pin, which is what `pnpm exec` does in
328
328
  the same repository.
329
329
 
330
330
  **The versions that judge a pull request are pinned in the workflow file**,
331
- which on a `pull_request` event is read from the base branch. That is the
332
- protected side, and it is the point: the pull request can change its own
333
- lockfile, and cannot change the pin that decides which conductor and which
334
- gates run over it.
331
+ and that is the point: the pull request can change its own lockfile,
332
+ manifest and `node_modules`, and none of those decide which conductor and
333
+ which gates run over it any more. Be clear about what that does not cover.
334
+ On a `pull_request` event GitHub runs the workflow as it is in the pull
335
+ request's merge commit, so a pull request that edits the workflow file can
336
+ change the pins or remove the gates step, exactly as it could rewrite any
337
+ other step in your CI. The boundary here is against the tree choosing its
338
+ own judge; the control for a workflow edit is branch protection on your
339
+ base branch with review required for `.github/workflows`, and no action can
340
+ provide that for you. Only `pull_request_target` runs the base branch's copy
341
+ of a workflow, and that event exposes the base's secrets to the pull
342
+ request's code, which is the wrong trade for a gate over untrusted changes.
343
+
344
+ One part of that is closed, and only one. Because the pins are written in a
345
+ file the pull request controls, a pull request could otherwise pin a gate
346
+ **backward** to a published version that predates the rule which would have
347
+ caught it: an exact version, so the validate step's shape check accepts it,
348
+ and a change that reads as ordinary version management. **On a pull request
349
+ the action now refuses any of the four `*-version` inputs naming a version
350
+ below the one the action tag ships.** Pinning forward is still accepted.
351
+ See "The Action" below.
335
352
 
336
353
  So on a pull-request run a gate's program must be **outside the working tree**
337
354
  (on PATH, or an absolute `command:` elsewhere on the machine), or else meet
@@ -532,11 +549,58 @@ defaulting to the version this release pins. A validate step refuses anything
532
549
  that is not an exact version, a range and `latest` included: the version that
533
550
  judges a pull request has to be a decision taken on the base branch rather
534
551
  than one the registry takes on the morning of the run. An install step then
535
- runs `npm install -g` under the runner temp, never into the workspace, and
536
- prepends that bin directory to `PATH`, so the run step invokes `conductor` off
537
- `PATH` and each gate resolves by name the same way. The install is
538
- **unconditional**, on push and `pull_request` alike, so there is one code path
539
- rather than one that matters and one that nobody exercises.
552
+ runs `npm install -g --ignore-scripts` under the runner temp, never into the
553
+ workspace, and prepends that bin directory to `PATH`, so the run step invokes
554
+ `conductor` off `PATH` and each gate resolves by name the same way. The install
555
+ is **unconditional**, on push and `pull_request` alike, so there is one code
556
+ path rather than one that matters and one that nobody exercises.
557
+
558
+ **On a pull request those four inputs may not pin backward.** The shape check
559
+ asks whether an input is an exact version; it says nothing about which one, and
560
+ on a `pull_request` event the workflow file comes from the head, so the pins are
561
+ written by the pull request being judged. Once a gate has two published versions
562
+ that is a bypass with an innocent shape: pin back to the release that predates
563
+ the rule which would have caught the change, and the change picks the rules it
564
+ is judged by. So where `GITHUB_BASE_REF` is set, the validate step refuses an
565
+ input naming a version below the one the action tag ships, naming both numbers,
566
+ and the fix is to **remove the input**: the default is that version. Pinning
567
+ **forward** is still accepted, on an assumption the rule does not enforce, that
568
+ a newer gate is at least as strict; nothing bounds how far forward you pin.
569
+
570
+ Three things follow from that, stated because the summary is wider than the rule.
571
+ It fires on fork pull requests too, where the base repository's workflow file is
572
+ the one that runs, so a deliberate backward pin you wrote yourself will refuse
573
+ every fork run until you remove it. Push runs are out of scope rather than safe:
574
+ a push to an unprotected branch runs that branch's own workflow file, written by
575
+ the same author. And `merge_group` runs are not covered at all: `GITHUB_BASE_REF`
576
+ is set on `pull_request` and `pull_request_target` only, so it is empty in a
577
+ merge queue even though the queue branch carries the pull request's commits and
578
+ its workflow file. If your only required check runs on `merge_group`, this rule
579
+ does nothing for you; keep the `pull_request` run required as well and the pin is
580
+ caught before the queue. Neither this nor anything else in `action.yml`
581
+ replaces branch protection with review required for `.github/workflows`, which
582
+ is still the only control over a pull request that edits the workflow.
583
+
584
+ `--ignore-scripts` is there because the step holds the job's token and the four
585
+ things it installs decide whether a pull request may merge; without it every
586
+ package in the resolved tree would run code on the runner. The step then runs
587
+ `npm audit signatures` over what it installed.
588
+
589
+ **What that verification proves, and what it does not.** It asks the registry
590
+ for each name and version in the tree, the four gates included, and checks the
591
+ signature served back, so an unpublished, replaced or unsigned package fails the
592
+ step. It does **not** read the installed files, so it will not detect a tampered
593
+ install; it does **not** defeat a compromised registry, which signs what it
594
+ serves; and a **missing** attestation is not a failure, so it does not require
595
+ provenance even though all four packages publish it.
596
+
597
+ > **This step needs a registry that serves `/-/npm/v1/keys`.** If your runner
598
+ > points npm at a mirror or proxy that does not (via `actions/setup-node`'s
599
+ > `registry-url:`, a corporate `~/.npmrc`, or `npm_config_registry`), the
600
+ > install succeeds and this step then fails with `EMISSINGSIGNATUREKEY`. A
601
+ > sigstore outage has the same effect. It fails closed on purpose, so that is a
602
+ > red gate rather than a skipped check; pin to `@v0.4.0`, which does not
603
+ > verify, if it blocks you.
540
604
 
541
605
  `--base` is passed only when the `base-ref` input names one; left empty, the
542
606
  umbrella reads `GITHUB_BASE_REF` itself and treats an empty value as "not a
@@ -557,6 +621,49 @@ event the workflow file itself runs from the pull request's own ref, so an
557
621
  opt-out here would be settable by the very pull request the mode exists to
558
622
  judge: the knob and the thing it protects against would be the same file.
559
623
 
624
+ **The normal way to use this is by tag, not by path.** `uses: ./` reads
625
+ `action.yml` out of whichever tree the workflow runs against, which is
626
+ correct only for this repository's own workflows testing themselves; on a
627
+ pull request from anywhere else it would read `action.yml` out of the pull
628
+ request being judged, and the version-pin protection described above
629
+ "protects nothing" against a tree that controls its own judge (the
630
+ validate step's own comment in `action.yml` says so in those words). Name
631
+ this action by owner and tag instead:
632
+
633
+ ```yaml
634
+ name: guardrails
635
+ on: pull_request
636
+
637
+ jobs:
638
+ gates:
639
+ runs-on: ubuntu-latest
640
+ permissions:
641
+ contents: read
642
+ security-events: write
643
+ steps:
644
+ - uses: actions/checkout@v4
645
+ with:
646
+ fetch-depth: 0
647
+ - uses: actions/setup-node@v4
648
+ with:
649
+ node-version: '22.11.0'
650
+ - id: conductor
651
+ uses: vaultcompasshq/conductor@v0.4.5
652
+ with:
653
+ output: conductor.sarif
654
+ - uses: github/codeql-action/upload-sarif@v3
655
+ if: always()
656
+ continue-on-error: true
657
+ with:
658
+ sarif_file: ${{ steps.conductor.outputs.sarif }}
659
+ ```
660
+
661
+ No version inputs there at all: left out, the four gates run at the versions
662
+ this tag ships, which is the intended default. The fully spelled-out example
663
+ below adds explicit version pins and comments explaining each one, for a
664
+ workflow that wants that transparency; the four lines can still be left out
665
+ entirely to take the tag's own versions, exactly as the form above does.
666
+
560
667
  ```yaml
561
668
  name: guardrails
562
669
  on: pull_request
@@ -579,26 +686,32 @@ jobs:
579
686
  - uses: pnpm/action-setup@v4
580
687
  - uses: actions/setup-node@v4
581
688
  with:
582
- node-version: 22
689
+ # Not a bare major: Node 22.0.0 ships npm 10.5.1, which the action
690
+ # refuses because that client reports a clean install as tampered
691
+ # with. 22.1.0 or later, or 20.13.0 or later, carries an npm that
692
+ # can verify.
693
+ node-version: '22.11.0'
583
694
  cache: pnpm
584
695
  # Your own dependencies. The gates are NOT among the things this has to
585
696
  # install: the action installs those itself, globally, at the versions
586
697
  # pinned below.
587
698
  - run: pnpm install --frozen-lockfile
588
699
  - id: conductor
589
- uses: ./
700
+ uses: vaultcompasshq/conductor@v0.4.5
590
701
  with:
591
702
  output: conductor.sarif
592
- # Exact versions, never a range and never "latest". On a
593
- # pull_request event this file is read from the base branch, so
594
- # these four lines are the protected side: a pull request can change
595
- # its own lockfile and cannot change which programs judge it.
596
- # Bump them like any other pin, in a pull request, on the base
597
- # branch first.
598
- conductor-version: 0.4.0
599
- dep-guard-version: 0.6.0
600
- vault-guard-version: 1.7.0
601
- intent-guard-version: 1.4.0
703
+ # Exact versions, never a range and never "latest". These four
704
+ # lines decide which programs judge a pull request, so a pull
705
+ # request's own lockfile no longer does. They are only as protected
706
+ # as this file is: require review on .github/workflows in your
707
+ # branch protection. Bump them like any other pin, in a pull
708
+ # request of their own. Forward only on a pull request: the action
709
+ # refuses a pin below what its tag ships, and the four lines can be
710
+ # left out entirely to take that tag's own versions.
711
+ conductor-version: 0.4.5
712
+ dep-guard-version: 0.7.0
713
+ vault-guard-version: 1.8.0
714
+ intent-guard-version: 1.5.2
602
715
  - uses: github/codeql-action/upload-sarif@v3
603
716
  # Always: the log is most worth having on the run that failed.
604
717
  if: always()
@@ -621,6 +734,99 @@ workflows do.
621
734
 
622
735
  ### The report as a pull request comment
623
736
 
737
+ **Built in, opt-in.** This matters most for an advisory job: a `pull_request`
738
+ check that is not marked required does not block anything when it fails, and
739
+ without a comment its findings live only in the job's exit code and log,
740
+ which teaches a developer nothing. Set `pr-comment: true` on the Action's own
741
+ step and add `pull-requests: write` to the job's `permissions`:
742
+
743
+ ```yaml
744
+ permissions:
745
+ contents: read
746
+ security-events: write
747
+ pull-requests: write
748
+ steps:
749
+ # ... checkout, pnpm, setup-node, install, as in the example above ...
750
+ - id: conductor
751
+ uses: vaultcompasshq/conductor@v0.4.5
752
+ with:
753
+ output: conductor.sarif
754
+ pr-comment: true
755
+ ```
756
+
757
+ That posts conductor's own text report, the one the README quotes above
758
+ ("conductor: clean, nothing blocked. 2 gate(s) ran: ..."), as a comment on
759
+ the pull request. It is **sticky**: a hidden marker in the comment body lets
760
+ a re-run find and update that same comment, so a push does not pile up a new
761
+ comment every time, the way the manual recipe below does. It runs on a
762
+ `pull_request` or `pull_request_target` event only, and it runs whether the
763
+ gates step passed or failed, since a blocking run is the one an advisory
764
+ check most needs a developer to actually see.
765
+
766
+ **It is a no-op on a pull request from a fork.** The default `GITHUB_TOKEN`
767
+ there is read-only regardless of the `pull-requests: write` permission you
768
+ grant, so the post fails; the step catches that, prints a `::warning::`
769
+ naming the likely cause, and continues. The gate's own pass/fail is decided
770
+ entirely by the earlier "Run the gates" step and never depends on whether
771
+ the comment posted, on a fork or anywhere else. `pull_request_target` runs
772
+ with a writable token and the base repository's own workflow instead, which
773
+ is a different security decision to take on purpose rather than a flag to
774
+ add; nothing here does that for you.
775
+
776
+ Off by default, so an existing consumer of this action is unaffected.
777
+
778
+ **The sticky match only ever adopts conductor's own comment.** On
779
+ `pull_request_target` this step runs with a write token even though the
780
+ pull request itself is untrusted, so anyone who can comment on the pull
781
+ request could, in principle, author a comment carrying the same hidden
782
+ marker before conductor's first run. The match requires the marker AND that
783
+ the comment was authored by the GitHub Actions bot; a marker in anyone
784
+ else's comment is never adopted, and conductor creates its own comment
785
+ instead, exactly as if no marked comment existed.
786
+
787
+ **Running this Action more than once against the same pull request** (for
788
+ example, once per package in a monorepo) needs its own marker per run, or
789
+ those runs fight over one shared comment. Set `pr-comment-marker` to a
790
+ distinct string per invocation and each run stays sticky to its own
791
+ comment; left unset (the default), every invocation uses the same built-in
792
+ marker, which is the existing, unchanged behaviour for a single invocation
793
+ per pull request.
794
+
795
+ ```yaml
796
+ - id: conductor-package-a
797
+ uses: vaultcompasshq/conductor@v0.4.5
798
+ with:
799
+ pr-comment: true
800
+ pr-comment-marker: 'package-a'
801
+ - id: conductor-package-b
802
+ uses: vaultcompasshq/conductor@v0.4.5
803
+ with:
804
+ pr-comment: true
805
+ pr-comment-marker: 'package-b'
806
+ ```
807
+
808
+ **A note for anyone changing this surface, not for a consumer of the
809
+ Action**: the comment body reaches `gh` with `-F body=@<file>` (`gh api`'s
810
+ file-read form), never `-f`, which sends the value as a literal string
811
+ instead of reading the file. The offline test suite
812
+ (`scripts/tests/pr-comment.test.mjs`, `scripts/tests/pr-comment-cli.test.mjs`)
813
+ replaces `gh` with a recorder or a shim, and neither can tell `-f` from `-F`
814
+ apart, since both simply accept a `key=value` string and neither actually
815
+ reads the `@file` form. `scripts/tests/pr-comment-smoke.test.mjs` is what
816
+ actually proves the distinction, against a real `gh` binary; it is skipped
817
+ by an ordinary offline `pnpm test` run and only runs with `GH_TOKEN` (or
818
+ `GITHUB_TOKEN`), `CONDUCTOR_PR_COMMENT_SMOKE_REPO`, and
819
+ `CONDUCTOR_PR_COMMENT_SMOKE_ISSUE` set. Run it for real against a scratch
820
+ issue or pull request before any release that touches
821
+ `scripts/lib/pr-comment.mjs` or `scripts/pr-comment.mjs`; the file itself
822
+ documents the exact invocation.
823
+
824
+ **The manual recipe below still has a reason to exist**: a non-sticky
825
+ comment (one per run, never edited), a report you want to post yourself with
826
+ different formatting, or a workflow that would rather not add
827
+ `pull-requests: write` to the same job the gates run in. For the common
828
+ case, `pr-comment: true` is the built-in answer.
829
+
624
830
  The SARIF upload produces no alerts on a private repository without GitHub
625
831
  Code Security, which is why that step carries `continue-on-error`. A comment
626
832
  is free there. Add `pull-requests: write` to the job's `permissions` and this
package/dist/cli.js CHANGED
@@ -79,49 +79,89 @@ function repoRoot(cwd) {
79
79
  * reported, and, when the trust base itself cannot be used, it names the
80
80
  * gates the report says did not run.
81
81
  */
82
+ /**
83
+ * An inventory, and only an inventory: a list of gate NAMES for the report,
84
+ * taken from the one file available when the trust base itself cannot supply
85
+ * a policy. It is head-controlled, so it can be SHORTER as well as longer
86
+ * than the base's -- every gate `enabled: false`, or a file that will not
87
+ * parse at all, leaves it empty.
88
+ *
89
+ * Neither direction can weaken the verdict, and that is the property this
90
+ * rests on rather than on the inventory being right. refusedTrustBase
91
+ * enforces every gate it names and writes exit 2 itself, and the refusal is
92
+ * carried on the result so both renderers lead with it whether the inventory
93
+ * names three gates or none. A longer list makes the report longer; a
94
+ * shorter one makes it shorter; the verdict is the same sentence either way.
95
+ *
96
+ * An unreadable head file leaves the list empty rather than throwing: the
97
+ * trust base is what went wrong, and reporting the head's malformed file
98
+ * would send the reader to the wrong fix on a run that would have ignored
99
+ * that file anyway.
100
+ */
101
+ function inventoryFromHead(root, overrides) {
102
+ try {
103
+ return applyCliOverrides(loadPolicy(root), overrides);
104
+ }
105
+ catch {
106
+ return { version: 1, gates: {}, report: { format: 'text' } };
107
+ }
108
+ }
82
109
  function policyForRun(root, trustBase, overrides) {
83
110
  if (trustBase === undefined) {
84
111
  return { kind: 'policy', policy: applyCliOverrides(loadPolicy(root), overrides) };
85
112
  }
86
113
  const refusal = refuseTrustBaseRef(root, trustBase);
87
114
  if (refusal !== null) {
88
- // An inventory, and only an inventory: a list of gate NAMES for the
89
- // report, taken from the one file available when the base ref cannot be
90
- // read. It is head-controlled, so it can be SHORTER as well as longer
91
- // than the base's -- every gate `enabled: false`, or a file that will not
92
- // parse at all, leaves it empty -- and an earlier comment here claimed
93
- // only the longer direction, which is how the empty case went unnoticed.
94
- //
95
- // Neither direction can weaken the verdict, and that is the property this
96
- // rests on rather than on the inventory being right. refusedTrustBase
97
- // enforces every gate it names and writes exit 2 itself, and the refusal
98
- // is carried on the result so both renderers lead with it whether the
99
- // inventory names three gates or none. A longer list makes the report
100
- // longer; a shorter one makes it shorter; the verdict is the same
101
- // sentence either way.
102
- //
103
- // An unreadable head file leaves the list empty rather than replacing the
104
- // refusal with a policy error: the ref is what went wrong, and reporting
105
- // the head's malformed file would send the reader to the wrong fix on a
106
- // run that would have ignored that file anyway.
107
- let inventory = { version: 1, gates: {}, report: { format: 'text' } };
108
- try {
109
- inventory = applyCliOverrides(loadPolicy(root), overrides);
110
- }
111
- catch {
112
- inventory = { version: 1, gates: {}, report: { format: 'text' } };
113
- }
114
- return { kind: 'refused', ref: trustBase, detail: refusal, inventory };
115
+ return {
116
+ kind: 'refused',
117
+ ref: trustBase,
118
+ detail: refusal,
119
+ inventory: inventoryFromHead(root, overrides),
120
+ };
115
121
  }
116
122
  const baseText = readPolicyAtRef(root, trustBase);
117
123
  const headText = readPolicyAtRef(root, 'HEAD');
118
124
  if (baseText === null) {
119
- throw new PolicyError(`No ${POLICY_FILE_NAME} on "${trustBase}". On a pull-request run every rule comes from the ` +
125
+ // CONFIG ABSENT ON THE BASE, not a policy error thrown from here. The old
126
+ // shape threw a PolicyError, which the run command's catch prints as one
127
+ // line on STDERR and nothing else: no report on stdout, no SARIF file
128
+ // written, exit code 2 by accident of `fail()` rather than by the same
129
+ // could-not-run machinery every other trust-base failure goes through.
130
+ // Two real adopters, running in advisory mode, hit exactly this on their
131
+ // first pull request -- before "conductor init" had ever landed on their
132
+ // base branch -- and read a red step with an empty report as either
133
+ // nothing to see or a broken tool, never as "finish adopting".
134
+ //
135
+ // This is DISCOVERED-empty, not IMPOSED-empty: nobody wrote a policy file
136
+ // down and disabled every gate in it, the base ref simply has none yet.
137
+ // That is the same "nothing here is a result of any kind" shape as a base
138
+ // ref that will not resolve, so it goes through the exact same
139
+ // refusedTrustBase reporting: could-not-run (exit 2), the reason on the
140
+ // text report and in the SARIF log, and the head's own gates named as not
141
+ // having run. A base ref whose file is merely ABSENT must not be treated
142
+ // more gently than one that will not resolve at all; both mean this run
143
+ // has no policy to have been judged by.
144
+ //
145
+ // CONTRAST: a base ref that DOES carry a policy file in which the user
146
+ // switched every gate off, or deferred them all past this stage, is left
147
+ // alone below in the ordinary `runAll` path and keeps reporting a clean
148
+ // exit 0 -- see the "no gate ran because none is enabled" verdict in
149
+ // output-text.ts. That is an IMPOSED-empty state, a decision written down
150
+ // on the base branch on purpose, and mirrors the no-contract
151
+ // (discovered, write one) vs contract-waived (imposed, a person already
152
+ // decided) distinction the intent gate already makes for a missing spec.
153
+ const detail = `No ${POLICY_FILE_NAME} on "${trustBase}". On a pull-request run every rule comes from the ` +
120
154
  'base ref, so this run has no policy at all and nothing was checked. ' +
121
155
  (headText === null
122
156
  ? `Run "conductor init" on the base branch.`
123
157
  : `The ${POLICY_FILE_NAME} in this pull request is a proposal: it decides what runs ` +
124
- 'once it is on the base branch, and never on the pull request that adds it.'));
158
+ 'once it is on the base branch, and never on the pull request that adds it.');
159
+ return {
160
+ kind: 'refused',
161
+ ref: trustBase,
162
+ detail,
163
+ inventory: inventoryFromHead(root, overrides),
164
+ };
125
165
  }
126
166
  return {
127
167
  kind: 'policy',
package/package.json CHANGED
@@ -1,8 +1,21 @@
1
1
  {
2
2
  "name": "@vaultcompass/conductor",
3
- "version": "0.4.0",
3
+ "version": "0.4.5",
4
4
  "type": "module",
5
5
  "description": "Umbrella installer and combined report over the independently installable guardrail gates.",
6
+ "keywords": [
7
+ "security",
8
+ "guardrails",
9
+ "sarif",
10
+ "code-scanning",
11
+ "github-actions",
12
+ "pre-commit",
13
+ "supply-chain",
14
+ "secrets-detection",
15
+ "cli"
16
+ ],
17
+ "homepage": "https://github.com/marketplace/actions/conductor-guardrail-gates",
18
+ "bugs": "https://github.com/vaultcompasshq/conductor/issues",
6
19
  "license": "MIT",
7
20
  "repository": {
8
21
  "type": "git",