@vaultcompass/conductor 0.14.0 → 0.15.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 +87 -19
- package/dist/gate-runner.d.ts +20 -0
- package/dist/gate-runner.js +51 -2
- package/dist/output-sarif.js +2 -2
- package/dist/output-text.js +16 -8
- package/dist/policy-diff.d.ts +9 -0
- package/dist/policy-diff.js +12 -4
- package/dist/resolve.d.ts +68 -0
- package/dist/resolve.js +156 -2
- package/dist/trust-base.d.ts +34 -0
- package/dist/trust-base.js +83 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -168,7 +168,7 @@ required.
|
|
|
168
168
|
A commit with a staged credential in it prints the full report and exits 1:
|
|
169
169
|
|
|
170
170
|
```
|
|
171
|
-
conductor 0.
|
|
171
|
+
conductor 0.15.0
|
|
172
172
|
verdict-token: blocked (1)
|
|
173
173
|
conductor run: 2 gate(s), 1 finding(s)
|
|
174
174
|
|
|
@@ -786,7 +786,10 @@ merged by someone allowed to merge without this check passing. A `.guardrails.ya
|
|
|
786
786
|
pull request never takes effect for that run, `command:` and `args:`
|
|
787
787
|
included, so **a pull request cannot change the rules it is judged by, and
|
|
788
788
|
cannot choose the program that judges it, as long as that program is
|
|
789
|
-
self-contained** (see the directory rule below). The
|
|
789
|
+
self-contained** (see the directory rule below). "The program" includes a
|
|
790
|
+
script handed to an interpreter: with `command: /usr/bin/node` and
|
|
791
|
+
`args: [tools/gate/run.mjs]`, the script is what judges, and it is vetted
|
|
792
|
+
exactly as a `command:` inside the tree would be. The same ref is passed
|
|
790
793
|
down to every gate that supports it, so their contracts, configs and
|
|
791
794
|
baselines come from the base branch too.
|
|
792
795
|
|
|
@@ -863,6 +866,61 @@ the message says to give it a directory: at the root the containing directory
|
|
|
863
866
|
is the whole repository, so the rule would mean "no pull request may change
|
|
864
867
|
anything".
|
|
865
868
|
|
|
869
|
+
**In-tree script arguments are vetted too.** Since 0.15.0 every entry of a
|
|
870
|
+
gate's `args:` that names something inside the working tree goes through the
|
|
871
|
+
same rule as the program, because an interpreter `command:` (Node, Python, a
|
|
872
|
+
shell) takes the program it runs as an argument. Before that, a base policy
|
|
873
|
+
of `command: /usr/bin/node` with `args: [tools/gate/run.mjs, scan]` let a
|
|
874
|
+
pull request rewrite `tools/gate/run.mjs` and report itself clean. Exactly
|
|
875
|
+
what counts:
|
|
876
|
+
|
|
877
|
+
- An entry is resolved against the repository root. Everything an
|
|
878
|
+
interpreter could load for it is vetted: the entry as written, and every
|
|
879
|
+
`<entry>.js`, `.mjs`, `.cjs`, `.json` or `.node` beside it, with or
|
|
880
|
+
without a slash. Node loads `tools/gate.js` before the directory
|
|
881
|
+
`tools/gate/`, and runs `run.js` for a bare `run`, so a sibling file the
|
|
882
|
+
pull request adds is refused because the base does not have it.
|
|
883
|
+
- A file (or a symbolic link) must meet the two conditions above; a
|
|
884
|
+
directory must have the same tree object id at the base and the head; the
|
|
885
|
+
repository root itself (`.`) is refused, since conductor already hands
|
|
886
|
+
each gate the repository it scans. A directory's `package.json` `main`
|
|
887
|
+
that points outside the directory is not vetted.
|
|
888
|
+
- `--name=value` is read for the value, so `--config=tools/gate/rules.json`
|
|
889
|
+
and `--import=./tools/gate/hook.mjs` are vetted. An option with no `=` and
|
|
890
|
+
a word that names nothing on disk are not paths and are never refused.
|
|
891
|
+
- The gate's own subcommand words (`scan`, `git`, `source`, `check`) are not
|
|
892
|
+
read as paths only when `command:` is the gate itself (its file name is
|
|
893
|
+
the gate's name, such as a vendored `vault-guard`). For an interpreter
|
|
894
|
+
they are paths like any other word: `node scan` runs `scan/index.js`.
|
|
895
|
+
A renamed gate binary, or any wrapper whose name is not a gate name, is
|
|
896
|
+
treated as an interpreter, so its `scan` or `source` is vetted if a file
|
|
897
|
+
or directory of that name exists, and a pull request touching it is
|
|
898
|
+
refused.
|
|
899
|
+
- Not recognised as a path, and **not** vetted: a Python `-m` module name, a
|
|
900
|
+
bare package name an interpreter resolves for itself, code passed as a
|
|
901
|
+
string (`node -e`, `bash -c`), and a package runner such as `npx`, which
|
|
902
|
+
resolves the gate from the head's own `node_modules`. Name the script by
|
|
903
|
+
its path, and do not run a gate through a package runner on pull requests.
|
|
904
|
+
- The sibling extensions tried are Node's (`.js`, `.mjs`, `.cjs`, `.json`,
|
|
905
|
+
`.node`). A TypeScript runner such as `tsx`, `ts-node` or `bun` also
|
|
906
|
+
resolves `.ts`, `.mts` and `.cts`, which are not tried, so name a
|
|
907
|
+
TypeScript script with its extension (`tools/gate/run.ts`, not
|
|
908
|
+
`tools/gate/run`).
|
|
909
|
+
- A script outside the working tree is accepted, as a program there is.
|
|
910
|
+
|
|
911
|
+
The version probe asks the script, not the interpreter: the args up to the
|
|
912
|
+
first non-option entry, when that entry names something loadable, then
|
|
913
|
+
`--version`, so `node tools/gate/run.mjs scan` is asked `node
|
|
914
|
+
tools/gate/run.mjs --version` and `node tools/gate` is asked `node
|
|
915
|
+
tools/gate --version`. The version conductor reports and checks against an
|
|
916
|
+
expected-version pin is then the gate's own. When the first non-option
|
|
917
|
+
entry names nothing loadable, or the command is the gate itself, the probe
|
|
918
|
+
is the command's own. One shape still reports the interpreter's version: a
|
|
919
|
+
flag that takes a file as its own entry before the script (`node -r
|
|
920
|
+
./setup.js tools/gate/run.mjs`) makes `./setup.js` the first entry, so the
|
|
921
|
+
probe is `node -r ./setup.js --version`; under an expected-version pin that
|
|
922
|
+
gate is could-not-run. Write `--require=./setup.js` instead.
|
|
923
|
+
|
|
866
924
|
A symlink inside the repository is refused on **its own entry**, before its
|
|
867
925
|
target is considered: it is either untracked, or its tree entry is a link
|
|
868
926
|
rather than a regular file, and either refuses. (A symlink whose own path is
|
|
@@ -1146,7 +1204,8 @@ policy with only `enabled`, `stage` and `enforce` taken from the head. Every
|
|
|
1146
1204
|
other head value, `command:`, `args:`, `options` and `timeout-seconds`
|
|
1147
1205
|
included, never reaches it: the base's command and the base's limit are what
|
|
1148
1206
|
run, and a base `command:` that resolves inside the working tree is refused
|
|
1149
|
-
there
|
|
1207
|
+
there, as is a base `args:` entry that names a path inside it (an
|
|
1208
|
+
interpreter's script). A gate's own config is another matter: in the preview, dep-guard and
|
|
1150
1209
|
vault-guard read their own `.dep-guard.json` and `.vault-guard.json` from the
|
|
1151
1210
|
head, because previewing the proposed rules means their rules too, while
|
|
1152
1211
|
gitleaks and osv-scanner keep the base's config. osv-scanner call analysis is
|
|
@@ -1167,7 +1226,13 @@ gate reached with no budget left is listed as over budget, and one that starts a
|
|
|
1167
1226
|
uses the same words as a primary section, so a finding may read `BLOCKING`
|
|
1168
1227
|
there: it means the finding would block under the proposed rules, and it does
|
|
1169
1228
|
not affect this run. A pull-request comment is cut at 60000 characters, the
|
|
1170
|
-
preview block first.
|
|
1229
|
+
preview block first. Every character outside printable ASCII in the preview
|
|
1230
|
+
(in the report, the job log and the SARIF notes) is written as a `\uXXXX`
|
|
1231
|
+
escape, because a gate there can read text the head chose, a
|
|
1232
|
+
right-to-left override in a pattern name included. The primary text report
|
|
1233
|
+
escapes finding file paths the same way, since a pull request names its own
|
|
1234
|
+
files; other primary gate text, and every path in the SARIF log, is printed
|
|
1235
|
+
as the gate gave it.
|
|
1171
1236
|
|
|
1172
1237
|
Ask for it with `--preview` on `conductor run`, or with the Action's `preview`
|
|
1173
1238
|
input, which defaults to `true`; any other value turns it off. There is no
|
|
@@ -1469,7 +1534,7 @@ request being judged, and the version-pin protection described above
|
|
|
1469
1534
|
"protects nothing" against a tree that controls its own judge (the
|
|
1470
1535
|
validate step's own comment in `action.yml` says so in those words). A tag
|
|
1471
1536
|
moves when someone pushes it. Name this action by owner and the full commit
|
|
1472
|
-
SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.
|
|
1537
|
+
SHA instead. The recipes in this README name vaultcompasshq/conductor@v0.15.0.
|
|
1473
1538
|
|
|
1474
1539
|
```yaml
|
|
1475
1540
|
name: guardrails
|
|
@@ -1489,9 +1554,9 @@ jobs:
|
|
|
1489
1554
|
fetch-depth: 0
|
|
1490
1555
|
- uses: actions/setup-node@v7
|
|
1491
1556
|
with:
|
|
1492
|
-
node-version: '22.
|
|
1557
|
+
node-version: '22.23.4'
|
|
1493
1558
|
- id: conductor
|
|
1494
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1559
|
+
uses: vaultcompasshq/conductor@v0.15.0
|
|
1495
1560
|
with:
|
|
1496
1561
|
output: conductor.sarif
|
|
1497
1562
|
- uses: github/codeql-action/upload-sarif@v3
|
|
@@ -1554,8 +1619,10 @@ jobs:
|
|
|
1554
1619
|
# Not a bare major: Node 22.0.0 ships npm 10.5.1, which the action
|
|
1555
1620
|
# refuses because that client reports a clean install as tampered
|
|
1556
1621
|
# with. 22.1.0 or later, or 20.13.0 or later, carries an npm that
|
|
1557
|
-
# can verify.
|
|
1558
|
-
|
|
1622
|
+
# can verify. 22.23.4 is the patched release this repository's own
|
|
1623
|
+
# release job pins after the 2026-10-21 Node security release; the
|
|
1624
|
+
# gates run over pull-request content under whatever Node you pick.
|
|
1625
|
+
node-version: '22.23.4'
|
|
1559
1626
|
# NOTHING FROM THE PULL REQUEST RUNS BEFORE THE ACTION IN THIS JOB.
|
|
1560
1627
|
# No `pnpm install`, `npm ci`, build or test step: an install runs the
|
|
1561
1628
|
# repository's own lifecycle scripts (a root postinstall), and that code
|
|
@@ -1566,7 +1633,7 @@ jobs:
|
|
|
1566
1633
|
# installs those itself, globally. Leave conductor-version unset so the
|
|
1567
1634
|
# umbrella is the default in the pinned action.yml.
|
|
1568
1635
|
- id: conductor
|
|
1569
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1636
|
+
uses: vaultcompasshq/conductor@v0.15.0
|
|
1570
1637
|
with:
|
|
1571
1638
|
output: conductor.sarif
|
|
1572
1639
|
# Exact versions, never a range and never "latest". These three
|
|
@@ -1577,9 +1644,9 @@ jobs:
|
|
|
1577
1644
|
# request of their own. On a pull request the action refuses a pin
|
|
1578
1645
|
# below what the pinned action.yml ships, and the three lines can
|
|
1579
1646
|
# be left out entirely to take that action's own versions.
|
|
1580
|
-
dep-guard-version: 0.
|
|
1647
|
+
dep-guard-version: 0.17.0
|
|
1581
1648
|
vault-guard-version: 1.12.1
|
|
1582
|
-
intent-guard-version: 1.10.
|
|
1649
|
+
intent-guard-version: 1.10.2
|
|
1583
1650
|
- uses: github/codeql-action/upload-sarif@v3
|
|
1584
1651
|
# Always: the log is most worth having on the run that failed.
|
|
1585
1652
|
if: always()
|
|
@@ -1603,7 +1670,7 @@ jobs:
|
|
|
1603
1670
|
- uses: pnpm/action-setup@v4
|
|
1604
1671
|
- uses: actions/setup-node@v7
|
|
1605
1672
|
with:
|
|
1606
|
-
node-version: '22.
|
|
1673
|
+
node-version: '22.23.4'
|
|
1607
1674
|
cache: pnpm
|
|
1608
1675
|
- run: pnpm install --frozen-lockfile
|
|
1609
1676
|
- run: pnpm test
|
|
@@ -1775,11 +1842,11 @@ jobs:
|
|
|
1775
1842
|
persist-credentials: false
|
|
1776
1843
|
- uses: actions/setup-node@v7
|
|
1777
1844
|
with:
|
|
1778
|
-
node-version: '22.
|
|
1845
|
+
node-version: '22.23.4'
|
|
1779
1846
|
- id: conductor
|
|
1780
1847
|
# The primary run's need (here 5 minutes) plus 300 seconds.
|
|
1781
1848
|
timeout-minutes: 10
|
|
1782
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1849
|
+
uses: vaultcompasshq/conductor@v0.15.0
|
|
1783
1850
|
with:
|
|
1784
1851
|
pr-comment: true
|
|
1785
1852
|
advisory: true
|
|
@@ -1915,7 +1982,7 @@ step and add `pull-requests: write` to the job's `permissions`:
|
|
|
1915
1982
|
# the pull request runs before the action in this job: no install, build
|
|
1916
1983
|
# or test step here; those belong in a separate job. ...
|
|
1917
1984
|
- id: conductor
|
|
1918
|
-
uses: vaultcompasshq/conductor@v0.
|
|
1985
|
+
uses: vaultcompasshq/conductor@v0.15.0
|
|
1919
1986
|
with:
|
|
1920
1987
|
output: conductor.sarif
|
|
1921
1988
|
pr-comment: true
|
|
@@ -1994,12 +2061,12 @@ per pull request.
|
|
|
1994
2061
|
|
|
1995
2062
|
```yaml
|
|
1996
2063
|
- id: conductor-package-a
|
|
1997
|
-
uses: vaultcompasshq/conductor@v0.
|
|
2064
|
+
uses: vaultcompasshq/conductor@v0.15.0
|
|
1998
2065
|
with:
|
|
1999
2066
|
pr-comment: true
|
|
2000
2067
|
pr-comment-marker: 'package-a'
|
|
2001
2068
|
- id: conductor-package-b
|
|
2002
|
-
uses: vaultcompasshq/conductor@v0.
|
|
2069
|
+
uses: vaultcompasshq/conductor@v0.15.0
|
|
2003
2070
|
with:
|
|
2004
2071
|
pr-comment: true
|
|
2005
2072
|
pr-comment-marker: 'package-b'
|
|
@@ -2120,7 +2187,7 @@ an explicit pin is unaffected, which is how a stale pin can sit unnoticed
|
|
|
2120
2187
|
until the first pull request after the upgrade.
|
|
2121
2188
|
|
|
2122
2189
|
**Pin the action ref to a full commit SHA** with the tag as a comment, for
|
|
2123
|
-
example `uses: vaultcompasshq/conductor@<40-character SHA> # v0.
|
|
2190
|
+
example `uses: vaultcompasshq/conductor@<40-character SHA> # v0.15.0`. To
|
|
2124
2191
|
find the SHA for a tag, run
|
|
2125
2192
|
`gh api repos/vaultcompasshq/conductor/git/ref/tags/v0.12.0` or read it off
|
|
2126
2193
|
the Releases page.
|
|
@@ -2143,6 +2210,7 @@ tag with no row here has an entry that does not state its defaults; read
|
|
|
2143
2210
|
|
|
2144
2211
|
| Action tag | Kind | `conductor-version` default | Gate defaults the entry says moved |
|
|
2145
2212
|
| --- | --- | --- | --- |
|
|
2213
|
+
| v0.15.0 | package | 0.15.0 | dep-guard 0.17.0 (from 0.16.1), intent-guard 1.10.2 (from 1.10.1) |
|
|
2146
2214
|
| v0.14.0 | package | 0.14.0 | none (gate defaults unchanged) |
|
|
2147
2215
|
| v0.13.2 | package | 0.13.2 | none (gate defaults unchanged) |
|
|
2148
2216
|
| v0.13.1 | action-only | 0.13.0 | dep-guard 0.16.1 (from 0.15.0) |
|
package/dist/gate-runner.d.ts
CHANGED
|
@@ -519,6 +519,13 @@ export declare function preparationTimedOut(gate: GatePolicy, stopped: {
|
|
|
519
519
|
* only the first left the probe free to spawn whatever the head put at the
|
|
520
520
|
* second, and a probe RUNS a program as thoroughly as a scan does.
|
|
521
521
|
*
|
|
522
|
+
* And every path the policy's `args:` name (`binary.argumentPaths`), because
|
|
523
|
+
* an interpreter `command:` takes the program as an argument: with `command:
|
|
524
|
+
* /usr/bin/node` and `args: [tools/gate/run.mjs]` the script judges, and
|
|
525
|
+
* vetting Node alone let a pull request rewrite the script (audit 2026-10-27,
|
|
526
|
+
* B1). The version probe's argv is a prefix of those same args, so it is
|
|
527
|
+
* covered by the same loop.
|
|
528
|
+
*
|
|
522
529
|
* The first refusal wins and the rest is not consulted. The verdict is the
|
|
523
530
|
* same either way, and the sentence a reader has to act on should name one
|
|
524
531
|
* file rather than two.
|
|
@@ -655,3 +662,16 @@ export declare function runGate(gate: GatePolicy, options: RunGateOptions): Gate
|
|
|
655
662
|
*/
|
|
656
663
|
/** The oldest git a history gate runs under on a pull-request run. */
|
|
657
664
|
export declare const HISTORY_GIT_FLOOR = "2.31.0";
|
|
665
|
+
/**
|
|
666
|
+
* cleanOutputLine, then every remaining character outside printable ASCII
|
|
667
|
+
* escaped as \uXXXX (escapeNonAscii). For every preview line: there a gate
|
|
668
|
+
* reads the head's own control files, so a rule id or a message can be
|
|
669
|
+
* head-chosen text, a right-to-left override included (audit 2026-10-27,
|
|
670
|
+
* N3). cleanOutputLine alone breaks a workflow command and keeps the
|
|
671
|
+
* override. The primary run is NOT safe by the same argument: its rule ids
|
|
672
|
+
* come from base-approved config, but its file paths are the head's own
|
|
673
|
+
* names. So the primary text report escapes finding paths (subjectLabel,
|
|
674
|
+
* src/output-text.ts), and only those; a primary gate message or stderr
|
|
675
|
+
* excerpt that quotes a path keeps its characters, a known limit.
|
|
676
|
+
*/
|
|
677
|
+
export declare function cleanPreviewLine(raw: string): string;
|
package/dist/gate-runner.js
CHANGED
|
@@ -30,8 +30,9 @@ import { checkEmptiedAgainstBase, compareWithBase, comparisonFailed, } from './o
|
|
|
30
30
|
import { ExternalConfigError, materializeExternalConfig, nestedConfigProposals, } from './external-config.js';
|
|
31
31
|
import { osvLockfileKind, profileFor } from './products.js';
|
|
32
32
|
import { unreadManifestsNote } from './unread-manifests.js';
|
|
33
|
-
import {
|
|
34
|
-
import {
|
|
33
|
+
import { escapeNonAscii } from './policy-diff.js';
|
|
34
|
+
import { atLeastVersion, refuseHeadControlledArgument, refuseHeadControlledProgram } from './trust-base.js';
|
|
35
|
+
import { ResolveError, argumentCandidates, candidateNames, commandIsGateProgram, nodeModulesCandidate, resolveGateBinary, } from './resolve.js';
|
|
35
36
|
/** The longest excerpt of a gate's own reason that is carried. */
|
|
36
37
|
export const GATE_SAID_MAX_CHARS = 160;
|
|
37
38
|
/**
|
|
@@ -653,6 +654,13 @@ const EMPTY_RUN = {
|
|
|
653
654
|
* only the first left the probe free to spawn whatever the head put at the
|
|
654
655
|
* second, and a probe RUNS a program as thoroughly as a scan does.
|
|
655
656
|
*
|
|
657
|
+
* And every path the policy's `args:` name (`binary.argumentPaths`), because
|
|
658
|
+
* an interpreter `command:` takes the program as an argument: with `command:
|
|
659
|
+
* /usr/bin/node` and `args: [tools/gate/run.mjs]` the script judges, and
|
|
660
|
+
* vetting Node alone let a pull request rewrite the script (audit 2026-10-27,
|
|
661
|
+
* B1). The version probe's argv is a prefix of those same args, so it is
|
|
662
|
+
* covered by the same loop.
|
|
663
|
+
*
|
|
656
664
|
* The first refusal wins and the rest is not consulted. The verdict is the
|
|
657
665
|
* same either way, and the sentence a reader has to act on should name one
|
|
658
666
|
* file rather than two.
|
|
@@ -667,6 +675,12 @@ export function refuseHeadControlledBinary(repoRoot, trustBase, binary) {
|
|
|
667
675
|
return refusal;
|
|
668
676
|
}
|
|
669
677
|
}
|
|
678
|
+
for (const argument of binary.argumentPaths) {
|
|
679
|
+
const refusal = refuseHeadControlledArgument(repoRoot, trustBase, argument);
|
|
680
|
+
if (refusal !== null) {
|
|
681
|
+
return refusal;
|
|
682
|
+
}
|
|
683
|
+
}
|
|
670
684
|
return null;
|
|
671
685
|
}
|
|
672
686
|
/**
|
|
@@ -1287,6 +1301,26 @@ function previewRefusal(gate, repoRoot) {
|
|
|
1287
1301
|
detail: `preview under the proposed rules: the base command ${gate.command} is inside the working tree, so this gate was not run`,
|
|
1288
1302
|
};
|
|
1289
1303
|
}
|
|
1304
|
+
// THE SAME FOR A PATH IN args:, for the same reason (audit 2026-10-27, B1):
|
|
1305
|
+
// an interpreter command takes the program as an argument, and a script in
|
|
1306
|
+
// the tree imports from the head as surely as a command there does. Refused
|
|
1307
|
+
// outright, as the command is, rather than by the base-equality rule: that
|
|
1308
|
+
// rule still runs in runGate on every preview spawn, so this is the
|
|
1309
|
+
// stricter of the two. The root counts as inside, and so does a link whose
|
|
1310
|
+
// own entry is in the tree, wherever it points (its directory is checked).
|
|
1311
|
+
// The candidate set is the primary run's (argumentCandidates): the entry and
|
|
1312
|
+
// every loadable sibling of it, so a head-added tools/gate.js beside a base
|
|
1313
|
+
// tools/gate/ is refused here too.
|
|
1314
|
+
const exempt = commandIsGateProgram(gate);
|
|
1315
|
+
for (const arg of gate.args ?? []) {
|
|
1316
|
+
const candidates = argumentCandidates(arg, repoRoot, gate.product, exempt);
|
|
1317
|
+
if (candidates.some((named) => realPathInside(repoRoot, named) || realPathInside(repoRoot, path.dirname(named)))) {
|
|
1318
|
+
return {
|
|
1319
|
+
reason: 'gate-program-refused',
|
|
1320
|
+
detail: `preview under the proposed rules: the base args entry ${arg} names a path inside the working tree, so this gate was not run`,
|
|
1321
|
+
};
|
|
1322
|
+
}
|
|
1323
|
+
}
|
|
1290
1324
|
return null;
|
|
1291
1325
|
}
|
|
1292
1326
|
/**
|
|
@@ -2359,3 +2393,18 @@ function spawnAndRead(ctx) {
|
|
|
2359
2393
|
};
|
|
2360
2394
|
}
|
|
2361
2395
|
}
|
|
2396
|
+
/**
|
|
2397
|
+
* cleanOutputLine, then every remaining character outside printable ASCII
|
|
2398
|
+
* escaped as \uXXXX (escapeNonAscii). For every preview line: there a gate
|
|
2399
|
+
* reads the head's own control files, so a rule id or a message can be
|
|
2400
|
+
* head-chosen text, a right-to-left override included (audit 2026-10-27,
|
|
2401
|
+
* N3). cleanOutputLine alone breaks a workflow command and keeps the
|
|
2402
|
+
* override. The primary run is NOT safe by the same argument: its rule ids
|
|
2403
|
+
* come from base-approved config, but its file paths are the head's own
|
|
2404
|
+
* names. So the primary text report escapes finding paths (subjectLabel,
|
|
2405
|
+
* src/output-text.ts), and only those; a primary gate message or stderr
|
|
2406
|
+
* excerpt that quotes a path keeps its characters, a known limit.
|
|
2407
|
+
*/
|
|
2408
|
+
export function cleanPreviewLine(raw) {
|
|
2409
|
+
return escapeNonAscii(cleanOutputLine(raw));
|
|
2410
|
+
}
|
package/dist/output-sarif.js
CHANGED
|
@@ -118,7 +118,7 @@
|
|
|
118
118
|
// normalize.ts, which is where the omission would stop mattering if the
|
|
119
119
|
// field were ever carried.
|
|
120
120
|
import { gateExitBlocks } from './exit-codes.js';
|
|
121
|
-
import {
|
|
121
|
+
import { cleanPreviewLine } from './gate-runner.js';
|
|
122
122
|
import { NATIVE_CONTRACT_PATH, isLegacyContractPath } from './intent-prepare.js';
|
|
123
123
|
import { INTENT_WARNING } from './normalize.js';
|
|
124
124
|
import { gateOutcomeWords, skewFound, skewPlace } from './output-text.js';
|
|
@@ -724,7 +724,7 @@ function previewNotifications(result) {
|
|
|
724
724
|
return [];
|
|
725
725
|
}
|
|
726
726
|
return guardPreview(() => preview.gates.map((gate) => {
|
|
727
|
-
const outcome =
|
|
727
|
+
const outcome = cleanPreviewLine(gateOutcomeWords(gate));
|
|
728
728
|
return {
|
|
729
729
|
id: 'conductor/preview-under-proposed-rules',
|
|
730
730
|
message: 'Preview under the proposed rules, which does not affect the verdict: ' +
|
package/dist/output-text.js
CHANGED
|
@@ -23,20 +23,26 @@
|
|
|
23
23
|
// everywhere is worth more here than a nicer-looking terminal.
|
|
24
24
|
import { compareFindings } from './envelope.js';
|
|
25
25
|
import { EXIT_BLOCKED, EXIT_COULD_NOT_RUN, gateExitBlocks } from './exit-codes.js';
|
|
26
|
-
import { CONDUCTOR_OWN_REASONS, cleanOutputLine, conductorStatedReason, resolutionPlace, versionCharacters, versionSkewRemedy, } from './gate-runner.js';
|
|
26
|
+
import { CONDUCTOR_OWN_REASONS, cleanOutputLine, cleanPreviewLine, conductorStatedReason, resolutionPlace, versionCharacters, versionSkewRemedy, } from './gate-runner.js';
|
|
27
27
|
import { isLegacyContractPath, legacyChangedSentence } from './intent-prepare.js';
|
|
28
28
|
import { SPEC_DIR } from './intent-spec.js';
|
|
29
29
|
import { PRODUCT_FOR_ROLE } from './policy.js';
|
|
30
|
+
import { escapeNonAscii } from './policy-diff.js';
|
|
30
31
|
import { guardPreview } from './run.js';
|
|
32
|
+
// A file path in a finding is the head's choice on any pull-request run (a
|
|
33
|
+
// file named with a right-to-left override in it), so in the text report,
|
|
34
|
+
// and so in the pull-request comment, every path is printed with
|
|
35
|
+
// escapeNonAscii (audit 2026-10-27 fix round, N3). SARIF keeps the real path:
|
|
36
|
+
// code scanning has to find the file.
|
|
31
37
|
function subjectLabel(finding) {
|
|
32
38
|
const subject = finding.subject;
|
|
33
39
|
switch (subject.kind) {
|
|
34
40
|
case 'package':
|
|
35
|
-
return `${subject.name} (${subject.manifest})`;
|
|
41
|
+
return `${subject.name} (${escapeNonAscii(subject.manifest)})`;
|
|
36
42
|
case 'location':
|
|
37
|
-
return `${subject.file}:${subject.line}:${subject.column}`;
|
|
43
|
+
return `${escapeNonAscii(subject.file)}:${subject.line}:${subject.column}`;
|
|
38
44
|
case 'paths':
|
|
39
|
-
return subject.paths.join(', ');
|
|
45
|
+
return subject.paths.map(escapeNonAscii).join(', ');
|
|
40
46
|
case 'contract':
|
|
41
47
|
return subject.category === undefined ? 'intent contract' : `contract: ${subject.category}`;
|
|
42
48
|
case 'none':
|
|
@@ -83,7 +89,7 @@ function osvSubject(entry) {
|
|
|
83
89
|
const name = first.subject.kind === 'package' ? first.subject.name : '';
|
|
84
90
|
const installed = typeof first.details.version === 'string' ? first.details.version : '';
|
|
85
91
|
const where = entry.length === 1 && first.subject.kind === 'package'
|
|
86
|
-
? `(${first.subject.manifest})`
|
|
92
|
+
? `(${escapeNonAscii(first.subject.manifest)})`
|
|
87
93
|
: `${entry.length} lockfiles`;
|
|
88
94
|
const fixed = typeof first.details.fixedVersion === 'string' ? `fix ${first.details.fixedVersion}` : 'no fix listed';
|
|
89
95
|
const dev = entry.filter(isDev).length;
|
|
@@ -150,7 +156,7 @@ function findingLines(entry, verbose, shortProblem) {
|
|
|
150
156
|
lines.push(...gitleaksLines(finding));
|
|
151
157
|
}
|
|
152
158
|
if (verbose && entry.length > 1) {
|
|
153
|
-
const manifests = entry.map((each) => (each.subject.kind === 'package' ? each.subject.manifest : ''));
|
|
159
|
+
const manifests = entry.map((each) => (each.subject.kind === 'package' ? escapeNonAscii(each.subject.manifest) : ''));
|
|
154
160
|
lines.push(` lockfiles: ${manifests.join(', ')}`);
|
|
155
161
|
}
|
|
156
162
|
return lines;
|
|
@@ -750,7 +756,9 @@ export function previewLines(result, verbose) {
|
|
|
750
756
|
}
|
|
751
757
|
return lines;
|
|
752
758
|
}, (message) => [`preview: could not be completed (${message})`]);
|
|
753
|
-
|
|
759
|
+
// cleanPreviewLine, not cleanOutputLine: a head .vault-guard.json can name
|
|
760
|
+
// a pattern id with a right-to-left override in it (audit 2026-10-27, N3).
|
|
761
|
+
return ['', PREVIEW_HEADER, ...body].map(cleanPreviewLine);
|
|
754
762
|
}
|
|
755
763
|
/**
|
|
756
764
|
* The preview's job log lines: one per preview gate in the per-gate lines'
|
|
@@ -767,7 +775,7 @@ export function previewLogLines(result) {
|
|
|
767
775
|
...preview.overBudget.map((role) => `conductor: preview ${role} (${PRODUCT_FOR_ROLE[role]}) over budget`),
|
|
768
776
|
...(preview.deferred.includes('intent') ? ['conductor: preview intent (intent-guard) deferred'] : []),
|
|
769
777
|
], (message) => [`conductor: preview could not be completed (${message})`]);
|
|
770
|
-
return lines.map(
|
|
778
|
+
return lines.map(cleanPreviewLine);
|
|
771
779
|
}
|
|
772
780
|
/**
|
|
773
781
|
* One plain line per gate, for the job log: which gate, which version, what
|
package/dist/policy-diff.d.ts
CHANGED
|
@@ -14,6 +14,15 @@ export declare const HEAD_POLICY_KEY = ".guardrails.yaml";
|
|
|
14
14
|
* file's. A null head (absent or unparseable) is one change that says so.
|
|
15
15
|
*/
|
|
16
16
|
export declare function diffPolicies(base: Policy, head: Policy | null): PolicyKeyChange[];
|
|
17
|
+
/**
|
|
18
|
+
* Every character outside printable ASCII as a \uXXXX escape (an astral
|
|
19
|
+
* character as its two surrogate escapes), so head-chosen text cannot smuggle
|
|
20
|
+
* a bidi override or a zero-width character into the report. Used for a head
|
|
21
|
+
* policy value here, and for every preview line (cleanPreviewLine,
|
|
22
|
+
* src/gate-runner.ts), whose gate text the head's own control files can
|
|
23
|
+
* choose (audit 2026-10-27, N3).
|
|
24
|
+
*/
|
|
25
|
+
export declare function escapeNonAscii(text: string): string;
|
|
17
26
|
/** One proposal line for one changed key. */
|
|
18
27
|
export declare function policyChangeLine(change: PolicyKeyChange): string;
|
|
19
28
|
/**
|
package/dist/policy-diff.js
CHANGED
|
@@ -92,14 +92,22 @@ export function diffPolicies(base, head) {
|
|
|
92
92
|
}
|
|
93
93
|
return changes;
|
|
94
94
|
}
|
|
95
|
+
/**
|
|
96
|
+
* Every character outside printable ASCII as a \uXXXX escape (an astral
|
|
97
|
+
* character as its two surrogate escapes), so head-chosen text cannot smuggle
|
|
98
|
+
* a bidi override or a zero-width character into the report. Used for a head
|
|
99
|
+
* policy value here, and for every preview line (cleanPreviewLine,
|
|
100
|
+
* src/gate-runner.ts), whose gate text the head's own control files can
|
|
101
|
+
* choose (audit 2026-10-27, N3).
|
|
102
|
+
*/
|
|
103
|
+
export function escapeNonAscii(text) {
|
|
104
|
+
return text.replace(/[^\x20-\x7e]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`);
|
|
105
|
+
}
|
|
95
106
|
function renderValue(value) {
|
|
96
107
|
if (value === undefined)
|
|
97
108
|
return '(absent)';
|
|
98
109
|
const text = JSON.stringify(value) ?? '(absent)';
|
|
99
|
-
|
|
100
|
-
// astral character as its two surrogate escapes), so a head option value
|
|
101
|
-
// cannot smuggle a bidi override or a zero-width character into the report.
|
|
102
|
-
const escaped = text.replace(/[^\x20-\x7e]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`);
|
|
110
|
+
const escaped = escapeNonAscii(text);
|
|
103
111
|
if (escaped.length <= MAX_VALUE_LENGTH)
|
|
104
112
|
return escaped;
|
|
105
113
|
// Keep whole tokens up to 77 characters, so no escape sequence is split.
|
package/dist/resolve.d.ts
CHANGED
|
@@ -34,6 +34,20 @@ export interface ResolvedBinary {
|
|
|
34
34
|
program: string;
|
|
35
35
|
/** Arguments placed before the ones the umbrella adds. */
|
|
36
36
|
argvPrefix: string[];
|
|
37
|
+
/**
|
|
38
|
+
* Every file or directory the policy's own `args:` names on disk, as an
|
|
39
|
+
* absolute path, with every loadable sibling of each (`argumentCandidates`),
|
|
40
|
+
* in args order. Empty when the policy has no `args:`.
|
|
41
|
+
*
|
|
42
|
+
* Carried because an interpreter `command:` hands the program to run as an
|
|
43
|
+
* ARGUMENT: with `command: /usr/bin/node` and `args: [tools/gate/run.mjs]`
|
|
44
|
+
* the script is what judges, not Node, and the pull-request provenance check
|
|
45
|
+
* has to vet it the way it vets `program` (audit 2026-10-27, B1). Only the
|
|
46
|
+
* policy's args, never a candidate's built-in prefix (`scan`, `source`):
|
|
47
|
+
* those are subcommands this package wrote, and a directory of the same
|
|
48
|
+
* name in somebody's repository is not a program.
|
|
49
|
+
*/
|
|
50
|
+
argumentPaths: string[];
|
|
37
51
|
source: ResolutionSource;
|
|
38
52
|
/** The candidate name this matched, for the report's gate header. */
|
|
39
53
|
candidate: string;
|
|
@@ -89,3 +103,57 @@ export declare function nodeModulesCandidate(gate: GatePolicy, repoRoot: string)
|
|
|
89
103
|
export declare function resolveGateBinary(gate: GatePolicy, repoRoot: string, pathValue: string, options?: ResolveOptions): ResolvedBinary | null;
|
|
90
104
|
/** Every name resolution would try, for the missing-gate finding's message. */
|
|
91
105
|
export declare function candidateNames(product: Product): string[];
|
|
106
|
+
/**
|
|
107
|
+
* Whether the policy's `command:` is itself the gate program, so its `args:`
|
|
108
|
+
* are that gate's own argv rather than something an interpreter will load.
|
|
109
|
+
*
|
|
110
|
+
* True when the command's name is a candidate name (`vault-guard`,
|
|
111
|
+
* `intent-guard.js`), and for a non-executable `.js` command, which this
|
|
112
|
+
* package runs through its own Node with the script as the program. False
|
|
113
|
+
* for anything else, an interpreter such as `node` or `python3` above all.
|
|
114
|
+
* Only then are the product's subcommand words (`scan`, `source`) exempt
|
|
115
|
+
* from being read as paths: an interpreter handed `scan` runs `scan.js` or
|
|
116
|
+
* `scan/index.js`, so for it the word is a path like any other (audit
|
|
117
|
+
* 2026-10-27 fix round, MB3).
|
|
118
|
+
*/
|
|
119
|
+
export declare function commandIsGateProgram(gate: GatePolicy): boolean;
|
|
120
|
+
/**
|
|
121
|
+
* Every path an interpreter could load for one `args:` entry, as absolute
|
|
122
|
+
* paths, in the order checked; empty when the entry names nothing on disk
|
|
123
|
+
* (audit 2026-10-27, B1, and its fix round).
|
|
124
|
+
*
|
|
125
|
+
* Relative entries are resolved against `repoRoot`. That is the working
|
|
126
|
+
* directory of the version probe and of the gate's own spawn for every
|
|
127
|
+
* product except one whose base config can name further files
|
|
128
|
+
* (`followsConfigExtend`): on a pull request that gate runs from a temporary
|
|
129
|
+
* directory holding the base ref's copies (src/gate-runner.ts, spawnCwd), so
|
|
130
|
+
* a relative script there resolves against base copies or not at all, never
|
|
131
|
+
* against the head tree. The rules, in order:
|
|
132
|
+
*
|
|
133
|
+
* - An option with no `=` (`--json`, `-r`) names nothing. An option with one
|
|
134
|
+
* (`--config=tools/cfg.json`, `--import=./hook.mjs`) is read for the value
|
|
135
|
+
* after the first `=`, since that is where an interpreter takes a file to
|
|
136
|
+
* load and a gate takes a file to read its rules from.
|
|
137
|
+
* - When `exemptSubcommands` is true (the command is the gate program
|
|
138
|
+
* itself, commandIsGateProgram), a bare word that is one of the product's
|
|
139
|
+
* own subcommands (`scan`, `git`, `source`, `check`) names nothing, even
|
|
140
|
+
* when a directory of that name exists. For an interpreter nothing is
|
|
141
|
+
* exempt.
|
|
142
|
+
* - The entry as written, when it exists as a file, a directory or a
|
|
143
|
+
* symlink, without following the symlink, so the caller can refuse an
|
|
144
|
+
* in-tree link on its own entry.
|
|
145
|
+
* - Then every `<entry>.js`, `.mjs`, `.cjs`, `.json` and `.node` that exists,
|
|
146
|
+
* slash or not, and whether or not the entry itself exists: Node tries
|
|
147
|
+
* those before a directory of the same name, and a bare `run` runs
|
|
148
|
+
* `run.js`. A sibling the head ADDED is listed too, which is what refuses
|
|
149
|
+
* it: the base does not track it.
|
|
150
|
+
*
|
|
151
|
+
* A directory's contents are covered by the caller's tree comparison, so
|
|
152
|
+
* `index.js` and `package.json` inside it are not listed separately; a
|
|
153
|
+
* `main` that points outside the directory is not vetted, the same limit as
|
|
154
|
+
* a program's directory. Everything else, a Python `-m` module name, a bare
|
|
155
|
+
* package specifier an interpreter resolves for itself, code passed as a
|
|
156
|
+
* string (`node -e`, `bash -c`), is not recognised as a path. The README says
|
|
157
|
+
* so.
|
|
158
|
+
*/
|
|
159
|
+
export declare function argumentCandidates(arg: string, repoRoot: string, product: Product, exemptSubcommands: boolean): string[];
|
package/dist/resolve.js
CHANGED
|
@@ -59,7 +59,7 @@
|
|
|
59
59
|
// depend on a package cache the report cannot describe, and a gate that
|
|
60
60
|
// "ran" from an unknown version is worse than one that is honestly
|
|
61
61
|
// reported missing.
|
|
62
|
-
import { accessSync, constants, statSync } from 'node:fs';
|
|
62
|
+
import { accessSync, constants, lstatSync, statSync } from 'node:fs';
|
|
63
63
|
import path from 'node:path';
|
|
64
64
|
import { profileFor } from './products.js';
|
|
65
65
|
export const CANDIDATES = {
|
|
@@ -220,6 +220,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
220
220
|
const prefix = gate.args ?? inferred?.prefix ?? table[0].prefix;
|
|
221
221
|
const candidateName = inferred?.name ?? baseName(gate.command);
|
|
222
222
|
const candidate = inferred ?? table[0];
|
|
223
|
+
const argumentPaths = argumentPathsOf(gate, repoRoot);
|
|
223
224
|
// A build directory holds plain .js files with a shebang but no
|
|
224
225
|
// executable bit surprisingly often (a fresh tsc output, a file copied
|
|
225
226
|
// out of a tarball). Running it through this same Node is exactly what
|
|
@@ -231,6 +232,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
231
232
|
// Node is the command; the script is what actually decides anything.
|
|
232
233
|
program: gate.command,
|
|
233
234
|
argvPrefix: [gate.command, ...prefix],
|
|
235
|
+
argumentPaths,
|
|
234
236
|
source: 'policy',
|
|
235
237
|
candidate: candidateName,
|
|
236
238
|
versionProbe: candidate.versionSafe && profileFor(gate.product).versionProbe !== null
|
|
@@ -241,13 +243,20 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
241
243
|
: versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
|
|
242
244
|
};
|
|
243
245
|
}
|
|
246
|
+
// A command that is not itself a gate name (an interpreter, typically)
|
|
247
|
+
// and whose args hand it a script is asked through the script, or the
|
|
248
|
+
// version reported is the interpreter's (audit 2026-10-27, N4). A
|
|
249
|
+
// version-unsafe candidate keeps its sibling lookup: rule 2 above.
|
|
250
|
+
const viaScript = inferred === undefined && candidate.versionSafe ? scriptVersionProbe(gate, repoRoot) : null;
|
|
244
251
|
return {
|
|
245
252
|
command: gate.command,
|
|
246
253
|
program: gate.command,
|
|
247
254
|
argvPrefix: prefix,
|
|
255
|
+
argumentPaths,
|
|
248
256
|
source: 'policy',
|
|
249
257
|
candidate: candidateName,
|
|
250
|
-
versionProbe:
|
|
258
|
+
versionProbe: viaScript ??
|
|
259
|
+
versionProbeFor(gate.product, candidate, gate.command, repoRoot, pathValue, skipNodeModules),
|
|
251
260
|
};
|
|
252
261
|
}
|
|
253
262
|
for (const candidate of table) {
|
|
@@ -259,6 +268,7 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
259
268
|
command: found.command,
|
|
260
269
|
program: found.command,
|
|
261
270
|
argvPrefix: [...candidate.prefix],
|
|
271
|
+
argumentPaths: [],
|
|
262
272
|
source: found.source,
|
|
263
273
|
candidate: candidate.name,
|
|
264
274
|
versionProbe: versionProbeFor(gate.product, candidate, found.command, repoRoot, pathValue, skipNodeModules),
|
|
@@ -270,3 +280,147 @@ export function resolveGateBinary(gate, repoRoot, pathValue, options = {}) {
|
|
|
270
280
|
export function candidateNames(product) {
|
|
271
281
|
return CANDIDATES[product].map((candidate) => candidate.name);
|
|
272
282
|
}
|
|
283
|
+
/**
|
|
284
|
+
* The extensions an interpreter can add to an entry before it looks at the
|
|
285
|
+
* entry as written: Node's main-entry resolution tries `.js`, `.json` and
|
|
286
|
+
* `.node` BEFORE a directory of the same name (`node tools/gate` runs
|
|
287
|
+
* `tools/gate.js` over `tools/gate/index.js`, measured on Node 22), and the
|
|
288
|
+
* ES module forms are listed too, so a sibling a loader might take is vetted
|
|
289
|
+
* whether or not this Node takes it (audit 2026-10-27 fix round, MB1 and
|
|
290
|
+
* MB2).
|
|
291
|
+
*/
|
|
292
|
+
const LOADABLE_EXTENSIONS = ['.js', '.mjs', '.cjs', '.json', '.node'];
|
|
293
|
+
function existsAtAll(candidate) {
|
|
294
|
+
try {
|
|
295
|
+
lstatSync(candidate);
|
|
296
|
+
return true;
|
|
297
|
+
}
|
|
298
|
+
catch {
|
|
299
|
+
return false;
|
|
300
|
+
}
|
|
301
|
+
}
|
|
302
|
+
/**
|
|
303
|
+
* Whether the policy's `command:` is itself the gate program, so its `args:`
|
|
304
|
+
* are that gate's own argv rather than something an interpreter will load.
|
|
305
|
+
*
|
|
306
|
+
* True when the command's name is a candidate name (`vault-guard`,
|
|
307
|
+
* `intent-guard.js`), and for a non-executable `.js` command, which this
|
|
308
|
+
* package runs through its own Node with the script as the program. False
|
|
309
|
+
* for anything else, an interpreter such as `node` or `python3` above all.
|
|
310
|
+
* Only then are the product's subcommand words (`scan`, `source`) exempt
|
|
311
|
+
* from being read as paths: an interpreter handed `scan` runs `scan.js` or
|
|
312
|
+
* `scan/index.js`, so for it the word is a path like any other (audit
|
|
313
|
+
* 2026-10-27 fix round, MB3).
|
|
314
|
+
*/
|
|
315
|
+
export function commandIsGateProgram(gate) {
|
|
316
|
+
if (gate.command === undefined) {
|
|
317
|
+
return true;
|
|
318
|
+
}
|
|
319
|
+
if (!isExecutableFile(gate.command) && /\.(?:js|mjs|cjs)$/.test(gate.command)) {
|
|
320
|
+
return true;
|
|
321
|
+
}
|
|
322
|
+
const name = baseName(gate.command);
|
|
323
|
+
return CANDIDATES[gate.product].some((candidate) => candidate.name === name);
|
|
324
|
+
}
|
|
325
|
+
/**
|
|
326
|
+
* Every path an interpreter could load for one `args:` entry, as absolute
|
|
327
|
+
* paths, in the order checked; empty when the entry names nothing on disk
|
|
328
|
+
* (audit 2026-10-27, B1, and its fix round).
|
|
329
|
+
*
|
|
330
|
+
* Relative entries are resolved against `repoRoot`. That is the working
|
|
331
|
+
* directory of the version probe and of the gate's own spawn for every
|
|
332
|
+
* product except one whose base config can name further files
|
|
333
|
+
* (`followsConfigExtend`): on a pull request that gate runs from a temporary
|
|
334
|
+
* directory holding the base ref's copies (src/gate-runner.ts, spawnCwd), so
|
|
335
|
+
* a relative script there resolves against base copies or not at all, never
|
|
336
|
+
* against the head tree. The rules, in order:
|
|
337
|
+
*
|
|
338
|
+
* - An option with no `=` (`--json`, `-r`) names nothing. An option with one
|
|
339
|
+
* (`--config=tools/cfg.json`, `--import=./hook.mjs`) is read for the value
|
|
340
|
+
* after the first `=`, since that is where an interpreter takes a file to
|
|
341
|
+
* load and a gate takes a file to read its rules from.
|
|
342
|
+
* - When `exemptSubcommands` is true (the command is the gate program
|
|
343
|
+
* itself, commandIsGateProgram), a bare word that is one of the product's
|
|
344
|
+
* own subcommands (`scan`, `git`, `source`, `check`) names nothing, even
|
|
345
|
+
* when a directory of that name exists. For an interpreter nothing is
|
|
346
|
+
* exempt.
|
|
347
|
+
* - The entry as written, when it exists as a file, a directory or a
|
|
348
|
+
* symlink, without following the symlink, so the caller can refuse an
|
|
349
|
+
* in-tree link on its own entry.
|
|
350
|
+
* - Then every `<entry>.js`, `.mjs`, `.cjs`, `.json` and `.node` that exists,
|
|
351
|
+
* slash or not, and whether or not the entry itself exists: Node tries
|
|
352
|
+
* those before a directory of the same name, and a bare `run` runs
|
|
353
|
+
* `run.js`. A sibling the head ADDED is listed too, which is what refuses
|
|
354
|
+
* it: the base does not track it.
|
|
355
|
+
*
|
|
356
|
+
* A directory's contents are covered by the caller's tree comparison, so
|
|
357
|
+
* `index.js` and `package.json` inside it are not listed separately; a
|
|
358
|
+
* `main` that points outside the directory is not vetted, the same limit as
|
|
359
|
+
* a program's directory. Everything else, a Python `-m` module name, a bare
|
|
360
|
+
* package specifier an interpreter resolves for itself, code passed as a
|
|
361
|
+
* string (`node -e`, `bash -c`), is not recognised as a path. The README says
|
|
362
|
+
* so.
|
|
363
|
+
*/
|
|
364
|
+
export function argumentCandidates(arg, repoRoot, product, exemptSubcommands) {
|
|
365
|
+
let value = arg;
|
|
366
|
+
if (arg.startsWith('-')) {
|
|
367
|
+
const equals = arg.indexOf('=');
|
|
368
|
+
if (equals < 0) {
|
|
369
|
+
return [];
|
|
370
|
+
}
|
|
371
|
+
value = arg.slice(equals + 1);
|
|
372
|
+
}
|
|
373
|
+
else if (exemptSubcommands && CANDIDATES[product].some((candidate) => candidate.prefix.includes(arg))) {
|
|
374
|
+
return [];
|
|
375
|
+
}
|
|
376
|
+
if (value === '') {
|
|
377
|
+
return [];
|
|
378
|
+
}
|
|
379
|
+
const absolute = path.resolve(repoRoot, value);
|
|
380
|
+
return [absolute, ...LOADABLE_EXTENSIONS.map((extension) => absolute + extension)].filter(existsAtAll);
|
|
381
|
+
}
|
|
382
|
+
/** `argumentCandidates` for every entry of a policy's `args:`, flattened. */
|
|
383
|
+
function argumentPathsOf(gate, repoRoot) {
|
|
384
|
+
const exempt = commandIsGateProgram(gate);
|
|
385
|
+
return (gate.args ?? []).flatMap((arg) => argumentCandidates(arg, repoRoot, gate.product, exempt));
|
|
386
|
+
}
|
|
387
|
+
/**
|
|
388
|
+
* The version probe for a policy `command:` that is not itself a gate name,
|
|
389
|
+
* when its `args:` hand it a script: the args up to and including the first
|
|
390
|
+
* non-option entry, when that entry names something the interpreter can load
|
|
391
|
+
* (argumentCandidates: a file, a directory, or a bare or extension-less name
|
|
392
|
+
* with a loadable sibling), then the product's own probe argv. The entry is
|
|
393
|
+
* passed as written, so the interpreter resolves it exactly as it will for
|
|
394
|
+
* the scan. So `node tools/gate/run.mjs scan` is asked `node
|
|
395
|
+
* tools/gate/run.mjs --version`, `node tools/gate` is asked `node tools/gate
|
|
396
|
+
* --version`, and the version reported is the script's, not Node's (audit
|
|
397
|
+
* 2026-10-27, N4). Null when the first non-option entry names nothing, or
|
|
398
|
+
* there is none, and the caller keeps the probe it would have made anyway.
|
|
399
|
+
*
|
|
400
|
+
* Only the first: everything after the script is the script's own argv, and
|
|
401
|
+
* carrying a subcommand or a target into a probe would make it do work,
|
|
402
|
+
* which is the one thing a probe must not do.
|
|
403
|
+
* An interpreter flag that takes a file as a separate entry (`-r
|
|
404
|
+
* ./setup.js`) makes that file the first, so the probe asks the interpreter
|
|
405
|
+
* and reports its version, as it did before; under an expected-version pin
|
|
406
|
+
* that is could-not-run, the fail-closed direction.
|
|
407
|
+
*/
|
|
408
|
+
function scriptVersionProbe(gate, repoRoot) {
|
|
409
|
+
const spec = profileFor(gate.product).versionProbe;
|
|
410
|
+
if (spec === null || gate.command === undefined || gate.args === undefined) {
|
|
411
|
+
return null;
|
|
412
|
+
}
|
|
413
|
+
for (let index = 0; index < gate.args.length; index += 1) {
|
|
414
|
+
const arg = gate.args[index];
|
|
415
|
+
if (arg.startsWith('-')) {
|
|
416
|
+
continue;
|
|
417
|
+
}
|
|
418
|
+
// Only the FIRST non-option entry can be the script. A later file is the
|
|
419
|
+
// script's own argument (`my-build check rules.json`), and a probe that
|
|
420
|
+
// carried the subcommand before it would make the gate do work.
|
|
421
|
+
return argumentCandidates(arg, repoRoot, gate.product, false).length > 0
|
|
422
|
+
? { command: gate.command, argv: [...gate.args.slice(0, index + 1), ...spec.argv] }
|
|
423
|
+
: null;
|
|
424
|
+
}
|
|
425
|
+
return null;
|
|
426
|
+
}
|
package/dist/trust-base.d.ts
CHANGED
|
@@ -336,3 +336,37 @@ export declare function refuseHeadControlledProgram(repoRoot: string, trustBase:
|
|
|
336
336
|
* for every repository pinning an older gate.
|
|
337
337
|
*/
|
|
338
338
|
export declare function atLeastVersion(version: string | null, minimum: string): boolean;
|
|
339
|
+
/**
|
|
340
|
+
* Why a path named in a gate's `args:` cannot be trusted on a pull-request
|
|
341
|
+
* run, or null (audit 2026-10-27, B1).
|
|
342
|
+
*
|
|
343
|
+
* An interpreter `command:` takes the program as an argument: with
|
|
344
|
+
* `command: /usr/bin/node` and `args: [tools/gate/run.mjs, scan]` the script
|
|
345
|
+
* judges and Node only runs it, so vetting `command:` alone let a pull request
|
|
346
|
+
* rewrite the script and choose its own judge. `argumentCandidates`
|
|
347
|
+
* (src/resolve.ts) lists every path an interpreter could load for an entry,
|
|
348
|
+
* the entry and each of its loadable siblings (`tools/gate.js` beside
|
|
349
|
+
* `tools/gate/`), and each one is asked here separately; this decides
|
|
350
|
+
* whether that one path is the base's.
|
|
351
|
+
*
|
|
352
|
+
* - A FILE, or a symlink of any kind, goes through refuseHeadControlledProgram
|
|
353
|
+
* unchanged: blob and containing directory identical at both refs, an
|
|
354
|
+
* in-tree link refused on its own entry, the root refused, anything outside
|
|
355
|
+
* the tree accepted. The same rule as a `command:`, because it is the same
|
|
356
|
+
* question.
|
|
357
|
+
* - A DIRECTORY inside the tree is accepted only when it is a tracked tree
|
|
358
|
+
* at both refs with the same tree object id: when no sibling file wins,
|
|
359
|
+
* an interpreter handed a directory (`node tools/gate`) runs what is
|
|
360
|
+
* inside it, so the whole subtree is the unit, as it is beside a program.
|
|
361
|
+
* A sibling file that would win is a separate candidate, vetted as a file.
|
|
362
|
+
* - THE REPOSITORY ROOT ITSELF is refused (`node .` runs the head's own
|
|
363
|
+
* package.json main). Approving it would mean comparing the whole tree,
|
|
364
|
+
* which differs on every pull request; conductor already hands every gate
|
|
365
|
+
* the repository it scans, so no gate needs the root in `args:`.
|
|
366
|
+
*
|
|
367
|
+
* NOTHING HERE READS THE WORKING TREE's CONTENTS, as for the program: both
|
|
368
|
+
* sides are `git ls-tree` listings. Only whether the entry is a directory is
|
|
369
|
+
* read from disk, and a link is never followed for that, so a link is always
|
|
370
|
+
* vetted as a link.
|
|
371
|
+
*/
|
|
372
|
+
export declare function refuseHeadControlledArgument(repoRoot: string, trustBase: string, argumentPath: string): string | null;
|
package/dist/trust-base.js
CHANGED
|
@@ -71,7 +71,7 @@
|
|
|
71
71
|
// RUN proceeds, so the caller can still learn the trees matched
|
|
72
72
|
// (`headTreeEqualsBase` below) and run only the gates whose input is
|
|
73
73
|
// history rather than the tree.
|
|
74
|
-
import { realpathSync } from 'node:fs';
|
|
74
|
+
import { lstatSync, realpathSync } from 'node:fs';
|
|
75
75
|
import path from 'node:path';
|
|
76
76
|
import { parse as parseYaml } from 'yaml';
|
|
77
77
|
import { gitComplaint, runGit, runGitBytes } from './git.js';
|
|
@@ -886,3 +886,85 @@ export function atLeastVersion(version, minimum) {
|
|
|
886
886
|
}
|
|
887
887
|
return true;
|
|
888
888
|
}
|
|
889
|
+
/**
|
|
890
|
+
* Why a path named in a gate's `args:` cannot be trusted on a pull-request
|
|
891
|
+
* run, or null (audit 2026-10-27, B1).
|
|
892
|
+
*
|
|
893
|
+
* An interpreter `command:` takes the program as an argument: with
|
|
894
|
+
* `command: /usr/bin/node` and `args: [tools/gate/run.mjs, scan]` the script
|
|
895
|
+
* judges and Node only runs it, so vetting `command:` alone let a pull request
|
|
896
|
+
* rewrite the script and choose its own judge. `argumentCandidates`
|
|
897
|
+
* (src/resolve.ts) lists every path an interpreter could load for an entry,
|
|
898
|
+
* the entry and each of its loadable siblings (`tools/gate.js` beside
|
|
899
|
+
* `tools/gate/`), and each one is asked here separately; this decides
|
|
900
|
+
* whether that one path is the base's.
|
|
901
|
+
*
|
|
902
|
+
* - A FILE, or a symlink of any kind, goes through refuseHeadControlledProgram
|
|
903
|
+
* unchanged: blob and containing directory identical at both refs, an
|
|
904
|
+
* in-tree link refused on its own entry, the root refused, anything outside
|
|
905
|
+
* the tree accepted. The same rule as a `command:`, because it is the same
|
|
906
|
+
* question.
|
|
907
|
+
* - A DIRECTORY inside the tree is accepted only when it is a tracked tree
|
|
908
|
+
* at both refs with the same tree object id: when no sibling file wins,
|
|
909
|
+
* an interpreter handed a directory (`node tools/gate`) runs what is
|
|
910
|
+
* inside it, so the whole subtree is the unit, as it is beside a program.
|
|
911
|
+
* A sibling file that would win is a separate candidate, vetted as a file.
|
|
912
|
+
* - THE REPOSITORY ROOT ITSELF is refused (`node .` runs the head's own
|
|
913
|
+
* package.json main). Approving it would mean comparing the whole tree,
|
|
914
|
+
* which differs on every pull request; conductor already hands every gate
|
|
915
|
+
* the repository it scans, so no gate needs the root in `args:`.
|
|
916
|
+
*
|
|
917
|
+
* NOTHING HERE READS THE WORKING TREE's CONTENTS, as for the program: both
|
|
918
|
+
* sides are `git ls-tree` listings. Only whether the entry is a directory is
|
|
919
|
+
* read from disk, and a link is never followed for that, so a link is always
|
|
920
|
+
* vetted as a link.
|
|
921
|
+
*/
|
|
922
|
+
export function refuseHeadControlledArgument(repoRoot, trustBase, argumentPath) {
|
|
923
|
+
const repoReal = realOrNull(repoRoot);
|
|
924
|
+
if (repoReal === null) {
|
|
925
|
+
return `the repository root ${repoRoot} could not be resolved, so the gate arguments could not be checked against "${trustBase}". Nothing was checked by this gate.`;
|
|
926
|
+
}
|
|
927
|
+
const spellings = [withResolvedParent(argumentPath), realOrNull(argumentPath)].filter((spelling) => spelling !== null);
|
|
928
|
+
if (spellings.some((spelling) => path.relative(repoReal, spelling) === '')) {
|
|
929
|
+
return (`the gate's args: name the repository root (${argumentPath}), so what would run is decided by ` +
|
|
930
|
+
`the whole working tree, and this pull request differs from "${trustBase}" somewhere in it. ` +
|
|
931
|
+
'conductor already hands each gate the repository it scans; name a script in its own ' +
|
|
932
|
+
'directory instead. Nothing was checked by this gate.');
|
|
933
|
+
}
|
|
934
|
+
let isDirectory;
|
|
935
|
+
try {
|
|
936
|
+
isDirectory = lstatSync(argumentPath).isDirectory();
|
|
937
|
+
}
|
|
938
|
+
catch {
|
|
939
|
+
// Gone between resolution and now: nothing for a child to run from here,
|
|
940
|
+
// and nothing for the program rule to approve either. Asking it anyway
|
|
941
|
+
// is the fail-closed direction, since an untracked or absent path refuses.
|
|
942
|
+
isDirectory = false;
|
|
943
|
+
}
|
|
944
|
+
if (!isDirectory) {
|
|
945
|
+
return refuseHeadControlledProgram(repoRoot, trustBase, argumentPath);
|
|
946
|
+
}
|
|
947
|
+
for (const spelling of new Set(spellings)) {
|
|
948
|
+
if (!insideWorkingTree(repoReal, spelling)) {
|
|
949
|
+
continue;
|
|
950
|
+
}
|
|
951
|
+
const relative = path.relative(repoReal, spelling).split(path.sep).join('/');
|
|
952
|
+
const baseEntry = treeEntryAt(repoRoot, trustBase, relative);
|
|
953
|
+
const headEntry = treeEntryAt(repoRoot, 'HEAD', relative);
|
|
954
|
+
for (const listed of [baseEntry, headEntry]) {
|
|
955
|
+
if (listed.kind === 'error') {
|
|
956
|
+
return (`the directory ${relative} named in the gate's args: could not be checked against ` +
|
|
957
|
+
`"${trustBase}": ${listed.detail}. Nothing was checked by this gate.`);
|
|
958
|
+
}
|
|
959
|
+
}
|
|
960
|
+
const base = baseEntry.kind === 'entry' ? baseEntry : null;
|
|
961
|
+
const head = headEntry.kind === 'entry' ? headEntry : null;
|
|
962
|
+
if (base === null || head === null || base.type !== 'tree' || head.type !== 'tree' || base.sha !== head.sha) {
|
|
963
|
+
return (`the directory ${relative} named in the gate's args: is not what "${trustBase}" approved: ` +
|
|
964
|
+
'this pull request adds, removes or changes something in it, and an interpreter handed a ' +
|
|
965
|
+
'directory runs what is inside. Land the change on the base branch first, or name a ' +
|
|
966
|
+
'script outside the repository. Nothing was checked by this gate.');
|
|
967
|
+
}
|
|
968
|
+
}
|
|
969
|
+
return null;
|
|
970
|
+
}
|